mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8decc7d1877d4f57467d0cb5df890a8033aef716
pikasTech-unidesk/docs/reference/hwlab.md
T

31 KiB
Raw Blame History

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 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 固定 namespace 为 hwlab-v03，公网入口为 http://74.48.78.17:20666/ 与 http://74.48.78.17:20667/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 runtime lane 规则冲突时，以 G14 runtime lane 规则为准。
  • /root/HWLAB、/workspace/hwlab、D601 workspace、master-server checkout 或临时 clone 都不能作为 G14:HWLAB source truth。

关键 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 入口

  • 退役 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 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 state；G14 侧 frpc ConfigMap/Deployment 只负责各 runtime namespace 的客户端 tunnel。

新增或恢复 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 至少应覆盖 active runtime lane 端口（例如 G14 v0.2 19666/19667 和 v0.3 20666/20667）以及仍被明确使用的维护端口。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；最后验证 active runtime lane 入口。v0.2 验证使用 http://74.48.78.17:19666/ 与 http://74.48.78.17:19667/health/live；v0.3 验证使用 http://74.48.78.17:20666/ 与 http://74.48.78.17:20667/health/live。

FRP 文档、issue 和日志只能记录端口、容器名、ConfigMap 名、Secret 对象/key 是否存在和健康摘要；不得记录 Secret value、provider token、完整 DB URL、Codex auth JSON 或其他凭据内容。

门禁最小化与扩容治理

不要滑向不必要的复杂门禁是 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 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 是人工开发和短连接源码工具 workspace，dirty/stale 状态不得影响 CI/CD source commit 选择。其他事项应先作为决策表或 runbook 固化，只有被证明无法靠边界和标准入口自然收敛时，才允许加最小检查。

最小 Device Agent/Gateway 桥接模型

最小打通目标是只新增桥接面，不改动既有 HWLAB 应用、GitOps、FRP、CD 或前端路径：

  • 在 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=<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 镜像。
  • 最小验收顺序是：active G14 runtime lane cloud-api /health/live ready；D601 Windows 能访问该 lane 的 public /health/live；D601 hwlab-gateway 注册后 cloud-api 能看到 gateway session/resource/capability；G14 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 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 当前真实 runtime lane 在 G14 原生 k3s 中。只读观察使用：

trans G14:k3s kubectl -n hwlab-v02 get deploy,svc,pod -o wide

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 回滚任务。此时必须显式使用：

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

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

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

Code Agent 模型通道

HWLAB 的 DeepSeek/Codex 兼容性属于 HWLAB runtime 规则，长期真相在 HWLAB 仓库 AGENTS.md 和 docs/reference/g14-gitops-cicd.md。UniDesk 指挥侧只保留监督边界：诊断这类问题时，先在 G14 目标 Pod 或临时 passthrough Pod 内闭环证明 Codex stdio、Responses 请求、tool call/tool result 顺序、模型目录和真实 provider 返回，再考虑 GitOps/CI/CD；不要用完整 CI/CD 作为每轮协议试错工具。

DeepSeek profile 应优先使用成熟 Responses/Anthropic 协议桥接方案，例如 Moon Bridge，来保留 prompt cache、tool-result 顺序和模型目录语义。HWLAB repo-owned compatibility bridge 只能承担薄层职责，例如 Codex zstd request body 解码、非 function tool 过滤、/v1/models 或 readiness 适配；不要在 UniDesk 或 HWLAB 中手写完整 Responses-to-Chat 转换器替代成熟桥接层。Secret 值、provider token 和完整模型请求正文不得写入 UniDesk 文档、issue 或日志。

HWLAB 与 AgentRun 协同修复必须按 docs/reference/agentrun.md 的职责边界执行：AgentRun 拥有的共享执行、trace/result、backend event、runner 和 CLI 能力缺失时改 AgentRun；HWLAB 拥有的鉴权、Cloud Web/CLI 对外 API、adapter 消费、业务和前端问题改 HWLAB。不得用一侧的观测、fallback 或兼容逻辑迁就另一侧未实现或未修复的能力。

Code Agent Provider Profile 配置与验收

本小节是 UniDesk 指挥侧对 HWLAB v0.2 Code Agent provider profile 配置、凭证写入和真实验收的唯一长期出处。G14 节点参考、CLI 参考和 hwlab-code-agent skill 只交叉引用这里；AgentRun 内部 Secret 物化和 backend adapter 设计仍以 AgentRun 仓库自身为准。

