pikasTech-unidesk/docs/reference/deployment.md

UniDesk Deployment Reference

主 server 使用根目录 docker-compose.yml 统一编排 database、backend-core、frontend 和 provider-gateway。当前环境本身就是主 server，因此 provider-gateway 也在同一台机器上启动，用与普通计算节点相同的 WebSocket 方式接入 core。

Services

• database 使用 postgres:16-alpine，数据保存到 named volume unidesk_pgdata_10gb，初始化 SQL 位于 src/components/database/init/。
• backend-core 是无状态核心服务，提供 Docker 内网 REST API、provider ingress WebSocket、任务调度入口和数据库访问层。
• 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 数据。
• 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

Docker Compose 只能向公网暴露两个接口：frontend host port 和 provider ingress host port。backend-core REST API 和 PostgreSQL database 必须只在 Docker 内部网络中可达，不允许映射到宿主机公网端口；浏览器访问 core API 必须通过 frontend 的同源代理完成。

计算节点上的用户服务后端也遵守同一边界：业务容器端口只绑定节点本机地址，并由 provider-gateway 主动连出 WebSocket 后接受 backend-core 的 microservice.http 调度访问。主 server 不为用户服务新增公网反向代理端口；最终用户只通过 UniDesk frontend 的 React 页面访问结构化业务控件。

Docker Compose Runtime

CLI 会优先使用 docker compose v2 plugin；当 v2 plugin 不存在时才回退到 docker-compose v1。主 server 可以通过安装系统包形式的 Compose v2 plugin 完成无中断升级，因为该动作只增加 Docker CLI plugin，不要求重启 Docker daemon，也不要求重建或停止已有容器。若 Compose v2 build 提示 buildx plugin 不存在，应同样以系统包安装 buildx CLI plugin，而不是重启 Docker 或重建业务容器。

Compose v2 安装后仍然必须遵守 UniDesk 的服务控制入口：全栈生命周期用 server start / server stop，单服务重建用 server rebuild <service>。不要因为 v2 可用就直接在生产栈上手工执行未纳入 CLI 的 up --build、down -v 或跨项目清理命令；所有会影响容器的动作都应保持 job 可观测、Compose project 固定、database named volume 保留。

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 旧容器或网络冲突时把 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/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”当作成功。

紧急灾备或数据迁移期间如需手工启动单个 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，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 必须保持明确的 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 读取和 /health 摘要必须优先从 PostgreSQL 直读或聚合，不能为了性能便利在 Bun 进程内缓存全量历史。任何提高 Code Queue 热窗口、日志缓冲、Playwright/Codex 子进程常驻规模或容器上限的变更，或把 CODE_QUEUE_MAX_ACTIVE_QUEUES 显式改成正数，都必须在同一任务里说明内存预算来源，并通过 docker inspect code-queue-backend、docker stats --no-stream code-queue-backend、microservice health code-queue 和对应 E2E 证明未重新引入内存爆炸风险。

Database Volume

架构要求数据库使用 10 GB named volume；当前实现将 volume 命名为 unidesk_pgdata_10gb 以固定生命周期。Docker named volume 默认不强制容量上限；如需硬配额，应在主机存储层或 Docker volume driver 层配置。CLI server 控制只能使用不删除 volume 的 down / up 流程，禁止使用 down -v、docker volume rm 或删除 unidesk_pgdata_10gb。

/api/overview 会返回 pgdata 字段，frontend 态势总览 / 核心指标 必须展示当前 PostgreSQL 数据库占用、命名卷名称和配置容量。Docker 状态页中 unidesk_pgdata_10gb 的命名卷检测只对 main-server Provider 生效，其他计算节点不需要也不应被要求存在该数据库卷。