Merge pull request #2707 from pikasTech/docs/hwlab-runtime-package-registry

固化 HWLAB 启动依赖诊断边界

docs/reference/hwlab.md

@@ -328,6 +328,14 @@ trans NC01:k3s kubectl -n hwlab-v03 get deploy,svc,pod -o wide
 
 HWLAB node/lane 的 PipelineRun 失败定位优先使用 `bun scripts/cli.ts hwlab nodes control-plane status --node <node> --lane <lane> --pipeline-run <name>`、PaC `status|history` 和返回的 bounded TaskRun/Pod logs 下钻，而不是手工拼查询。PaC 或 `unknown` authority 的失败态不得给 trigger、refresh、mirror sync/flush 或 rerun；应由只读证据定位 owning YAML、controller 或源码缺陷，再用修复 PR 合并产生的新自动事件验收。默认状态不得打印完整 pod 日志、Secret、DSN、API key 或其他可复制凭据。
 
+- Cloud Web 启动阶段依赖安装或静态资产构建卡住时：
+  - 先区分 startup probe 预算耗尽与依赖下载无进展；
+  - 在目标 Pod 内一次核对有效 package registry、proxy 和目标 registry 可达性；
+  - registry 可用但镜像默认配置失效时，只在选中服务和 lane 的 owning YAML 中声明 service-level registry 覆盖；
+  - 禁止修改共享镜像配置、其他业务 Pod、共享代理或继续提高 probe 预算来掩盖下载停滞；
+  - service-level 覆盖只用于恢复当前声明式交付，长期目标仍是把锁文件依赖和静态资产构建进镜像，运行时不再执行依赖安装或前端构建；
+  - 长期改造涉及制品边界变化时必须由 TaskTree 独立跟踪，不能夹带在运行面恢复 PR 中。
+
 `hwlab-cloud-api` 和 `hwlab-edge-proxy` 在集群内可使用 `6667` Service 端口；对外入口以 NC01 target 的 publicExposure/public URL 为准。Node/Bun/undici 的 Fetch 实现会按 Fetch bad-port 规则拒绝 `6667`，因此任何需要代理、转发、探测或服务间访问该端口的 Node 实现都必须使用 `node:http`/`node:https`、已有 repo-owned HTTP helper，或改用不触发 bad-port 的受控代理端口；不要把 Fetch bad-port 造成的 `fetch failed` / 502 误判为 Service DNS、PVC、数据库或 trace 数据缺失。NC01 target 以 `config/hwlab-node-lanes.yaml` 的 `nodes.NC01` 和 `lanes.v03.targets.NC01` 为准。
 
 NC01 k3s 是 HWLAB 当前正式控制面。任何 HWLAB k3s 操作都必须显式使用 UniDesk route `NC01:k3s` 或等价的 NC01 kubeconfig，不能使用裸默认 kubeconfig：