pikasTech-unidesk/docs/reference/hwlab.md

HWLAB 指挥侧参考

本文定义 UniDesk 指挥官推进 pikasTech/HWLAB 时的固定入口、workspace、上线口径和常见误判边界。HWLAB 的项目内操作细则以 HWLAB 仓库自己的 AGENTS.md 和 docs/reference/ 为准；本文只记录 UniDesk 侧如何进入和监督。

固定入口

• UniDesk 指挥侧 workspace：/root/unidesk，固定使用 master，开始前执行 git status 和 git pull --ff-only origin master。
• HWLAB 指挥侧 workspace：/workspace/hwlab，固定使用 main，开始前执行 git status 和 git pull --ff-only origin main。
• HWLAB 项目内长期规则入口：/workspace/hwlab/AGENTS.md。
• D601 HWLAB 运行副本：通过 bun scripts/cli.ts ssh D601 进入，优先使用 /home/ubuntu/workspace/hwlab；该目录是 D601 上的部署/构建副本，开始前也要 git -C /home/ubuntu/workspace/hwlab pull --ff-only origin main。
• D601 上 /home/ubuntu/hwlab 可能是 runner 或并行任务工作区。指挥官不能把它当作部署真相，也不能清理、reset 或复用其中的 runner worktree。

关键 GitHub 入口

• UniDesk 总看板：pikasTech/unidesk#20。
• HWLAB 总看板：pikasTech/HWLAB#7。
• HWLAB 上位会议/冻结规则：pikasTech/HWLAB#78，当前 P0 是 M3 虚拟硬件可信闭环。
• HWLAB Cloud Workbench 用户界面：pikasTech/HWLAB#99。
• HWLAB 用户反馈入口：pikasTech/HWLAB#108。
• HWLAB 手动发布复盘与自动化收敛：pikasTech/HWLAB#61。

pikasTech/unidesk#20 只记录 UniDesk 侧 commander、Code Queue、CLI 和 infra governance。HWLAB 用户反馈、Cloud Workbench、DEV-LIVE、M3 闭环和其他产品事项必须写入 pikasTech/HWLAB 的 issue；如果需要在 #20 出现，只能作为 UniDesk 侧调度、CLI guard、infra blocker 或验收治理 lane 的上下文，而不能作为 HWLAB 产品 row。

DEV 入口

• DEV 前端入口固定为 http://74.48.78.17:16666/。
• DEV API/live 入口固定为 http://74.48.78.17:16667/health/live。
• 旧公网 :6666 和 :6667 不是浏览器验收入口；内部 k3s service 仍可使用 6667 作为服务端口。
• 16666 由 master 侧 hwlab-frps-dev 接收 D601 hwlab-frpc 的反向代理流量；不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。

D601 k3s 口径

HWLAB 的真实 DEV runtime 在 D601 原生 k3s 中，必须显式使用：

KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev get deploy,svc,pod -o wide

不要直接相信默认 kubectl context。D601 上默认 context 可能是 docker-desktop，它会展示另一套与公网 16666/16667 无关的状态，并可能给出误导性的 ImagePullBackOff。

frpc 配置不是 D601 host /etc/frp/frpc.toml，而是 hwlab-dev namespace 里的 hwlab-frpc-config ConfigMap 和 hwlab-frpc Deployment。master 侧 frps 配置由 hwlab-frps-dev 容器挂载 /opt/hwlab-frp/frps.dev.toml。

UniDesk HWLAB DEV CD Wrapper

UniDesk 指挥侧固定入口：

bun scripts/cli.ts hwlab cd status --env dev
bun scripts/cli.ts hwlab cd audit --env dev
bun scripts/cli.ts hwlab cd preflight --env dev
bun scripts/cli.ts hwlab cd apply --env dev --dry-run

wrapper 的职责是把 host commander 常用的 HWLAB DEV rollout 查看/准备动作收敛到单一入口。默认路径通过 UniDesk main-server frontend/backend-core 的 provider host.ssh 能力进入 D601，再在 D601 上执行有界检查脚本；它只调用 HWLAB repo-owned 受控脚本，不在 UniDesk 内重写发布流程或拼接 ad hoc kubectl apply：

