feat: retire legacy HWLAB G14 runtime

This commit is contained in:
Codex
2026-06-08 17:57:41 +00:00
parent 799f35de06
commit 0920d39c7c
6 changed files with 487 additions and 80 deletions
+26 -27
View File
@@ -5,13 +5,13 @@
## 固定入口
- UniDesk 指挥侧 workspace`/root/unidesk`,固定使用 `master`,开始前执行 `git status``git pull --ff-only origin master`
- HWLAB 当前主阵地:`G14:HWLAB`,唯一长期 source workspace 是 G14 节点上的 `/root/hwlab`,固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。新开发、文档、render、polling、CI/CD、GitOps、DEV/PROD runtime 和验收默认都以这个 workspace 和 G14 k3s 为准
- 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`,例如 `trans G14:k3s kubectl get pods -n hwlab-dev`;禁止写成 `ssh G14 k3s ...`。第一个 route token 必须定位分布式目标,后续 token 才是 operation。
- HWLAB legacy G14 DEV/PROD 已退役;`G14`/`G14-gitops``hwlab-dev`/`hwlab-prod`、17666/17667 和 18666/18667 不再是当前 source/runtime truth。退役状态和执行入口是 `bun scripts/cli.ts hwlab g14 retirement status|plan|execute --confirm`,细则见 `docs/reference/g14.md`
- HWLAB 当前 G14 主阵地是 runtime lane`v0.2` 固定分支为 `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.3+` `hwlab nodes --node G14 --lane vNN``config/hwlab-node-lanes.yaml` 管理
- HWLAB 项目内长期规则入口仍以目标 repo 的 `AGENTS.md` 为准。进入 G14 runtime lane 分布式开发、切换任务、恢复中断或上下文压缩后,必须重新读取目标 workspace 的规则文件;不能只凭主 server 的压缩上下文继续操作。
- 每次开始 G14 runtime lane 工作前必须通过 UniDesk SSH 桥检查目标 workspace,例如 `trans G14:/root/hwlab-v02 script -- 'git status --short --branch && git remote -v'`;若不满足目标 lane 预期,先修正 workspace,不能继续开发、render、polling 或部署。
- G14 k3s 操作必须使用 route 语法 `G14:k3s`,例如 `trans G14:k3s kubectl get pods -n hwlab-v02`;禁止写成 `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 当前规则为准。
- D601 上 `/home/ubuntu/workspace/hwlab``/home/ubuntu/hwlab``/tmp/hwlab-*``/home/ubuntu/workspace/hwlab-*`、master-server checkout 或其他 runner clone 都不能作为当前 HWLAB source truth。发现 D601 口径与当前 G14 runtime lane 规则冲突时,以 G14 runtime lane 规则为准。
- `/root/HWLAB``/workspace/hwlab`、D601 workspace、master-server checkout 或临时 clone 都不能作为 `G14:HWLAB` source truth。
## 关键 GitHub 入口
@@ -27,62 +27,61 @@
## DEV 入口
- 当前 G14 DEV 前端入口固定为 `http://74.48.78.17:17666/`
- 当前 G14 DEV API/live 入口固定为 `http://74.48.78.17:17667/health/live`
- 规划中的 G14 `v0.2` 前端/API 入口固定为 `http://74.48.78.17:19666/``http://74.48.78.17:19667/health/live`,只能指向 `hwlab-v02` namespace,不得复用或覆盖 DEV/PROD 入口。
- 退役 G14 DEV/PROD 前端/API 入口曾使用 `http://74.48.78.17:17666/``http://74.48.78.17:17667/health/live``http://74.48.78.17:18666/``http://74.48.78.17:18667/health/live`;这些端口不再作为当前 HWLAB runtime 证据
- 当前 G14 `v0.2` 前端/API 入口固定为 `http://74.48.78.17:19666/``http://74.48.78.17:19667/health/live`,只能指向 `hwlab-v02` namespace
- D601 legacy DEV 前端/API 入口曾使用 `http://74.48.78.17:16666/``http://74.48.78.17:16667/health/live`;只在显式 D601 legacy 排障或迁移对照时使用,不能作为当前 HWLAB DEV 运行面证据。
- 旧公网 `:6666``:6667` 不是浏览器验收入口;内部 k3s service 仍可使用 `6667` 作为服务端口。
- 当前 G14 入口由 G14 侧公开代理承担;不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。D601 legacy `16666/16667` 的 FRP 说明只用于历史对照。
- 当前 G14 runtime lane 入口由 G14 侧公开代理承担;不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。D601 legacy `16666/16667` 和 retired G14 DEV/PROD 端口的 FRP 说明只用于历史对照。
## HWLAB FRP 维护
HWLAB 公网 FRP server 由 master server 上的 `hwlab-frps-dev` 容器承担,容器使用 host network,并把 `/opt/hwlab-frp/frps.dev.toml` 只读挂载到 `/etc/frp/frps.toml`。这个 server 侧 allowlist 是 UniDesk 指挥侧维护对象,不属于 G14 k3s GitOps desired stateG14 侧 `frpc` ConfigMap/Deployment 只负责各 runtime namespace 的客户端 tunnel。
新增或恢复 HWLAB 公网入口时,先判断问题是否只是 server 侧 `allowPorts` 缺口。若 `frpc` 日志出现 `port not allowed`,优先在 master server 修改 `/opt/hwlab-frp/frps.dev.toml``allowPorts`,而不是改 DEV/PROD/v0.2 的 GitOps、Service 或 `frpc` ConfigMap。修改前保留一份本机备份,例如 `/opt/hwlab-frp/frps.dev.toml.bak-<reason>`;修改后只重启 `hwlab-frps-dev`,不要重建镜像、清理 Docker volume、重启无关 UniDesk/HWLAB 服务或触碰数据库状态。
新增或恢复 HWLAB 公网入口时,先判断问题是否只是 server 侧 `allowPorts` 缺口。若 `frpc` 日志出现 `port not allowed`,优先在 master server 修改 `/opt/hwlab-frp/frps.dev.toml``allowPorts`,而不是改 active runtime lane 的 GitOps、Service 或 `frpc` ConfigMap。修改前保留一份本机备份,例如 `/opt/hwlab-frp/frps.dev.toml.bak-<reason>`;修改后只重启 `hwlab-frps-dev`,不要重建镜像、清理 Docker volume、重启无关 UniDesk/HWLAB 服务或触碰数据库状态。
当前 HWLAB FRP server allowlist 至少应覆盖 legacy `16666/16667`、G14 DEV `17666/17667`、G14 PROD `18666/18667`G14 `v0.2` `19666/19667`,以及仍被明确使用的维护端口。新增端口必须对应一个明确的 namespace/runtime 入口,不能把大范围端口段作为默认放行策略。
当前 HWLAB FRP server allowlist 至少应覆盖 active runtime lane 端口(例如 G14 `v0.2` `19666/19667`)以及仍被明确使用的维护端口。Legacy `16666/16667` 和 retired G14 DEV/PROD `17666/17667``18666/18667` 只作为历史对照,不应作为新增 runtime 入口要求。新增端口必须对应一个明确的 namespace/runtime 入口,不能把大范围端口段作为默认放行策略。
FRP 维护验证顺序是:确认 `hwlab-frps-dev` 容器仍挂载 `/opt/hwlab-frp/frps.dev.toml`;重启后用 `ss -ltnp` 或等价只读命令确认 `frps` 正在监听 `7000` 和目标公网端口;再在目标 namespace 查看 `frpc` 日志,确认对应 proxy `start proxy success`;最后分别验证新增入口和既有 DEV 入口。`v0.2` 验证使用 `http://74.48.78.17:19666/``http://74.48.78.17:19667/health/live`DEV 回归验证使用 `http://74.48.78.17:17666/``http://74.48.78.17:17667/health/live`
FRP 维护验证顺序是:确认 `hwlab-frps-dev` 容器仍挂载 `/opt/hwlab-frp/frps.dev.toml`;重启后用 `ss -ltnp` 或等价只读命令确认 `frps` 正在监听 `7000` 和目标公网端口;再在目标 namespace 查看 `frpc` 日志,确认对应 proxy `start proxy success`;最后验证 active runtime lane 入口。`v0.2` 验证使用 `http://74.48.78.17:19666/``http://74.48.78.17:19667/health/live`
FRP 文档、issue 和日志只能记录端口、容器名、ConfigMap 名、Secret 对象/key 是否存在和健康摘要;不得记录 Secret value、provider token、完整 DB URL、Codex auth JSON 或其他凭据内容。
## 门禁最小化与扩容治理
不要滑向不必要的复杂门禁是 HWLAB 指挥侧通用原则。G14 DEV/PROD`v0.2` 扩容、CI/CD 迁移、运行面热修和文档治理都应优先靠固定边界、清晰命名、唯一真相源、标准入口和长期参考文档收敛,不要把每个设计约定、运行策略或回滚手册都做成新的 preflight、guard、gate 或报告生成器。
不要滑向不必要的复杂门禁是 HWLAB 指挥侧通用原则。Legacy G14 DEV/PROD 退役、runtime lane 扩容、CI/CD 迁移、运行面热修和文档治理都应优先靠固定边界、清晰命名、唯一真相源、标准入口和长期参考文档收敛,不要把每个设计约定、运行策略或回滚手册都做成新的 preflight、guard、gate 或报告生成器。
旧 DEV/D601/main 门禁如果阻碍当前 G14 或 `v0.2` 路径,默认处理是从当前调用链删除,而不是做兼容迁移、fallback、legacy mode、双路径绕行或在旧门禁上叠加例外。新增门禁只能覆盖明确高价值风险,且必须最小、低噪声、容易删除;资源配额、RBAC 命名、清理策略、回滚顺序、人工同步策略等默认是设计约定或 runbook,不是 CI/CD 通过条件。
`v0.2` 扩容时指挥侧只把以下内容视为硬边界:source branch 是 `v0.2`、CI/CD source repo 是 `G14:/root/hwlab-v02-cicd.git`、GitOps branch 是 `v0.2-gitops`、runtime namespace 是 `hwlab-v02`、runtime path 是 `deploy/gitops/g14/runtime-v02`、公网入口是 `19666/19667``v0.2` source branch 不跟踪生成物、旧 DEV/D601/main 门禁不进入 `v0.2` 调用链。`/root/hwlab-v02` 是人工开发和短连接源码工具 workspacedirty/stale 状态不得影响 CI/CD source commit 选择。其他事项应先作为决策表或 runbook 固化,只有被证明无法靠边界和标准入口自然收敛时,才允许加最小检查。
`v0.2` runtime lane 只把以下内容视为硬边界:source branch 是 `v0.2`、CI/CD source repo 是 `G14:/root/hwlab-v02-cicd.git`、GitOps branch 是 `v0.2-gitops`、runtime namespace 是 `hwlab-v02`、runtime path 是 `deploy/gitops/g14/runtime-v02`、公网入口是 `19666/19667``v0.2` source branch 不跟踪生成物、旧 DEV/D601/main 门禁不进入 `v0.2` 调用链。`/root/hwlab-v02` 是人工开发和短连接源码工具 workspacedirty/stale 状态不得影响 CI/CD source commit 选择。其他事项应先作为决策表或 runbook 固化,只有被证明无法靠边界和标准入口自然收敛时,才允许加最小检查。
## 最小 Device Agent/Gateway 桥接模型
最小打通目标是只新增桥接面,不改动既有 HWLAB 应用、GitOps、FRP、CD 或前端路径:
-`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`
-active G14 runtime lane 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 runtime lane cloud-api,例如 v0.2 的 `http://74.48.78.17:19667`,注册稳定的 `gatewaySessionId``resourceId``capabilityId`
- `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 的受控代理端口。
- D601 Windows gateway 的最小配置必须来自 profile 或环境变量,核心字段是 `HWLAB_GATEWAY_CLOUD_URL=<active-runtime-lane-cloud-api>``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 时优先使用目标 runtime lane 的 Service DNS,例如 `http://hwlab-cloud-api.hwlab-v02.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 镜像。
- 最小验收顺序是:G14 `hwlab-dev` cloud-api `/health/live` readyD601 Windows 能访问 `http://74.48.78.17:17667/health/live`D601 `hwlab-gateway` 注册后 cloud-api 能看到 gateway session/resource/capabilityG14 `device-agent-71-freq` `/health``/skills` 返回 ready;通过 device-agent 发起一条只读或 `echo` 级 gateway shell operation,并返回 operation/evidence/trace 摘要。
- 最小验收顺序是:active G14 runtime lane cloud-api `/health/live` readyD601 Windows 能访问该 lane 的 public `/health/live`D601 `hwlab-gateway` 注册后 cloud-api 能看到 gateway session/resource/capabilityG14 `device-agent-71-freq` `/health``/skills` 返回 ready;通过 device-agent 发起一条只读或 `echo` 级 gateway shell operation,并返回 operation/evidence/trace 摘要。
- 这个模型只证明 `device-agent Pod -> G14 cloud-api -> D601 hwlab-gateway -> Windows host` 的控制链路。Keil 编译下载、串口日志抓取和 workspace CRUD 可以作为后续 device-agent skill 子命令逐步接入;未接入前不能把 device-agent 标成完整 71-FREQ 硬件代理。
## Master Server 校验边界
- 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 路径执行,例如 `trans G14:/root/hwlab script -- ...``trans G14:k3s ...`,而不是直接在 `/root/unidesk` 或 master server 上本地运行。
- 需要正式验证时,固定切到目标 G14 runtime lane workspace、G14 k3s/Tekton、HWLAB repo-owned CI 或其他获批外部执行面;master server 只负责发起、观察和记录,不负责实际跑 check。
- 如果为了排障必须从 master server 生成命令或查看源码,后续验证命令也必须显式改到目标 G14 runtime lane 路径执行,例如 `trans G14:/root/hwlab-v02 script -- ...``trans G14:k3s ...`,而不是直接在 `/root/unidesk` 或 master server 上本地运行。
## G14 运行面与 D601 Legacy 口径
HWLAB 当前真实 DEV/PROD runtime 在 G14 原生 k3s 中。只读观察使用:
HWLAB 当前真实 runtime lane 在 G14 原生 k3s 中。只读观察使用:
```sh
trans G14:k3s kubectl -n hwlab-dev get deploy,svc,pod -o wide
trans G14:k3s kubectl -n hwlab-v02 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`
`hwlab-cloud-api``hwlab-edge-proxy` 在集群内使用 `6667` Service 端口,对外 v0.2 API 使用 `19667`。G14 local details 见 `docs/reference/g14.md` 和 G14 节点 `/root/docs/hwlab-g14-workspace.md`
D601 原生 k3s 口径只用于 legacy 对照、迁移排障或明确指定的 D601 回滚任务。此时必须显式使用:
@@ -124,7 +123,7 @@ profile 配置后的最小真实验收是通过同一 HWLAB v0.2 Cloud API/Web d
## D601 Legacy HWLAB DEV CD Wrapper
以下 UniDesk wrapper 是旧 D601 DEV CD 指挥入口,只用于显式 legacy 诊断和迁移对照。当前 G14 DEV/PROD 发布、GitOps 和运行面收敛必须优先按 G14 `/root/hwlab` 与 HWLAB repo-owned 规则执行;不要把下面的 D601 wrapper 当作当前 HWLAB release truth。
以下 UniDesk wrapper 是旧 D601 DEV CD 指挥入口,只用于显式 legacy 诊断和迁移对照。当前 HWLAB 发布、GitOps 和运行面收敛必须优先按 G14 active runtime lane 与 HWLAB repo-owned 规则执行;不要把下面的 D601 wrapper 当作当前 HWLAB release truth。
本节里的 `deploy/deploy.json` 只属于 D601 legacy DEV CD wrapper。当前 G14/v0.2 的单一人写部署配置源是 `deploy/deploy.yaml`,并由 HWLAB repo 的 format-agnostic config layer 读取;权威规则在 `docs/reference/g14.md#hwlab-v02-expansion-line`
@@ -172,7 +171,7 @@ node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production -
## D601 Legacy Cloud Web 手动 DEV 发布路径
以下路径是 D601 legacy DEV 的历史手动发布基准,只用于迁移对照或显式 D601 回滚排障。当前 G14 DEV/PROD 发布必须优先按 G14 `/root/hwlab`、G14 GitOps 和 HWLAB repo-owned 规则执行;不要把这里的 D601 命令当作当前发布入口。
以下路径是 D601 legacy DEV 的历史手动发布基准,只用于迁移对照或显式 D601 回滚排障。当前 HWLAB 发布必须优先按 G14 active runtime lane、G14 GitOps 和 HWLAB repo-owned 规则执行;不要把这里的 D601 命令当作当前发布入口。
1. 更新 D601 部署副本: