feat: add master code queue manager
This commit is contained in:
Codex
@@ -1,6 +1,6 @@
|
||||
# UniDesk Deployment Reference
|
||||
|
||||
主 server 使用根目录 `docker-compose.yml` 统一编排 database、backend-core、frontend、provider-gateway 以及必须留在主 server 的用户服务。当前环境本身就是主 server，因此 provider-gateway 也在同一台机器上启动，用与普通计算节点相同的 WebSocket 方式接入 core。Code Queue 不再属于主 server Compose，也不再由 backend-core 通过 provider-gateway 直连业务容器；它作为 `k3sctl-managed` 用户服务经 D601 `k3sctl-adapter` 进入 k3s 标准服务路由。
|
||||
主 server 使用根目录 `docker-compose.yml` 统一编排 database、backend-core、frontend、provider-gateway 以及必须留在主 server 的用户服务。当前环境本身就是主 server，因此 provider-gateway 也在同一台机器上启动，用与普通计算节点相同的 WebSocket 方式接入 core。Code Queue 按“master 低资源低抖动控制面、D601 高资源高抖动执行面”拆分：队列 CRUD、任务提交、历史摘要和轻量 Trace 读取由主 server Compose 中的 `code-queue-mgr` 直管 PostgreSQL；Codex/OpenCode scheduler、runner、dev-container、active run steer/interrupt 和执行态写回仍由 D601 原生 k3s/k8s Code Queue 执行面承担。
|
||||
|
||||
## Services
|
||||
|
||||
@@ -9,8 +9,9 @@
|
||||
- `frontend` 是唯一公开 Web 控制台，提供登录、从 TSX 转译出的 React 应用资产和到 backend-core 的同源代理。
|
||||
- `provider-gateway` 是当前主 server 的本机计算节点代理，通过 WebSocket 主动连到 provider ingress，挂载 `/var/run/docker.sock` 作为自动任务执行主路径，使用 `pid: "host"` 读取节点级进程资源，并周期性上报系统资源指标、进程占用与 Docker daemon 状态；计算节点 provider-gateway 还必须把 egress proxy 仅发布到宿主 loopback `127.0.0.1:18789` 供本节点执行环境出网，维护用 Host SSH / WSL SSH 私钥目录只读挂载到 `/run/host-ssh`，不得作为自动任务调度主路径。
|
||||
- `todo-note` 是主 server 承载的 Todo Note 纯后端用户服务，容器名 `todo-note-backend`，只在 Compose 内网暴露 `4211/tcp`，使用主 PostgreSQL 存储迁移后的 Todo Note 数据。
|
||||
- `code-queue-mgr` 是主 server 承载的轻量 Code Queue 控制面用户服务，容器名 `code-queue-mgr-backend`，只在 Compose 内网暴露 `4278/tcp`，只连接主 PostgreSQL，负责 `code-queue` 稳定代理路径下的队列管理、任务提交、历史摘要、已读状态和轻量 Trace 读取；不得引入 Codex/OpenCode/Playwright/Chromium/Docker socket/runner 依赖。
|
||||
- `k3sctl-adapter` 是 D601 上由 UniDesk 直管的 k3s 控制面适配微服务，容器名 `k3sctl-adapter`，只绑定 `127.0.0.1:4266`，由 UniDesk frontend/backend-core 通过用户服务代理访问并提供 `/api/control-plane` 可见性。
|
||||
- `code-queue` 是由 D601 原生 k3s/k8s 控制面代管的 Codex/OpenCode 队列用户服务，当前拓扑为 D601 内的 read/write/scheduler 多 Service，通过 `src/components/microservices/k3sctl-adapter/k3s/code-queue.k3s.json` 声明，运行对象通过 `code-queue.k8s.yaml` 创建 Kubernetes Deployment/ClusterIP Service；任务、queue、未读状态、控制状态和通知 outbox 一律写入主 PostgreSQL，不保留本地状态文件 fallback。浏览器只使用稳定的 `code-queue` 用户服务 ID，backend-core 在内部把只读请求分到 `code-queue-read`，把命令写入分到 `code-queue-write`，把执行端 `/health`、dev-container 和 running task control 分到 `code-queue-scheduler`。
|
||||
- `code-queue` 是稳定对外用户服务 ID。backend-core 对 `/api/microservices/code-queue/proxy/...` 做内部职责分流：控制/读取路径默认转到主 server `code-queue-mgr`，D601 k3s `code-queue-read`/`code-queue-write`/`code-queue-scheduler` 只承担执行面兼容、scheduler/runner、dev-container、judge 和 running task control。D601 执行面通过 `src/components/microservices/k3sctl-adapter/k3s/code-queue.k3s.json` 声明，运行对象通过 `code-queue.k8s.yaml` 创建 Kubernetes Deployment/ClusterIP Service；任务、queue、未读状态、控制状态和通知 outbox 一律写入主 PostgreSQL，不保留本地状态文件 fallback。
|
||||
- `project-manager` 是主 server 承载的项目管理用户服务，容器名 `project-manager-backend`，仅在 Compose 内网暴露 `4233/tcp`，项目清单写入主 PostgreSQL，浏览器只能通过 UniDesk frontend 同源代理执行增删改查、Excel 导入和 Excel 导出。
|
||||
- `baidu-netdisk` 是主 server 承载的百度网盘存储用户服务，容器名 `baidu-netdisk-backend`，仅在 Compose 内网暴露 `4244/tcp`，OAuth/token/transfer 状态写入主 PostgreSQL，浏览器只能通过 UniDesk frontend 同源代理执行设备码登录、文件浏览和 staging 传输任务控制。
|
||||
|
||||
@@ -34,7 +35,7 @@ Compose v2 安装后仍然必须遵守 UniDesk 的服务控制入口：全栈生
|
||||
|
||||
## Single Service Rebuild
|
||||
|
||||
前端、backend-core、本机 provider-gateway 或主 server 承载的 Todo Note/Project Manager/Baidu Netdisk/OA Event Flow 用户服务需要重建时，统一使用 `bun scripts/cli.ts server rebuild <service>`，其中 `<service>` 只能是 `backend-core`、`frontend`、`provider-gateway`、`todo-note`、`project-manager`、`baidu-netdisk` 或 `oa-event-flow`。Code Queue、File Browser、FindJob、Pipeline、MET Nonlinear 和 ClaudeQQ 部署在计算节点，不属于主 server Compose 可重建服务；其中 D601 Code Queue 的正式入口是 `bun scripts/cli.ts codex deploy <commitId>`。该命令先执行目标服务镜像构建，构建成功后才通过 `up -d --no-deps --force-recreate <service>` 替换目标容器，避免构建失败导致运行中的服务被提前停掉。
|
||||
前端、backend-core、本机 provider-gateway 或主 server 承载的 Todo Note/Code Queue Manager/Project Manager/Baidu Netdisk/OA Event Flow 用户服务需要重建时，统一使用 `bun scripts/cli.ts server rebuild <service>`，其中 `<service>` 只能是 `backend-core`、`frontend`、`provider-gateway`、`todo-note`、`code-queue-mgr`、`project-manager`、`baidu-netdisk` 或 `oa-event-flow`。D601 Code Queue 执行面、File Browser、FindJob、Pipeline、MET Nonlinear 和 ClaudeQQ 部署在计算节点，不属于主 server Compose 可重建服务；其中 D601 Code Queue 执行面的正式入口是 `bun scripts/cli.ts codex deploy <commitId>`。该命令先执行目标服务镜像构建，构建成功后才通过 `up -d --no-deps --force-recreate <service>` 替换目标容器，避免构建失败导致运行中的服务被提前停掉。
|
||||
|
||||
frontend 改动必须明确上线到公网：修改 `src/components/frontend/src/`、`src/components/frontend/public/style.css`、frontend 使用的共享 TSX/TS 模块或 WebUI 导航后，必须在同一变更集中执行 `bun scripts/cli.ts server rebuild frontend`，并等待 job 成功。公网 WebUI 的 `/app.js` 是 `unidesk-frontend` 容器启动时从镜像内源码转译生成的运行时 bundle；只改工作区文件、只跑 `bun run check`、只跑 `Bun.build` 或只刷新浏览器都不会替换已经运行的容器。
|
||||
|
||||
@@ -52,15 +53,17 @@ frontend 的 Docker 上线顺序为：先运行必要的本地校验，例如 `b
|
||||
|
||||
## Health Criteria
|
||||
|
||||
服务跑通的最低标准是：backend-core 内网 `/health` 返回 ok，frontend 公网 `/health` 返回 ok，provider ingress 公网 `/health` 返回 ok，database 在容器内 `pg_isready` 可用，Todo Note 后端 `/api/health` 返回 `storage=postgres`，`k3sctl-adapter` `/api/control-plane` 可见 `unidesk-k3s` Kubernetes API service proxy 状态、D601 scheduler serving healthy、D601 read/write Service healthy、`presentNodeIds` 包含 `D601`、`missingNodeIds=[]` 和 no-fallback 路径，Code Queue `/health` 经 k3s scheduler Service 返回轻量 readiness、默认模型、`queue.storage` 和 `egressProxy.connected=true`，`/api/tasks/overview` 经 `code-queue-read` 返回 PostgreSQL 队列总览，写入类入口经 `code-queue-write` 入库后由 `code-queue-scheduler` 轮询并执行，Project Manager `/health` 返回 `storage.primary=postgres` 和项目数量，backend-core `/api/performance` 返回性能指标，`/api/nodes` 中出现 `main-server`、`D601` 和 `D518` provider 且状态为 `online`，`/api/nodes/system-status` 中出现对应 CPU/内存/硬盘采样，`/api/nodes/docker-status` 中能看到主 server、D601 与 D518 Docker 快照。D601/D518 上不得存在 active `rancher/k3s` 容器；D518 只有在原生 k3s-agent 与稳定 Kubernetes 网络完成验证后才可加入 Code Queue expected nodes。交付前还必须运行 `bun scripts/cli.ts e2e run`，并以 `docs/reference/e2e.md` 的门禁作为最终判定。
|
||||
服务跑通的最低标准是：backend-core 内网 `/health` 返回 ok，frontend 公网 `/health` 返回 ok，provider ingress 公网 `/health` 返回 ok，database 在容器内 `pg_isready` 可用，Todo Note 后端 `/api/health` 返回 `storage=postgres`，`code-queue-mgr` `/health` 返回 `role=master-control-plane`、`schemaReady=true` 和资源预算字段，`bun scripts/cli.ts microservice health code-queue` 与 `/api/tasks/overview` 默认经主 server `code-queue-mgr` 返回 PostgreSQL 队列总览，`k3sctl-adapter` `/api/control-plane` 可见 `unidesk-k3s` Kubernetes API service proxy 状态、D601 scheduler serving healthy、D601 read/write Service healthy、`presentNodeIds` 包含 `D601`、`missingNodeIds=[]` 和 no-fallback 路径，D601 Code Queue scheduler `/health` 返回轻量 readiness、默认模型、`queue.storage` 和 `egressProxy.connected=true`，提交类入口经 `code-queue-mgr` 入库后由 D601 `code-queue-scheduler` 轮询并执行，Project Manager `/health` 返回 `storage.primary=postgres` 和项目数量，backend-core `/api/performance` 返回性能指标，`/api/nodes` 中出现 `main-server`、`D601` 和 `D518` provider 且状态为 `online`，`/api/nodes/system-status` 中出现对应 CPU/内存/硬盘采样，`/api/nodes/docker-status` 中能看到主 server、D601 与 D518 Docker 快照。D601/D518 上不得存在 active `rancher/k3s` 容器；D518 只有在原生 k3s-agent 与稳定 Kubernetes 网络完成验证后才可加入 Code Queue expected nodes。交付前还必须运行 `bun scripts/cli.ts e2e run`，并以 `docs/reference/e2e.md` 的门禁作为最终判定。
|
||||
|
||||
## Code Queue D601 Resource Budget
|
||||
## Code Queue Control/Execution Resource Budget
|
||||
|
||||
Code Queue 已从主 server 迁移到 D601 k3s/k8s，但仍必须保持明确的 memory/swap 硬上限，默认 `CODE_QUEUE_MAX_ACTIVE_QUEUES=0` 以恢复 queue 间并行，仍保持 `CODE_QUEUE_IN_MEMORY_OUTPUT_RECORDS=10`、`CODE_QUEUE_IN_MEMORY_EVENT_RECORDS=10` 这类小热窗口；任务历史、队列统计和 Trace/output 读取必须优先从 PostgreSQL 直读或聚合，`/health` 只做轻量 readiness，不能为了性能便利在 Bun 进程内缓存全量历史。任何提高 Code Queue 热窗口、日志缓冲、Playwright/Codex 子进程常驻规模或容器上限的变更，或把 `CODE_QUEUE_MAX_ACTIVE_QUEUES` 显式改成正数，都必须在同一任务里说明 D601 资源预算来源，并通过 D601 `KUBECONFIG=/home/ubuntu/unidesk-code-queue-deploy/.state/k3s/kubeconfig kubectl -n unidesk get deploy,svc,pod`、`kubectl -n unidesk top pod` 或等价 Docker stats、`microservice health code-queue` 和对应 E2E 证明未重新引入内存爆炸风险。
|
||||
主 server `code-queue-mgr` 是低资源控制面，目标常驻内存不超过 100 MB，只允许 PostgreSQL 小连接池、日志和基础 CRUD/摘要逻辑；不得安装或运行 Playwright、Chromium、Codex/OpenCode、Docker socket、dev-container 或执行器。它的 `/health` 必须暴露 `resourceBudget.targetMemoryMb=100`、`noRunnerDependencies=true`、连接池上限和 `role=master-control-plane`，便于在主 server 低内存环境中识别是否越界。
|
||||
|
||||
D601 Code Queue 执行面仍必须保持明确的 memory/swap 硬上限，默认 `CODE_QUEUE_MAX_ACTIVE_QUEUES=0` 以恢复 queue 间并行，仍保持 `CODE_QUEUE_IN_MEMORY_OUTPUT_RECORDS=10`、`CODE_QUEUE_IN_MEMORY_EVENT_RECORDS=10` 这类小热窗口；任务历史、队列统计和 Trace/output 读取必须优先从 PostgreSQL 直读或聚合，执行面 `/health` 只做轻量 readiness，不能为了性能便利在 Bun 进程内缓存全量历史。任何提高 Code Queue 热窗口、日志缓冲、Playwright/Codex 子进程常驻规模或容器上限的变更，或把 `CODE_QUEUE_MAX_ACTIVE_QUEUES` 显式改成正数，都必须在同一任务里说明 D601 资源预算来源，并通过 D601 `KUBECONFIG=/home/ubuntu/unidesk-code-queue-deploy/.state/k3s/kubeconfig kubectl -n unidesk get deploy,svc,pod`、`kubectl -n unidesk top pod` 或等价 Docker stats、D601 scheduler health 和对应 E2E 证明未重新引入内存爆炸风险。
|
||||
|
||||
## Database Connection Budget
|
||||
|
||||
主 PostgreSQL 的内存预算按“少量长驻服务连接池 + 短查询按需连接”设计，不允许每个 Bun 服务沿用默认 8 到 10 个连接。`backend-core` 默认 `DATABASE_POOL_MAX=4`，主 server 上的 `oa-event-flow`、`baidu-netdisk` 默认 `DATABASE_POOL_MAX=2`，`project-manager` 默认 `DATABASE_POOL_MAX=1`，D601 `code-queue` 默认 `CODE_QUEUE_DATABASE_POOL_MAX=2`；如需提高任一连接池上限，必须同时说明并发 SQL 需求、验证 `pg_stat_activity` 中该服务没有长期 idle 堆积，并确认 `max_connections` 仍有足够余量。PostgreSQL 基础配置固定保守值：`shared_buffers=128MB`、`work_mem=4MB`、`maintenance_work_mem=64MB`、`max_connections=50`，避免主 server 低内存环境被空闲 backend 和过大的 per-query 内存预算挤占。
|
||||
主 PostgreSQL 的内存预算按“少量长驻服务连接池 + 短查询按需连接”设计，不允许每个 Bun 服务沿用默认 8 到 10 个连接。`backend-core` 默认 `DATABASE_POOL_MAX=4`，主 server 上的 `oa-event-flow`、`baidu-netdisk` 默认 `DATABASE_POOL_MAX=2`，`project-manager` 默认 `DATABASE_POOL_MAX=1`，`code-queue-mgr` 默认 `CODE_QUEUE_MGR_DATABASE_POOL_MAX=2` 与 `CODE_QUEUE_TRACE_DATABASE_POOL_MAX=1`，D601 `code-queue` 默认 `CODE_QUEUE_DATABASE_POOL_MAX=2`；如需提高任一连接池上限，必须同时说明并发 SQL 需求、验证 `pg_stat_activity` 中该服务没有长期 idle 堆积，并确认 `max_connections` 仍有足够余量。PostgreSQL 基础配置固定保守值：`shared_buffers=128MB`、`work_mem=4MB`、`maintenance_work_mem=64MB`、`max_connections=50`，避免主 server 低内存环境被空闲 backend 和过大的 per-query 内存预算挤占。
|
||||
|
||||
排查 PostgreSQL 内存时以 `docker stats unidesk-database`、`pg_stat_activity` 分组和 `pg_settings` 为准；主机 `ps` 中每个 `postgres` 进程的 RSS 会重复计入共享内存，不能把所有 backend RSS 简单相加当作真实容器占用。所有 UniDesk PostgreSQL 客户端都必须设置可识别的 `application_name`，便于按服务统计连接数、状态和慢查询归属。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user