• 默认 HWLAB CD repo 是 D601 固定干净 mirror /home/ubuntu/hwlab_cd，也可用 --hwlab-repo 显式指定同等干净 clone。wrapper 必须检查 git status --short --branch、origin remote、当前 branch main、本地 origin/main、FETCH_HEAD 和 worktree 权限；任何 dirty worktree、错误 remote、非 main、HEAD 未跟上本地 origin/main 或权限异常都返回结构化 blocker。/home/ubuntu/hwlab 是 runner 历史目录，不得作为发布真相。
• deploy/deploy.json 是唯一 desired-state。wrapper 只把 deploy/artifact-catalog.dev.json、deploy/k8s/base/workloads.yaml 和 reports/dev-gate/dev-artifacts.json 当作派生/证据读数；status/preflight 必须显示 target commit/ref、deploy.json、artifact catalog、workloads 和 live workload image 是否同源/收敛，不引入第二套 desired state。
• status 只读汇总 HWLAB repo path、Git clean/main/origin-main、desired-state 收敛、D601 native k3s guard 和 Lease/hwlab-dev/hwlab-dev-cd-lock；同时调用 HWLAB scripts/dev-cd-apply.mjs --status --skip-live-verify 取得 repo-owned target/promotion/deploy.json/artifact 摘要。16666/16667 live verification 不由本 runner 执行。
• audit 是 DEV CD 恢复后的只读健康审计，不是验收 gate 或报告生成器。它在 status 受控路径上补充只读 kubectl get/HTTP health probes，输出有界 JSON summary，分类 control-plane-unavailable、docker-desktop-context-risk、second-control-plane-risk、workspace-unavailable、dirty-worktree、secret-missing、registry-unavailable、lease-held、lease-stale-candidate、artifact-missing、artifact-mismatch、runtime-job-blocked、rollout-unhealthy、public-tunnel-unhealthy 和 db-runtime-durability-risk。audit 只显示 Secret 对象/key 是否存在，不显示值；只读判断 Lease 是否 stale，不释放或 break；只读拉取 16666/16667 /health/live 的 commit/readiness 摘要，不把它当作 M3 DEV-LIVE 验收。
• preflight 在 status 的基础上检查 apply 前 SecretRef：hwlab-cloud-api-dev-db/database-url、hwlab-cloud-api-dev-db-admin/admin-url、hwlab-code-agent-provider/openai-api-key。只验证 Secret 对象和 key 元数据存在性，缺失时返回 blocker、影响范围和修复 runbook；禁止读取或打印 Secret value。
• apply --dry-run 调用 HWLAB scripts/dev-cd-apply.mjs --dry-run --kubeconfig /etc/rancher/k3s/k3s.yaml --skip-live-verify，只生成受控事务准备/阻塞摘要，不做真实 apply、rollout、Lease mutation 或 live verification。历史 scripts/dev-deploy-apply.mjs 可作为 HWLAB 内部支持脚本出现，但 UniDesk wrapper 不能把它当成平行 CD 入口。
• 完整下游 stdout/stderr 和 kubectl 读命令输出写入 D601 ~/.state/unidesk-hwlab-cd/<run-id>/，UniDesk 本地仅保存 provider task stdout/stderr dump；CLI stdout 只显示有界摘要和 dump path。
• wrapper 显式注入 KUBECONFIG=/etc/rancher/k3s/k3s.yaml 并以这个显式目标作为唯一 gate：目标 context/server/nodes 若出现 docker-desktop、desktop-control-plane 或 127.0.0.1:11700 必须拒绝继续，写操作计划或 apply --dry-run 前目标 nodes 必须包含 d601。裸 kubectl 默认 context 只作为诊断输出；即使默认 kubeconfig 仍残留 Docker Desktop，只要显式 D601 kubeconfig 通过，也不能把默认 context 当成 CD blocker。

真实 DEV apply 只允许 host commander 在明确授权后执行。UniDesk wrapper 可以展示受控命令形状：

node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report --kubeconfig /etc/rancher/k3s/k3s.yaml

