pikasTech-unidesk/docs/plan/d601-k3s-dev-environment.md

# D601 k3s 开发环境建设计划

> 状态：本过程计划的环境分支方案已废弃。长期权威规则以 `docs/reference/deploy.md` 和 `docs/reference/ci.md` 为准：dev/prod 期望状态统一写在 `master` 分支的根目录 `deploy.json`，通过 `environments.dev` 和 `environments.prod` 区分，不再以 `deploy/dev` 或 `deploy/prod` 分支作为环境事实源。本文件保留为阶段性历史计划，不作为新实现依据。

## 目标

在现有 D601 原生 k3s 集群内建设一套与生产隔离的 UniDesk 开发环境，让以 LLM 为主力的开发流程可以部署、破坏、重建和验证 backend-core、frontend、Code Queue 及其数据库依赖，而不打断生产主 server。

第一版必须支持通过 GitHub commit id 部署。长期控制点是 GitHub 托管的 `deploy.json`：部署某个环境时，自动读取对应 GitHub 环境分支里的 `deploy.json`，并应用其中声明的 commit id。

初始环境分支：

- `deploy/dev`：D601 k3s 开发环境的期望状态。
- `deploy/prod`：生产环境的期望状态。分支保护可以后续补上；第一版仍必须把 prod 部署命令和凭据与 dev 隔离。

## 非目标

- 第一版不创建第二套物理 k3s 控制平面。先复用现有 D601 原生 k3s 集群，通过 namespace 做隔离。
- 第一版不把生产主 server 的 backend-core/frontend 迁入 k3s。
- dev 环境不得共享生产 PostgreSQL 表、Provider 身份、Provider token、Code Queue 任务状态或部署 worktree 路径。
- `deploy/dev` 和 `deploy/prod` 不是普通源码开发分支的别名，只是环境期望状态分支。

## 目标开发拓扑

第一版 dev 环境运行在 D601 的 `unidesk-dev` namespace：

- `postgres-dev`：dev 独立 PostgreSQL StatefulSet，或等价的持久化数据库。
- `backend-core-dev`：从 `deploy/dev:deploy.json` 声明的 commit id 构建。
- `frontend-dev`：从 `deploy/dev:deploy.json` 声明的 commit id 构建，并且只代理到 `backend-core-dev`。
- `code-queue-mgr-dev`：轻量 Code Queue 控制面，使用 dev 数据库。
- `code-queue-read-dev`、`code-queue-write-dev`、`code-queue-scheduler-dev`：Code Queue k3s 执行组件，使用 dev 数据库、dev 日志、dev state 路径和 dev Code Queue 配置。
- 第一阶段访问方式可选：SSH port-forward 或 D601 私有 ingress。阶段 1 不要求公网暴露。

所有 dev 服务的 `/health` 必须输出环境身份：

- `environment=dev`
- namespace 名称
- 数据库名称
- service id
- GitHub repo 和 commit id
- 部署 ref，预期为 `origin/deploy/dev`

## 核心隔离规则

1. dev 服务只能使用 `unidesk-dev` namespace。
2. dev 服务必须使用 dev PostgreSQL 实例或 dev 数据库，不能连接生产 PostgreSQL。
3. dev Provider 身份必须独立，例如 `D601-dev`，不能复用生产 `D601` 的 provider id 或 provider token。
4. dev Code Queue 的 task、queue、attempt、notification 和 trace state 不能写入生产表；除非表名已经显式 namespace 化并经过安全验证。第一版优先使用独立 dev 数据库。
5. dev manifest 不得挂载生产部署根目录，例如主 server 的 `/root/unidesk` 或 D601 生产部署路径；除非只读挂载且确实用于诊断。
6. dev Code Queue 必须使用 dev workdir、dev log dir 和 dev state dir。
7. 生产部署不能读取本地 dirty `deploy.json`；必须从配置好的 GitHub 生产环境 ref 读取生产期望状态。
8. LLM/Code Queue 开发任务默认只获得 dev 部署凭据。

## 部署清单模型

环境 manifest 使用同一套 schema：

```json
{
  "schemaVersion": 1,
  "environment": "dev",
  "services": [
    {
      "id": "backend-core",
      "repo": "https://github.com/pikasTech/unidesk",
      "commitId": "<commit>"
    },
    {
      "id": "frontend",
      "repo": "https://github.com/pikasTech/unidesk",
      "commitId": "<commit>"
    },
    {
      "id": "code-queue",
      "repo": "https://github.com/pikasTech/unidesk",
      "commitId": "<commit>"
    },
    {
      "id": "code-queue-mgr",
      "repo": "https://github.com/pikasTech/unidesk",
      "commitId": "<commit>"
    }
  ]
}
```