HWLAB v0.2 provider profile 必须通过已部署的 HWLAB Cloud API/CLI 管理，正式入口是 hwlab-cli client provider-profiles。不要把手工 patch agentrun-v01 Secret、直接调用 AgentRun manager 或临时 runner job 当作正式配置路径或关闭证据；这些只可作为基础设施定位证据。标准执行面是 G14:/root/hwlab-v02，调用前锁定 HWLAB_RUNTIME_NAMESPACE=hwlab-v02、HWLAB_RUNTIME_WEB_URL=http://74.48.78.17:19666 和 HWLAB_RUNTIME_ENDPOINT_LOCKED=1，HWLAB_API_KEY 从 /root/.config/hwlab-v02/master-server-admin-api-key.env 加载。

当明确需要把当前 operator 的 Codex 凭据作为 AgentRun 动态 profile 提供给 HWLAB Code Agent 或 CaseRun 使用时，固定操作手册在 $hwlab-code-agent 的 AgentRun 动态 sub2api profile 小节。该场景是 AgentRun runtime profile 投影，不替代上面的 HWLAB provider-profiles 正式配置路径；默认 profile 名为 sub2api、模型为 gpt-5.5，优先使用 G14 k3s 内 Sub2API ClusterIP 作为 base_url，并只记录 SecretRef、keyPresence、hash suffix 和原入口验收结果。

config.toml 和 Codex auth.json 是两个独立输入。set-config <profile> --config-stdin 写入 profile 的 Codex 配置文本；set-auth-json <profile> --auth-json-stdin 写入完整 Codex auth JSON object，并在 AgentRun runtime Secret 中作为 auth.json key 保留。set-key --key-stdin 只用于单值 API key profile；当输入本来就是 Codex auth.json 时，不得再把它压扁、拆成单个 key、改走 legacy API-key-only 路径或保留旧断言阻塞提交。遇到 CLI 不支持完整 auth JSON、输出不可见或缺少 hash/keyPresence 等证据时，先补 HWLAB CLI/API 和 AgentRun provider-profile 能力，再继续试机。

标准命令形态如下，文件名可按实际 profile 替换：

bun tools/hwlab-cli/bin/hwlab-cli.ts client provider-profiles set-config <profile> --config-stdin --no-session < config.toml
bun tools/hwlab-cli/bin/hwlab-cli.ts client provider-profiles set-auth-json <profile> --auth-json-stdin --no-session < auth.json
bun tools/hwlab-cli/bin/hwlab-cli.ts client provider-profiles list --no-session

AgentRun v0.1 运行面物化对象是 agentrun-v01 namespace 中的 agentrun-v01-provider-<profile> Secret。基础 Codex profile 的稳定 key 是 config.toml 和 auth.json；需要本地模型目录的 profile 还必须按 AgentRun backend profile 声明补齐额外 key，例如 dsflash-go 必须同时具备 model-catalog.json，且 config.toml 中的 model_catalog_json 指向 runner 内 profile-local catalog 路径。文档、issue、trace 和 CLI 输出只能记录 profile 名、SecretRef、key 是否存在、字节数、redacted hash/hash suffix、resourceVersion 和验证结果；不得记录 Secret value、完整 auth.json、provider token、完整 API key 或可复用凭据命令。

profile 配置后的最小真实验收是通过同一 HWLAB v0.2 Cloud API/Web dispatcher 路径创建 Code Agent session 并完成一轮真实 turn：client agent session create --provider-profile <profile>，再 client agent send --session-id <sessionId> --provider-profile <profile>，最后用 client agent result <traceId> 和 client agent trace <traceId> --render web 确认终端状态和最终 assistant 文本。只看到 Secret 存在、AgentRun canary 通过、PipelineRun 成功或源码测试通过，都不能替代这一真实入口验收。对 profile-sensitive CaseRun 或 provider 修复，关闭证据还必须来自原入口 case run/Web 等价路径，结果中应同时显示 requestedProviderProfile、resolvedBackendProfile、AgentRun backendProfile、模型名和终端状态；涉及 ds-flash/Moon Bridge 时，还要确认 deepseek-v4-flash、1M context/model catalog 元数据生效，且归档中不再出现 responses/compact 404 或 404 page not found。当前 HY 凭据对的稳定 profile 名是 hy；复测时使用同一标准入口，不在任何长期文档或 issue 中记录凭据内容。

D601 Legacy HWLAB DEV CD Wrapper