本 Code Queue runner 没有 ROLLOUT_OK 时不得执行真实 apply、rollout、CD lock 竞争或 live health 复验。

HWLAB 热修边界

当 HWLAB DEV runtime 的 Secret、环境变量、rollout、DNS、egress 或 provider 权限缺口阻塞业务闭环，并且 Code Queue runner 无法安全完成对应运行态操作时，UniDesk 指挥官只能承担指挥入口、授权确认、监督验收和误判边界收敛。UniDesk reference 可以记录“哪些状态不能被误判”和“哪些动作必须上收”，但不能成为 HWLAB runtime truth。

这类热修必须满足以下边界：

• 先确认用户或项目负责人已授权具体运行态修复范围；没有授权时只做只读诊断、issue 记录和修复方案准备。
• 证据只记录对象名、状态、revision、健康结果和已脱敏差异；不得把 Secret 值、token、可复用凭证命令或完整敏感 env 输出写入 issue、PR、日志或文档。
• live Secret、env、ConfigMap、Deployment patch 或 rollout 结果只能作为临时恢复证据，不能成为长期部署真相。
• HWLAB runtime truth 必须回写到 HWLAB 仓库自己的 issue、AGENTS.md、docs/reference/、部署配置或 secret 管理入口；UniDesk 只保留指挥侧边界和交叉引用。
• 热修后必须说明 durable source fix 如何进入 HWLAB 的 CLI、manifest、deploy/deploy.json 或等价发布路径；如果尚未完成，要保留 HWLAB issue 追踪。

已验证的 Cloud Web 手动 DEV 发布路径

当只需要发布 hwlab-cloud-web 到 DEV 时，使用以下路径；它是当前手动 CD 的基准，后续自动化应收敛到 HWLAB deploy/deploy.json 和 CLI，而不是重新发明路径。

1. 更新 D601 部署副本：

bun scripts/cli.ts ssh D601 'cd /home/ubuntu/workspace/hwlab && git pull --ff-only origin main'

2. 刷新 Cloud Web 静态构建产物。运行时 wrapper 优先读取 web/hwlab-cloud-web/dist，如果该目录残留旧内容，即使源码已经更新，镜像仍可能继续服务旧页面：

bun scripts/cli.ts ssh D601 'cd /home/ubuntu/workspace/hwlab && node web/hwlab-cloud-web/scripts/build.mjs'

3. 发布镜像到 D601 本地 registry：

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'

4. 在滚动前用一次本地容器探针确认镜像内容，不把 commit tag 等同于页面内容：

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'

5. 滚动 D601 原生 k3s：

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'

6. 用公网入口验收：

curl -fsS http://74.48.78.17:16666/health/live
curl -fsS http://74.48.78.17:16666/ | sed -n '1,80p'
curl -fsS http://74.48.78.17:16666/styles.css | rg 'overflow: hidden|100dvh'

验收时必须同时看 health/live 的 revision、HTML 语言/标题和 CSS 外层滚动锁定。不能只看镜像 tag 或 deployment 镜像字段。

监督原则

• HWLAB 派单 prompt 必须自包含，并在开头引用 DC-DCSN-P0-2026-003，说明任务服务 M3 闭环的哪一环。
• SOURCE、LOCAL、DRY-RUN、fixture 或只读报告不能被当作 DEV-LIVE。真正的 M3 DEV-LIVE 需要证明 res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1 并带有 operation、audit、evidence 链。
• 前端体验、Cloud Workbench polish、Gate 页面、诊断页和发布路径修复都是支撑任务，不等同于 M3 PASS。
• 指挥官可以手动处理 PR 冲突和最终合并判断；runner 不应承担复杂冲突合并。
• 任何临时手动上线或绕行都要回写 HWLAB issue 与 HWLAB 长期参考文档，并标明后续如何收敛到 CLI 和 deploy/deploy.json。
• HWLAB Secret/env/rollout 热修按本文“HWLAB 热修边界”和 docs/reference/devops-hygiene.md 执行；UniDesk 侧只沉淀边界，HWLAB 侧沉淀运行真相。