环境到 ref 的映射必须固定在代码或权威配置中：

- `dev` 映射到 `origin/deploy/dev`。
- `prod` 映射到 `origin/deploy/prod`。

部署命令应接收环境名，而不是让生产部署任意指定分支。debug 或 admin-only 命令可以查看任意 ref，但普通 prod 部署必须走固定映射。

## 阶段 0：设计与护栏

目的：在加入第二套运行环境前，把目标行为说清楚。

实现项：

- 定义环境 manifest schema 和校验规则。
- 给 deploy manifest 增加 `environment` 字段，并拒绝环境不匹配的 manifest。
- 定义固定环境映射：`dev -> deploy/dev`，`prod -> deploy/prod`。
- 记录 dev 的目标 namespace、数据库、Provider 身份和 service id。
- 增加 CLI dry-run plan 输出：
  - 选中的环境
  - GitHub ref
  - 解析到的 manifest commit
  - services 和 commit id
  - 目标 namespace
- 目标数据库指纹
  - 目标 Provider 身份

验收标准：

- `deploy plan --env dev` 可以读取并校验 dev manifest，且不修改集群。
- `deploy plan --env prod` 可以读取并校验 prod manifest，且不使用本地 worktree 的 `deploy.json`。
- `environment=prod` 的 manifest 必须被 `--env dev` 拒绝，反向也必须拒绝。

## 阶段 1：GitHub 环境分支作为部署源

目的：让 GitHub 里的环境期望状态 ref 成为部署真相源。

实现项：

- 创建或初始化 `deploy/dev`，包含有效的 `deploy.json`。
- 创建或初始化 `deploy/prod`，包含有效的 `deploy.json`。
- 增加 CLI 支持：fetch 环境 ref，并从该 ref 读取 `deploy.json`。
- 现有本地 `deploy.json` 只保留为显式本地/管理员流程的兼容模式。
- 校验 manifest 中列出的 commit id 存在于声明的 repo。
- 确保 dev/prod 部署不依赖本地 dirty working tree。

验收标准：

- `deploy plan --env dev` 读取 `origin/deploy/dev:deploy.json`。
- `deploy plan --env prod` 读取 `origin/deploy/prod:deploy.json`。
- 修改本地 `deploy.json` 不影响 `--env dev` 或 `--env prod`。
- plan 输出包含实际使用的 Git ref 和 manifest blob/commit。

## 阶段 2：D601 开发 Namespace 与数据库

目的：创建 dev backend 和 Code Queue state 的最小隔离底座。

实现项：

- 增加 `unidesk-dev` namespace 的 k8s manifest。
- 增加 dev PostgreSQL StatefulSet/Service/PVC，或等价持久化 DB。
- 增加 dev DB init 和 migration 流程，用于 backend-core 和 Code Queue 表。
- 增加 dev secrets/config：
  - 数据库凭据
  - provider token
  - auth/session secret
  - 必要时的 Code Queue model secrets
- 增加资源 requests/limits，避免 dev DB 挤占 D601 生产 k3s workload。

技术决策：

- 优先使用独立 dev PostgreSQL 实例，而不是共享生产 PostgreSQL 的不同数据库名。独立实例的故障边界最清晰。
- 如果临时使用共享 PostgreSQL server，CLI 和服务启动时必须硬校验数据库名和连接目标。

验收标准：

- `kubectl -n unidesk-dev get pods,svc,pvc` 显示 dev DB ready。
- dev DB 在 Pod 重启后数据仍存在。
- dev 服务误连生产数据库 URL 时，必须启动失败。

## 阶段 3：backend-core-dev 与 frontend-dev

目的：做出一套可用的 UniDesk dev 控制面，不依赖生产主 server Compose。

实现项：

- 增加 `backend-core-dev` 和 `frontend-dev` 的 k8s manifest。
- 从 `deploy/dev:deploy.json` 声明的 commit id 构建镜像。
- 向 backend-core 注入 dev-only config：
  - `UNIDESK_ENV=dev`
  - dev `MICROSERVICES_JSON`
  - dev database URL
  - dev provider token
  - dev log paths
- 注入 frontend 配置，使其代理到 `backend-core-dev`，不能代理生产 backend-core。
- 增加 service health 和 readiness probe。
- 通过 port-forward 或私有 dev ingress 暴露 dev frontend。

技术决策：

