mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
93d9488d36d2bb2f0d37557c855de13ba8b8dc26
pikasTech-unidesk/docs/reference/artifact-registry.md
T
Codex 93d9488d36 feat: extend main-server artifact consumers
2026-05-20 01:10:38 +00:00

136 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# D601 Artifact Registry
D601 artifact registry 是为 backend-core 和标准用户服务轻量 CD 准备的本地镜像制品入口。它使用开源、成熟的 CNCF Distribution Docker registry，不自定义镜像协议，也不把镜像托管到第三方服务。
backend-core 和 reviewed user services 的长期分工是：CI 在 D601 构建并发布 commit-pinned 镜像，CD 在运行目标只拉取、替换/导入和验证该镜像。registry 是这条链路的本地制品缓存，不是构建编排器，也不是生产部署控制面。
Production CI/CD runtime pinning and release-line boundaries follow `docs/reference/release-governance.md` and [GitHub issue #6](https://github.com/pikasTech/unidesk/issues/6). The registry may cache commit-pinned artifacts, but it must not become a floating replacement for `deploy.json`, `release/v1`, or `master` source history.
The CI-side artifact catalog is root `CI.json`. That file describes only artifact producer inputs and naming; registry consumers still verify the real image labels, manifest digest and live runtime separately. The producer summary contract is owned by `docs/reference/ci.md` and includes `serviceId`, `sourceCommit`, `sourceRepo`, `dockerfile`, `imageRef`, `tag`, `digest` and `digestRef`.
## 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 Compose CD 和 D601 k3s 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。
- 第三方镜像托管服务作为 artifact source of truth。
- main server backend-core 本地 Rust 编译或 artifact-consumer 服务本地 Docker build。
- 公开 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-service --service baidu-netdisk --commit <full-sha>
bun scripts/cli.ts artifact-registry deploy-service --service frontend --env prod --commit <full-sha>
bun scripts/cli.ts artifact-registry deploy-service --service frontend --env dev --commit <full-sha>
bun scripts/cli.ts artifact-registry deploy-service --service decision-center --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 必须使用 `bun scripts/cli.ts deploy apply --env prod --service backend-core --commit <full-sha>`，由 deploy reconciler 先执行共同的 artifact-consumer guardrail，再调用通用 `deploy-service` consumer。旧入口只能返回 structured deprecated 结果，不得绕过 `deploy apply --env prod`。
`deploy-service` 是标准化后的最小通用 artifact consumer。它目前只支持 `backend-core`、`baidu-netdisk`、prod/dev `frontend` 和 `decision-center`，并且必须先通过 D601 registry 的 commit-pinned manifest 校验，再执行拉取、导入/retag、部署和健康验证：
```bash
bun scripts/cli.ts artifact-registry deploy-service --service baidu-netdisk --commit <full-sha> --run-now
bun scripts/cli.ts artifact-registry deploy-service --service frontend --env prod --commit <full-sha> --run-now
bun scripts/cli.ts artifact-registry deploy-service --service frontend --env dev --commit <full-sha> --run-now
bun scripts/cli.ts artifact-registry deploy-service --env dev --service decision-center --commit <full-sha> --run-now
bun scripts/cli.ts artifact-registry deploy-service --service decision-center --commit <full-sha> --run-now
```
dry-run 输出会暴露 registry probe URL、required labels、目标 image、部署形态和回滚信息。`baidu-netdisk` 的 Compose 路径会通过 provider-gateway Host SSH 把 `unidesk/baidu-netdisk:<commit>` 流式拉到 master server，retag 为 `baidu-netdisk` 和 `baidu-netdisk:<commit>`，写入 `UNIDESK_BAIDU_NETDISK_DEPLOY_*`，只 recreate `baidu-netdisk` service，并验证容器 image label 与 `/health.deploy.commit`。`frontend --env prod` 使用同一 Compose artifact consumer，流式拉取 `unidesk/frontend:<commit>`，retag 为 `unidesk-frontend` 和 `unidesk-frontend:<commit>`，写入 `UNIDESK_FRONTEND_DEPLOY_*`，只 recreate `frontend` service，并验证 image label 与 `/health.deploy.commit`。`frontend --env dev` 和 `decision-center` 的 k3s 路径会在 D601 上验证 commit image、导入 native k3s containerd、更新 Deployment image/env/annotations，并通过 Kubernetes API service proxy 验证 `/health` 中的 `deploy.commit` 和 `deploy.requestedCommit`；dev frontend 还会在 rollout 前把主 server `config.json.auth` 同步到 `unidesk-dev` Secret/ConfigMap。`decision-center --env dev` 落到 `unidesk-dev/decision-center-dev`，prod 落到 `unidesk/decision-center`。回滚信息通过同一 artifact consumer 的 `rollback` 字段暴露，提示操作者重新对一个旧 commit 运行相同命令，而不是切回 legacy maintenance-channel 构建。
`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，操作者需要确认这是受控升级还是漂移。
## Artifact CD
目标流程是：
1. D601 artifact registry 已安装并通过 `health`。
2. D601 CI 从 pushed Git checkout 构建 `unidesk/<service-id>:<commit>`。
3. CI 将镜像 push 到 `127.0.0.1:5000/unidesk/<service-id>:<commit>`，并记录完整 artifact summary，包括 service id、source repo、source commit、Dockerfile、image ref、tag、digest 和 digest ref。
4. CD 在运行目标上确认目标 commit/tag/digest 存在。
5. Compose runtime 通过 provider-gateway Host SSH 从 D601 registry 流式读取 commit-pinned 镜像 tar；D601 k3s runtime 通过 host-local registry/containerd import 消费同一 commit-pinned 镜像。不开放 registry 端口，也不使用第三方镜像托管。
6. Compose runtime retag 为 Compose 使用的镜像名，并执行 `docker compose up -d --no-build --no-deps --force-recreate <service>`；k3s runtime 设置 Deployment image/env/annotations 并等待 rollout。
7. 部署后通过 image label、runtime env、health payload 验证 live commit。
Baidu Netdisk is the first main-server direct user-service sample in this flow. Its dev validation command and prod CD command both consume `127.0.0.1:5000/unidesk/baidu-netdisk:<commit>` and must not build source on the master server. Frontend is the standard UniDesk UI artifact sample: CI publishes `127.0.0.1:5000/unidesk/frontend:<commit>`, production CD consumes that artifact into the master-server Compose `frontend` service, and dev CD consumes the same artifact into D601 native k3s `frontend-dev`. Project Manager and OA Event Flow use the same master-server Compose artifact-consumer shape as Baidu Netdisk, with `project-manager-backend` and `oa-event-flow-backend` as the runtime containers. Code Queue Manager is supported as an artifact consumer for validation, but prod live apply is supervisor-gated. Todo Note currently returns a structured runtime-verification block until the checked-in health contract proves `deploy.commit` and `deploy.requestedCommit`. Neither path may use `server rebuild frontend`, dirty source, mutable `latest`, or target-side frontend source builds as release truth. Decision Center follows the same artifact-consumer pattern in both dev and prod, except the runtime target is native k3s on D601 instead of the master-server Compose stack. The consumer must check the registry manifest, pull the commit-pinned image, import it into `/run/k3s/containerd/containerd.sock`, set the Deployment image to the commit tag, stamp `UNIDESK_DEPLOY_*` env/annotations, and reject an old healthy revision if the live commit or requested commit does not match.
这个 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 <service>` 或任何等价构建动作。
- `artifact-registry deploy-backend-core`、`server rebuild backend-core` 和 `server rebuild baidu-netdisk` 仍是维护/兼容/非标准路径，不得作为 artifact CD 完成证据。
Reference in New Issue View Git Blame Copy Permalink