feat: add code queue services and baidu netdisk
This commit is contained in:
Codex
@@ -9,8 +9,9 @@
|
||||
- `frontend` 是唯一公开 Web 控制台，提供登录、从 TSX 转译出的 React 应用资产和到 backend-core 的同源代理。
|
||||
- `provider-gateway` 是当前主 server 的本机计算节点代理，通过 WebSocket 主动连到 provider ingress，挂载 `/var/run/docker.sock` 作为自动任务执行主路径，使用 `pid: "host"` 读取节点级进程资源，并周期性上报系统资源指标、进程占用与 Docker daemon 状态；维护用 Host SSH / WSL SSH 私钥目录只读挂载到 `/run/host-ssh`，不得作为自动任务调度主路径。
|
||||
- `todo-note` 是主 server 承载的 Todo Note 纯后端用户服务，容器名 `todo-note-backend`，只在 Compose 内网暴露 `4211/tcp`，使用主 PostgreSQL 存储迁移后的 Todo Note 数据。
|
||||
- `codex-queue` 是主 server 承载的 Codex app-server 队列用户服务，容器名 `codex-queue-backend`，仅在 Compose 内网暴露 `4222/tcp` 给本机 provider-gateway 私有代理访问，任务、queue、未读状态、控制状态和通知 outbox 一律写入主 PostgreSQL，不保留本地状态文件 fallback，浏览器只能通过 UniDesk frontend 同源代理查看运行输出、追加 prompt、打断和重试。
|
||||
- `code-queue` 是主 server 承载的 Codex app-server 队列用户服务，容器名 `code-queue-backend`，仅在 Compose 内网暴露 `4222/tcp` 给本机 provider-gateway 私有代理访问，容器硬上限为 `300m` memory/swap；任务、queue、未读状态、控制状态和通知 outbox 一律写入主 PostgreSQL，不保留本地状态文件 fallback，浏览器只能通过 UniDesk frontend 同源代理查看运行输出、追加 prompt、打断和重试。
|
||||
- `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 传输任务控制。
|
||||
|
||||
## Public Exposure Boundary
|
||||
|
||||
@@ -26,19 +27,29 @@ Compose v2 安装后仍然必须遵守 UniDesk 的服务控制入口：全栈生
|
||||
|
||||
## Start And Stop
|
||||
|
||||
`bun scripts/cli.ts server start` 与 `bun scripts/cli.ts server stop` 都是异步 job。启动 job 只执行固定 Compose project 的 `up -d --build --remove-orphans`，不得先 `down`，避免在 provider-gateway 旧容器或网络冲突时把 `codex-queue-backend` 等长任务容器先删掉又启动失败；停止 job 才允许执行 `down --remove-orphans`。启动和停止流程都禁止删除 Docker named volume。所有会改变主 server Compose 状态的 job 必须通过 `.state/locks/server-compose.lock` 串行化；`server rebuild codex-queue && server rebuild frontend` 这类连续命令只代表连续创建异步 job，不能代表第一个 job 已结束，实际容器变更仍必须由 Compose lock 串行执行。
|
||||
`bun scripts/cli.ts server start` 与 `bun scripts/cli.ts server stop` 都是异步 job。启动 job 只执行固定 Compose project 的 `up -d --build --remove-orphans`，不得先 `down`，避免在 provider-gateway 旧容器或网络冲突时把 `code-queue-backend` 等长任务容器先删掉又启动失败；停止 job 才允许执行 `down --remove-orphans`。启动和停止流程都禁止删除 Docker named volume。所有会改变主 server Compose 状态的 job 必须通过 `.state/locks/server-compose.lock` 串行化；`server rebuild code-queue && server rebuild frontend` 这类连续命令只代表连续创建异步 job，不能代表第一个 job 已结束，实际容器变更仍必须由 Compose lock 串行执行。
|
||||
|
||||
## Single Service Rebuild
|
||||
|
||||
前端、backend-core、本机 provider-gateway 或主 server 承载的 Todo Note/Codex Queue/Project Manager 用户服务需要重建时，统一使用 `bun scripts/cli.ts server rebuild <service>`，其中 `<service>` 只能是 `backend-core`、`frontend`、`provider-gateway`、`todo-note`、`codex-queue` 或 `project-manager`。该命令先执行目标服务镜像构建，构建成功后才通过 `up -d --no-deps --force-recreate <service>` 替换目标容器，避免构建失败导致运行中的服务被提前停掉。
|
||||
前端、backend-core、本机 provider-gateway 或主 server 承载的 Todo Note/Code Queue/Project Manager/Baidu Netdisk 用户服务需要重建时，统一使用 `bun scripts/cli.ts server rebuild <service>`，其中 `<service>` 只能是 `backend-core`、`frontend`、`provider-gateway`、`todo-note`、`code-queue`、`project-manager` 或 `baidu-netdisk`。File Browser 部署在 D518/D601 计算节点，不属于主 server Compose 可重建服务。该命令先执行目标服务镜像构建，构建成功后才通过 `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` 或只刷新浏览器都不会替换已经运行的容器。
|
||||
|
||||
frontend 的 Docker 上线顺序为：先运行必要的本地校验，例如 `bun scripts/cli.ts check` 或对应的 frontend bundle 检查；然后运行 `bun scripts/cli.ts server rebuild frontend`；再用 `bun scripts/cli.ts job status latest` 或具体 job id 确认 `status=succeeded`；最后用 `bun scripts/cli.ts server status`、`curl -fsS http://74.48.78.17:18081/health` 和真实页面/深链接验证。若必须手工复现 CLI 行为，等价 Docker Compose 命令只能是固定 project/env 的 `docker compose --env-file .state/docker-compose.env -f docker-compose.yml -p unidesk build frontend`，随后 `docker compose --env-file .state/docker-compose.env -f docker-compose.yml -p unidesk up -d --no-deps --force-recreate frontend`；手工路径仍必须做同样的健康检查，不得改用全栈 `up --build`、`down`、删除容器或重启 database/backend-core 来“顺手上线”前端。
|
||||
|
||||
单服务重建必须由 CLI 解析出的 Compose 命令执行，且只能影响目标 service，不得连带重启 database、backend-core 或其他未指定服务。重建后 job 必须按 Docker Compose label 校验目标容器：`com.docker.compose.project` 等于 `config.json` 中的固定 project name，`com.docker.compose.service` 等于目标服务名，并等待容器进入 `healthy`；没有 healthcheck 的服务至少要进入 `running`。如果验证失败，job 必须失败并输出目标容器状态，禁止把“无输出”或“只完成 build”当作成功。
|
||||
|
||||
正式流程不得依赖人工 `docker rm` 兜底；手工删除旧容器后若 job、Docker client 或 daemon 在 `up` 前中断，会直接造成 `direct microservice proxy failed`。`server rebuild <service>` 必须是可观测 job：build-first、Compose lock、no-deps force-recreate、post-up validation、保留 named volume。Codex Queue 等长任务服务即使被重建也必须依赖服务自身 restart-recovery 恢复任务，不能用“避免重建”掩盖恢复缺陷。
|
||||
紧急灾备或数据迁移期间如需手工启动单个 Compose service，也必须保持与 CLI 相同的隔离语义：使用固定 `--env-file .state/docker-compose.env` 和 `up -d --no-deps <service>`，只启动目标容器；如果需要刷新 backend-core 的服务目录或环境变量，应把 `backend-core` 作为显式目标单独重建/替换，不能依赖 `up` 的依赖解析顺手重建 database、backend-core 或其他服务。
|
||||
|
||||
正式流程不得依赖人工 `docker rm` 兜底；手工删除旧容器后若 job、Docker client 或 daemon 在 `up` 前中断，会直接造成 `direct microservice proxy failed`。`server rebuild <service>` 必须是可观测 job：build-first、Compose lock、no-deps force-recreate、post-up validation、保留 named volume。Code Queue 等长任务服务即使被重建也必须依赖服务自身 restart-recovery 恢复任务，不能用“避免重建”掩盖恢复缺陷。
|
||||
|
||||
## Health Criteria
|
||||
|
||||
服务跑通的最低标准是：backend-core 内网 `/health` 返回 ok，frontend 公网 `/health` 返回 ok，provider ingress 公网 `/health` 返回 ok，database 在容器内 `pg_isready` 可用，Todo Note 后端 `/api/health` 返回 `storage=postgres`，Codex Queue `/health` 返回队列摘要、默认模型和 `queue.storage`，Project Manager `/health` 返回 `storage.primary=postgres` 和项目数量，backend-core `/api/performance` 返回性能指标，`/api/nodes` 中出现 `main-server` provider 且状态为 `online`，`/api/nodes/system-status` 中出现 `main-server` 的 CPU/内存/硬盘采样，`/api/nodes/docker-status` 中出现 `main-server` 的 Docker 快照。交付前还必须运行 `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 `/health` 返回队列摘要、默认模型和 `queue.storage`，Project Manager `/health` 返回 `storage.primary=postgres` 和项目数量，backend-core `/api/performance` 返回性能指标，`/api/nodes` 中出现 `main-server` provider 且状态为 `online`，`/api/nodes/system-status` 中出现 `main-server` 的 CPU/内存/硬盘采样，`/api/nodes/docker-status` 中出现 `main-server` 的 Docker 快照。交付前还必须运行 `bun scripts/cli.ts e2e run`，并以 `docs/reference/e2e.md` 的门禁作为最终判定。
|
||||
|
||||
## Main Server Memory Budget
|
||||
|
||||
主 server 内存预算按稀缺资源管理，不能把用户服务当作无限内存的 worker 节点使用。`code-queue-backend` 必须保持 `300m` memory/swap 硬上限，默认只允许 `CODE_QUEUE_MAX_ACTIVE_QUEUES=1`，并保持 `CODE_QUEUE_IN_MEMORY_OUTPUT_RECORDS=10`、`CODE_QUEUE_IN_MEMORY_EVENT_RECORDS=10` 这类小热窗口；任务历史、队列统计、Trace/output 读取和 `/health` 摘要必须优先从 PostgreSQL 直读或聚合，不能为了性能便利在 Bun 进程内缓存全量历史。任何提高 Code Queue 并发度、热窗口、日志缓冲、Playwright/Codex 子进程常驻规模或容器上限的变更，都必须在同一任务里说明内存预算来源，并通过 `docker inspect code-queue-backend`、`docker stats --no-stream code-queue-backend`、`microservice health code-queue` 和对应 E2E 证明未重新引入内存爆炸风险。
|
||||
|
||||
## Database Volume
|
||||
|
||||
|
||||
Reference in New Issue
Block a user