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 纯后端 microservice，容器名 todo-note-backend，只在 Compose 内网暴露 4211/tcp，使用主 PostgreSQL 存储迁移后的 Todo Note 数据。

Public Exposure Boundary

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

计算节点上的 microservice 后端也遵守同一边界：业务容器端口只绑定节点本机地址，并由 provider-gateway 主动连出 WebSocket 后接受 backend-core 的 microservice.http 调度访问。主 server 不为 microservice 新增公网反向代理端口；最终用户只通过 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 的旧容器，再重新构建并启动，避免主 server 上残留旧容器或旧镜像配置。启动和停止流程禁止删除 Docker named volume。

Single Service Rebuild

前端、backend-core、本机 provider-gateway 或主 server 承载的 Todo Note microservice 需要重建时，统一使用 bun scripts/cli.ts server rebuild <service>，其中 <service> 只能是 backend-core、frontend、provider-gateway 或 todo-note。该命令先执行目标服务镜像构建，只有构建成功后才移除旧容器，避免构建失败导致运行中的服务被提前停掉。

单服务重建必须按 Docker Compose label 精确选择旧容器：com.docker.compose.project 等于 config.json 中的固定 project name，com.docker.compose.service 等于目标服务名。删除范围不得扩大到其他 Compose project、database 容器、named volume 或未匹配 label 的容器；随后必须通过 CLI 解析出的 Compose 命令执行 up -d --no-deps <service> 启动目标服务，避免因为重建 frontend 而连带重启 database 或 backend-core。

当前主 server 只安装 Docker Compose v1 时，直接执行 docker-compose up -d --no-deps --build frontend 可能走 recreate 路径并触发 ContainerConfig 兼容问题。正式流程不得依赖人工 docker rm 兜底，而应由 server rebuild frontend 固化为可观测 job：build-first、label-scoped remove、no-deps up、保留 named volume。

Health Criteria

服务跑通的最低标准是：backend-core 内网 /health 返回 ok，frontend 公网 /health 返回 ok，provider ingress 公网 /health 返回 ok，database 在容器内 pg_isready 可用，Todo Note 后端 /api/health 返回 storage=postgres，/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。

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

5.9 KiB Raw Blame History Unescape Escape