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 作为自动任务执行主路径，并周期性上报系统资源指标与 Docker daemon 状态。

Public Exposure Boundary

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

Start And Stop

bun scripts/cli.ts server start 与 bun scripts/cli.ts server stop 都是异步 job。启动 job 会先清理固定 Compose project 的旧容器，再重新构建并启动，避免主 server 上残留旧容器或旧镜像配置。启动和停止流程禁止删除 Docker named volume。

Health Criteria

服务跑通的最低标准是：backend-core 内网 /health 返回 ok，frontend 公网 /health 返回 ok，provider ingress 公网 /health 返回 ok，database 在容器内 pg_isready 可用，/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 的门禁作为最终判定。

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。

2.6 KiB Raw Blame History Unescape Escape