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

12 KiB
Raw Blame History

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. 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

入口是：

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、部署和健康验证：

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 通过：

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 管理员可以用标准工具维护：

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