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 是无状态核心服务，提供 REST API、provider WebSocket、任务调度入口和数据库访问层。
• frontend 是独立 Web 容器，通过浏览器访问 core 的公开 API URL。
• provider-gateway 是当前主 server 的本机计算节点代理，通过 WebSocket 主动连到 backend-core，并挂载 /var/run/docker.sock 作为自动任务执行主路径。

Start And Stop

bun scripts/cli.ts server start 与 bun scripts/cli.ts server stop 都是异步 job。启动 job 会先清理固定 Compose project 的旧容器，再重新构建并启动，避免主 server 上残留旧容器或旧镜像配置。启动后用 job status latest 观察后台命令，用 server status 验证端口、容器和健康检查。

Health Criteria

服务跑通的最低标准是：backend-core /health 返回 ok，frontend /health 返回 ok，database 端口监听，/api/nodes 中出现 main-server provider 且状态为 online，debug dispatch main-server docker.ps 能完成真实任务下发。交付前还必须运行 bun scripts/cli.ts e2e run，并以 docs/reference/e2e.md 的门禁作为最终判定。

Database Volume

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