- 第一版可以不做公网暴露。验证隔离时使用 port-forward 即可。
- dev frontend 必须有明显 DEV 环境标记，避免操作员混淆。

验收标准：

- dev backend-core `/health` 返回 ok，并包含 `environment=dev`。
- dev frontend `/health` 返回 ok，并且只代理到 dev backend-core。
- dev backend/frontend 重部署期间，生产 `bun scripts/cli.ts server status` 仍健康。
- 重建 dev backend/frontend 不触碰主 server Docker Compose 容器。
- 当前实施切片：`deploy apply --env dev --service backend-core|frontend` 先支持 dev core 两个服务；`deploy/dev` 只保存 `deploy.json`，不保存 k8s manifest 或源码。

## 阶段 4：code-queue-mgr-dev

目的：提供 dev 队列管理和提交路径，同时不写生产 Code Queue 表。

实现项：

- 增加 `code-queue-mgr-dev` k8s manifest。
- 配置它只使用 dev 数据库。
- 配置 dev backend-core service catalog，使 dev 稳定 `code-queue` 控制/读取路径路由到 `code-queue-mgr-dev`。
- 确保 `code-queue-mgr-dev` 可以提交、列出、汇总和更新 dev queue state。
- health 输出必须证明：
  - role 是 `master-control-plane` 或 `dev-control-plane`
  - database 是 dev
  - schema ready
  - no runner dependencies

验收标准：

- dev UI/CLI 可以向 dev DB 提交 dry-run 或 queued task。
- dev 提交不会改变生产 Code Queue task list。
- `code-queue-mgr-dev` 内存占用保持在轻量控制面预算内。

## 阶段 5：code-queue-dev 执行组件

目的：在 `unidesk-dev` 内运行 dev Code Queue 执行面，不干扰生产 Code Queue。

实现项：

- 增加 Code Queue manifest 的 dev 变体：
  - `code-queue-read-dev`
  - `code-queue-write-dev`
  - `code-queue-scheduler-dev`
- 所有 dev 组件使用 dev 数据库、dev 日志和 dev state 路径。
- 使用 dev service name 和 label，避免生产 k3s adapter 混淆 dev/prod 服务。
- 决定第一版支持真实 Codex 执行，还是只支持 smoke-only 执行。
- 如果启用真实执行：
  - 隔离 workdir 路径
  - 隔离 Codex/OpenCode XDG/state 路径
  - 隔离通知
  - 限制并发和内存
  - 默认不写生产 OA Event Flow，除非显式配置为 dev

技术决策：

- 第一版采用真实 Code Queue 进程和 dev PostgreSQL，但部署验收先以执行面可部署、`/health` 通过和 dev DB 隔离为准。
- dev scheduler 使用 `D601-dev` 作为本机 Provider 标识，默认工作目录为 `/workspace-dev`，远程工作目录为 `/home/ubuntu/unidesk-dev-workspace`。
- 默认禁用生产 ClaudeQQ 通知，不使用生产 `d601-tcp-egress-gateway` 或生产 PostgreSQL 入口。
- dev frontend/backend-core 的稳定 `code-queue` 业务路由需要等 `code-queue-mgr-dev` 和 dev service catalog 完成后再接入，本阶段不把 dev 执行面伪装成完整业务入口。

验收标准：

- dev Code Queue `/health` 返回 ok，并包含 `environment=dev`。
- `deploy apply --env dev --service code-queue` 可以根据 `origin/deploy/dev:deploy.json` 构建 `unidesk-code-queue:dev`，部署 `code-queue-scheduler-dev`、`code-queue-read-dev`、`code-queue-write-dev`，并验证 health commit。
- 后续接入 `code-queue-mgr-dev` 后，dev scheduler 可以拾取 dev queued task，并推进到终态。
- 重启 dev scheduler 不影响生产 running task。
- dev Code Queue rollout 期间，生产 `code-queue` health 仍健康。

## 阶段 6：Dev 部署执行

目的：让 `deploy/dev:deploy.json` 端到端驱动 dev 环境。

实现项：

- 增加 `deploy apply --env dev`。
- 对 dev manifest 中的每个服务：
  - fetch 声明的 repo 和 commit
  - 在 D601 上构建镜像，或复用既有 target-side build 路径
  - 用环境和 commit 给镜像打 tag
  - apply dev k8s manifest
  - 等待 rollout
  - 从 `/health` 或 Deployment annotation 验证 live commit
- 部署记录包含 environment、ref、service id、commit id、image tag、namespace 和 rollout 状态。
- 增加 `deploy status --env dev` 或等价 drift check。

验收标准：

