feat: 优化异地 artifact registry 拉取

docs/reference/platform-infra.md

@@ -172,6 +172,36 @@
   bun scripts/cli.ts platform-infra public-edge status --target NC01
   ```
 
+### 异地节点只读 Artifact Registry
+
+- NC01 集群内 registry 的内部 endpoint 是唯一写入 authority：
+  - CI、BuildKit 和 publish 继续使用内部 `127.0.0.1:5000` 语义；
+  - 公网 `registry.hwpod.com` 只用于异地 worker 拉取，不接受 push 或删除。
+- 公网入口归共享 public-edge 管理：
+  - hostname、DNS、upstream、允许方法和鉴权 SecretRef 来自集群 owning YAML；
+  - Caddy 只允许 `GET`、`HEAD`，其余方法返回拒绝；
+  - Basic Auth 只消费 SecretRef 中的用户名与 bcrypt hash，不把值写入 Git、计划输出或 Caddyfile；
+  - 可信 TLS 由 public-edge 管理，镜像层不得经过 CDN 代理。
+- worker containerd 归集群 CLI 管理：
+  - 既有 `127.0.0.1:5000/...` 镜像引用保持不变；
+  - `registries.yaml` 把该引用映射到 YAML 声明的公网 HTTPS endpoint；
+  - 用户名和密码只从同一 SecretRef 渲染；
+  - registry 配置单独变化时只重启 agent 使配置生效，不卸载或重装 k3s。
+- 受控入口：
+
+  ```bash
+  bun scripts/cli.ts platform-infra k3s-cluster registry-credential-init --target nc01-d601 --confirm
+  bun scripts/cli.ts platform-infra k3s-cluster apply --target nc01-d601 --confirm
+  bun scripts/cli.ts platform-infra k3s-cluster registry-smoke --target nc01-d601 --confirm
+  ```
+
+- `registry-smoke` 必须验证：
+  - 未鉴权拒绝、有效凭据、manifest digest、blob range 和写方法拒绝；
+  - YAML 选定的真实镜像冷拉取、并发拉取和重复拉取；
+  - 拉取期间 Kubernetes API 连通，前后 control-plane 与 worker 均为 Ready；
+  - Provider 控制通道能返回结构化终态；
+  - 结束后不保留临时 Kubernetes workload。
+
 ## Gitea 与 Pipelines-as-Code 边界
 
 - Gitea mirror 与 Pipelines-as-Code 是 UniDesk 运维的 CI source/trigger 服务。`config/platform-infra/gitea.yaml` 和 `config/platform-infra/pipelines-as-code.yaml` 分别拥有 mirror/webhook 与 PaC Repository/consumer 配置；repo URL、snapshot、webhook、public exposure、FRP/Caddy port、token sourceRef 和 PaC params 不得隐藏在代码特例中。