Codex
115 lines
6.3 KiB
Markdown
115 lines
6.3 KiB
Markdown
# D601 Artifact Registry
|
||
|
||
D601 artifact registry 是为 backend-core 轻量 CD 准备的本地镜像制品入口。它使用开源、成熟的 CNCF Distribution Docker registry，不自定义镜像协议，也不把镜像托管到第三方服务。
|
||
|
||
backend-core 的长期分工是：CI 在 D601 构建并发布 commit-pinned 镜像，CD 在 master server 只拉取、替换和验证该镜像。registry 是这条链路的本地制品缓存，不是构建编排器，也不是生产部署控制面。
|
||
|
||
## 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 制品缓存基础设施，D601 CI 向它推送 commit-pinned 镜像，master server CD 从它消费镜像。
|
||
|
||
## 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 端口或公网反向代理。
|
||
- k3s Service、NodePort、Ingress 或任何长期暴露的 registry 代理。
|
||
|
||
## CLI
|
||
|
||
入口是：
|
||
|
||
```bash
|
||
bun scripts/cli.ts artifact-registry plan
|
||
bun scripts/cli.ts artifact-registry render
|
||
bun scripts/cli.ts artifact-registry install
|
||
bun scripts/cli.ts artifact-registry status
|
||
bun scripts/cli.ts artifact-registry health
|
||
bun scripts/cli.ts artifact-registry deploy-backend-core --commit <full-sha>
|
||
```
|
||
|
||
`plan` 输出架构边界、依赖项、默认路径和 backend-core artifact CD 流程。`render` 输出 systemd unit、Compose 文件和 registry config 的完整内容与 SHA-256。`install --dry-run` 只列出将要执行的远端动作，不写 D601 文件、不启动容器、不 reload systemd。
|
||
|
||
真实 `install` 必须是幂等动作：创建远端目录，写入 CLI 渲染出的 config/compose/unit，执行 `systemctl daemon-reload`，启用并启动 `unidesk-artifact-registry.service`，然后运行与 `health` 相同的验收检查。若远端文件 hash 与期望不一致，install 可以覆盖由本 CLI 管理的 unit/config/compose，但不得删除 registry storage。
|
||
|
||
`deploy-backend-core` 是 production backend-core 的 CD 入口。它必须先通过 CNCF Distribution HTTP API 确认 D601 registry 中已经存在 `unidesk/backend-core:<commit>`，随后通过 provider-gateway Host SSH 流式执行 `docker save | gzip`，在 master server 侧 `docker load`、retag、Compose `--no-build` recreate 和 live commit 验证；如果镜像不存在，应失败并要求先运行 CI artifact publication。
|
||
|
||
`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，操作者需要确认这是受控升级还是漂移。
|
||
|
||
## Backend-Core Artifact CD
|
||
|
||
目标流程是：
|
||
|
||
1. D601 artifact registry 已安装并通过 `health`。
|
||
2. D601 CI 从 pushed Git checkout 构建 `unidesk/backend-core:<commit>`。
|
||
3. CI 将镜像 push 到 `127.0.0.1:5000/unidesk/backend-core:<commit>`，并记录 image ref 与 digest。
|
||
4. CD 在 master server 上确认目标 commit/tag/digest 存在。
|
||
5. master server 通过 provider-gateway Host SSH 从 D601 registry 流式读取 commit-pinned 镜像 tar，不开放 registry 端口，也不使用第三方镜像托管。
|
||
6. master server retag 为 Compose 使用的 backend-core 镜像名，并执行 `docker compose up -d --no-build --no-deps --force-recreate backend-core`。
|
||
7. 部署后通过 image label、runtime env、health payload 验证 live commit。
|
||
|
||
这个 CD 路径必须满足：
|
||
|
||
- source commit 来自 pushed Git，不来自 dirty worktree。
|
||
- 镜像 tag 必须 commit-pinned，不能用 mutable latest 作为部署真相。
|
||
- provider-gateway SSH image stream 是临时控制动作，不开放长期公网 registry。
|
||
- CI 可以有较多依赖；CD 只做拉取、retag、recreate 和 live commit 验证。
|
||
- CD 不执行 `cargo build`、`docker build`、`docker compose build backend-core` 或任何等价的 Rust 构建动作。
|
||
- `server rebuild backend-core` 仍不得作为 master server Rust 编译路径。
|