feat(cli): add D601 artifact registry planning
Add a first-stage artifact-registry CLI for D601 host-managed CNCF Distribution planning, rendering, dry-run install, and readonly status checks. Document the loopback-only boundary and future backend-core artifact CD flow.\n\nCloses #1.
This commit is contained in:
Codex
@@ -0,0 +1,107 @@
|
||||
# D601 Artifact Registry
|
||||
|
||||
D601 artifact registry 是为 backend-core 轻量 CD 准备的本地镜像制品入口。它使用开源、成熟的 CNCF Distribution Docker registry，不自定义镜像协议，也不把镜像托管到第三方服务。
|
||||
|
||||
第一阶段只提供声明、渲染、dry-run install 和只读状态检查；不会安装、启动或替换任何生产服务。backend-core 现有生产部署路径保持不变。
|
||||
|
||||
## Architecture
|
||||
|
||||
registry 运行在 D601 host/WSL OS 上，由 systemd 管理 Docker Compose 项目：
|
||||
|
||||
- systemd unit：`unidesk-artifact-registry.service`
|
||||
- Compose project：`unidesk-artifact-registry`
|
||||
- container：`unidesk-artifact-registry`
|
||||
- image：`registry:2.8.3`
|
||||
- config：`/home/ubuntu/.unidesk/artifact-registry/config.yml`
|
||||
- compose：`/home/ubuntu/.unidesk/artifact-registry/compose.yml`
|
||||
- storage：`/home/ubuntu/.unidesk/registry-storage`
|
||||
- endpoint：`http://127.0.0.1:5000`
|
||||
|
||||
它不是 k3s workload，不使用 NodePort、hostPort、LoadBalancer 或公开端口。Docker 端口映射必须绑定到 D601 loopback：`127.0.0.1:5000:5000`。容器内部 registry 可监听 `:5000`，安全边界由 host loopback 绑定保证。
|
||||
|
||||
这个服务和 `k3sctl-adapter` 一样位于 k3s 故障域外，但职责不同：
|
||||
|
||||
- `k3sctl-adapter` 是 UniDesk 到 native k3s 的控制桥，属于 UniDesk 直管服务。
|
||||
- artifact registry 是 D601 host-managed 制品缓存基础设施，后续服务 CD 会使用它拉取或推送 commit-pinned 镜像。
|
||||
|
||||
## Dependency Boundary
|
||||
|
||||
registry 运行期依赖应保持低且可手动维护：
|
||||
|
||||
- D601 host Docker Engine。
|
||||
- Docker Compose plugin。
|
||||
- systemd。
|
||||
- `registry:2.8.3` 镜像，后续可升级为 digest pin。
|
||||
- D601 本地持久化目录。
|
||||
- provider-gateway Host SSH 只用于 UniDesk CLI 的只读 `status` / `health` 检查。
|
||||
|
||||
它不得依赖：
|
||||
|
||||
- k3s 控制面或任意 k3s namespace。
|
||||
- 第三方镜像托管服务作为 backend-core artifact source of truth。
|
||||
- main server backend-core 本地 Rust 编译。
|
||||
- 公开 registry 端口或公网反向代理。
|
||||
|
||||
## CLI
|
||||
|
||||
入口是：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts artifact-registry plan
|
||||
bun scripts/cli.ts artifact-registry render
|
||||
bun scripts/cli.ts artifact-registry install --dry-run
|
||||
bun scripts/cli.ts artifact-registry status
|
||||
bun scripts/cli.ts artifact-registry health
|
||||
```
|
||||
|
||||
`plan` 输出架构边界、依赖项、默认路径和未来 backend-core artifact CD 流程。`render` 输出 systemd unit、Compose 文件和 registry config 的完整内容与 SHA-256。`install --dry-run` 只列出将来要执行的远端动作，不写 D601 文件、不启动容器、不 reload systemd。
|
||||
|
||||
第一阶段 `install` 不带 `--dry-run` 必须失败。启用真实安装前，需要单独评审并补齐幂等写入、配置 hash 比对、回滚/停止策略和验收门禁。
|
||||
|
||||
`status` 和 `health` 通过：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts ssh D601 argv bash -lc '<readonly script>'
|
||||
```
|
||||
|
||||
只读检查 D601 状态。检查项包括：
|
||||
|
||||
- systemd unit 是否存在、active、enabled。
|
||||
- Docker 是否可用，registry container 是否 running。
|
||||
- host 端口是否只监听 `127.0.0.1:5000` 或 `[::1]:5000`。
|
||||
- `curl http://127.0.0.1:5000/v2/` 是否返回 200。
|
||||
- storage 目录是否存在。
|
||||
- 远端 config、compose、unit 的 hash 是否匹配 CLI 渲染结果。
|
||||
- 运行镜像是否匹配期望版本。
|
||||
|
||||
`status` 表示只读查询是否成功；未安装时仍可 `ok=true` 并报告 `installed=false`。`health` 表示 registry 是否已按期望运行；未安装或不健康时返回 `ok=false`。
|
||||
|
||||
## Manual Maintenance
|
||||
|
||||
服务采用 systemd + Docker Compose 管理，目的是让 D601 host 管理员可以用标准工具维护：
|
||||
|
||||
```bash
|
||||
systemctl status unidesk-artifact-registry.service
|
||||
systemctl restart unidesk-artifact-registry.service
|
||||
docker compose -p unidesk-artifact-registry -f /home/ubuntu/.unidesk/artifact-registry/compose.yml ps
|
||||
```
|
||||
|
||||
手动维护必须遵守 Git-backed deployment truth：运行态可以临时修复，但长期配置应回到 `artifact-registry render` 的声明文件和本文档。若 D601 runtime 文件 hash 与 CLI 渲染结果不一致，`status` / `health` 会显示 mismatch，操作者需要确认这是受控升级还是漂移。
|
||||
|
||||
## Future Backend-Core Artifact CD
|
||||
|
||||
目标流程是：
|
||||
|
||||
1. D601 CI/dev execution 在 D601 构建 `unidesk/backend-core:<commit>`。
|
||||
2. 构建产物 push 到 D601 loopback registry。
|
||||
3. main server 通过受控、短生命周期的 localhost relay 从 D601 registry 拉取 commit-pinned 镜像。
|
||||
4. main server retag 后替换 backend-core Compose 服务。
|
||||
5. 部署后通过 image label、runtime env、health payload 验证 live commit。
|
||||
|
||||
这个未来 CD 路径仍必须满足：
|
||||
|
||||
- source commit 来自 pushed Git，不来自 dirty worktree。
|
||||
- 镜像 tag 必须 commit-pinned，不能用 mutable latest 作为部署真相。
|
||||
- relay 是临时控制动作，不开放长期公网 registry。
|
||||
- CI 可以有较多依赖；CD 只做拉取、retag、recreate 和 live commit 验证。
|
||||
- `server rebuild backend-core` 仍不得作为 master server Rust 编译路径。
|
||||
@@ -26,6 +26,7 @@ UniDesk 的统一 CLI 入口是根目录 `scripts/cli.ts`，运行方式固定
|
||||
- `deploy check/plan/apply` 默认从根目录 `deploy.json` 读取服务 repo 与 commit 期望状态，join `config.json` 和现有 manifest 后使用 target-side build 单一路径校验或更新已支持目标；`deploy plan --env dev|prod` 只从 `origin/master:deploy.json#environments.<env>` 读取 manifest 并输出 dry-run 环境计划，不使用本地 dirty worktree；当前 `deploy apply --env dev` 只支持 D601 `backend-core` 与 `frontend` persistent dev rollout，dev desired-state smoke 使用 `ci run-dev-e2e`；规则见 `docs/reference/deploy.md`、`docs/reference/dev-environment.md` 和 `docs/reference/dev-ci-runner.md`。
|
||||
- `dev-env validate [--manifest path] [--kubectl-dry-run]` 离线校验 D601 `unidesk-dev` namespace、dev PostgreSQL 底座和 dev workload manifest。默认检查 `src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-foundation.k8s.yaml`；也可显式校验 `src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-core.k8s.yaml` 或 `src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-code-queue.k8s.yaml`。所有 namespaced 对象必须只落到 `unidesk-dev`，foundation manifest 必须包含 `postgres-dev` StatefulSet/Service、dev secret/config、迁移 Job 和 DB URL guard，core manifest 必须包含 `backend-core-dev`/`frontend-dev` Deployment/Service，Code Queue dev manifest 必须包含 `code-queue-scheduler-dev`、`code-queue-read-dev`、`code-queue-write-dev` 和 dev provider egress proxy。加 `--kubectl-dry-run` 时额外执行 `kubectl apply --dry-run=client --validate=false -f <manifest>`，仍不 apply 资源。
|
||||
- `dev-env prewarm-images [--image image] [--provider-id D601] [--no-pull] [--proxy-url URL] [--pull-timeout-ms N] [--dry-run]` 创建异步 job，通过 UniDesk SSH 维护桥在 D601 上把开发底座依赖镜像从 Docker 缓存导入原生 k3s containerd。默认镜像是 `postgres:16-alpine` 和 `rancher/mirrored-library-busybox:1.36.1`，用于避免 `postgres-dev` 与 local-path helper pod 卡在外部 registry 拉取。该命令固定验证 `/etc/rancher/k3s/k3s.yaml` 指向的 native k3s 上下文，并输出 `dev_env_containerd_image_ready=...` 作为成功判据；它不 apply manifest、不修改生产 `unidesk` namespace。
|
||||
- `artifact-registry plan|render|status|health|install --dry-run` 管理 D601 host-managed CNCF Distribution registry 的声明和只读检查。该 registry 固定为 D601 loopback `127.0.0.1:5000`，由 systemd + Docker Compose 管理，位于 native k3s 故障域外；第一阶段只允许渲染和 dry-run install，不写 D601 runtime，不改变 backend-core 生产部署路径。长期规则见 `docs/reference/artifact-registry.md`。
|
||||
- `ci install|status|run|run-dev-e2e|logs` 管理 D601 原生 k3s 上的 Tekton CI。`run` 手动创建每 commit 检查和 Code Queue 只读性能门禁；`run-dev-e2e` 的 Git 控制 runner、短 launcher、host fetch 边界、临时 smoke namespace 和 no-CD 规则只在 `docs/reference/dev-ci-runner.md` 定义；Tekton CI 通用规则见 `docs/reference/ci.md`。
|
||||
- `codex deploy <commitId>` 是旧 Code Queue 兼容部署入口，已禁用以防止维护通道直连 D601 部署 Code Queue；当前 dev 自动化只做 `ci run-dev-e2e` smoke，不提供 Code Queue CD，详细规则见 `docs/reference/codex-deploy.md`。
|
||||
- `codex submit [prompt] [--prompt-file path|--prompt-stdin] [--queue queueId] [--provider-id id] [--cwd path] [--model model] [--reasoning-effort effort] [--execution-mode mode] [--max-attempts N] [--reference-task-id id] [--dry-run]` 通过 backend-core 私有代理向稳定 `code-queue` 用户服务路径提交任务；prompt 必须且只能来自位置参数、文件或 stdin 之一，`--dry-run` 只返回结构化请求且不实际入队。提交确认和 dry-run 必须返回完整 prompt、字符数和 `truncated=false`，不能套用任务详情的预览截断策略，否则长任务 prompt 无法被人工验收。backend-core 默认把提交、队列 CRUD、已读状态、历史摘要和轻量 Trace 读取分流到主 server `code-queue-mgr`，由它写入主 PostgreSQL；D601 scheduler 只轮询并执行已入库任务。
|
||||
|
||||
Reference in New Issue
Block a user