以下 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。

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；frontend transport 先用多个短 host.ssh 命令把远端 runner 分块上传到 /tmp/unidesk-hwlab-cd/，再在 D601 上执行有界检查脚本，避免 provider-gateway 的短命令长度限制成为审计入口单点故障。经 frontend/backend-core 返回的 stdout 只允许承载短 JSON 摘要；完整结果必须写入 D601 ~/.state/unidesk-hwlab-cd/<run-id>/result.full.json，防止 backend JSON 安全摘要把 stdout 截断后导致 CLI 失明。它只调用 HWLAB repo-owned 受控脚本，不在 UniDesk 内重写发布流程或拼接 ad hoc kubectl apply：

  • 默认 HWLAB CD repo 是每次运行在 D601 ~/.state/unidesk-hwlab-cd/<run-id>/ephemeral-repo/HWLAB 新建的一次性 clone。一次性 repo 只从专用 full bare cache ~/.cache/unidesk/hwlab-cd/git-cache/HWLAB.git 拷贝生成，必须使用 --no-hardlinks 形成独立 .git 对象库，不能通过 --shared 或 alternates 在运行时依赖 cache 对象库。cache 本身只允许作为 HWLAB CD 专用 Git 加速源，不承载 runner workspace、部署副本、手工改代码、报告留痕或任何其他用途。
  • 专用 cache 由当前 host.ssh 执行用户拥有，~/.cache/unidesk/hwlab-cd 必须保持 owner-only 权限；owner 不匹配、不可写或权限收紧失败时返回结构化 blocker。cache 初始化可以从本机已有 HWLAB clone seed 一次性拷贝，但 seed 只能用于降低首次出网成本，不能作为 release truth。cache remote 固定优先 git@github.com:pikasTech/HWLAB.git，GitHub 出网通过 D601 provider egress proxy 127.0.0.1:18789 和 SSH ProxyCommand。cache 必须保存 full bare repo 历史，而不是 depth=1 浅缓存；wrapper 需要能解析 refs/heads/main:deploy/deploy.json 指向的 promotion commit，浅缓存即使 main HEAD 一致也不能证明 CD desired-state 完整。若 GitHub refresh 失败但本地 full cache 同时满足 main HEAD 和 deploy promotion commit，可作为 stale-cache 诊断继续读数，但必须暴露 hwlab-cache-refresh blocker，不能伪装成 release-truth PASS。
  • 一次性 repo 是当前 host.ssh 执行用户创建的临时发布读数，避免长期 /home/ubuntu/hwlab_cd 被 root 或其他 runner owner 污染后成为 CD 单点故障。--hwlab-repo 或 UNIDESK_HWLAB_REPO 仍可显式指定同等干净 clone 供人工诊断；被指定的 clone 必须由执行用户拥有并可读写。root-owned 或其他用户拥有的 clone 会触发 Git dubious ownership、FETCH_HEAD 不可写和 .git/worktrees 权限 blocker。修复 owner 污染应重建或显式修正 mirror 权限，不能用 git config --global safe.directory 掩盖发布真相污染。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、当前 G14/v0.2 deploy/deploy.yaml、显式 D601 legacy deploy/deploy.json 或等价发布路径；如果尚未完成，要保留 HWLAB issue 追踪。

D601 Legacy Cloud Web 手动 DEV 发布路径

以下路径是 D601 legacy DEV 的历史手动发布基准，只用于迁移对照或显式 D601 回滚排障。当前 HWLAB 发布必须优先按 G14 active runtime lane、G14 GitOps 和 HWLAB repo-owned 规则执行；不要把这里的 D601 命令当作当前发布入口。

  1. 更新 D601 部署副本：
trans D601 'cd /home/ubuntu/workspace/hwlab && git pull --ff-only origin main'
  1. 刷新 Cloud Web 静态构建产物。运行时 wrapper 优先读取 web/hwlab-cloud-web/dist，如果该目录残留旧内容，即使源码已经更新，镜像仍可能继续服务旧页面：
trans D601 'cd /home/ubuntu/workspace/hwlab && node web/hwlab-cloud-web/scripts/build.mjs'
  1. 发布镜像到 D601 本地 registry：
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'
  1. 在滚动前用一次本地容器探针确认镜像内容，不把 commit tag 等同于页面内容：
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'
  1. 滚动 D601 原生 k3s：
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'
  1. 用公网入口验收：
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、当前 G14/v0.2 deploy/deploy.yaml、显式 D601 legacy deploy/deploy.json 或等价发布路径。
  • HWLAB Secret/env/rollout 热修按本文“HWLAB 热修边界”和 docs/reference/devops-hygiene.md 执行；UniDesk 侧只沉淀边界，HWLAB 侧沉淀运行真相。
Reference in New Issue View Git Blame Copy Permalink