From 7d89a5e8bb3bec5bf5172db835a6fddfff26151a Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 20 May 2026 03:40:59 +0000 Subject: [PATCH] docs: document D601 direct artifact consumers --- AGENTS.md | 4 ++-- docs/reference/ci.md | 4 ++-- docs/reference/cicd-standardization.md | 18 ++++++++++++++++-- scripts/src/artifact-registry.ts | 11 +++++++---- scripts/src/help.ts | 10 +++++++++- 5 files changed, 36 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a525d86f..c8f9150c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,9 +38,9 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - `bun scripts/cli.ts microservice list/status/health/diagnostics/tunnel-self-test/proxy`：管理和验证挂载在主 server、计算节点 Docker 或 k3s 控制面上的用户服务，`proxy` 支持受控 JSON body，OA Event Flow/Todo Note/Baidu Netdisk/Code Queue Manager on main-server、k3s Control/Code Queue 执行面/MDTODO/Decision Center/FindJob/Pipeline/MET Nonlinear on D601 的规则见 `docs/reference/microservices.md`。 - `bun scripts/cli.ts decision upload/list/show/health`：通过 backend-core 用户服务代理上传会议记录/决议 Markdown、列出记录和查看详情；Decision Center 运行在 D601 k3s，规则见 `docs/reference/microservices.md`。 - `bun scripts/cli.ts decision diary import/list/months/show`：把带日期标题的工作日志 Markdown 拆成 `YYYY-MM/YYYY-MM-DD.md` 日记条目并写入 PostgreSQL，规则见 `docs/reference/microservices.md`。 -- `bun scripts/cli.ts deploy check/plan/apply [--file deploy.json|--env dev|prod] [--service ]`：按根目录 `deploy.json` 或 `origin/master:deploy.json#environments.` 的服务 repo 和 commit 期望状态校验或更新用户服务；`--env dev` 开放 D601 `backend-core` rollout 和 `frontend`/`baidu-netdisk`/`decision-center`/`mdtodo`/`claudeqq`/dev-only `code-queue`/direct consumer validation，`code-queue` prod unsupported，规则见 `docs/reference/deploy.md` 与 `docs/reference/dev-environment.md`。 +- `bun scripts/cli.ts deploy check/plan/apply [--file deploy.json|--env dev|prod] [--service ]`：按根目录 `deploy.json` 或 `origin/master:deploy.json#environments.` 的服务 repo 和 commit 期望状态校验或更新用户服务；`--env dev` 开放 D601 `backend-core` rollout、reviewed registry artifact consumers 和 D601 direct consumer validation，`findjob`/`pipeline` 是 D601 direct pull-only 样板，`met-nonlinear` dry-run blocked，`k3sctl-adapter` supervisor-only，`code-queue` prod unsupported，规则见 `docs/reference/deploy.md` 与 `docs/reference/dev-environment.md`。 - `bun scripts/cli.ts dev-env validate [--manifest path] [--kubectl-dry-run]` / `dev-env prewarm-images`：离线校验 D601 `unidesk-dev` 生产隔离护栏和 dev workload manifests，或把开发底座基础镜像预热到 D601 原生 k3s containerd，规则见 `docs/reference/deploy.md` 与 `docs/reference/microservices.md`。 -- `bun scripts/cli.ts artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service`：管理 D601 host-managed CNCF Distribution registry，并通过短生命周期 relay 或 D601 pull/import 做 commit-pinned pull-only artifact CD；`deploy-backend-core` 是 deprecated 兼容名，`mdtodo`/`claudeqq` 支持 dev/prod，`code-queue` 只支持 dev，规则见 `docs/reference/artifact-registry.md`。 +- `bun scripts/cli.ts artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service`：管理 D601 host-managed CNCF Distribution registry，并通过短生命周期 relay 或 D601 pull/import 做 commit-pinned pull-only artifact CD；`deploy-backend-core` 是 deprecated 兼容名，`findjob`/`pipeline` 支持 D601 direct dev/prod，`met-nonlinear` 和 `k3sctl-adapter` 只给受限计划路径，`code-queue` 只支持 dev，规则见 `docs/reference/artifact-registry.md`。 - `bun scripts/cli.ts ci install/status/run/publish-backend-core/publish-user-service/run-dev-e2e/logs`：在 D601 原生 k3s 上安装和运行 Tekton CI，支持每 commit 检查、Code Queue 只读性能门禁、`CI.json` catalog 驱动的 backend-core 与 user-service commit-pinned 镜像发布和手动触发的 `origin/master:deploy.json#environments.dev` 临时 namespace e2e；catalog/producer/consumer 分工见 `docs/reference/cicd-standardization.md`，`run-dev-e2e` 的 Git 控制 runner、短 launcher 和 no-CD 边界见 `docs/reference/dev-ci-runner.md`，Tekton 规则见 `docs/reference/ci.md`。 - `bun scripts/cli.ts codex deploy `：旧 Code Queue 兼容部署入口已禁用，原因是它会绕过受控部署边界直连 D601 部署 Code Queue；规则见 `docs/reference/codex-deploy.md`。 - `bun scripts/cli.ts codex submit [prompt] [--prompt-file path|--prompt-stdin] [--queue ]`：通过 backend-core 私有代理提交 Code Queue 任务；控制面默认走主 server `code-queue-mgr` 写入 PostgreSQL，`--dry-run` 可只检查请求体不入队，规则见 `docs/reference/cli.md`。 diff --git a/docs/reference/ci.md b/docs/reference/ci.md index 2c2d304b..f6f0ffae 100644 --- a/docs/reference/ci.md +++ b/docs/reference/ci.md @@ -46,8 +46,7 @@ Each catalog artifact also has a `status`. `supported` means the matching produc Current catalog coverage: -- `source-build/supported`: `backend-core`, `frontend`, `baidu-netdisk`, `decision-center`, `project-manager`, `oa-event-flow`, `todo-note`, `code-queue-mgr`, `findjob`, `pipeline`, `met-nonlinear`, `k3sctl-adapter`, `mdtodo`, `claudeqq`. -- `source-build/blocked`: `code-queue`. +- `source-build/supported`: `backend-core`, `frontend`, `baidu-netdisk`, `decision-center`, `project-manager`, `oa-event-flow`, `todo-note`, `code-queue-mgr`, `findjob`, `pipeline`, `met-nonlinear`, `k3sctl-adapter`, `mdtodo`, `claudeqq`, and dev-only `code-queue`. - `upstream-image/blocked`: `filebrowser`, `filebrowser-d601`. `publish-user-service` reads `source.repo` and `source.dockerfile` from `CI.json`. The command rejects ad hoc `--repo` overrides; the catalog is the only source for producer build inputs. `publish-backend-core` also reads its producer inputs from `CI.json`, while preserving the dedicated backend-core command and Rust/D601 build boundary. For `findjob`, `pipeline`, `met-nonlinear`, and `k3sctl-adapter`, the catalog can also carry consumer-only notes so CI producers and deploy consumers stay aligned on the live contract. @@ -122,6 +121,7 @@ The CI user-service artifact task must follow these rules: - The command output must include the common `artifactSummary` fields: `serviceId`, `sourceCommit`, `sourceRepo`, `dockerfile`, `imageRef`, `tag`, `digest` and `digestRef`. The digest ref is suitable as immutable input for later dev/prod deployment work. - CI is an artifact producer only. It must not restart production services, call production `deploy apply`, mutate the production namespace, or change `deploy.json`. - `CI.json` may also list downstream consumer-only catalog entries for D601 direct Compose services such as `findjob`, `pipeline`, `met-nonlinear`, and `k3sctl-adapter`; these entries describe the artifact contract and dry-run/support status, not new producer behavior. +- For D601 direct services, `findjob` and `pipeline` have reviewed dev/prod D601 Compose artifact consumers, `met-nonlinear` is dry-run only until the long-running service image contract matches the published artifact, and `k3sctl-adapter` is supervisor-only because it is the native k3s control bridge outside the k3s failure domain. - ClaudeQQ source comes from `https://gitee.com/lyon1998/agent_skills`; the producer exports the `claudeqq/` subtree and overlays the UniDesk Dockerfile plus API adapter from `src/components/microservices/claudeqq/` before building. Runtime topology and deploy intent still live in manifests and `deploy.json`, not in `CI.json`. Publish a Baidu Netdisk artifact: diff --git a/docs/reference/cicd-standardization.md b/docs/reference/cicd-standardization.md index 632a6719..36301b89 100644 --- a/docs/reference/cicd-standardization.md +++ b/docs/reference/cicd-standardization.md @@ -55,11 +55,11 @@ The successful `artifactSummary` must contain `serviceId`, `sourceCommit`, `sour Supported source-build artifact producers: - `backend-core` through `ci publish-backend-core`; -- `frontend`, `baidu-netdisk`, `decision-center`, `project-manager`, `oa-event-flow`, `todo-note`, `code-queue-mgr`, `findjob`, `pipeline`, `met-nonlinear`, `k3sctl-adapter`, `mdtodo`, `claudeqq` through `ci publish-user-service`. +- `frontend`, `baidu-netdisk`, `decision-center`, `project-manager`, `oa-event-flow`, `todo-note`, `code-queue-mgr`, `findjob`, `pipeline`, `met-nonlinear`, `k3sctl-adapter`, `mdtodo`, `claudeqq` through `ci publish-user-service`; +- `code-queue` through `ci publish-user-service` for dev image validation only. Cataloged but blocked: -- `code-queue`: source input is known, but this phase allows only dev image validation and not prod-oriented artifact publication. - `filebrowser` and `filebrowser-d601`: upstream image-only services pinned to `docker.io/filebrowser/filebrowser@sha256:289c5dd677c56662440f26eeb44266ed9746fe563d2e9100f546bff558534d70`; they need a future upstream mirror producer before CI can publish them. `code-queue-mgr` is a supported CI producer because the source-build input is known and the remote consumer commit already added a reviewed artifact consumer shape. Its production live apply remains supervisor-gated by deploy/artifact-registry and is not authorized by `CI.json`. @@ -75,6 +75,20 @@ Cataloged but blocked: The catalog records the resolved upstream digest for the current image. If a future tag refresh cannot resolve the registry manifest digest, rollout must remain blocked until a reachable registry path resolves the manifest digest and records the mirror digest. A local Docker image id is supporting evidence only and not a registry digest pin. +## D601 Direct Services + +D601 direct / host-managed services keep runtime ownership outside native k3s. Their standard path is still the artifact split: CI builds a commit-pinned image on D601, CD on D601 only checks the registry manifest, pulls or retags the artifact, recreates the existing Compose service with `--no-build --no-deps --force-recreate`, and verifies image labels plus service health. The provider-gateway/SSH path is a controlled maintenance bridge for those D601-local actions, not a target-side build standard and not a new public ingress. + +| Service | Producer | Consumer | Dev validation | Prod validation | Blocker | +| --- | --- | --- | --- | --- | --- | +| `findjob` | `ci publish-user-service --service findjob` builds `Dockerfile` from `https://gitee.com/Lyon1998/findjob` into `unidesk/findjob:` | D601 direct Compose artifact consumer, service `server`, container `findjob-server` | `deploy apply --env dev --service findjob --dry-run` plans pull-only CD and live apply is allowed when the artifact exists | `deploy apply --env prod --service findjob --dry-run` plans the same path; prod live apply is allowed by policy | health does not report deploy commit, so strict commit proof relies on image and container labels plus `/api/health` | +| `pipeline` | `ci publish-user-service --service pipeline` builds `Dockerfile` from `https://github.com/pikasTech/pipeline` into `unidesk/pipeline:` | D601 direct Compose artifact consumer, service `pipeline-control`, container `pipeline-v2-control` | `deploy apply --env dev --service pipeline --dry-run` plans pull-only CD and live apply is allowed when the artifact exists | `deploy apply --env prod --service pipeline --dry-run` plans the same path; prod live apply is allowed by policy | health does not report deploy commit, so strict commit proof relies on image and container labels plus `/health` | +| `met-nonlinear` | `ci publish-user-service --service met-nonlinear` builds `docker/unidesk/Dockerfile.ml` from `https://github.com/pikasTech/met_nonlinear` into `unidesk/met-nonlinear:` | D601 direct Compose dry-run contract for service `met-nonlinear-ts` | `deploy apply --env dev --service met-nonlinear --dry-run` returns `runtime-verification-blocked` until the runtime image contract is fixed | `deploy apply --env prod --service met-nonlinear --dry-run` returns `runtime-verification-blocked`; live prod apply is unsupported | catalog Dockerfile is the ML image while the long-running service is `met-nonlinear-ts`; publish a labeled artifact for the running TS service or separate the server Dockerfile contract | +| `k3sctl-adapter` | `ci publish-user-service --service k3sctl-adapter` builds `src/components/microservices/k3sctl-adapter/Dockerfile` from UniDesk into `unidesk/k3sctl-adapter:` | D601 direct Compose plan/dry-run for service `k3sctl-adapter`, container `k3sctl-adapter` | no normal dev target; it is the control bridge for dev/prod k3s visibility | `deploy apply --env prod --service k3sctl-adapter --dry-run` exposes the pull-only contract; live prod apply is supervisor-only | must remain outside the k3s failure domain and be recoverable before any live replacement; worker automation must not replace it without explicit supervisor confirmation | +| `filebrowser-d601` | no UniDesk source-build producer; `CI.json` marks it `upstream-image/blocked` | future pull-only upstream digest or D601 mirror digest consumer only | not implemented | not implemented | must not be represented as a Dockerfile build; first implement upstream digest resolution and mirror governance for `docker.io/filebrowser/filebrowser:v2.63.3` | + +`findjob`, `pipeline` and `met-nonlinear` deliberately do not create NodePort, hostPort or new public business ports. Runtime traffic stays behind backend-core, provider-gateway and the configured private service proxy. `k3sctl-adapter` is a control bridge, not an ordinary business service; it must be versioned, dry-run verifiable and manually recoverable before live replacement. + ### Upstream Image Evidence The catalog expression is intentionally minimal and parseable: diff --git a/scripts/src/artifact-registry.ts b/scripts/src/artifact-registry.ts index cfe3abbe..293923ec 100644 --- a/scripts/src/artifact-registry.ts +++ b/scripts/src/artifact-registry.ts @@ -2220,9 +2220,12 @@ function localHelp(): Record { "bun scripts/cli.ts artifact-registry deploy-service --env prod --service code-queue-mgr --commit --dry-run [--provider-id D601]", "bun scripts/cli.ts artifact-registry deploy-service --env prod --service todo-note --commit [--dry-run] [--run-now] [--provider-id D601]", "bun scripts/cli.ts artifact-registry deploy-service --env dev --service todo-note --commit [--dry-run] [--run-now] [--provider-id D601]", - "bun scripts/cli.ts artifact-registry deploy-service --env dev --service findjob --commit --dry-run [--provider-id D601]", - "bun scripts/cli.ts artifact-registry deploy-service --env dev --service pipeline --commit --dry-run [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env dev --service findjob --commit [--dry-run] [--run-now] [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env prod --service findjob --commit [--dry-run] [--run-now] [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env dev --service pipeline --commit [--dry-run] [--run-now] [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env prod --service pipeline --commit [--dry-run] [--run-now] [--provider-id D601]", "bun scripts/cli.ts artifact-registry deploy-service --env dev --service met-nonlinear --commit --dry-run [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env prod --service met-nonlinear --commit --dry-run [--provider-id D601]", "bun scripts/cli.ts artifact-registry deploy-service --env prod --service k3sctl-adapter --commit --dry-run [--provider-id D601]", "bun scripts/cli.ts artifact-registry deploy-service --env dev --service mdtodo --commit [--dry-run] [--run-now] [--provider-id D601]", "bun scripts/cli.ts artifact-registry deploy-service --env prod --service mdtodo --commit [--dry-run] [--run-now] [--provider-id D601]", @@ -2244,8 +2247,8 @@ function localHelp(): Record { "bun scripts/cli.ts deploy apply --env prod --service oa-event-flow", "bun scripts/cli.ts deploy apply --env prod --service code-queue-mgr --dry-run", "bun scripts/cli.ts deploy apply --env prod --service todo-note", - "bun scripts/cli.ts deploy apply --env prod --service findjob --dry-run", - "bun scripts/cli.ts deploy apply --env prod --service pipeline --dry-run", + "bun scripts/cli.ts deploy apply --env prod --service findjob", + "bun scripts/cli.ts deploy apply --env prod --service pipeline", "bun scripts/cli.ts deploy apply --env prod --service met-nonlinear --dry-run", "bun scripts/cli.ts deploy apply --env prod --service k3sctl-adapter --dry-run", "bun scripts/cli.ts deploy apply --env prod --service mdtodo", diff --git a/scripts/src/help.ts b/scripts/src/help.ts index 78b279bf..7eb6b097 100644 --- a/scripts/src/help.ts +++ b/scripts/src/help.ts @@ -38,7 +38,7 @@ export function rootHelp(): unknown { { command: "decision show ", description: "Show one Decision Center record." }, { command: "deploy check|plan|apply [--file deploy.json|--env dev|prod] [--service id] [--commit full-sha] [--dry-run] [--force]", description: "Reconcile services from a repo+commit manifest; --env reads origin/master:deploy.json environments and applies supported dev target-side rollouts or reviewed D601 registry artifact consumers. code-queue artifact consumption is dev-only." }, { command: "dev-env validate|prewarm-images", description: "Validate D601 unidesk-dev guardrails or prewarm dev foundation images into native k3s containerd through a bounded async job." }, - { command: "artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service", description: "Manage the D601 host-managed CNCF Distribution registry and run pull-only artifact CD for supported services, including k3s-managed dev/prod consumers and code-queue dev-only validation." }, + { command: "artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service", description: "Manage the D601 host-managed CNCF Distribution registry and run pull-only artifact CD for supported services, including D601 direct, k3s-managed, and code-queue dev-only consumers." }, { command: "schedule list|get|runs|run|delete", description: "Manage backend-core scheduled tasks and run history; schedule run supports --wait-ms N." }, { command: "schedule upsert-pgdata-backup [--time HH:MM] [--remote-base /SERVER_DATA/UNIDESK_PG_DATA]", description: "Create or update the daily PGDATA physical backup task that uploads monthly rotated archives to Baidu Netdisk." }, { command: "codex deploy [--provider-id D601] [--timeout-ms N]", description: "Disabled legacy Code Queue deploy path; use the dev-only artifact consumer instead." }, @@ -276,6 +276,13 @@ function artifactRegistryHelp(): unknown { "bun scripts/cli.ts artifact-registry deploy-service --env prod --service oa-event-flow --commit [--dry-run] [--run-now] [--provider-id D601]", "bun scripts/cli.ts artifact-registry deploy-service --env prod --service code-queue-mgr --commit --dry-run [--provider-id D601]", "bun scripts/cli.ts artifact-registry deploy-service --env prod --service todo-note --commit [--dry-run] [--run-now] [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env dev --service findjob --commit [--dry-run] [--run-now] [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env prod --service findjob --commit [--dry-run] [--run-now] [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env dev --service pipeline --commit [--dry-run] [--run-now] [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env prod --service pipeline --commit [--dry-run] [--run-now] [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env dev --service met-nonlinear --commit --dry-run [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env prod --service met-nonlinear --commit --dry-run [--provider-id D601]", + "bun scripts/cli.ts artifact-registry deploy-service --env prod --service k3sctl-adapter --commit --dry-run [--provider-id D601]", "bun scripts/cli.ts artifact-registry deploy-service --env dev --service mdtodo --commit [--dry-run] [--run-now] [--provider-id D601]", "bun scripts/cli.ts artifact-registry deploy-service --env prod --service mdtodo --commit [--dry-run] [--run-now] [--provider-id D601]", "bun scripts/cli.ts artifact-registry deploy-service --env dev --service claudeqq --commit [--dry-run] [--run-now] [--provider-id D601]", @@ -289,6 +296,7 @@ function artifactRegistryHelp(): unknown { "install writes the rendered host unit/config and starts the registry", "deploy-backend-core only pulls commit-pinned backend-core artifacts and does not build backend-core on the master server", "deploy-service currently supports backend-core, baidu-netdisk, prod/dev frontend, decision-center, mdtodo, claudeqq, project-manager, oa-event-flow, code-queue-mgr, todo-note, findjob, pipeline, met-nonlinear, k3sctl-adapter, and dev-only code-queue as standardized consumers", + "findjob and pipeline have D601 direct dev/prod Compose artifact consumers; met-nonlinear is runtime-verification blocked; k3sctl-adapter is supervisor-only", "code-queue has no prod artifact deploy target and prod requests return structured unsupported", "status and health use provider-gateway Host SSH readonly checks", ],