docs: standardize trans passthrough alias
This commit is contained in:
Codex
@@ -9,7 +9,7 @@
|
||||
- HWLAB `v0.2` 是 G14 上的加法扩容线，固定分支为 `v0.2`，固定开发 workspace 为 `G14:/root/hwlab-v02`，固定 CI/CD source repo 为 `G14:/root/hwlab-v02-cicd.git`，固定 namespace 为 `hwlab-v02`，公网入口规划为 `http://74.48.78.17:19666/` 与 `http://74.48.78.17:19667/health/live`。创建和集成 `v0.2` 时不得删除、重命名或改义现有 `G14`/`G14-gitops` 分支、`hwlab-dev`/`hwlab-prod` namespace 或 17666/17667、18666/18667 入口；细则见 `docs/reference/g14.md`。
|
||||
- HWLAB 项目内长期规则入口：`/root/hwlab/AGENTS.md`。开始 `G14:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取该文件；不能只凭主 server 的压缩上下文继续操作。
|
||||
- 每次开始 G14 工作前必须通过 UniDesk SSH 桥执行 `cd /root/hwlab && git status --short --branch && git remote -v`，期望分支是 `G14...origin/G14`；若不满足，先修正 workspace，不能继续开发、render、polling 或部署。
|
||||
- G14 k3s 操作必须使用 route 语法 `G14:k3s`，例如 `tran G14:k3s kubectl get pods -n hwlab-dev`；禁止写成 `ssh G14 k3s ...`。第一个 route token 必须定位分布式目标，后续 token 才是 operation。
|
||||
- G14 k3s 操作必须使用 route 语法 `G14:k3s`，例如 `trans G14:k3s kubectl get pods -n hwlab-dev`；禁止写成 `ssh G14 k3s ...`。第一个 route token 必须定位分布式目标，后续 token 才是 operation。
|
||||
- `D601:HWLAB` 已降级为 legacy/migration 对照和 D601 Windows 硬件 bridge 入口，不再是默认开发主阵地或运行面真相。只有用户明确指定 D601 legacy、D601 回滚对照或 D601 Windows/Keil/串口硬件桥接时，才使用 `/home/ubuntu/workspace/hwlab-dev`；进入前仍要执行 `cd /home/ubuntu/workspace/hwlab-dev && git status --short --branch && git remote -v` 并读取该目录的 `AGENTS.md`。
|
||||
- D601 上 `/home/ubuntu/workspace/hwlab`、`/home/ubuntu/hwlab`、`/tmp/hwlab-*`、`/home/ubuntu/workspace/hwlab-*`、master-server checkout 或其他 runner clone 都不能作为当前 HWLAB source truth。发现 D601 口径与 G14 `/root/hwlab/AGENTS.md` 冲突时，以 G14 当前规则为准。
|
||||
- `/root/HWLAB`、`/workspace/hwlab`、D601 workspace、master-server checkout 或临时 clone 都不能作为 `G14:HWLAB` source truth。
|
||||
@@ -60,7 +60,7 @@ FRP 文档、issue 和日志只能记录端口、容器名、ConfigMap 名、Sec
|
||||
|
||||
- 在 `G14:k3s` 的 `hwlab-dev` namespace 手动建立一个 standalone `device-agent-71-freq` Pod/Deployment 和 ClusterIP Service。它暴露设备语义入口，例如 `/health`、`/skills`、`/workspace/*`、`/run`，并把真实硬件调用转成 HWLAB cloud-api 的 gateway operation，而不是在 Pod 内直接访问 Windows 硬件。
|
||||
- 在 `D601:win` 上启动 `hwlab-gateway`，作为 71-FREQ/ConStart/Keil/串口资源的外部 host bridge。gateway 通过公网或受控网络出站连接当前 G14 DEV cloud-api：`http://74.48.78.17:17667`，注册稳定的 `gatewaySessionId`、`resourceId` 和 `capabilityId`。
|
||||
- `hwlab-gateway` 是 Windows 长驻 outbound poll 进程，不能用 `tran D601:win cmd start ...` 或 PowerShell `Start-Process` 直接挂在一次性 tran 会话下；这种启动方式可能继承输出句柄或被 provider 按子进程树等待，导致 tran 卡住并阻塞后续 provider session。临时实验也应通过 Windows Task Scheduler、Windows Service、NSSM、PM2 service 或等价 detached launcher 启动，`tran` 只负责触发和读取状态；通用规则见 `docs/reference/windows-passthrough.md`。
|
||||
- `hwlab-gateway` 是 Windows 长驻 outbound poll 进程，不能用 `trans D601:win cmd start ...` 或 PowerShell `Start-Process` 直接挂在一次性 trans/tran 会话下；这种启动方式可能继承输出句柄或被 provider 按子进程树等待，导致 trans/tran 卡住并阻塞后续 provider session。临时实验也应通过 Windows Task Scheduler、Windows Service、NSSM、PM2 service 或等价 detached launcher 启动，`trans` 只负责触发和读取状态；通用规则见 `docs/reference/windows-passthrough.md`。
|
||||
- D601 Windows gateway 的最小配置必须来自 profile 或环境变量，核心字段是 `HWLAB_GATEWAY_CLOUD_URL=http://74.48.78.17:17667`、`HWLAB_GATEWAY_ID`、`HWLAB_GATEWAY_SESSION_ID`、`HWLAB_GATEWAY_RESOURCE_ID`、`HWLAB_GATEWAY_CMD_CAPABILITY_ID`、`HWLAB_GATEWAY_CMD_EXEC_ENABLED=1`、`HWLAB_GATEWAY_DEMO_OPEN=1`、`HWLAB_GATEWAY_MAX_INFLIGHT` 和 `HWLAB_GATEWAY_CMD_TIMEOUT_MS`。这些值用于声明能力和执行边界，不得散落在 device-agent 代码里。
|
||||
- device-agent 访问 G14 集群内 cloud-api 时优先使用 `http://hwlab-cloud-api.hwlab-dev.svc.cluster.local:6667`。Node/undici `fetch` 会按 Fetch bad-port 规则拒绝 `6667`，因此 Node 实现必须使用 `node:http`/`node:https`、已有 repo-owned HTTP helper，或改用不触发 bad-port 的受控代理端口。
|
||||
- 71-FREQ 的 device profile 必须配置化保存，至少包含工程根目录、Keil project/target、默认串口波特率、gateway/resource/capability 选择器和 workspace 根。不得把 `F:\Work\ConStart`、工程名、串口号或 probe UID 硬编码进 device-agent 镜像。
|
||||
@@ -72,14 +72,14 @@ FRP 文档、issue 和日志只能记录端口、容器名、ConfigMap 名、Sec
|
||||
- master server 是 UniDesk/HWLAB 的生产入口且资源紧张；它只能承担轻量源码编辑、Git 操作、日志/健康观察、JSON CLI 指挥和受控 CD 审阅，不能承担正式校验执行面。
|
||||
- 禁止在 master server 上运行 HWLAB 或 UniDesk 的仓库级 `check`/`test`/smoke 命令，包括但不限于 `bun scripts/cli.ts check`、`node --test`、`node web/hwlab-cloud-web/scripts/check.mjs`、`node scripts/dev-cloud-workbench-smoke.mjs`、Playwright/browser layout smoke，以及其他会长时间占用 CPU/内存、启动浏览器或遍历大仓库的校验流程。
|
||||
- 需要正式验证时，固定切到 G14 `/root/hwlab`、G14 k3s/Tekton、HWLAB repo-owned CI 或其他获批外部执行面；master server 只负责发起、观察和记录，不负责实际跑 check。
|
||||
- 如果为了排障必须从 master server 生成命令或查看源码，后续验证命令也必须显式改到 G14 路径执行，例如 `tran G14:/root/hwlab script -- ...` 或 `tran G14:k3s ...`，而不是直接在 `/root/unidesk` 或 master server 上本地运行。
|
||||
- 如果为了排障必须从 master server 生成命令或查看源码，后续验证命令也必须显式改到 G14 路径执行，例如 `trans G14:/root/hwlab script -- ...` 或 `trans G14:k3s ...`，而不是直接在 `/root/unidesk` 或 master server 上本地运行。
|
||||
|
||||
## G14 运行面与 D601 Legacy 口径
|
||||
|
||||
HWLAB 当前真实 DEV/PROD runtime 在 G14 原生 k3s 中。只读观察使用：
|
||||
|
||||
```sh
|
||||
tran G14:k3s kubectl -n hwlab-dev get deploy,svc,pod -o wide
|
||||
trans G14:k3s kubectl -n hwlab-dev get deploy,svc,pod -o wide
|
||||
```
|
||||
|
||||
`hwlab-cloud-api` 和 `hwlab-edge-proxy` 在集群内使用 `6667` Service 端口，对外 DEV API 使用 `17667`。G14 local details 见 `docs/reference/g14.md` 和 G14 节点 `/root/docs/hwlab-g14-workspace.md`。
|
||||
@@ -155,31 +155,31 @@ node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production -
|
||||
1. 更新 D601 部署副本：
|
||||
|
||||
```sh
|
||||
bun scripts/cli.ts ssh D601 'cd /home/ubuntu/workspace/hwlab && git pull --ff-only origin main'
|
||||
trans D601 'cd /home/ubuntu/workspace/hwlab && git pull --ff-only origin main'
|
||||
```
|
||||
|
||||
2. 刷新 Cloud Web 静态构建产物。运行时 wrapper 优先读取 `web/hwlab-cloud-web/dist`，如果该目录残留旧内容，即使源码已经更新，镜像仍可能继续服务旧页面：
|
||||
|
||||
```sh
|
||||
bun scripts/cli.ts ssh D601 'cd /home/ubuntu/workspace/hwlab && node web/hwlab-cloud-web/scripts/build.mjs'
|
||||
trans D601 'cd /home/ubuntu/workspace/hwlab && node web/hwlab-cloud-web/scripts/build.mjs'
|
||||
```
|
||||
|
||||
3. 发布镜像到 D601 本地 registry：
|
||||
|
||||
```sh
|
||||
bun scripts/cli.ts ssh D601 'cd /home/ubuntu/workspace/hwlab && node scripts/dev-artifact-publish.mjs --publish --services hwlab-cloud-web --report reports/dev-gate/dev-artifacts-hwlab-cloud-web-<tag>.json'
|
||||
trans D601 'cd /home/ubuntu/workspace/hwlab && node scripts/dev-artifact-publish.mjs --publish --services hwlab-cloud-web --report reports/dev-gate/dev-artifacts-hwlab-cloud-web-<tag>.json'
|
||||
```
|
||||
|
||||
4. 在滚动前用一次本地容器探针确认镜像内容，不把 commit tag 等同于页面内容：
|
||||
|
||||
```sh
|
||||
bun scripts/cli.ts ssh D601 'docker run --rm -d --name hwlab-cloud-web-probe -p 127.0.0.1:18088:8080 127.0.0.1:5000/hwlab/hwlab-cloud-web:<tag> && sleep 1 && curl -fsS http://127.0.0.1:18088/health/live && curl -fsS http://127.0.0.1:18088/ | sed -n "1,40p"; docker rm -f hwlab-cloud-web-probe'
|
||||
trans D601 'docker run --rm -d --name hwlab-cloud-web-probe -p 127.0.0.1:18088:8080 127.0.0.1:5000/hwlab/hwlab-cloud-web:<tag> && sleep 1 && curl -fsS http://127.0.0.1:18088/health/live && curl -fsS http://127.0.0.1:18088/ | sed -n "1,40p"; docker rm -f hwlab-cloud-web-probe'
|
||||
```
|
||||
|
||||
5. 滚动 D601 原生 k3s：
|
||||
|
||||
```sh
|
||||
bun scripts/cli.ts ssh D601 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev set image deployment/hwlab-cloud-web hwlab-cloud-web=127.0.0.1:5000/hwlab/hwlab-cloud-web:<tag> && KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev rollout status deployment/hwlab-cloud-web --timeout=180s'
|
||||
trans D601 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev set image deployment/hwlab-cloud-web hwlab-cloud-web=127.0.0.1:5000/hwlab/hwlab-cloud-web:<tag> && KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev rollout status deployment/hwlab-cloud-web --timeout=180s'
|
||||
```
|
||||
|
||||
6. 用公网入口验收：
|
||||
|
||||
Reference in New Issue
Block a user