From 2815975c6b56833e189275b600e7b7a2e03468ec Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 9 Jul 2026 20:22:00 +0200 Subject: [PATCH] docs: retire stale decision center d601 references --- docs/reference/artifact-registry.md | 10 ++++------ docs/reference/cicd-standardization.md | 14 +++++++------- docs/reference/cli.md | 10 +++++----- docs/reference/deploy.md | 12 ++++++------ docs/reference/deployment.md | 4 ++-- docs/reference/dev-environment.md | 4 ++-- docs/reference/frontend.md | 2 +- docs/reference/microservices.md | 20 ++++++++++---------- docs/reference/repo-tree.md | 2 +- docs/reference/user-service-delivery.md | 14 +++++++------- 10 files changed, 45 insertions(+), 47 deletions(-) diff --git a/docs/reference/artifact-registry.md b/docs/reference/artifact-registry.md index 7c7bd62d..41065ddd 100644 --- a/docs/reference/artifact-registry.md +++ b/docs/reference/artifact-registry.md @@ -63,7 +63,7 @@ bun scripts/cli.ts artifact-registry deploy-service --service backend-core --env bun scripts/cli.ts artifact-registry deploy-service --service baidu-netdisk --commit bun scripts/cli.ts artifact-registry deploy-service --service frontend --env prod --commit bun scripts/cli.ts artifact-registry deploy-service --service frontend --env dev --commit -bun scripts/cli.ts artifact-registry deploy-service --service decision-center --commit +# Decision Center current production deploy is NC01 YAML-first k8s, not artifact-registry deploy-service. bun scripts/cli.ts artifact-registry deploy-service --env prod --service project-manager --commit bun scripts/cli.ts artifact-registry deploy-service --env prod --service oa-event-flow --commit bun scripts/cli.ts artifact-registry deploy-service --env prod --service code-queue-mgr --commit --dry-run @@ -85,15 +85,13 @@ bun scripts/cli.ts artifact-registry deploy-service --service code-queue --env d `deploy-backend-core` 是旧兼容入口，当前作为标准路径已禁用。Backend-core CD 必须使用 `bun scripts/cli.ts deploy apply --env dev --service backend-core --commit ` 或 `bun scripts/cli.ts deploy apply --env prod --service backend-core --commit `，由 deploy reconciler 先执行共同的 artifact-consumer guardrail，再调用通用 `deploy-service` consumer。旧入口只能返回 structured deprecated 结果，不得绕过 `deploy apply --env ...`。 -`deploy-service` 是标准化后的最小通用 artifact consumer。它目前支持 dev/prod `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`，以及 dev-only `code-queue` dry-run。所有路径都必须先通过 D601 registry 的 commit-pinned manifest 校验，再执行拉取、导入/retag、部署和健康验证；`code-queue --env dev --dry-run` 必须显示 `requiresSupervisorApproval=true`、`selfBootstrapGuard`、commit tag/digest provenance、pull-only/no-build build boundary 和不会影响 production scheduler/runner/active tasks 的 `affectedRuntime` / `excludedTargets`；非 dry-run DEV apply 必须返回 supervisor/human authorization gate，不能由正在运行的 Code Queue task 自举执行；`code-queue --env prod` 必须返回 structured unsupported，不能回退到生产 artifact deploy、rollout 或 manifest 变更；`code-queue-mgr` 的 prod live apply 仍需 supervisor 单独确认，`met-nonlinear` 与 `k3sctl-adapter` 当前只提供 plan/dry-run： +`deploy-service` 是标准化后的最小通用 artifact consumer。它目前支持 dev/prod `backend-core`、`baidu-netdisk`、prod/dev `frontend`、`mdtodo`、`claudeqq`、`project-manager`、`oa-event-flow`、`code-queue-mgr`、`todo-note`、`findjob`、`pipeline`、`met-nonlinear` 和 `k3sctl-adapter`，以及 dev-only `code-queue` dry-run。Decision Center 已迁移到 NC01 YAML-first k8s + GitHub repo storage，不再把 D601 artifact registry 作为当前生产 deploy truth。其余 artifact consumer 路径都必须先通过 D601 registry 的 commit-pinned manifest 校验，再执行拉取、导入/retag、部署和健康验证；`code-queue --env dev --dry-run` 必须显示 `requiresSupervisorApproval=true`、`selfBootstrapGuard`、commit tag/digest provenance、pull-only/no-build build boundary 和不会影响 production scheduler/runner/active tasks 的 `affectedRuntime` / `excludedTargets`；非 dry-run DEV apply 必须返回 supervisor/human authorization gate，不能由正在运行的 Code Queue task 自举执行；`code-queue --env prod` 必须返回 structured unsupported，不能回退到生产 artifact deploy、rollout 或 manifest 变更；`code-queue-mgr` 的 prod live apply 仍需 supervisor 单独确认，`met-nonlinear` 与 `k3sctl-adapter` 当前只提供 plan/dry-run： ```bash bun scripts/cli.ts artifact-registry deploy-service --service baidu-netdisk --commit --run-now bun scripts/cli.ts artifact-registry deploy-service --service backend-core --env dev --commit --run-now bun scripts/cli.ts artifact-registry deploy-service --service frontend --env prod --commit --run-now bun scripts/cli.ts artifact-registry deploy-service --service frontend --env dev --commit --run-now -bun scripts/cli.ts artifact-registry deploy-service --env dev --service decision-center --commit --run-now -bun scripts/cli.ts artifact-registry deploy-service --service decision-center --commit --run-now bun scripts/cli.ts artifact-registry deploy-service --env prod --service project-manager --commit --run-now bun scripts/cli.ts artifact-registry deploy-service --env prod --service oa-event-flow --commit --run-now bun scripts/cli.ts artifact-registry deploy-service --env prod --service todo-note --commit --run-now @@ -113,7 +111,7 @@ Code Queue Manager supervisor gate 通过 dry-run 和 live health 证据验证 Code Queue DEV live apply is not an automation default. The reviewed path is: publish the commit-pinned artifact, run `deploy plan --env dev --service code-queue` and `deploy apply --env dev --service code-queue --dry-run` or the equivalent artifact-registry dry-run, then have a human operator or supervisor authorize any DEV apply outside the running Code Queue task. PROD has no apply authorization point in this phase. -dry-run 输出会暴露 registry probe URL、required labels、目标 image、部署形态、目标 Deployment 列表、回滚信息，以及结构化 `registry`、`source` 和 `build` 字段；`registry.digest` 在 dry-run 中为 `null`，`digestSource` 指明真实 digest 来自 live registry manifest HEAD，`build.willCompile`、`build.willRunCargoBuild`、`build.willRunDockerBuild` 和 `build.willRunDockerComposeBuild` 必须为 false。dry-run 不得打印运行时密钥。`backend-core --env dev` 使用 `ci publish-backend-core` 产出的 `127.0.0.1:5000/unidesk/backend-core:`，导入 D601 native k3s containerd，更新 `unidesk-dev/backend-core-dev` Deployment，设置 image/env/annotations，并通过 Kubernetes API service proxy 验证 `/health.deploy.commit` 和 `deploy.requestedCommit`；CD 阶段不得运行 Rust 编译或 Docker build。`baidu-netdisk` 是 PGDATA 备份链路依赖服务；它的 Compose artifact 路径会通过 provider-gateway Host SSH 把 `unidesk/baidu-netdisk:` 流式拉到 master server，retag 为 `baidu-netdisk` 和 `baidu-netdisk:`，在 canonical UniDesk 根目录使用 `providerGateway.upgrade.composeEnvFile` 指向的受控 env 文件写入 `UNIDESK_BAIDU_NETDISK_DEPLOY_*`，只 recreate `baidu-netdisk` service，并验证容器 image label 与 `/health.deploy.commit`。live apply 在 recreate 前必须确认受控 env 文件中存在 `UNIDESK_BAIDU_NETDISK_CLIENT_ID`、`UNIDESK_BAIDU_NETDISK_CLIENT_SECRET` 和 `UNIDESK_BAIDU_NETDISK_TOKEN_KEY`，输出只能包含 present/length/boolean；dry-run 输出 `runtimeSecrets.secretSource`、`requiredSecretsPresent`、`missingSecretKeys` 和 `recommendedAction`，让 dev secret source blocker 可诊断但不打印值；recreate 后必须验收 `/health.auth.configured`、`clientIdConfigured`、`clientSecretConfigured`、`tokenKeyConfigured` 和 `loggedIn` 全部为 true，否则返回失败或 degraded，并提示先恢复 env、单服务 recreate、再验证 `microservice health baidu-netdisk`。`findjob`、`pipeline` 和 `met-nonlinear` 的 D601 direct Compose 路径在 D601 本机验证 registry manifest、pull image、retag stable image、写入 `UNIDESK_*_DEPLOY_*` labels/env，并用 `docker compose up -d --no-build --no-deps --force-recreate ` 重新拉起对应 compose service；其中 `met-nonlinear` 当前因为 registered Dockerfile 和 long-running service contract 不一致而 live deploy blocked。`k3sctl-adapter` 是基础设施控制桥，只做 plan/dry-run，真实生产部署需要 supervisor 单独确认。`frontend --env prod` 使用同一 Compose artifact consumer，流式拉取 `unidesk/frontend:`，retag 为 `unidesk-frontend` 和 `unidesk-frontend:`，写入 `UNIDESK_FRONTEND_DEPLOY_*`，只 recreate `frontend` service，并验证 image label 与 `/health.deploy.commit`。`frontend --env dev`、`decision-center`、`mdtodo`、`claudeqq` 和 dev `code-queue` 的 k3s 路径会在 D601 上验证 commit image、导入 native k3s containerd、更新 Deployment image/env/annotations，并通过 Kubernetes API service proxy 验证 `/health` 中的 live commit 与 requested commit；dev frontend 还会在 rollout 前把主 server `config.json.auth` 同步到 `unidesk-dev` Secret/ConfigMap。`decision-center --env dev` 落到 `unidesk-dev/decision-center-dev`，prod 落到 `unidesk/decision-center`；`mdtodo` 和 `claudeqq` 使用同样的 dev 后 prod k3s consumer 结构。`code-queue --env dev` 只更新 `unidesk-dev` 中的 scheduler/read/write/provider-egress-proxy dev Deployments，prod 没有 consumer target。D601 direct Compose consumer 与 k3s-managed consumer 的区别是：前者只接触 D601 Docker/Compose 项目和私有 backend health，不创建 Kubernetes 对象；后者只通过 native k3s Deployment/Service、containerd import 和 Kubernetes API service proxy 验证 live commit。回滚信息通过同一 artifact consumer 的 `rollback` 字段暴露，提示操作者重新对一个旧 commit 运行相同命令，而不是切回 legacy maintenance-channel 构建。 +dry-run 输出会暴露 registry probe URL、required labels、目标 image、部署形态、目标 Deployment 列表、回滚信息，以及结构化 `registry`、`source` 和 `build` 字段；`registry.digest` 在 dry-run 中为 `null`，`digestSource` 指明真实 digest 来自 live registry manifest HEAD，`build.willCompile`、`build.willRunCargoBuild`、`build.willRunDockerBuild` 和 `build.willRunDockerComposeBuild` 必须为 false。dry-run 不得打印运行时密钥。`backend-core --env dev` 使用 `ci publish-backend-core` 产出的 `127.0.0.1:5000/unidesk/backend-core:`，导入 D601 native k3s containerd，更新 `unidesk-dev/backend-core-dev` Deployment，设置 image/env/annotations，并通过 Kubernetes API service proxy 验证 `/health.deploy.commit` 和 `deploy.requestedCommit`；CD 阶段不得运行 Rust 编译或 Docker build。`baidu-netdisk` 是 PGDATA 备份链路依赖服务；它的 Compose artifact 路径会通过 provider-gateway Host SSH 把 `unidesk/baidu-netdisk:` 流式拉到 master server，retag 为 `baidu-netdisk` 和 `baidu-netdisk:`，在 canonical UniDesk 根目录使用 `providerGateway.upgrade.composeEnvFile` 指向的受控 env 文件写入 `UNIDESK_BAIDU_NETDISK_DEPLOY_*`，只 recreate `baidu-netdisk` service，并验证容器 image label 与 `/health.deploy.commit`。live apply 在 recreate 前必须确认受控 env 文件中存在 `UNIDESK_BAIDU_NETDISK_CLIENT_ID`、`UNIDESK_BAIDU_NETDISK_CLIENT_SECRET` 和 `UNIDESK_BAIDU_NETDISK_TOKEN_KEY`，输出只能包含 present/length/boolean；dry-run 输出 `runtimeSecrets.secretSource`、`requiredSecretsPresent`、`missingSecretKeys` 和 `recommendedAction`，让 dev secret source blocker 可诊断但不打印值；recreate 后必须验收 `/health.auth.configured`、`clientIdConfigured`、`clientSecretConfigured`、`tokenKeyConfigured` 和 `loggedIn` 全部为 true，否则返回失败或 degraded，并提示先恢复 env、单服务 recreate、再验证 `microservice health baidu-netdisk`。`findjob`、`pipeline` 和 `met-nonlinear` 的 D601 direct Compose 路径在 D601 本机验证 registry manifest、pull image、retag stable image、写入 `UNIDESK_*_DEPLOY_*` labels/env，并用 `docker compose up -d --no-build --no-deps --force-recreate ` 重新拉起对应 compose service；其中 `met-nonlinear` 当前因为 registered Dockerfile 和 long-running service contract 不一致而 live deploy blocked。`k3sctl-adapter` 是基础设施控制桥，只做 plan/dry-run，真实生产部署需要 supervisor 单独确认。`frontend --env prod` 使用同一 Compose artifact consumer，流式拉取 `unidesk/frontend:`，retag 为 `unidesk-frontend` 和 `unidesk-frontend:`，写入 `UNIDESK_FRONTEND_DEPLOY_*`，只 recreate `frontend` service，并验证 image label 与 `/health.deploy.commit`。`frontend --env dev`、`mdtodo`、`claudeqq` 和 dev `code-queue` 的 k3s 路径会在 D601 上验证 commit image、导入 native k3s containerd、更新 Deployment image/env/annotations，并通过 Kubernetes API service proxy 验证 `/health` 中的 live commit 与 requested commit；dev frontend 还会在 rollout 前把主 server `config.json.auth` 同步到 `unidesk-dev` Secret/ConfigMap。Decision Center 当前不属于这条 D601 artifact consumer 运行面；它的生产发布和存储验证以 NC01 k8s 与 GitHub repo storage 为准。`mdtodo` 和 `claudeqq` 使用同样的 dev 后 prod k3s consumer 结构。`code-queue --env dev` 只更新 `unidesk-dev` 中的 scheduler/read/write/provider-egress-proxy dev Deployments，prod 没有 consumer target。D601 direct Compose consumer 与 k3s-managed consumer 的区别是：前者只接触 D601 Docker/Compose 项目和私有 backend health，不创建 Kubernetes 对象；后者只通过 native k3s Deployment/Service、containerd import 和 Kubernetes API service proxy 验证 live commit。回滚信息通过同一 artifact consumer 的 `rollback` 字段暴露，提示操作者重新对一个旧 commit 运行相同命令，而不是切回 legacy maintenance-channel 构建。 `status` 和 `health` 通过： @@ -161,7 +159,7 @@ docker compose -p unidesk-artifact-registry -f /home/ubuntu/.unidesk/artifact-re 6. Compose runtime retag 为 Compose 使用的镜像名，并执行 `docker compose up -d --no-build --no-deps --force-recreate `；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:` and must not build source on the master server. Backend-core is the Rust artifact sample: CI publishes `127.0.0.1:5000/unidesk/backend-core:`, dev CD consumes it into D601 native k3s `backend-core-dev`, and prod CD consumes it into the master-server Compose `backend-core` service. Frontend is the standard UniDesk UI artifact sample: CI publishes `127.0.0.1:5000/unidesk/frontend:`, 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, OA Event Flow and Todo Note use the same master-server Compose artifact-consumer shape as Baidu Netdisk, with `project-manager-backend`, `oa-event-flow-backend` and `todo-note-backend` as the runtime containers; Todo Note keeps its external source repository and requires a pre-existing `127.0.0.1:5000/unidesk/todo-note:` artifact. Its consumer injects `UNIDESK_TODO_NOTE_DEPLOY_*` runtime metadata and the container health probe combines `/api/health` with that metadata before enforcing `deploy.commit` / `deploy.requestedCommit`. Code Queue Manager is supported as an artifact consumer for validation, but prod live apply is supervisor-gated. Neither path may use `server rebuild frontend`, dirty source, mutable `latest`, or target-side frontend source builds as release truth. Decision Center, MDTODO and ClaudeQQ follow 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. Dev `code-queue` is a deliberately narrower consumer: it validates only the `unidesk-dev` Code Queue execution slice and has no prod target. The k3s 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, verify health through the Kubernetes API service proxy, and reject an old healthy revision if the live commit or requested commit does not match. +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:` and must not build source on the master server. Backend-core is the Rust artifact sample: CI publishes `127.0.0.1:5000/unidesk/backend-core:`, dev CD consumes it into D601 native k3s `backend-core-dev`, and prod CD consumes it into the master-server Compose `backend-core` service. Frontend is the standard UniDesk UI artifact sample: CI publishes `127.0.0.1:5000/unidesk/frontend:`, 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, OA Event Flow and Todo Note use the same master-server Compose artifact-consumer shape as Baidu Netdisk, with `project-manager-backend`, `oa-event-flow-backend` and `todo-note-backend` as the runtime containers; Todo Note keeps its external source repository and requires a pre-existing `127.0.0.1:5000/unidesk/todo-note:` artifact. Its consumer injects `UNIDESK_TODO_NOTE_DEPLOY_*` runtime metadata and the container health probe combines `/api/health` with that metadata before enforcing `deploy.commit` / `deploy.requestedCommit`. Code Queue Manager is supported as an artifact consumer for validation, but prod live apply is supervisor-gated. Neither path may use `server rebuild frontend`, dirty source, mutable `latest`, or target-side frontend source builds as release truth. MDTODO and ClaudeQQ follow 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. Decision Center is the exception: its current runtime target is NC01 k8s and its durable state is GitHub repo `pikasTech/decision-center-data`, so D601 registry artifact evidence is not production closeout for that service. Dev `code-queue` is a deliberately narrower consumer: it validates only the `unidesk-dev` Code Queue execution slice and has no prod target. The k3s 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, verify health through the Kubernetes API service proxy, and reject an old healthy revision if the live commit or requested commit does not match. Main-server direct production dry-runs for the user-service matrix must be enough to review the blast radius before any live apply. `artifact-registry deploy-service --env prod --service --commit --dry-run` is non-mutating and reports this fixed target shape: diff --git a/docs/reference/cicd-standardization.md b/docs/reference/cicd-standardization.md index b5da30ea..be8c66b3 100644 --- a/docs/reference/cicd-standardization.md +++ b/docs/reference/cicd-standardization.md @@ -60,14 +60,14 @@ Phase one extends the desired-state model in this order: 4. Add deployment-time metadata that must be common across CI, dev CD and prod CD: deploy env prefix, health deploy-metadata requirement, required runtime secret key names, rollback policy, service port, health path, and resource profile identifiers. The planned first keys are `runtime.containerPort`, `runtime.healthPath`, `runtime.memory.request`, `runtime.memory.limit`, `health.deployMetadataRequired` and `runtime.requiredSecretKeys`. Secret values, credentials, volumes and host paths do not move into `deploy.json`. 5. Teach CI producer dry-run, deploy plan and artifact-registry dry-run to render from `deploy.json` first and compare mirrored `CI.json`/`config.json`/manifest values as derived copies. A mismatch is drift, not an alternate source of truth. -Phase two starts with low-risk D601 k3s user-service artifact consumers plus the dev-only Code Queue artifact consumer: `dev/mdtodo`, `dev/decision-center` and `dev/code-queue`. Their `deploy.json` entries now own the source-build artifact repository/tag policy, D601 k3s consumer target, stable image, manifest reference, service port, health path, memory request/limit and health deploy-metadata requirement. `deploy plan --env dev --service ` and dry-run artifact consumer plans must read those fields from `deploy.json`; the k8s manifest and artifact-registry executor constants are derived mirrors checked by a structured `deploy-json-drift` preflight. +Phase two starts with low-risk D601 k3s user-service artifact consumers plus the dev-only Code Queue artifact consumer: `dev/mdtodo` and `dev/code-queue`. Decision Center has since moved out of this D601 artifact-consumer lane; its current production truth is NC01 YAML-first k8s plus GitHub repo storage. The remaining phase-two `deploy.json` entries own the source-build artifact repository/tag policy, D601 k3s consumer target, stable image, manifest reference, service port, health path, memory request/limit and health deploy-metadata requirement. `deploy plan --env dev --service ` and dry-run artifact consumer plans must read those fields from `deploy.json`; the k8s manifest and artifact-registry executor constants are derived mirrors checked by a structured `deploy-json-drift` preflight. Fields that stay outside `deploy.json` during phase one: - `CI.json`: producer pipeline name, source root, Dockerfile path and success summary shape. Once artifact identity is in `deploy.json`, `CI.json.artifacts[].image.repository` becomes a compatibility mirror checked for drift. -- `config.json`: provider id, proxy route policy, Compose file/service/container names for services not yet migrated, development SSH/worktree details, and secret source locations. For `dev/mdtodo`, `dev/decision-center` and `dev/code-queue`, port/health target values in dry-run are deploy-owned and config is no longer an alternate source. -- Compose and Kubernetes manifests: volumes, PVCs, security context and rollout strategy remain concrete manifests. For `dev/mdtodo`, `dev/decision-center` and `dev/code-queue`, container port, memory request/limit and deploy metadata env presence are deploy-owned values and manifest copies are drift-checked mirrors until a renderer owns the file. -- Artifact-registry executor code: low-level pull/import/retag/recreate commands, registry probes and platform-specific verification scripts. For `dev/mdtodo`, `dev/decision-center` and `dev/code-queue`, executor dry-run consumes the deploy-owned artifact/consumer/runtime contract; any hardcoded mismatch returns `deploy-json-drift`. +- `config.json`: provider id, proxy route policy, Compose file/service/container names for services not yet migrated, development SSH/worktree details, and secret source locations. For `dev/mdtodo` and `dev/code-queue`, port/health target values in dry-run are deploy-owned and config is no longer an alternate source. Decision Center config moved to the NC01 YAML-first k8s target and GitHub storage declaration. +- Compose and Kubernetes manifests: volumes, PVCs, security context and rollout strategy remain concrete manifests. For `dev/mdtodo` and `dev/code-queue`, container port, memory request/limit and deploy metadata env presence are deploy-owned values and manifest copies are drift-checked mirrors until a renderer owns the file. +- Artifact-registry executor code: low-level pull/import/retag/recreate commands, registry probes and platform-specific verification scripts. For `dev/mdtodo` and `dev/code-queue`, executor dry-run consumes the deploy-owned artifact/consumer/runtime contract; any hardcoded mismatch returns `deploy-json-drift`. The drift contract is: @@ -176,7 +176,7 @@ This matrix is the single review surface for the remaining D601 service lane. It | `met-nonlinear` | D601 `unidesk-direct` GPU/business execution service in Docker Compose; control path is backend-core -> provider-gateway private HTTP proxy -> D601 loopback `/health` and `/api/`. | `CI.json` source-build supported through `ci publish-user-service --service met-nonlinear`; cataloged artifact uses `docker/unidesk/Dockerfile.ml` from `https://github.com/pikasTech/met_nonlinear`. | D601 direct Compose consumer is plan/dry-run only for service/container `met-nonlinear-ts`; dry-run exposes the no-build pull-only shape but returns `runtime-verification-blocked`. | Dry-run/read-only only. `deploy apply --env dev --service met-nonlinear --dry-run` must remain blocked until the running service image contract matches the published artifact. | Not authorized. Prod dry-run must remain `runtime-verification-blocked`; live prod apply is unsupported. | Published artifact is the ML image contract while the long-running service is `met-nonlinear-ts`, so CD cannot prove the running container image label equals the requested commit. | Split the TS server artifact from the ML image or publish a labeled artifact that exactly matches `met-nonlinear-ts`; then add live commit proof before enabling apply. | | `k3sctl-adapter` | UniDesk-managed D601 direct Compose control bridge, outside the native k3s fault domain; it is the control path for k3s-managed services and must not be moved into k3s. | `CI.json` source-build supported through `ci publish-user-service --service k3sctl-adapter`; artifact is `127.0.0.1:5000/unidesk/k3sctl-adapter:` from the UniDesk Dockerfile. | Artifact consumer exposes plan/dry-run only for service/container `k3sctl-adapter`; live replacement is supervisor-only because replacing the bridge can remove the repair path for k3s. | No normal dev target. DEV acceptance is read-only bridge health, service catalog/proxy checks and dry-run contract review only. | Dry-run/read-only only in this lane. Real prod replacement requires explicit supervisor confirmation, rollback proof and out-of-band recovery access. | Must remain recoverable while k3s may be broken; worker automation must not self-replace or k3s-manage the bridge. | Write a supervised bridge-upgrade runbook with rollback and out-of-band access checks; keep CLI dry-run as the standard preflight. | | `code-queue` | Production execution plane is D601 native k3s (`unidesk` namespace) behind `k3sctl-adapter`; dev execution plane is `unidesk-dev` scheduler/read/write/provider-egress-proxy. Main-server `code-queue-mgr` is a separate control-plane sidecar. | `CI.json` source-build supported through `ci publish-user-service --service code-queue` for dev image validation only; artifact is `127.0.0.1:5000/unidesk/code-queue:`. | Reviewed dev-only k3s artifact consumer updates only `unidesk-dev` Code Queue objects. `deploy plan --env prod --service code-queue` and `artifact-registry deploy-service --env prod --service code-queue` must stay unsupported. | Allowed only as dry-run/source evidence here; a later human-approved dev live apply may consume the artifact into `unidesk-dev` outside the running Code Queue task. | Not implemented and not authorized. No production artifact deploy, manifest mutation, scheduler/runner restart, interrupt or cancel is allowed. | Production still has hostPath/source and active-run safety boundaries; self-deploy would couple the deployment actor to the target being replaced. | Keep dev dry-run coverage; design a separate supervisor-approved production CD consumer before any prod mutation is considered. | -| `decision-center` | D601 native k3s user service; dev runs `unidesk-dev/decision-center-dev`, prod runs `unidesk/decision-center`, both behind backend-core -> provider-gateway -> k3sctl-adapter -> Kubernetes API service proxy. | `CI.json` source-build supported through `ci publish-user-service --service decision-center`; artifact is `127.0.0.1:5000/unidesk/decision-center:` from the UniDesk Dockerfile. | Dev and prod are reviewed D601 k3s artifact consumers. Desired state, live health, and registry artifact must point at the same commit; drift where live is newer than `deploy.json` is corrected by repinning `deploy.json`, not by redeploying. | Closed for artifact CD when `deploy plan --env dev --service decision-center` is no-build and health reports matching `deploy.commit` / `deploy.requestedCommit`. Focused product gates remain record CRUD, diary lifecycle and frontend Decision Center visibility. | Closed for artifact CD when `deploy plan --env prod --service decision-center` is no-build and health reports matching `deploy.commit` / `deploy.requestedCommit`. Remaining acceptance is manual UI/product verification: health, records, diary editor, frontend page, no public business ports and live commit/artifact information. | Product completeness and manual UI acceptance can remain open, but they are not deployment drift. Registry artifact digest and health commit are the release evidence. | Keep dry-run and live health evidence sufficient so future desired-state edits cannot reintroduce source-build or stale-commit drift. | +| `decision-center` | NC01 k8s user service; prod runs `unidesk/deployment/decision-center` and `unidesk/service/decision-center` selected by `config/unidesk-host-k8s.yaml`. | Source image may still be built from the UniDesk Dockerfile, but production release evidence is YAML-first NC01 k8s state plus GitHub repo storage, not D601 registry artifact consumption. | D601 k3s artifact consumer is retired for the current production path. Desired state must include NC01 target, namespace, GitHub repo `pikasTech/decision-center-data`, base path `data`, and Secret sourceRef for `decision-center-github-ssh`. | Dev gate remains focused product validation: record CRUD, diary lifecycle, doc-number uniqueness and frontend visibility. It must not require a D601 `decision-center-dev` runtime as current truth. | Prod acceptance verifies NC01 `/health`, records, diary editor, frontend page, no public business ports, GitHub storage read/write and Secret presence/fingerprint. | Product completeness and manual UI acceptance can remain open, but PostgreSQL is index/cache only and D601 artifact evidence is not storage/deploy truth. | Keep YAML-first NC01 deploy and GitHub storage checks sufficient so future desired-state edits cannot reintroduce old D601/PostgreSQL truth. | Minimum evidence for this lane is: @@ -247,7 +247,7 @@ This table freezes the boundary between standard artifact services, upstream ima | Path | Classification | Current guardrail | Cleanup condition | | --- | --- | --- | --- | | `deploy apply --env prod` for services without a reviewed artifact consumer | Must stay disabled/degraded | returns structured unsupported and refuses maintenance-channel fallback | enable only after each service has a documented artifact producer, dev consumer, prod consumer and live verification | -| Local-manifest `deploy apply` for prod artifact consumers (`backend-core`, `frontend`, `baidu-netdisk`, `decision-center`) | Must stay disabled/degraded as a standard prod path | blocked before source build; operator is pointed to `deploy apply --env prod` | remove only after all production deploys use env-ref artifact consumers and no recovery runbook depends on local manifests | +| Local-manifest `deploy apply` for prod artifact consumers (`backend-core`, `frontend`, `baidu-netdisk`) | Must stay disabled/degraded as a standard prod path | blocked before source build; operator is pointed to `deploy apply --env prod`; Decision Center is excluded because its current prod path is NC01 YAML-first k8s + GitHub storage | remove only after all production deploys use env-ref artifact consumers and no recovery runbook depends on local manifests | | `artifact-registry deploy-backend-core` | Legacy compatibility entry | returns structured deprecated result; replacement is `deploy apply --env dev|prod --service backend-core` | remove after callers and docs use only `deploy apply --env dev|prod` | | `server rebuild frontend` and `server rebuild baidu-netdisk` | Maintenance / non-standard | docs classify as maintenance-only; standard release requires CI artifact plus dev/prod artifact consumer | keep until recovery runbooks have equivalent pull-only repair commands | | `server rebuild backend-core` | Diagnostic/recovery only; not Rust iteration or prod CD | docs forbid Rust iteration and prod backend-core artifact CD through this command | keep for bootstrap/recovery until backend-core artifact CD and rollback are proven under outage conditions | @@ -316,7 +316,7 @@ This matrix describes the next promotion stage after dry-run coverage is in plac | `project-manager` | `master` | source-build supported | dev + prod artifact consumer | dev artifact validation with `/api/projects` | prod artifact validation with live commit proof | none beyond standard artifact/CD checks | `MiniMax` for dry-run/reporting, `GPT-5.5` for release sign-off | | `oa-event-flow` | `master` | source-build supported | dev + prod artifact consumer | dev artifact validation with `/api/diagnostics` | prod artifact validation with live commit proof | none beyond standard artifact/CD checks | `MiniMax` for dry-run/reporting, `GPT-5.5` for release sign-off | | `todo-note` | `master` | external source-build supported | dev + prod Compose artifact consumer | consumer dry-run is ready; live dev remains blocked until the desired artifact exists | prod behavior is healthy, but runtime commit proof is absent until the no-build recreate lands image labels and health deploy metadata | registry artifact, runtime commit proof and health deploy metadata | `DeepSeek` for digesting external-source evidence, `GPT-5.5` for final gate | -| `decision-center` | `master` | source-build supported | dev + prod k3s consumer closed when desired/live/artifact commit match and dry-run stays no-build | dev artifact CD closed; remaining dev acceptance is focused record CRUD, diary lifecycle, doc-number uniqueness and frontend visibility | prod artifact CD closed; remaining prod acceptance is manual UI/product verification after health/live commit proof | doc-management completeness, PostgreSQL truth and UI acceptance; no deployment drift when desired/live/artifact are aligned | `GPT-5.5` | +| `decision-center` | `master` | source-build supported | NC01 YAML-first k8s + GitHub repo storage | dev acceptance is focused record CRUD, diary lifecycle, doc-number uniqueness and frontend visibility, without D601 runtime as current truth | prod acceptance is NC01 health, GitHub read/write, frontend and CLI proof | doc-management completeness, GitHub storage migration/backfill and UI acceptance; PostgreSQL is index/cache only | `GPT-5.5` | | `mdtodo` | `master` | source-build supported | dev + prod k3s consumer | dev service is absent until the health-metadata-capable desired artifact is published and `unidesk-dev/mdtodo-dev` is created/verified | prod is healthy at the previous annotated commit, but the desired artifact now points at the commit that added `/health.deploy` and `/live.deploy`; prod replacement remains blocked until dev proof exists | registry artifact, dev service, runtime health metadata proof and prod runtime commit drift; no NodePort/hostPort/public backend exposure | `MiniMax` for prompt prep, `GPT-5.5` for approval | | `claudeqq` | `master` | source-build supported | dev + prod k3s consumer | dev service is absent until the desired artifact is published and `unidesk-dev/claudeqq-dev` is created/verified | prod health reports the desired commit and NapCat login, but artifact and event API proof remain open | registry artifact, dev service, event API surface; NapCat/backend port exposure must stay private | `MiniMax` for prompt prep, `GPT-5.5` for approval | | `findjob` | `master` | source-build supported | dev + prod direct Compose consumer | pull-only dev validation on D601 with image labels and `/api/health` | pull-only prod recreate with live commit proof | target-side compose health/labels only, no public business ports | `DeepSeek` for dry-run matrix drafting, `GPT-5.5` for final gate | diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 8122a7a8..8a4fbb95 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -74,9 +74,9 @@ PipelineRun 失败或长时间未完成时，先按定点 `control-plane status - `trans :k3s[:namespace:workload[:container]] ...` 是原生 k3s 结构化 route 入口，route 只定位控制面或 workload，`kubectl`、`logs`、`exec`、`sh`、`bash`、`apply-patch`、旧 `apply-patch-v1` fallback 和普通容器命令作为 operation 放在 route 之后；CLI 固定注入 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml` 并把 kubectl、workload exec、logs 和 pod workspace 读写参数组装成 argv，避免在 Host SSH、bash、kubectl exec 和容器 shell 之间反复手写多层引号；D601 与 G14 都有 provider-specific guard，分别校验 `d601` 和 G14 k3s 节点身份。 - Code Queue runner 镜像必须在 PATH 上提供 `/usr/local/bin/tran`。runner 内的 `tran` 检测到 `CODE_QUEUE_*` 或 `KUBERNETES_SERVICE_HOST` 后，默认执行 `bun /root/unidesk/scripts/cli.ts --main-server-ip ssh ...`，其中 `` 优先来自 `UNIDESK_MAIN_SERVER_IP` / `UNIDESK_MAIN_SERVER_HOST` / `CODE_QUEUE_DEV_CONTAINER_MASTER_HOST`。runner remote frontend HTTP 客户端默认使用 `curl` 后端，降低 Bun 在部分 runner 内读取非 SSH HTTP response body 时触发 native crash 的风险；显式 `UNIDESK_REMOTE_HTTP_CLIENT=fetch` 可用于诊断。runner 内跨 D601/G14 的分布式访问应优先使用结构化 route/operation，例如 `tran D601 argv ...`、`tran G14 argv ...`、`tran D601:k3s kubectl ...`、`tran D601:k3s:: argv ...`、`tran G14:/absolute/workspace apply-patch ...` 和 `tran upload|download ...`；`apply-patch`、`upload`、`download`、`sh`、`bash`、`py` 和旧 `apply-patch-v1` fallback 经 frontend `/ws/ssh` 通道执行，stdout/stderr 也必须完整直通，不得退回 `/api/dispatch` task JSON。非 UniDesk admin runner 可通过 `UNIDESK_SSH_CLIENT_TOKEN` 使用 scoped `/ws/ssh` client token，frontend 侧用 `UNIDESK_SSH_CLIENT_ROUTE_ALLOWLIST` 约束允许 route；该 token 只授予 ssh passthrough，不下发 provider token、主 server SSH key 或完整 frontend 登录态。 - `microservice list/status/health/diagnostics/tunnel-self-test/proxy` 通过 backend-core 内网 API 管理挂载在计算节点 Docker 或 k3s 控制面中的用户服务（底层命令名仍为 microservice）；`health`、`status` 和 `diagnostics` 默认返回 compact summary、body 字节数和 `--full|--raw` 展开命令，只有小 body 或无法抽取 summary 时才带有界 body preview，避免 Code Queue/k3s 诊断一次性输出爆炸；`tunnel-self-test` 和 `proxy` 会走真实 backend-core -> provider-gateway 或 k3sctl-adapter -> 节点服务链路。`microservice health code-queue` 使用 commander-safe 专用摘要，必须保留 ok/status、service id、running count、queue count、heartbeat freshness/risk、split-brain/live/degraded 解释和 raw drill-down 命令；需要完整健康 JSON 时显式加 `--raw` 或 `--full`，等价深挖路径是 `microservice proxy code-queue /health --raw --full`。`proxy` 支持受控 JSON 请求体并对超大响应 body 默认输出有界预览，规则见 `docs/reference/microservices.md`。 -- `decision upload/list/show/health` 通过 backend-core 用户服务代理访问 D601 k3s Decision Center，用于上传会议记录/决议 Markdown、列出权威记录、查看详情和健康检查；`decision list` 默认只返回摘要并省略完整 Markdown body，需要排查大正文时显式加 `--include-body`。正式文书字段通过 records 模型一等字段返回和查询：`--doc-no DC-...`、`--doc-type DCSN|GOAL|PLAN|RPRT|ACTN|ISSU|RETR|RQST|RESP|MINS`、`--doc-priority P0|P1|P2|P3`、`--year YYYY`、`--signer`、`--issued-at`、`--effective-scope`、`--supersedes`、`--superseded-by`；`show` 和 `requirement update` 可使用 `id` 或 `docNo`。`decision requirement list/create/upsert/update/show` 在同一 records 模型上管理 `goal|decision|blocker|debt|experiment` 需求记录，`docNo` 唯一，未传 `--doc-no` 但提供 `--doc-type/--doc-priority/--year` 时由服务分配下一个序号。它们不得直连 D601 Service、NodePort 或 provider-gateway 业务 HTTP。 -- `decision diary import ` 将带 `# YYYY年M月D日`、`# YYYY-MM-DD` 或 `# YYYY/M/D` 标题的工作日志拆成每天一篇 Markdown 日记，按 `YYYY-MM/YYYY-MM-DD.md` 虚拟路径写入 Decision Center PostgreSQL；`decision diary list/history` 默认只返回摘要，需要完整 Markdown 时显式加 `--include-body`；`decision diary show [--source-file path]` 查看单日正文，`--source-file` 用于同一天存在多个导入来源时精确选择；`decision diary edit|upsert --body-file [--title text] [--source-file path] [--tag tag]` 通过 `PUT /api/diary/entries/:idOrDate` 创建当天或历史条目并编辑既有条目。 -- `deploy check/plan/apply` 默认从根目录 `deploy.json` 读取服务 repo 与 commit 期望状态，join `config.json` 和现有 manifest 后使用 target-side build 或 reviewed artifact consumer 校验/更新已支持目标；`deploy plan --env dev|prod` 只从 `origin/master:deploy.json#environments.` 读取 manifest 并输出 dry-run 环境计划，不使用本地 dirty worktree；当前 `deploy apply --env dev` 支持 `backend-core`、`frontend`、`baidu-netdisk`、`decision-center`、`mdtodo`、`claudeqq` 和 dev-only `code-queue` artifact consumers，`findjob`/`pipeline`/`met-nonlinear` 为 D601 direct Compose artifact consumers，`k3sctl-adapter` 只提供 plan/dry-run；dev desired-state smoke 使用 `ci run-dev-e2e`；规则见 `docs/reference/deploy.md`、`docs/reference/dev-environment.md` 和 `docs/reference/dev-ci-runner.md`。`deploy apply --env prod` 同时覆盖 `findjob` 和 `pipeline` 的 pull-only Compose CD，但 `met-nonlinear` 仍然只允许 dry-run/plan，`k3sctl-adapter` 只允许 plan/dry-run。 +- `decision upload/list/show/health` 通过 `config/unidesk-host-k8s.yaml` 选择 NC01 k8s `unidesk/decision-center` 入口，用于上传会议记录/决议 Markdown、列出权威记录、查看详情和健康检查；持久化权威是 GitHub repo `pikasTech/decision-center-data` 的 `main:data`，PostgreSQL 只作为运行时索引/缓存。`decision list` 默认只返回摘要并省略完整 Markdown body，需要排查大正文时显式加 `--include-body`。正式文书字段通过 records 模型一等字段返回和查询：`--doc-no DC-...`、`--doc-type DCSN|GOAL|PLAN|RPRT|ACTN|ISSU|RETR|RQST|RESP|MINS`、`--doc-priority P0|P1|P2|P3`、`--year YYYY`、`--signer`、`--issued-at`、`--effective-scope`、`--supersedes`、`--superseded-by`；`show` 和 `requirement update` 可使用 `id` 或 `docNo`。`decision requirement list/create/upsert/update/show` 在同一 records 模型上管理 `goal|decision|blocker|debt|experiment` 需求记录，`docNo` 唯一，未传 `--doc-no` 但提供 `--doc-type/--doc-priority/--year` 时由服务分配下一个序号。它们不得直连 Service、NodePort、provider-gateway 业务 HTTP 或旧 D601 Decision Center 路径。 +- `decision diary import ` 将带 `# YYYY年M月D日`、`# YYYY-MM-DD` 或 `# YYYY/M/D` 标题的工作日志拆成每天一篇 Markdown 日记，按 `YYYY-MM/YYYY-MM-DD.md` 虚拟路径写入 Decision Center GitHub 存储；`decision diary list/history` 默认只返回摘要，需要完整 Markdown 时显式加 `--include-body`；`decision diary show [--source-file path]` 查看单日正文，`--source-file` 用于同一天存在多个导入来源时精确选择；`decision diary edit|upsert --body-file [--title text] [--source-file path] [--tag tag]` 通过 `PUT /api/diary/entries/:idOrDate` 创建当天或历史条目并编辑既有条目。 +- `deploy check/plan/apply` 默认从根目录 `deploy.json` 读取服务 repo 与 commit 期望状态，join `config.json` 和现有 manifest 后使用 target-side build 或 reviewed artifact consumer 校验/更新已支持目标；`deploy plan --env dev|prod` 只从 `origin/master:deploy.json#environments.` 读取 manifest 并输出 dry-run 环境计划，不使用本地 dirty worktree；当前 `deploy apply --env dev` 支持 `backend-core`、`frontend`、`baidu-netdisk`、`mdtodo`、`claudeqq` 和 dev-only `code-queue` artifact consumers，`findjob`/`pipeline`/`met-nonlinear` 为 D601 direct Compose artifact consumers，`k3sctl-adapter` 只提供 plan/dry-run；Decision Center 生产部署走 NC01 YAML-first k8s + GitHub repo storage，不再用 D601 artifact consumer 作为当前 closeout；dev desired-state smoke 使用 `ci run-dev-e2e`；规则见 `docs/reference/deploy.md`、`docs/reference/dev-environment.md` 和 `docs/reference/dev-ci-runner.md`。`deploy apply --env prod` 同时覆盖 `findjob` 和 `pipeline` 的 pull-only Compose CD，但 `met-nonlinear` 仍然只允许 dry-run/plan，`k3sctl-adapter` 只允许 plan/dry-run。 - `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，以及只读挂载宿主 `/home/ubuntu/.agents/skills` 到容器 `/root/.agents/skills` 的 `skills-dir` volume。加 `--kubectl-dry-run` 时额外以 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml` 执行 `kubectl apply --dry-run=client --validate=false -f `，仍不 apply 资源；默认 `docker-desktop` kubeconfig 不得作为 D601 dry-run 目标。 - `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|deploy-backend-core|deploy-service` 管理 D601 host-managed CNCF Distribution registry 的声明、安装、只读检查和 pull-only artifact CD。该 registry 固定为 D601 loopback `127.0.0.1:5000`，由 systemd + Docker Compose 管理，位于 native k3s 故障域外；`deploy-service` 只拉取 CI 已发布的 commit-pinned 镜像、retag/recreate 或导入 native k3s，并做 live commit 验证，不构建 runtime source。`deploy-backend-core` 是 deprecated 兼容名，标准 backend-core prod CD 入口是 `deploy apply --env prod --service backend-core`。长期规则见 `docs/reference/artifact-registry.md`。 @@ -161,9 +161,9 @@ UniDesk/HWLAB Web 开发、HWLAB `web-probe run|script|observe|screenshot`、fak 定点状态查询优先使用后台 job 输出的稳定对象名：PipelineRun 用 `hwlab g14 control-plane status --lane v02 --pipeline-run `，已知 source commit 用 `--source-commit `。不要在 source branch 可能继续推进时用默认最新 head status 判定历史 run 成败；默认最新 head 口径只适合判断当前 lane 是否整体最新。`control-plane status` 会汇总 source、mirror、Tekton、Argo、runtime workload 和公网探针，可能比普通只读命令慢；高频轮询应先用 `job status` 或更窄的 status，完整 status 留给阶段收口和异常定位。 -`server rebuild` 与 `server start`、`server stop` 一样必须通过返回的 job id 确认结果；不要把连续 `server rebuild` 命令理解成“前一个重建已完成”，因为两个命令只是在快速创建异步 job。重建 frontend 只保留为维护/非标准路径；标准 frontend 发布必须先运行 `ci publish-user-service --service frontend --commit `，再运行 `deploy apply --env dev --service frontend` 和 `deploy apply --env prod --service frontend`，并验证 `/health.deploy.commit`。重建 dev 入口薄代理使用 `bun scripts/cli.ts server rebuild dev-frontend-proxy`，随后验证 `server status` 的 `urls.devFrontend` 和 `http://127.0.0.1:18083/health`；重建 Todo Note 后端使用 `bun scripts/cli.ts server rebuild todo-note`，随后用 `microservice health todo-note` 和 `microservice proxy todo-note /api/instances` 验证；重建 Code Queue Manager 使用 `bun scripts/cli.ts server rebuild code-queue-mgr`，随后用 `microservice health code-queue-mgr`、`microservice health code-queue`、`codex tasks --view commander --limit 5` 和冻结的 `codex submit` 返回 `legacy-code-queue-frozen` 验证主 server 控制面路径；重建 Project Manager 后端使用 `bun scripts/cli.ts server rebuild project-manager`，随后用 `microservice health project-manager` 和 `microservice proxy project-manager /api/projects` 验证；重建 Baidu Netdisk 后端使用 `bun scripts/cli.ts server rebuild baidu-netdisk`，随后用 `microservice health baidu-netdisk` 和 `microservice proxy baidu-netdisk /api/transfers` 验证，但该命令只保留为维护/非标准路径；重建 OA Event Flow 后端使用 `bun scripts/cli.ts server rebuild oa-event-flow`，随后用 `microservice health oa-event-flow` 和 `microservice proxy oa-event-flow /api/diagnostics` 验证。D601 Code Queue 执行面和 Decision Center 后端由 D601 k3s/k8s 控制面代管；persistent dev backend-core、frontend 和 Decision Center 都走 artifact consumer，当前 Code Queue 仍不得通过维护通道直连 D601 做部署。不得把 `docker rm` 手工兜底当成正式交付步骤。 +`server rebuild` 与 `server start`、`server stop` 一样必须通过返回的 job id 确认结果；不要把连续 `server rebuild` 命令理解成“前一个重建已完成”，因为两个命令只是在快速创建异步 job。重建 frontend 只保留为维护/非标准路径；标准 frontend 发布必须先运行 `ci publish-user-service --service frontend --commit `，再运行 `deploy apply --env dev --service frontend` 和 `deploy apply --env prod --service frontend`，并验证 `/health.deploy.commit`。重建 dev 入口薄代理使用 `bun scripts/cli.ts server rebuild dev-frontend-proxy`，随后验证 `server status` 的 `urls.devFrontend` 和 `http://127.0.0.1:18083/health`；重建 Todo Note 后端使用 `bun scripts/cli.ts server rebuild todo-note`，随后用 `microservice health todo-note` 和 `microservice proxy todo-note /api/instances` 验证；重建 Code Queue Manager 使用 `bun scripts/cli.ts server rebuild code-queue-mgr`，随后用 `microservice health code-queue-mgr`、`microservice health code-queue`、`codex tasks --view commander --limit 5` 和冻结的 `codex submit` 返回 `legacy-code-queue-frozen` 验证主 server 控制面路径；重建 Project Manager 后端使用 `bun scripts/cli.ts server rebuild project-manager`，随后用 `microservice health project-manager` 和 `microservice proxy project-manager /api/projects` 验证；重建 Baidu Netdisk 后端使用 `bun scripts/cli.ts server rebuild baidu-netdisk`，随后用 `microservice health baidu-netdisk` 和 `microservice proxy baidu-netdisk /api/transfers` 验证，但该命令只保留为维护/非标准路径；重建 OA Event Flow 后端使用 `bun scripts/cli.ts server rebuild oa-event-flow`，随后用 `microservice health oa-event-flow` 和 `microservice proxy oa-event-flow /api/diagnostics` 验证。D601 Code Queue 执行面由 D601 k3s/k8s 控制面代管；Decision Center 由 NC01 k8s 代管并写入 GitHub repo storage；persistent dev backend-core/frontend 仍走 artifact consumer，当前 Code Queue 仍不得通过维护通道直连 D601 做部署。不得把 `docker rm` 手工兜底当成正式交付步骤。 -新部署入口优先使用 `deploy apply`。`deploy apply --env dev --service backend-core` 是 D601 k3s artifact consumer，消费 `ci publish-backend-core` 产出的成品镜像；`deploy apply --env dev|prod --service frontend`、`deploy apply --env dev|prod --service baidu-netdisk` 和 `deploy apply --env dev|prod --service decision-center` 是 artifact-consumer 样板；旧的 `codex deploy` 已禁用；后续 Code Queue 等 D601 服务部署应另行收敛到同一类受控 CD 路径，部署后用 live commit 校验证明不是旧服务。 +新部署入口优先使用受控 deploy path。`deploy apply --env dev --service backend-core` 是 D601 k3s artifact consumer，消费 `ci publish-backend-core` 产出的成品镜像；`deploy apply --env dev|prod --service frontend` 和 `deploy apply --env dev|prod --service baidu-netdisk` 是 artifact-consumer 样板；Decision Center 当前样板是 NC01 YAML-first k8s + GitHub repo storage；旧的 `codex deploy` 已禁用；后续 Code Queue 等 D601 服务部署应另行收敛到同一类受控 CD 路径，部署后用 live commit 校验证明不是旧服务。 ## Output Contract diff --git a/docs/reference/deploy.md b/docs/reference/deploy.md index 65236642..5ea97bfb 100644 --- a/docs/reference/deploy.md +++ b/docs/reference/deploy.md @@ -52,7 +52,7 @@ The root `deploy.json` is the single desired-state source for both prod and dev. The optional non-service execution declaration under `environments.dev` is intentionally not specified here. The only currently allowed declaration is `ci`, and its authoritative `repo`, `scriptPath`, `timeoutMs`, short launcher, host fetch boundary and no-CD rules are defined only in `docs/reference/dev-ci-runner.md`. -Environment mode never reads the local dirty working tree manifest. `deploy check --env ...`, `deploy plan --env ...` and `deploy apply --env ...` fetch `origin/master`, read `origin/master:deploy.json`, select `environments.`, and report the manifest commit/blob, service commit IDs, target namespace, database fingerprint and Provider identity. `deploy apply --env dev` is currently enabled for reviewed artifact consumers `backend-core`, `frontend`, `baidu-netdisk`, `decision-center`, `mdtodo`, `claudeqq`, dev-only `code-queue`, `project-manager`, `oa-event-flow`, `code-queue-mgr`, `todo-note`, `findjob`, `pipeline` and `met-nonlinear`. `deploy apply --env prod` exposes reviewed registry artifact consumers (`backend-core`, `frontend`, `baidu-netdisk`, `decision-center`, `mdtodo`, `claudeqq`, `project-manager`, `oa-event-flow`, `todo-note`, `findjob`, `pipeline` and `met-nonlinear`), while `code-queue` must report unsupported, `code-queue-mgr` remains supervisor-gated and `k3sctl-adapter` is plan/dry-run only. Backend-core artifact CD is a pull-only consumer in both dev and prod; the build target is D601 CI, while dev runtime target is D601 native k3s and prod runtime target is the master server Compose stack. The default user-service delivery policy, including CI build, registry publication, dev validation, production CD and manual acceptance, is documented in `docs/reference/user-service-delivery.md`. +Environment mode never reads the local dirty working tree manifest. `deploy check --env ...`, `deploy plan --env ...` and `deploy apply --env ...` fetch `origin/master`, read `origin/master:deploy.json`, select `environments.`, and report the manifest commit/blob, service commit IDs, target namespace, database fingerprint and Provider identity. `deploy apply --env dev` is currently enabled for reviewed artifact consumers `backend-core`, `frontend`, `baidu-netdisk`, `mdtodo`, `claudeqq`, dev-only `code-queue`, `project-manager`, `oa-event-flow`, `code-queue-mgr`, `todo-note`, `findjob`, `pipeline` and `met-nonlinear`. `deploy apply --env prod` exposes reviewed registry artifact consumers (`backend-core`, `frontend`, `baidu-netdisk`, `mdtodo`, `claudeqq`, `project-manager`, `oa-event-flow`, `todo-note`, `findjob`, `pipeline` and `met-nonlinear`), while Decision Center uses the NC01 YAML-first k8s path and GitHub storage checks, `code-queue` must report unsupported, `code-queue-mgr` remains supervisor-gated and `k3sctl-adapter` is plan/dry-run only. Backend-core artifact CD is a pull-only consumer in both dev and prod; the build target is D601 CI, while dev runtime target is D601 native k3s and prod runtime target is the master server Compose stack. The default user-service delivery policy, including CI build, registry publication, dev validation, production CD and manual acceptance, is documented in `docs/reference/user-service-delivery.md`. `--commit ` is allowed only with `--env dev|prod --service ` for reviewed artifact consumers. It overrides the selected service commit for that one artifact consumer while still using the Git-backed environment manifest for target, namespace, repo, deploy ref and guardrails. It is the supported temporary shape for release-line frontend/backend-core validation and rollback when the artifact was produced from a pushed `release/v1` commit but `origin/master:deploy.json#environments..services..commitId` has not been repinned. It must not be used for local-manifest mode, multi-service apply, or target-side source-build services. @@ -62,7 +62,7 @@ The current implementation has not yet enabled separate stable and integration d CI/CD server and control-plane services are normal deployable services for versioning purposes: production runtime must be pinned by `deploy.json` to a known commit. A CLI built from `master` may orchestrate the pinned server only through backward-compatible APIs and server-reported capabilities; it must not bypass server-side deploy policy when the pinned server does not support a requested operation. -The only D601 direct-service exception in local manifest mode is `k3sctl-adapter`, because it is the UniDesk-managed control bridge outside the k3s fault domain and owns the Kubernetes service catalog used by the dev public frontend path. Its artifact consumer path is plan/dry-run only and never performs real prod deployment without supervisor confirmation. D601 Code Queue, Decision Center, MDTODO, ClaudeQQ and future k3s-managed workloads remain blocked from maintenance-channel direct deploy. +The only D601 direct-service exception in local manifest mode is `k3sctl-adapter`, because it is the UniDesk-managed control bridge outside the k3s fault domain and owns the Kubernetes service catalog used by the dev public frontend path. Its artifact consumer path is plan/dry-run only and never performs real prod deployment without supervisor confirmation. D601 Code Queue, MDTODO, ClaudeQQ and future k3s-managed workloads remain blocked from maintenance-channel direct deploy. Decision Center is also blocked from maintenance-channel direct deploy, but its current runtime lane is NC01 k8s rather than D601. `config.json.microservices[].repository.commitId` is retained for catalog compatibility, but `deploy.json` is the deployment version authority for the reconciler. @@ -99,7 +99,7 @@ Phase 3 introduces the dev backend/frontend manifest at `src/components/microser `backend-core-dev` must use `unidesk-dev-runtime-config` and `unidesk-dev-runtime-secrets`, connect to `postgres-dev.../unidesk_dev`, expose HTTP on 8080 and provider ingress on 8081, and write logs under `/var/log/unidesk-dev`. `frontend-dev` must set `CORE_INTERNAL_URL=http://backend-core-dev.unidesk-dev.svc.cluster.local:8080` and must not proxy to production backend-core. -The manifest keeps placeholder image tags and deploy commit values in source control. The controlled `deploy apply --env dev --service backend-core` path consumes the existing D601 registry artifact `127.0.0.1:5000/unidesk/backend-core:` produced by `ci publish-backend-core`; it does not compile Rust or build a Docker image during CD. Backend-core and frontend use the same selected dev core manifest objects: CD verifies the commit-pinned registry image and labels, imports the artifact into native k3s containerd, applies only the selected `unidesk-dev` objects, stamps the Deployment, and verifies live commit/requestedCommit through the Kubernetes API service proxy. Decision Center, MDTODO and ClaudeQQ use the same dev namespace and D601 registry artifact consumer path. `project-manager`, `oa-event-flow`, `code-queue-mgr`, `todo-note`, `findjob`, `pipeline` and `met-nonlinear` consume existing D601 registry artifacts for direct Docker/Compose validation rather than separate parallel k3s dev instances; `code-queue-mgr` live prod apply remains supervisor-gated. Client dry-run and static validation remain useful checks before controlled apply: +The manifest keeps placeholder image tags and deploy commit values in source control. The controlled `deploy apply --env dev --service backend-core` path consumes the existing D601 registry artifact `127.0.0.1:5000/unidesk/backend-core:` produced by `ci publish-backend-core`; it does not compile Rust or build a Docker image during CD. Backend-core and frontend use the same selected dev core manifest objects: CD verifies the commit-pinned registry image and labels, imports the artifact into native k3s containerd, applies only the selected `unidesk-dev` objects, stamps the Deployment, and verifies live commit/requestedCommit through the Kubernetes API service proxy. MDTODO and ClaudeQQ use the same dev namespace and D601 registry artifact consumer path. Decision Center is governed by the NC01 YAML-first k8s lane and GitHub repo storage checks instead of this D601 dev namespace. `project-manager`, `oa-event-flow`, `code-queue-mgr`, `todo-note`, `findjob`, `pipeline` and `met-nonlinear` consume existing D601 registry artifacts for direct Docker/Compose validation rather than separate parallel k3s dev instances; `code-queue-mgr` live prod apply remains supervisor-gated. Client dry-run and static validation remain useful checks before controlled apply: - `bun scripts/cli.ts dev-env validate --manifest src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-core.k8s.yaml` - `KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl apply --dry-run=client --validate=false -f src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-core.k8s.yaml` @@ -128,7 +128,7 @@ Environment plan output must be sufficient to review the artifact matrix without For `--env dev --service code-queue`, the environment plan must also expose a `boundary` block that separates the CI producer from the dev CD consumer. CI is allowed to publish only `127.0.0.1:5000/unidesk/code-queue:` plus digest/label evidence. DEV CD may consume that artifact only for `unidesk-dev` Code Queue scheduler/read/write/provider-egress-proxy objects after an operator reviews the dry-run; the plan must set `artifactConsumer.dryRunOnly=true`, `liveApply.allowed=false`, `requiresSupervisorApproval=true`, and expose a `selfBootstrapGuard` so a running Code Queue task cannot authorize its own replacement. For `--env prod --service code-queue`, the service item must remain `deploymentPath=unsupported`, `artifactConsumer.consumerKind=unsupported`, `target.deployCommandShape=none` and `liveApply.allowed=false`; it must not expose production k3s as an executable target. The prod boundary must state that production Code Queue CD needs a future supervisor-approved design and that this runner cannot self-deploy, mutate the production namespace, restart scheduler/runner, or interrupt/cancel tasks. -`bun scripts/cli.ts deploy apply [--file deploy.json | --env dev|prod] [--service ] [--commit ] [--dry-run] [--force]` starts an asynchronous job only for supported targets. Use `bun scripts/cli.ts job status --tail-bytes 30000` to observe progress. `--dry-run` resolves the same plan but does not build or replace runtime objects. `--force` redeploys even when the live commit matches. Environment apply is not the dev e2e trigger; use `bun scripts/cli.ts ci run-dev-e2e` for the Git-controlled temporary namespace smoke flow. `--env dev` apply is enabled for `backend-core`/`frontend`/`baidu-netdisk`/`decision-center`/`mdtodo`/`claudeqq`/dev-only `code-queue` dry-run/authorized apply, `project-manager`/`oa-event-flow`/`code-queue-mgr`/`todo-note`/`findjob`/`pipeline`/`met-nonlinear` artifact consumers. `--env prod` apply exposes the D601 registry artifact consumer for `backend-core`, `frontend`, `baidu-netdisk`, `decision-center`, `mdtodo`, `claudeqq`, `project-manager`, `oa-event-flow`, `todo-note`, `findjob`, `pipeline` and `met-nonlinear`; `code-queue-mgr` prod live apply is supervisor-gated and `k3sctl-adapter` is plan/dry-run only. `--commit` may override one selected reviewed artifact consumer in either dev or prod, for example `deploy apply --env dev --service backend-core --commit ` or `deploy apply --env dev --service frontend --commit `, and the image must already exist as `127.0.0.1:5000/unidesk/:`. Unsupported prod services, especially `code-queue`, return a structured `unsupported` payload instead of silently falling back to a maintenance-channel source build. +`bun scripts/cli.ts deploy apply [--file deploy.json | --env dev|prod] [--service ] [--commit ] [--dry-run] [--force]` starts an asynchronous job only for supported targets. Use `bun scripts/cli.ts job status --tail-bytes 30000` to observe progress. `--dry-run` resolves the same plan but does not build or replace runtime objects. `--force` redeploys even when the live commit matches. Environment apply is not the dev e2e trigger; use `bun scripts/cli.ts ci run-dev-e2e` for the Git-controlled temporary namespace smoke flow. `--env dev` apply is enabled for `backend-core`/`frontend`/`baidu-netdisk`/`mdtodo`/`claudeqq`/dev-only `code-queue` dry-run/authorized apply, `project-manager`/`oa-event-flow`/`code-queue-mgr`/`todo-note`/`findjob`/`pipeline`/`met-nonlinear` artifact consumers. `--env prod` apply exposes the D601 registry artifact consumer for `backend-core`, `frontend`, `baidu-netdisk`, `mdtodo`, `claudeqq`, `project-manager`, `oa-event-flow`, `todo-note`, `findjob`, `pipeline` and `met-nonlinear`; Decision Center production uses NC01 YAML-first k8s + GitHub storage, `code-queue-mgr` prod live apply is supervisor-gated and `k3sctl-adapter` is plan/dry-run only. `--commit` may override one selected reviewed artifact consumer in either dev or prod, for example `deploy apply --env dev --service backend-core --commit ` or `deploy apply --env dev --service frontend --commit `, and the image must already exist as `127.0.0.1:5000/unidesk/:`. Unsupported prod services, especially `code-queue`, return a structured `unsupported` payload instead of silently falling back to a maintenance-channel source build. All deploy commands output JSON. Long operations must use `.state/jobs/` and bounded log tails; no deploy path may succeed with missing progress output. @@ -204,7 +204,7 @@ The reconciler selects the executor from `config.json`: - `deployment.mode=internal-sidecar` on `main-server`: use the same main-server target-side source export, Docker build, image label stamping, fixed Compose project replacement and live commit verification as direct Compose services. This class is for private sidecars such as `code-queue-mgr`; it is still versioned by `deploy.json.commitId`, not by the operator's current worktree, and prod live apply remains supervisor-gated. - `deployment.mode=unidesk-direct` on a provider: this executor is disabled for D601 service deployment. The historical behavior dispatched `host.ssh` to the provider, built on the provider, then used the service's provider-local compose file and project; that shape must not remain a second deployment control plane. - Control bridges that UniDesk needs in order to inspect or repair an orchestrator must stay in this direct class. In particular, `k3sctl-adapter` is a UniDesk-managed bridge to native k3s and must remain outside k3s; Docker packaging on Docker Desktop/WSL must create an explicit host-local bridge, currently an adapter-container SSH local tunnel, to reach `/etc/rancher/k3s/k3s.yaml` and WSL `127.0.0.1:6443`. -- `deployment.mode=k3sctl-managed`: the target behavior is to build on the active control target unless the service has a reviewed artifact-consumer exception, verify native k3s on the host OS/WSL distro, import the image into native k3s/containerd, apply the existing Kubernetes manifest, stamp the Deployment and wait for rollout. On D601, persistent dev apply uses artifact consumption for `backend-core`, `frontend`, `decision-center`, `mdtodo`, `claudeqq` and dev-only `code-queue` in `unidesk-dev`; production artifact consumers are limited to reviewed services and exclude Code Queue. Normal production services still cannot use a maintenance-channel direct rollout. The executor must use the native kubeconfig and containerd socket, for example `/etc/rancher/k3s/k3s.yaml` and `/run/k3s/containerd/containerd.sock`; running k3s itself in Docker is forbidden for both control-plane and worker nodes. A `rancher/k3s` image or legacy container may only be used as a temporary artifact source during migration, and any active containerized k3s control plane must be stopped before verification succeeds. The executor must preload a valid `rancher/mirrored-pause:3.6` sandbox image into native k3s containerd through the provider-gateway one-shot egress path, verify its entrypoint is `/pause`, and reject fake or sleep-based replacement images. k3s-managed deploys must use ClusterIP Services and Kubernetes API service proxy health checks; they must not add NodePort, hostPort, public business ports or provider-gateway direct business backends. +- `deployment.mode=k3sctl-managed`: the target behavior is to build on the active control target unless the service has a reviewed artifact-consumer exception, verify native k3s on the host OS/WSL distro, import the image into native k3s/containerd, apply the existing Kubernetes manifest, stamp the Deployment and wait for rollout. On D601, persistent dev apply uses artifact consumption for `backend-core`, `frontend`, `mdtodo`, `claudeqq` and dev-only `code-queue` in `unidesk-dev`; production artifact consumers are limited to reviewed services and exclude Code Queue. Decision Center is excluded from this D601 k3s-managed lane because current production is NC01 YAML-first k8s + GitHub storage. Normal production services still cannot use a maintenance-channel direct rollout. The executor must use the native kubeconfig and containerd socket, for example `/etc/rancher/k3s/k3s.yaml` and `/run/k3s/containerd/containerd.sock`; running k3s itself in Docker is forbidden for both control-plane and worker nodes. A `rancher/k3s` image or legacy container may only be used as a temporary artifact source during migration, and any active containerized k3s control plane must be stopped before verification succeeds. The executor must preload a valid `rancher/mirrored-pause:3.6` sandbox image into native k3s containerd through the provider-gateway one-shot egress path, verify its entrypoint is `/pause`, and reject fake or sleep-based replacement images. k3s-managed deploys must use ClusterIP Services and Kubernetes API service proxy health checks; they must not add NodePort, hostPort, public business ports or provider-gateway direct business backends. D601 Docker local images are not the source of truth for k3s runtime availability. For Code Queue, the deploy gate must verify `unidesk-code-queue:d601` exists in native k3s containerd after import with `ctr --address /run/k3s/containerd/containerd.sock -n k8s.io images ls`, and it must fail before rollout if the tag is missing. The same gate must verify every production Code Queue Deployment that uses the image (`code-queue`, `code-queue-read`, `code-queue-write`, `d601-provider-egress-proxy`, `d601-tcp-egress-gateway`) still references exactly `unidesk-code-queue:d601`; otherwise kubelet may attempt an external registry pull and leave base gateways in `ImagePullBackOff`. @@ -216,7 +216,7 @@ Baidu Netdisk is the main-server `unidesk-direct` sample for artifact CD and a d For PGDATA-to-Baidu-Netdisk incident review, the no-authorization read-only boundary is limited to `server status`, `schedule list`, `schedule get`, `schedule runs`, `microservice status/health baidu-netdisk`, `microservice proxy baidu-netdisk /api/auth/status --raw`, and `microservice proxy baidu-netdisk '/api/transfers?limit=20' --raw`. These commands may report `failureKind=target-stack-not-running` when `unidesk-backend-core`, `unidesk-database`, or `baidu-netdisk-backend` is absent, especially when only `*.verify-*` containers are visible; that state is an infrastructure blocker, not a successful empty backup history. Recovery actions such as restoring non-empty Baidu secrets, `server start`, `server rebuild backend-core`, `server rebuild baidu-netdisk`, `deploy apply --env prod --service baidu-netdisk`, `schedule run`, or `schedule retry-run` can affect production or trigger a real backup and require explicit operator authorization. -Decision Center is a standard `k3sctl-managed` service in this model, but D601 maintenance-channel direct apply must not deploy it. Controlled CD for Decision Center uses the D601 registry artifact consumer in both dev and prod: it verifies `unidesk/decision-center:` exists in the registry, imports `unidesk-decision-center:` into native k3s containerd, applies the appropriate Decision Center manifest, stamps the Deployment, and verifies health through `/api/microservices/decision-center/health` while proving the live and requested commit match. It must not add a main-server Compose service, NodePort, hostPort, or provider-gateway direct HTTP backend for Decision Center. +Decision Center no longer uses the D601 registry artifact consumer as its current production deploy path. Current controlled CD for Decision Center is the NC01 YAML-first k8s path: apply the declared target from `config/unidesk-host-k8s.yaml`, verify `unidesk/deployment/decision-center` and `unidesk/service/decision-center`, verify the YAML-declared GitHub repo `pikasTech/decision-center-data` and `decision-center-github-ssh` Secret presence/fingerprint, and then verify `/health` through the controlled NC01 k8s entrypoint. It must not add a main-server Compose service, bare Docker runtime, NodePort, hostPort, provider-gateway direct HTTP backend, or old D601 Decision Center rollout. MDTODO and ClaudeQQ are standard `k3sctl-managed` artifact consumers in the same model. Dev rollout lands in `unidesk-dev` using their dev manifests; production rollout lands in `unidesk` using the production manifests. Both services must pass dev validation before production rollout, must expose deploy metadata in health when practical, and must verify through the Kubernetes API service proxy instead of NodePort, hostPort or provider-gateway direct HTTP. diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md index 709343ea..4f9dff6e 100644 --- a/docs/reference/deployment.md +++ b/docs/reference/deployment.md @@ -30,7 +30,7 @@ CLI 会优先使用 `docker compose` v2 plugin；当 v2 plugin 不存在时才 Compose v2 安装后仍然必须遵守 UniDesk 的服务控制入口：全栈生命周期用 `server start` / `server stop`，单服务重建用 `server rebuild `。不要因为 v2 可用就直接在生产栈上手工执行未纳入 CLI 的 `up --build`、`down -v` 或跨项目清理命令；所有会影响容器的动作都应保持 job 可观测、Compose project 固定、database named volume 保留。主 server Compose 命令必须从 `providerGateway.upgrade.hostProjectRoot` 指定的 canonical UniDesk 根目录运行，临时 worktree、Code Queue 导出目录或实验分支不得复用生产 `-p unidesk` 和固定 `container_name` 去替换生产容器。 -版本化用户服务部署优先使用 `bun scripts/cli.ts deploy apply` 已支持的受控路径；D601 persistent dev apply 当前支持 `backend-core`/`frontend`/`baidu-netdisk`/`decision-center`/`mdtodo`/`claudeqq` artifact consumer、dev-only `code-queue` artifact consumer，以及 `project-manager`、`oa-event-flow`、`code-queue-mgr`、`todo-note`、`findjob`、`pipeline` 和 `met-nonlinear` 的 artifact consumer validation，dev desired-state smoke 使用 `ci run-dev-e2e`。`deploy.json` 只声明服务 `id`、`repo` 和 `commitId`；目标节点、Dockerfile、Compose、Kubernetes manifest、健康检查和代理路径继续来自 `config.json` 与现有 manifest。主 server 直管微服务和内部 sidecar，例如 `code-queue-mgr`，也必须支持这一路径：`deploy apply --service code-queue-mgr` 从 `deploy.json` 指定 commit 导出源码、构建镜像、替换固定 Compose service 并验证运行中镜像/健康信息的 commit，但 prod live apply 仍需 supervisor 确认。部署默认遵循 target-side build：服务部署到哪台 target，就在哪台 target 从 remote commit 导出源码、一次性代理构建镜像并部署；不得把中心构建镜像作为默认分发路径，也不得用 `docker commit` 或脏 worktree 作为部署输入。backend-core 是明确例外；`frontend` 是用户服务 UI / 前端镜像化样板，`baidu-netdisk` 是主 server 直管微服务的镜像化样板，`decision-center`、`mdtodo` 和 `claudeqq` 是 k3s-managed artifact consumer 样板，`findjob` 和 `pipeline` 是 D601 direct Docker/Compose pull-only 样板：D601 CI 构建并推送 commit-pinned 镜像到 D601 artifact registry，CD 只拉取、retag 或导入、recreate/rollout 和验证，不在 master server 或 runtime target 执行 Compose build。Dev backend-core consumes `127.0.0.1:5000/unidesk/backend-core:` into `unidesk-dev/backend-core-dev` and must not compile Rust during CD. `met-nonlinear` 当前只允许 dry-run/plan，`k3sctl-adapter` 只允许 plan/dry-run 且真实 prod 部署需要 supervisor 确认。`code-queue` 只允许 dev artifact consumer，prod artifact deploy/rollout/manifest mutation 必须 unsupported。完整规则见 `docs/reference/deploy.md`，D601 dev/Rust 边界见 `docs/reference/dev-environment.md`，artifact registry 见 `docs/reference/artifact-registry.md`。 +版本化用户服务部署优先使用受控路径；D601 persistent dev apply 当前支持 `backend-core`/`frontend`/`baidu-netdisk`/`mdtodo`/`claudeqq` artifact consumer、dev-only `code-queue` artifact consumer，以及 `project-manager`、`oa-event-flow`、`code-queue-mgr`、`todo-note`、`findjob`、`pipeline` 和 `met-nonlinear` 的 artifact consumer validation，dev desired-state smoke 使用 `ci run-dev-e2e`。Decision Center 是当前例外：生产部署和存储 truth 已迁移到 NC01 YAML-first k8s + GitHub repo storage，不再把 D601 artifact consumer 作为 closeout。`deploy.json` 只声明服务 `id`、`repo` 和 `commitId`；目标节点、Dockerfile、Compose、Kubernetes manifest、健康检查和代理路径继续来自 `config.json` 与现有 manifest。主 server 直管微服务和内部 sidecar，例如 `code-queue-mgr`，也必须支持这一路径：`deploy apply --service code-queue-mgr` 从 `deploy.json` 指定 commit 导出源码、构建镜像、替换固定 Compose service 并验证运行中镜像/健康信息的 commit，但 prod live apply 仍需 supervisor 确认。部署默认遵循 target-side build：服务部署到哪台 target，就在哪台 target 从 remote commit 导出源码、一次性代理构建镜像并部署；不得把中心构建镜像作为默认分发路径，也不得用 `docker commit` 或脏 worktree 作为部署输入。backend-core 是明确例外；`frontend` 是用户服务 UI / 前端镜像化样板，`baidu-netdisk` 是主 server 直管微服务的镜像化样板，`mdtodo` 和 `claudeqq` 是 k3s-managed artifact consumer 样板，`findjob` 和 `pipeline` 是 D601 direct Docker/Compose pull-only 样板：D601 CI 构建并推送 commit-pinned 镜像到 D601 artifact registry，CD 只拉取、retag 或导入、recreate/rollout 和验证，不在 master server 或 runtime target 执行 Compose build。Dev backend-core consumes `127.0.0.1:5000/unidesk/backend-core:` into `unidesk-dev/backend-core-dev` and must not compile Rust during CD. `met-nonlinear` 当前只允许 dry-run/plan，`k3sctl-adapter` 只允许 plan/dry-run 且真实 prod 部署需要 supervisor 确认。`code-queue` 只允许 dev artifact consumer，prod artifact deploy/rollout/manifest mutation 必须 unsupported。完整规则见 `docs/reference/deploy.md`，D601 dev/Rust 边界见 `docs/reference/dev-environment.md`，artifact registry 见 `docs/reference/artifact-registry.md`。 ## Host Codex Profiles @@ -60,7 +60,7 @@ swap 管理不能被强塞进所有热路径。`server start/status` 可以暴 ## Single Service Rebuild -前端、本机 provider-gateway、dev-frontend-proxy 或主 server 承载的 Todo Note/Code Queue Manager/Project Manager/Baidu Netdisk/OA Event Flow 用户服务需要非版本化本地重建时，统一使用 `bun scripts/cli.ts server rebuild `，其中 `` 只能是 `backend-core`、`frontend`、`dev-frontend-proxy`、`provider-gateway`、`todo-note`、`code-queue-mgr`、`project-manager`、`baidu-netdisk` 或 `oa-event-flow`。对 `database`、`filebrowser`、`filebrowser-d601`、`code-queue`、`k3sctl-adapter` 或未知对象，CLI 必须返回结构化 `unsupported-server-rebuild`，不得创建 job、不得执行 Compose mutation，也不得把对象强行转成源码构建服务。需要按 commit 上线或恢复到 desired-state 时必须改用 `bun scripts/cli.ts deploy apply --service `、backend-core artifact CD、`deploy apply --env dev|prod --service frontend|baidu-netdisk|decision-center|mdtodo|claudeqq` artifact consumer，或 dev-only `deploy apply --env dev --service code-queue` artifact consumer；直管微服务也不能把脏工作树或手工重建作为部署真相。`server rebuild frontend`、`server rebuild baidu-netdisk`、`server rebuild project-manager`、`server rebuild oa-event-flow`、`server rebuild todo-note` 和 `server rebuild code-queue-mgr` 都只作为维护/非标准路径保留，不得作为标准发布完成证据。Rust backend-core 常规迭代和 dev artifact CD 不得在 master server 用 `server rebuild backend-core` 替代 D601 CI；唯一例外是已提交的 backend-core 修复需要上线到主 server Compose runtime 时，可以用 `server rebuild backend-core` 受控编译并替换该服务，要求限流并发、异步 job/status 轮询、容器 health 验证和 issue 证据回写。D601 Code Queue 执行面、File Browser、FindJob、Pipeline、MET Nonlinear 和 ClaudeQQ 部署在计算节点，不属于主 server Compose 可重建服务；其中 D601 Code Queue 执行面不得再通过 `codex deploy` 或维护通道直连 D601 部署，且本阶段 prod artifact deploy/rollout/manifest mutation 仍 unsupported。特例冻结清单和下一阶段删除判断见 `docs/reference/cicd-standardization.md`。 +前端、本机 provider-gateway、dev-frontend-proxy 或主 server 承载的 Todo Note/Code Queue Manager/Project Manager/Baidu Netdisk/OA Event Flow 用户服务需要非版本化本地重建时，统一使用 `bun scripts/cli.ts server rebuild `，其中 `` 只能是 `backend-core`、`frontend`、`dev-frontend-proxy`、`provider-gateway`、`todo-note`、`code-queue-mgr`、`project-manager`、`baidu-netdisk` 或 `oa-event-flow`。对 `database`、`filebrowser`、`filebrowser-d601`、`code-queue`、`k3sctl-adapter` 或未知对象，CLI 必须返回结构化 `unsupported-server-rebuild`，不得创建 job、不得执行 Compose mutation，也不得把对象强行转成源码构建服务。需要按 commit 上线或恢复到 desired-state 时必须改用受控 deploy path；Decision Center 必须走 NC01 YAML-first k8s + GitHub storage path，不能再引用 D601 artifact consumer 作为生产路径；`deploy apply --env dev|prod --service frontend|baidu-netdisk|mdtodo|claudeqq` 和 dev-only `deploy apply --env dev --service code-queue` 仍是对应服务的 artifact consumer 路径。直管微服务也不能把脏工作树或手工重建作为部署真相。`server rebuild frontend`、`server rebuild baidu-netdisk`、`server rebuild project-manager`、`server rebuild oa-event-flow`、`server rebuild todo-note` 和 `server rebuild code-queue-mgr` 都只作为维护/非标准路径保留，不得作为标准发布完成证据。Rust backend-core 常规迭代和 dev artifact CD 不得在 master server 用 `server rebuild backend-core` 替代 D601 CI；唯一例外是已提交的 backend-core 修复需要上线到主 server Compose runtime 时，可以用 `server rebuild backend-core` 受控编译并替换该服务，要求限流并发、异步 job/status 轮询、容器 health 验证和 issue 证据回写。D601 Code Queue 执行面、File Browser、FindJob、Pipeline、MET Nonlinear 和 ClaudeQQ 部署在计算节点，不属于主 server Compose 可重建服务；其中 D601 Code Queue 执行面不得再通过 `codex deploy` 或维护通道直连 D601 部署，且本阶段 prod artifact deploy/rollout/manifest mutation 仍 unsupported。特例冻结清单和下一阶段删除判断见 `docs/reference/cicd-standardization.md`。 backend-core 的 Dockerfile 必须把 Rust 依赖构建和业务源码构建拆开：先只复制 `Cargo.toml` / `Cargo.lock`，用临时 `src/main.rs` 填充 release 依赖层；再复制真实 `src/` 并编译最终 `backend-core` 二进制。这样同一 builder 上只改业务源码时可以复用依赖层，避免每次重新编译全部 crate。该缓存策略只改善后续源码迭代；全新 builder 的第一次冷编译仍然需要下载和编译依赖，若要把第一次也做快，长期方案应是预构建依赖 builder image、BuildKit registry cache 或由 CI 发布 commit-pinned runtime image 后让部署侧只 pull 成品镜像。 diff --git a/docs/reference/dev-environment.md b/docs/reference/dev-environment.md index 4d18807c..d70494c9 100644 --- a/docs/reference/dev-environment.md +++ b/docs/reference/dev-environment.md @@ -61,7 +61,7 @@ During a `release/v1` stabilization window, this same implemented `environments. The persistent dev rollout currently supports: -- `backend-core`, `frontend`, `decision-center`, `mdtodo`, `claudeqq` and `code-queue` as D601 registry artifact consumers in `unidesk-dev`. +- `backend-core`, `frontend`, `mdtodo`, `claudeqq` and `code-queue` as D601 registry artifact consumers in `unidesk-dev`. Decision Center moved to the NC01 YAML-first k8s lane and is no longer a current D601 persistent dev workload. - `baidu-netdisk` as the main-server direct user-service artifact validation sample. `deploy apply --env dev --service baidu-netdisk` consumes the D601 registry artifact and validates the main-server Compose service; it is not a persistent D601 k3s dev workload. `deploy apply --env dev --service code-queue` is intentionally dev-only and may mutate only `unidesk-dev` Code Queue scheduler/read/write/provider-egress-proxy objects. `deploy apply --env prod --service code-queue` must remain unsupported. The `environments.dev.ci` declaration and short launcher runner are owned by `docs/reference/dev-ci-runner.md`. @@ -93,7 +93,7 @@ Not allowed on the master server for this path: ## Dev Deploy Path -`deploy apply --env dev --service backend-core|frontend|decision-center|mdtodo|claudeqq|code-queue` is the controlled persistent dev rollout path for D601 dev workloads. The controller runs on the master server, but dev CD is a pull-only artifact consumer. All listed services consume CI-published commit-pinned artifacts from the D601 registry. +`deploy apply --env dev --service backend-core|frontend|mdtodo|claudeqq|code-queue` is the controlled persistent dev rollout path for D601 dev workloads. The controller runs on the master server, but dev CD is a pull-only artifact consumer. All listed services consume CI-published commit-pinned artifacts from the D601 registry. Decision Center uses the NC01 k8s lane and GitHub storage checks instead of this D601 dev path. 1. Fetch `origin/master:deploy.json#environments.dev` and resolve the requested service commit to a full SHA. 2. Dispatch to D601 through the existing provider-gateway/Host SSH maintenance capability. diff --git a/docs/reference/frontend.md b/docs/reference/frontend.md index 486de0b1..e20b778e 100644 --- a/docs/reference/frontend.md +++ b/docs/reference/frontend.md @@ -112,7 +112,7 @@ Workbench 前端的 SSE、REST gap-fill、health probe、session refresh、trace - `Baidu Netdisk` 子标签必须把主 server `baidu-netdisk-backend` 后端渲染为 UniDesk React 控件，包括 OAuth 设备码二维码/用户码登录、账号容量、配置工作根文件浏览（当前默认百度网盘根目录 `/`）、staging 目录上传/下载任务、上传/下载自测按钮与 MD5 结果、脱敏安全说明、日志摘要和显式原始 JSON 按钮；不得把 access token、refresh token、dlink 或 staging 文件字节流裸露到浏览器。 - `OA Event Flow` 子标签必须把主 server `oa-event-flow-backend` 后端渲染为 UniDesk React 控件，包括服务健康、事件表、tag 过滤、SSE live 状态、Trace/STEP stats 表、Code Queue/Pipeline 标签入口和显式原始 JSON 按钮；默认页面不得裸铺完整事件 JSON，事件表只展示结构化摘要，完整 envelope/payload 只能通过 `查看原始JSON` 打开。 - `k3s Control` 子标签必须把 D601 `k3sctl-adapter` 控制面渲染为 UniDesk React 控件，包括 control plane 状态、manifest 列表、D601 scheduler/read/write 实例、active instance、single-writer/no-fallback 路径、Kubernetes API service proxy 状态、kubectl/k3s snapshot 摘要和显式原始 JSON 按钮；页面只能通过 `/api/microservices/k3sctl-adapter/proxy/api/control-plane` 取数，不得直接访问 provider-gateway、NodePort、业务容器端口或裸 k3s/kubectl API。 - - `Decision Center` 子标签必须把 D601 `decision-center` 用户服务渲染为需求管理与工作日记工作台。默认 `需求管理` 视图必须是一等工作区，结构化展示并录入外部目标、内部目标、阻塞、停放事项、决议、实验和债务，提供类型/状态/等级/关联目标筛选、记录编辑器、记录表和显式原始 JSON 按钮；默认页面不得裸铺 JSON。`工作日记` 视图必须提供“今天”按钮，使用浏览器当前日期生成 `YYYY-MM-DD`，自动打开或创建当天 Markdown 日记，允许编辑历史日记 Markdown 并通过 `/api/microservices/decision-center/proxy/api/diary/import` 保存到 PostgreSQL；完整日记 JSON 只能通过 `查看原始JSON` 打开。页面不得提供聊天/LLM 会话窗口。 + - `Decision Center` 子标签必须把 NC01 k8s `decision-center` 用户服务渲染为需求管理与工作日记工作台。默认 `需求管理` 视图必须是一等工作区，结构化展示并录入外部目标、内部目标、阻塞、停放事项、决议、实验和债务，提供类型/状态/等级/关联目标筛选、记录编辑器、记录表和显式原始 JSON 按钮；默认页面不得裸铺 JSON。`工作日记` 视图必须提供“今天”按钮，使用浏览器当前日期生成 `YYYY-MM-DD`，自动打开或创建当天 Markdown 日记，允许编辑历史日记 Markdown 并通过 `/api/microservices/decision-center/proxy/api/diary/import` 保存到 GitHub repo `pikasTech/decision-center-data`；完整日记 JSON 只能通过 `查看原始JSON` 打开。页面不得提供聊天/LLM 会话窗口。 - `Code Queue` 子标签必须把稳定 `code-queue` 用户服务渲染为 UniDesk React 控件，前端 API 基址只能是 `/api/microservices/code-queue/proxy`，不能继续使用旧 `/api/code-queue-direct` 别名；backend-core 会把 queue CRUD、submit、history、readAt 和轻量 Trace 读取分流到主 server `code-queue-mgr`，把 active run steer/interrupt、judge、dev-container 和执行面健康分流到 D601 k3s/k8s Code Queue 执行面。页面包括多 queue lane、queue 内串行、queue 间并行、queue 合并（点击“合并 queue”后必须用公共 `UniDeskDialog` 打开独立小窗口，用下拉菜单选择源 queue；不得把源 queue 选择控件塞进正常提交任务的 Queue 选择区；合并后自动删除源 queue，只保留合并后的目标 queue，目标 queue 按原 queueEnteredAt/createdAt 时间顺序串行）、任务 ID/复制任务 ID、引用按钮、任务耗时、任务提交/批量提交、引用任务 ID、创建成功提示、清空输入、模型下拉、执行 Provider 下拉、执行模式下拉（默认容器/本机或 `windows-native`）、显式入队份数、默认模型 `gpt-5.5`、MiniMax judge 状态、Codex CLI-like 输出流、attempt 终态、运行中追加 prompt、打断、手动重试和显式原始 JSON 按钮；`windows-native` 模式必须在任务 JSON、卡片和 Trace 头部显示，并要求非本机 WSL Provider 与 `/mnt/` 工作目录；Codex CLI-like 输出流必须始终保留任务的初始 `Submitted prompt` 和运行中 `Steer prompt`；整个 agent loop 消息流统一命名为专有名词 `Trace`，`Trace` 包含 assistant message、user prompt、system event 和 tool call，但非错误 system event 默认只保留在原始输出/数据库中，不在 TraceView 展示；Code Queue 与 Pipeline/OpenCode messages 必须共用 `src/components/frontend/src/trace.tsx` 的 Trace 公共组件、统一 Trace item 接口和 codex/opencode port 适配层；连续 read/edit/run 工具调用只是在 Trace 内折叠为可展开工具调用组，汇总格式至少包含 `xx read, xx edit, xx run`，并展示读取文件、编辑文件、运行命令和耗时摘要；最近 3 个工具调用保持展开，工具调用内容不得自动换行且必须在工具调用块内部横向滚动，工具调用组展开后不得再增加额外左侧缩进；message 与 prompt 必须自动换行，普通 message 不显示左侧项目符号缩进且永不折叠；Trace 首屏可以是摘要预览，但终态任务被选中后必须自动在后台加载完整 Trace，手动“加载完整 Trace”也必须从 Code Queue output archive 分页补齐早期 trace，不得把 preview 的 `hasMore=false` 当成完整历史；即使热状态为控制体积裁剪了早期 raw output，也要从结构化 `basePrompt/displayPrompt/promptHistory` 和 archive 合成完整用户输入与 agent trace，并且初始 prompt 默认显示注入前 prompt 而不是引用注入全文；当初始 prompt 含引用注入时，引用内容必须默认折叠，并只在 Trace 的初始消息中提供可展开的“最终传入 Codex 的真实完整 prompt”，不得再渲染独立 Prompt 全量卡片；多轮引用注入必须按上游/最早上下文在前、直接引用在后的顺序排列，每一轮必须有明确 `Reference Round N/M` 分割线和时间范围，不能用固定 6 轮截断引用链；点击队列引用按钮必须自动把该任务 ID 写入提交表单的引用输入框，引用任务 ID 创建新任务时必须自动注入 `bun scripts/cli.ts codex task ` 的提示；连续执行同一 prompt 应通过入队份数一次性生成多条任务，避免快速连点造成操作员误判。 - `MDTODO` 子标签必须把 D601 k3s `mdtodo` Service 渲染为 UniDesk React 控件，前端 API 基址只能是 `/api/microservices/mdtodo/proxy`；页面包括 TODO Markdown 文件列表、任务树、状态徽标、标题与正文编辑、新增根任务/子任务、删除任务、执行命令生成、hostPath 健康摘要和显式原始 JSON 按钮，不得 iframe 原 VS Code webview、公开 VSIX 旧前端或把完整 Markdown/JSON 默认铺在页面上。 - `Code Queue` 前端改进必须在同一任务内重建并上线公网 frontend，不能只修改源码或本地 bundle；重建 frontend 是无状态 WebUI 替换，不会导致 Code Queue 长期任务失败。已结束未读任务只能在 task card 边角显示类似未读消息的 `codex-unread-badge` 圆点和“标为已读”操作，不得把整张卡片改成红色/琥珀色失败态边框、背景或胶囊标签；状态栏的“结束未读”提示也不得使用失败态红色。 diff --git a/docs/reference/microservices.md b/docs/reference/microservices.md index fccc1bab..c2e8d0e4 100644 --- a/docs/reference/microservices.md +++ b/docs/reference/microservices.md @@ -182,7 +182,7 @@ Baidu Netdisk 在 UniDesk 语境中按纯后端服务管理：不得暴露百度 D601 开发环境底座只允许创建 `unidesk-dev` namespace 与 dev 专用对象，manifest 固定为 `src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-foundation.k8s.yaml`。该 manifest 包含 `postgres-dev` 独立 PostgreSQL StatefulSet/Service/PVC、dev-only secret/config 模板、dev DB 初始化 SQL 和迁移 Job、ResourceQuota/LimitRange，以及 `unidesk-dev-db-guard`。它不得修改生产 `unidesk` namespace、生产 PostgreSQL、生产 PVC、生产 Deployment/Service/Secret 或主 server Docker Compose。 -`postgres-dev` 是 dev backend-core 与 dev Code Queue 状态的默认唯一数据库。dev 运行时必须使用 `postgres-dev.unidesk-dev.svc.cluster.local:5432/unidesk_dev` 和 dev Provider 身份 `D601-dev`；不得共享生产 `d601-tcp-egress-gateway.../unidesk`。Persistent dev backend-core/frontend/Decision Center/MDTODO/ClaudeQQ artifact rollout, dev-only Code Queue artifact rollout, public dev frontend port and Rust CI artifact boundary are defined in `docs/reference/dev-environment.md`. +`postgres-dev` 是 dev backend-core 与 dev Code Queue 状态的默认唯一数据库。dev 运行时必须使用 `postgres-dev.unidesk-dev.svc.cluster.local:5432/unidesk_dev` 和 dev Provider 身份 `D601-dev`；不得共享生产 `d601-tcp-egress-gateway.../unidesk`。Persistent dev backend-core/frontend/MDTODO/ClaudeQQ artifact rollout, dev-only Code Queue artifact rollout, public dev frontend port and Rust CI artifact boundary are defined in `docs/reference/dev-environment.md`; Decision Center is governed by the NC01 k8s/GitHub storage lane. 验收入口：先运行 `bun scripts/cli.ts dev-env validate` 做静态资源与 DB URL 护栏检查；具备 D601 kubeconfig 时运行 `bun scripts/cli.ts dev-env validate --kubectl-dry-run` 做 Kubernetes client dry-run。首次或镜像缓存不确定时，先运行 `bun scripts/cli.ts dev-env prewarm-images`，把 `postgres:16-alpine` 和 local-path helper 所需的 `rancher/mirrored-library-busybox:1.36.1` 导入 D601 原生 k3s containerd；否则 D601 的 Docker 代理/缓存正常也不能保证 k3s/containerd 能实时拉到外部镜像。若实际 apply，只能 apply 到 `unidesk-dev`，随后用 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n unidesk-dev get pods,svc,pvc` 验证 dev DB ready，并对比 apply 前后的 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n unidesk get deploy,sts,svc,secret,pvc -o name` 证明生产 workload 未变化。 @@ -259,23 +259,23 @@ D601 上必须显式使用原生 k3s kubeconfig：`KUBECONFIG=/etc/rancher/k3s/k - Dev/prod CD：ClaudeQQ 的 dev/prod rollout 都必须走 D601 registry artifact consumer。CI 从 Gitee commit 导出 `claudeqq/` 源码并 overlay UniDesk Dockerfile/adapter，CD 验证同一个 commit-pinned artifact contract，dev 落到 `unidesk-dev/claudeqq-dev`，prod 落到 `unidesk/claudeqq`，健康检查通过 Kubernetes API service proxy 完成；不得回退到维护通道直连或 NodePort/hostPort。 - UniDesk 前端：`用户服务 / ClaudeQQ` React 页面负责展示 D601、仓库引用、私有 k3s 后端映射、NapCat 登录二维码、NapCat HTTP/WS 状态、事件缓存、订阅表、订阅创建表单、消息推送表单、主用户私聊账号 `645275593`、最近 QQ 事件和已发送记录；完整原始 JSON 只能通过显式 `查看原始JSON` 打开。浏览器只能通过 UniDesk frontend 同源代理访问 ClaudeQQ，不得直接访问 D601 `3290/3000/3001/6099`，也不得 iframe ClaudeQQ 旧 WebUI。 -### Decision Center k3s-Managed +### Decision Center NC01 k8s-Managed -当前 Decision Center 作为 `id=decision-center` 的 `k3sctl-managed` 用户服务登记在 `config.json`，用于沉淀 Codex/人工会议后的会议记录、决议、目标、问题分级、停放事项、证据和按天工作日记，同时也作为外部需求向内部目标分解的工作台。它只负责权威记录、Markdown 日记、需求管理和展示，不承载通用聊天、LLM 会话窗口或自动参谋对话。 +当前 Decision Center 生产运行面固定在 NC01 k8s `unidesk` namespace，运行对象是 `deployment/decision-center` 和 `service/decision-center`，并由 `config/unidesk-host-k8s.yaml` 选择目标。它用于沉淀 Codex/人工会议后的会议记录、决议、目标、问题分级、停放事项、证据和按天工作日记，同时也作为外部需求向内部目标分解的工作台。它只负责权威记录、Markdown 日记、需求管理和展示，不承载通用聊天、LLM 会话窗口或自动参谋对话。 -- Orchestrator：`deployment.mode=k3sctl-managed`，`deployment.adapterServiceId=k3sctl-adapter`，`deployment.k3sServiceId=decision-center`，`backend.proxyMode=k3sctl-adapter-http`，`backend.nodeBaseUrl=k3s://decision-center`；正式链路只能是 `frontend/CLI -> backend-core -> k3sctl-adapter -> Kubernetes API service proxy -> Kubernetes Service decision-center:4277`。 -- 部署引用：后端源码位于 UniDesk 仓库 `src/components/microservices/decision-center`，Dockerfile 为 `src/components/microservices/decision-center/Dockerfile`；k3s manifest 为 `src/components/microservices/k3sctl-adapter/k3s/decision-center.k3s.json`，Kubernetes 运行清单为 `src/components/microservices/k3sctl-adapter/k3s/decision-center.k8s.yaml`，镜像名固定为 `unidesk-decision-center:d601`。dev 环境使用 `src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-decision-center.k8s.yaml` 和 `unidesk-dev-decision-center.k3s.json`，服务名为 `decision-center-dev`。主 server `docker-compose.yml` 不得加入该服务，也不得公开 `4277`。 -- 状态权威：Decision Center 必须写入主 PostgreSQL，权威记录表为 `decision_center_records`，日记表为 `decision_center_diary_entries`；不得使用浏览器 `localStorage`、IndexedDB、容器 writable layer 或本地 JSON 文件作为会议、决议、目标、问题或日记状态权威。D601 Pod 通过集群内 `d601-tcp-egress-gateway.unidesk.svc.cluster.local:15432` 访问主 PostgreSQL。 +- Orchestrator：正式链路是 `frontend/CLI -> NC01 k8s decision-center Service:4277`，CLI 通过受控 NC01 k8s entrypoint 进入 Pod 本地 HTTP 接口；不得把裸 Docker/Compose、NodePort、hostPort、provider-gateway 业务 HTTP 或旧 D601 Decision Center 作为生产入口。 +- 部署引用：后端源码位于 UniDesk 仓库 `src/components/microservices/decision-center`，Dockerfile 为 `src/components/microservices/decision-center/Dockerfile`。当前生产部署由 YAML-first k8s 配置控制，目标、namespace、GitHub repo、base path 和 Secret sourceRef 必须来自 YAML；主 server `docker-compose.yml` 不得加入该服务，也不得公开 `4277`。 +- 状态权威：Decision Center 持久化权威是 GitHub repo `pikasTech/decision-center-data` 的 `main:data`，GitHub SSH 凭据由 `decision-center-github-ssh` Secret 分发；PostgreSQL 只作为运行时索引/缓存，不再作为会议、决议、目标、问题或日记的 durable truth。不得使用浏览器 `localStorage`、IndexedDB、容器 writable layer 或本地 JSON 文件作为权威存储。 - 记录数据模型：记录类型为 `meeting|decision|goal|external_goal|internal_goal|blocker|debt|experiment`，等级/优先级为 `G0|G1|G2|G3|P0|P1|P2|P3|none`，状态为 `active|blocked|parked|done`，字段包含 `title`、Markdown `summary/body`、`priority`/`level`、`source`、`issueId`、`linkedGoalId`、`tags`、`evidenceLinks`、`sourceSession`、`taskId`、`commitId`、`createdAt` 和 `updatedAt`。 - 文书正规化：Decision Center 记录应逐步从松散需求记录升级为带文号的工程化文书系统，默认文号格式为 `DC----`。`TYPE` 固定为 4 位英文缩写，当前保留 `DCSN` 决策/决议、`GOAL` 目标、`PLAN` 计划、`RPRT` 报告/态势评估、`ACTN` 行动项、`ISSU` 问题/阻塞、`RETR` 复盘、`RQST` 请示、`RESP` 批复/答复、`MINS` 纪要；`PRIORITY` 使用 `P0|P1|P2|P3`，G 级目标在文号中映射为 P 级紧迫度，其中 G0 默认映射 P0；`YEAR` 使用签发年份，`SEQ` 是同一 `TYPE+PRIORITY+YEAR` 下从 `001` 起递增的三位序号。示例：`DC-DCSN-P0-2026-001`、`DC-GOAL-P0-2026-001`。 - 文书元数据：正式产品化后，记录模型必须显式保存 `docNo`、`docType`、`docPriority`、`docSeq`、`signer`、`issuedAt`、`effectiveScope`、`supersedes` 和 `supersededBy` 等字段，并为 `docNo` 建立唯一约束；在 schema 完成前，临时过渡可以把文号写入 `title` 前缀、`tags` 和 Markdown `body` 首段，但不得把临时正文约定当作长期数据模型。 - 文书流转：正式文书应支持 `draft` 草拟、`review` 核稿、`issued` 已签发、`active` 执行中、`done` 办结、`void` 作废等状态或等价状态映射；Agent 可以起草、核稿和生成报告，但涉及战略优先级、外部目标和长期约束的 `DCSN`/`GOAL` 文书必须由用户签发后才进入已签发序列。编号一经签发不得复用，作废也必须保留编号和替代关系。 - 需求管理：Decision Center 里的 `external_goal` 记录应承接外部需求或外部目标，`internal_goal`/`goal` 记录应承接拆解后的内部目标，`decision` 记录应承接需求分解后的取舍，`blocker` 记录应承接当前阻塞，`experiment` 记录应承接验证性工作，`debt` 记录应承接必须偿还的技术/流程债。任何新需求都应先写成可验证的外部收益，再分解为这些内部记录，而不是先发散成内部审美或架构偏好。需求管理 API 复用 `decision_center_records`，`/api/requirements` 在同一模型上排除 `meeting`，并提供 list/create/show/update/upsert 的需求语义入口，不引入第二套需求表。 - 日记数据模型：基于 Markdown 的日记系统以“每天一篇”为最小单元，导入器识别 `# YYYY年M月D日`、`# YYYY-MM-DD` 或 `# YYYY/M/D` 标题并拆分为 `entry_date`、`month`、Markdown `body`、`source_file`、`content_hash` 与虚拟 `markdown_path=YYYY-MM/YYYY-MM-DD.md`；同一 `source_file + entry_date` 使用 upsert，内容未变时保持幂等；同一天存在多个 `source_file` 时，列表项应保留 `id` 与 `sourceFile`，按日期读取可用 `sourceFile` 查询参数消歧。 -- 日记编辑：工作日记必须支持按真实日期创建当天条目，并支持按日期回看和编辑历史条目；`GET /api/diary/today` 按服务当前真实日期自动创建或返回当天条目，`PUT /api/diary/today` 保存当天 Markdown，`PUT /api/diary/entries/:idOrDate` 允许安全更新 `body`/`markdown`、`title`、`tags` 和 `sourceFile`，按 `YYYY-MM-DD` key 且不存在时创建当天或历史条目，按非日期 id 时只编辑既有条目。数据库仍是唯一权威，前端只是编辑入口和展示入口。 +- 日记编辑：工作日记必须支持按真实日期创建当天条目，并支持按日期回看和编辑历史条目；`GET /api/diary/today` 按服务当前真实日期自动创建或返回当天条目，`PUT /api/diary/today` 保存当天 Markdown，`PUT /api/diary/entries/:idOrDate` 允许安全更新 `body`/`markdown`、`title`、`tags` 和 `sourceFile`，按 `YYYY-MM-DD` key 且不存在时创建当天或历史条目，按非日期 id 时只编辑既有条目。GitHub repo 是唯一持久化权威，前端只是编辑入口和展示入口。 - API：只允许 `/health`、`/live`、`/logs` 和 `/api/` 前缀；允许 `GET`、`HEAD`、`POST`、`PUT` 和 `DELETE`。业务 API 包含 `GET /api/records`、`POST /api/records`、`GET|PUT|DELETE /api/records/:id`、`GET|POST|PUT /api/requirements`、`GET|PUT /api/requirements/:id`、`POST /api/meetings/import`、`POST /api/diary/import`、`GET /api/diary/entries`、`GET /api/diary/history`、`GET|POST|PUT /api/diary/today`、`GET|PUT /api/diary/entries/:idOrDate` 和 `GET /api/diary/months`，错误必须返回结构化 JSON，便于 CLI 与 frontend 诊断。记录与日记列表默认只返回摘要级正文，完整 Markdown body 只能由详情接口或显式 `includeBody=true` 获取，避免大 body 列表穿过 frontend/proxy 链路导致超时。 -- CLI：`bun scripts/cli.ts decision upload `、`decision list`、`decision show `、`decision requirement list/create/show/update/upsert`、`decision diary import/list/history/months/today/show/edit/upsert` 和 `decision health` 只能通过 backend-core 用户服务代理访问 Decision Center，不得直连 D601 Service、NodePort 或 provider-gateway `microservice.http`。列表命令默认省略完整正文，需要完整 body 时显式加 `--include-body`；日记编辑验收应使用 `decision diary today` 确认真实日期自动创建当天条目，使用 `decision diary today --edit --body-file ` 保存当天 Markdown，使用 `decision diary upsert --body-file ` 创建或更新历史日记，再用 `decision diary show --source-file ` 或 `decision diary show ` 读取确认。 -- Dev/prod CD：Decision Center 的 dev/prod rollout 都必须走 D601 registry artifact consumer，验证同一个 commit-pinned artifact contract，证明 live `deploy.commit` 与 `deploy.requestedCommit` 一致，再通过 Kubernetes API service proxy 验证健康；不得回退到维护通道直连或 NodePort/hostPort。 +- CLI：`bun scripts/cli.ts decision upload `、`decision list`、`decision show `、`decision requirement list/create/show/update/upsert`、`decision diary import/list/history/months/today/show/edit/upsert` 和 `decision health` 只能通过 `config/unidesk-host-k8s.yaml` 选中的 NC01 k8s entrypoint 访问 Decision Center，不得直连旧 D601 Service、NodePort 或 provider-gateway `microservice.http`。列表命令默认省略完整正文，需要完整 body 时显式加 `--include-body`；日记编辑验收应使用 `decision diary today` 确认真实日期自动创建当天条目，使用 `decision diary today --edit --body-file ` 保存当天 Markdown，使用 `decision diary upsert --body-file ` 创建或更新历史日记，再用 `decision diary show --source-file ` 或 `decision diary show ` 读取确认。 +- Dev/prod CD：Decision Center 的当前生产 rollout 必须走 NC01 YAML-first k8s 部署，验证 `deployment/decision-center`、`service/decision-center`、GitHub repo 配置和 `decision-center-github-ssh` Secret presence/fingerprint；不得回退到 D601 registry artifact consumer、维护通道直连、裸 Docker/Compose、NodePort 或 hostPort。旧 D601 dev/prod artifact consumer 描述只保留为迁移历史，不再作为当前生产 closeout 证据。 - UniDesk 前端：`用户服务 / Decision Center` React 页面展示权威记录筛选、当前 G0/G1 目标、P0/P1 blocker、停放事项、最近会议/决议和工作日记；它还应成为需求管理入口，让外部目标、内部拆解和每日工作记录在同一页面中可追溯。日记视图按月份筛选并展示每天 Markdown 正文，未来应支持当天自动创建与历史编辑。默认不得展示裸 JSON，完整原始数据只能通过 `查看原始JSON` 打开。 ### MDTODO k3s-Managed @@ -298,7 +298,7 @@ D601 上必须显式使用原生 k3s kubeconfig：`KUBECONFIG=/etc/rancher/k3s/k - `pipeline`：Pipeline v2 控制与观测服务，UniDesk frontend 渲染组件矩阵、React Flow 控制图、epoch 甘特图、运行材料索引和 node 精细控制面板。 - `met-nonlinear`：MET Nonlinear 训练编排服务，UniDesk frontend 渲染 GPU/镜像、训练队列、Project config 预览、训练进度、ETA 和历史记录。 - `claudeqq`：ClaudeQQ 纯后端 QQ 消息网关，UniDesk frontend 渲染 NapCat 连接、事件订阅、消息推送、最近 QQ 事件和发送记录。 -- `decision-center`：Decision Center 决策权威记录和 Markdown 日记服务，D601 k3s 代管，状态写入主 PostgreSQL，UniDesk frontend 渲染记录筛选、目标、blocker、停放事项、会议/决议和按月工作日记。 +- `decision-center`：Decision Center 决策权威记录和 Markdown 日记服务，生产由 NC01 k8s 代管，状态持久化到 GitHub repo `pikasTech/decision-center-data`，UniDesk frontend 渲染记录筛选、目标、blocker、停放事项、会议/决议和按月工作日记。 ### D601 Docker/k3s Restart Recovery diff --git a/docs/reference/repo-tree.md b/docs/reference/repo-tree.md index b3e76976..610fcd84 100644 --- a/docs/reference/repo-tree.md +++ b/docs/reference/repo-tree.md @@ -100,7 +100,7 @@ - code-queue/ (Codex/OpenCode execution plane backend; k3s-managed on D601) - code-queue-mgr/ (Lightweight master-side Code Queue control plane; PostgreSQL CRUD/read path only) - oa-event-flow/ (Unified OA event ledger, tag stream, and Trace/STEP stats center) - - decision-center/ (Decision records backend; k3s-managed on D601 and PostgreSQL-backed) + - decision-center/ (Decision records backend; k8s-managed on NC01 and GitHub-backed) - k3sctl-adapter/ (D601 k3s control-plane adapter and managed service manifests) - k3s/ci/ (Tekton CI install marker, Pipeline/Task, and in-cluster Trigger manifests) - example-service/ diff --git a/docs/reference/user-service-delivery.md b/docs/reference/user-service-delivery.md index 3a3396c0..22a8ea09 100644 --- a/docs/reference/user-service-delivery.md +++ b/docs/reference/user-service-delivery.md @@ -4,7 +4,7 @@ This document owns the default delivery path for UniDesk user services registere ## Scope -User services are non-core business services mounted onto the UniDesk platform. They must remain deliverable without changing the base platform strategy. The default policy here applies to user services that are expected to reach production after validation, including the UniDesk user-service UI artifact (`frontend`), main-server direct services such as Baidu Netdisk, D601-managed k3s services such as Decision Center, MDTODO and ClaudeQQ, and D601 direct Docker/Compose services such as FindJob and Pipeline. Code Queue is a special dev-only artifact consumer in this policy; its production execution plane must not be deployed by the user-service artifact consumer. +User services are non-core business services mounted onto the UniDesk platform. They must remain deliverable without changing the base platform strategy. The default policy here applies to user services that are expected to reach production after validation, including the UniDesk user-service UI artifact (`frontend`), main-server direct services such as Baidu Netdisk, NC01-managed k8s services such as Decision Center, D601-managed k3s services such as MDTODO and ClaudeQQ, and D601 direct Docker/Compose services such as FindJob and Pipeline. Code Queue is a special dev-only artifact consumer in this policy; its production execution plane must not be deployed by the user-service artifact consumer. This policy does not apply to: @@ -140,19 +140,19 @@ FindJob and Pipeline are D601 direct Docker/Compose user services. They differ f ## Decision Center -Decision Center is the canonical example of a user service that doubles as a product workflow for requirements, decisions, and daily work diaries. +Decision Center is the canonical example of a user service that doubles as a product workflow for requirements, decisions, and daily work diaries. Its current production truth is NC01 k8s plus GitHub repo storage; the older D601 artifact-consumer text is migration history only. -- The minimal standard artifact command is `bun scripts/cli.ts ci publish-user-service --service decision-center --commit --wait-ms 1200000`. -- The expected artifact is `127.0.0.1:5000/unidesk/decision-center:` plus its registry digest from the CI output. -- Dev and prod CD both consume that same commit-pinned artifact contract through the D601 registry artifact consumer; dev lands in `unidesk-dev`, prod lands in the production k3s namespace, and both must prove `deploy.commit` and `deploy.requestedCommit`. +- Production deploy must use the YAML-first NC01 k8s path from `config/unidesk-host-k8s.yaml`; the live objects are `unidesk/deployment/decision-center` and `unidesk/service/decision-center`. +- Durable data must be stored in GitHub repo `pikasTech/decision-center-data` branch `main` under `data`; PostgreSQL is only an index/cache and must not be treated as the durable truth. +- GitHub SSH access must be distributed through YAML-declared Secret sourceRefs, with operator output limited to object/key presence and fingerprints. - Requirements and follow-up items should be represented with structured records such as `goal`, `decision`, `blocker`, `debt`, and `experiment`, with linked evidence and goal references. - The service should act as a demand-management surface for external goals that need to be decomposed into internal tasks, blockers, and decisions. - The document-management surface must support the engineering document number format `DC----` defined in `docs/reference/microservices.md`, including unique `docNo` storage, 4-letter document type codes, P-level priority, signing metadata, replacement links and list/detail filtering by document number. - The work-diary surface should support creating today's diary entry automatically from the real current date. -- Historical diary entries should be editable by date, with PostgreSQL remaining the source of truth. +- Historical diary entries should be editable by date, with the GitHub repo remaining the source of truth. - The resulting product surface should stay structured and reviewable, not collapse into an untracked chat log. - Before any production deploy, the dev gate must pass first with the focused Decision Center E2E set covering `microservice:decision-center-record-crud`, `microservice:decision-center-diary-lifecycle`, `frontend:decision-center-visible`, `frontend:decision-center-demand-management-visible`, and `frontend:decision-center-diary-visible`; this is an automated user-service validation gate, not a production deploy. -- Document-management changes must first land in the D601 dev Decision Center service and extend the focused E2E set with doc-number creation/upsert/list/detail uniqueness, migration/backfill, frontend visibility and temporary body-prefix compatibility before production rollout. +- Document-management changes must first land through the NC01 Decision Center lane and extend the focused E2E set with doc-number creation/upsert/list/detail uniqueness, GitHub storage migration/backfill, frontend visibility and temporary body-prefix compatibility before production rollout. - Production acceptance is manual after the dev gate and must explicitly verify `health`, `records`, `diary editor`, the paired frontend page, no public business ports, and live commit / artifact information. - Acceptance notes may cite diagnostics/status pages as evidence, but those pages must be labeled as diagnostics and not as the default user workflow.