- 更新 `deploy/dev:deploy.json` 到新 commit 后，运行 `deploy apply --env dev` 会更新 dev backend-core/frontend/code-queue 组件。
- live `/health` commit 与 manifest commit 一致。
- dev 部署不会修改任何生产 Deployment、Service、Secret、PVC、DB table 或 Docker Compose 容器。

## 阶段 7：生产部署 Ref 兼容

目的：让生产部署从 `deploy/prod` 读取期望状态，同时保持生产运行方式不变。

实现项：

- 增加 `deploy plan --env prod` 和 `deploy apply --env prod`，读取 `origin/deploy/prod:deploy.json`。
- 初期保持现有生产 executor：
  - 生产 backend-core/frontend 和 direct sidecar 继续使用主 server Compose。
  - 生产 Code Queue 执行面继续使用 D601 k3s。
- 强化生产命令护栏：
  - 只能在权威根目录执行
  - 生产凭据只存在主 server
  - manifest 必须声明 `environment=prod`
  - 目标 namespace 和 Provider 身份必须匹配生产
- 建议后续给 `deploy/prod` 增加 branch protection；第一版可暂缓。

验收标准：

- 生产部署不再依赖本地 `deploy.json`。
- 生产部署报告实际使用的 Git ref 和 manifest commit。
- 生产部署 rollout 后仍校验 live commit。

## 阶段 8：操作员与 LLM 安全

目的：降低 LLM agent 和人工操作员混淆环境的概率。

实现项：

- 每次 deploy 的 CLI 输出都清晰显示：
  - environment
  - ref
  - namespace
  - DB 指纹
  - provider id
  - services 和 commits
- dev frontend 增加明确 DEV 标记。
- 增加硬启动检查：
  - dev service 拒绝生产 DB
  - dev service 拒绝生产 provider id/token
  - prod service 拒绝 dev namespace/DB
- 确保 LLM task container 默认只拿到 dev deploy 凭据，拿不到 prod 凭据。
- 增加 smoke check：故意尝试不安全组合，并验证它们失败。

验收标准：

- dev 服务使用生产 DB 配置启动时，在监听端口前失败。
- 从非权威上下文运行 prod deploy 时失败。
- LLM/Code Queue 默认环境可以部署 dev，但没有独立生产凭据路径时不能部署 prod。

## 风险与缓解

- 风险：namespace 不能隔离节点级 CPU、内存、Docker socket、hostPath 或 containerd 压力。
  - 缓解：资源 requests/limits、独立 dev workdir、不挂载生产路径，并限制 Code Queue 并发。
- 风险：dev Code Queue 误写生产 task 表。
  - 缓解：独立 dev DB、启动时 DB 指纹检查、health 输出 DB 身份。
- 风险：dev frontend 看起来像 prod，或代理到 prod backend-core。
  - 缓解：可见 DEV 标记、`CORE_INTERNAL_URL` 固定到 dev service、proxy target health check。
- 风险：deploy 命令误读本地 manifest，而不是 GitHub 环境 ref。
  - 缓解：`--env` 模式必须只读取 remote ref，并报告实际使用的 ref/blob。
- 风险：D601 k3s 控制面故障同时影响 dev 和生产 k3s workload。
  - 缓解：Phase 1 接受该风险；只有 namespace 隔离被证明不足后，再考虑独立物理节点或节点级 dev 集群。
- 风险：`deploy/prod` 初期未开启 branch protection。
  - 缓解：即使没有 branch protection，生产部署仍必须要求权威主 server 凭据，并报告用于审计的 ref。

## 建议实现顺序

1. Phase 0 和 Phase 1：建立 GitHub 环境分支期望状态和 dry-run planning。
2. Phase 2 和 Phase 3：创建 dev namespace、dev DB、backend-core-dev 和 frontend-dev。
3. Phase 4 和 Phase 5：增加 dev Code Queue 控制面和执行组件。
4. Phase 6：让 `deploy apply --env dev` 按 commit id 部署完整第一版 dev stack。
5. Phase 7：把生产部署迁移到 `deploy/prod`。
6. Phase 8：强化操作员和 LLM 安全检查。

第一个完整里程碑完成条件：`deploy apply --env dev` 可以根据 `origin/deploy/dev:deploy.json` 声明的 commit id，把 backend-core、frontend、code-queue-mgr 以及 Code Queue read/write/scheduler 部署进 `unidesk-dev`；反复 dev redeploy 不改变生产主 server status，也不改变生产 Code Queue state。阶段 3 的阶段性里程碑先以 `--service backend-core` 和 `--service frontend` 分别部署成功为准。