Codex
44 lines
6.5 KiB
Markdown
44 lines
6.5 KiB
Markdown
# Provider Gateway Reference
|
||
|
||
Provider Gateway 是计算节点侧容器。它只主动连出到主 server 暴露的 provider ingress WebSocket，不要求计算节点有公网 IP，适合 NAT、内网和防火墙后的机器。
|
||
|
||
## Main Server Self Provider
|
||
|
||
当前主 server 也运行一个 provider-gateway，`providerId` 固定来自 `config.json` 的 `providerGateway.id`。这让单机环境也能验证完整的分布式调度闭环：frontend 发起任务，core 写数据库并通过 provider ingress WebSocket 下发，provider gateway 执行后回传状态。
|
||
|
||
## Deployment Method
|
||
|
||
当前主 server 公网 IP 是 `74.48.78.17`，`config.json` 中的 `network.publicHost` 必须保持为该地址；公网 frontend 入口是 `http://74.48.78.17:18081/`，provider gateway 对外接入入口是 `ws://74.48.78.17:18082/ws/provider`，provider ingress 健康检查是 `http://74.48.78.17:18082/health`。主 server 本机 provider 由根目录 `docker-compose.yml` 的 `provider-gateway` 服务启动，容器内使用 Docker 内网地址 `ws://backend-core:8081/ws/provider` 自接入；外部计算节点部署 provider-gateway 时必须改用公网 provider ingress URL，并复用 `config.json` / `.state/docker-compose.env` 中的 provider token、心跳间隔和重连参数。
|
||
|
||
计算节点部署 provider-gateway 的最小方法是：准备可运行 `unidesk_provider-gateway` 镜像的 Docker 环境，为节点分配唯一 `PROVIDER_ID` 与可读 `PROVIDER_NAME`，设置 `PROVIDER_SERVER_URL=ws://74.48.78.17:18082/ws/provider`、`PROVIDER_TOKEN`、`PROVIDER_LABELS_JSON`、`HEARTBEAT_INTERVAL_MS`、`RECONNECT_BASE_MS` 和 `RECONNECT_MAX_MS`，并挂载 `/var/run/docker.sock:/var/run/docker.sock` 作为 Docker 状态采集、任务执行和远程升级的唯一自动化通道。需要支持 `provider.upgrade` 的节点还必须设置 `PROVIDER_UPGRADE_*` 环境变量，把节点上的 UniDesk 仓库只读挂载到 `PROVIDER_UPGRADE_WORKSPACE_PATH`，并确保升级命令只重建 `provider-gateway` service，不影响 database、backend-core、frontend。
|
||
|
||
## Deployment Verification
|
||
|
||
provider-gateway 部署是否成功必须以 UniDesk frontend 中可见的 Provider 信息为准，不能只看节点容器 `running`。验证时访问 `http://74.48.78.17:18081/`，使用配置中的账号密码登录，进入 `资源节点 / 节点清单`，确认目标 `PROVIDER_ID`、`PROVIDER_NAME`、`online` 状态、`lastHeartbeat` 和 labels 可见；点击该节点的 `查看原始JSON`，确认 raw payload 中的 `providerId`、`name`、`status`、`labels` 与部署环境变量一致。随后进入 `资源节点 / 资源监控`，确认该 Provider 有 CPU、实际内存和硬盘采样曲线；进入 `资源节点 / Docker 状态`，确认 Docker daemon、containers、images、volumes、networks 已渲染出来，且 `dockerSocketPresent` 或 Docker ready 状态与预期一致。只有这些前端信息都能通过 UniDesk 正常读取，才说明 provider-gateway 已经真正挂载到主 server。
|
||
|
||
自动化验证必须使用 Playwright 访问公网 frontend，而不是在容器内直接调 core API 代替浏览器验收。标准命令是 `bun scripts/cli.ts e2e run`；该命令会让 Playwright 打开公网 `http://74.48.78.17:18081/`、登录、抓取页面中的 Provider 信息和 `查看原始JSON` 内容，并检查 Provider 自接入、资源指标、Docker 状态和 `provider.upgrade` 预检。外部新增节点的人工验收应复用同一套前端路径：先确认 Provider 信息出现在节点清单，再确认资源监控和 Docker 状态页面有该节点的数据，最后通过任务调度向该 Provider 下发 `echo` 或 `docker.ps` 并在任务历史中查看耗时、状态和失败原因。
|
||
|
||
## Provider Ingress
|
||
|
||
provider ingress 是唯一允许公网暴露的 provider 连接接口，当前由 backend-core 容器的独立端口提供 `/ws/provider` 和 `/health`。backend-core REST API 仍只在 Docker 内网开放，外部计算节点只应连接 provider ingress。
|
||
|
||
## Docker Socket Path
|
||
|
||
自动任务执行只允许走本地 Docker socket。Compose 将 `/var/run/docker.sock` 挂入 provider-gateway，provider 标签会报告 `dockerSocketPresent`，`docker.ps` 调试任务会通过该 socket 查询宿主 Docker 容器。
|
||
|
||
## Docker Status Telemetry
|
||
|
||
provider-gateway 连接成功后必须周期性上报 Docker daemon 状态，数据来源是本地 Docker socket 上的 `docker info`、`docker ps -a`、`docker images`、`docker volume ls` 和 `docker network ls`。backend-core 将最新快照保存到 `unidesk_node_docker_status`，frontend 的资源节点 `Docker 状态` 子标签用该快照渲染 Docker Desktop 风格视图；该能力仍然只通过 provider 主动上报，不要求主 server 反向连接计算节点。
|
||
|
||
## System Status Telemetry
|
||
|
||
provider-gateway 连接成功后必须周期性上报节点 CPU、内存和硬盘用量。采集来源是节点本地 `/proc/stat`、`/proc/loadavg`、`/proc/meminfo` 与 `df -PB1`，backend-core 将最新快照保存到 `unidesk_node_system_status`，并将历史采样保存到 `unidesk_node_metric_samples` 供 frontend 绘制任务管理器风格曲线。内存使用量采用实际占用口径：`MemTotal - MemFree - Buffers - Cached - SReclaimable + Shmem`，也就是不把 Linux page cache / buffer 计入占用；上报中同时保留 `cacheBytes` 便于排查。该链路仍然由 provider 主动上报，主 server 不反向探测计算节点。
|
||
|
||
## Remote Provider Upgrade
|
||
|
||
backend-core 可以通过真实 WebSocket 调度向在线 provider 下发 `provider.upgrade`。`mode: "plan"` 只返回升级计划，用于 E2E 和人工预检；`mode: "schedule"` 会要求 provider-gateway 通过本地 Docker socket 启动一个 detached updater 容器，由 updater 在节点本地执行 `docker compose up -d --no-deps --build provider-gateway`。`--no-deps` 是强制要求，升级 provider-gateway 时不得重建或停止 database、backend-core、frontend。升级执行路径使用 Docker socket 和只读仓库挂载，不使用 Host SSH 维护桥作为自动调度通道。
|
||
|
||
## Host SSH Maintenance Bridge
|
||
|
||
宿主 SSH 转发只作为应急维护辅助路径，不用于自动任务调度。实现参考 `../web-terminal` 的经验：容器内使用只读挂载的私钥，通过 `ssh -tt` 主动连接宿主 sshd，并设置 `StrictHostKeyChecking=accept-new`、`ServerAliveInterval` 和 `ServerAliveCountMax`。本仓库保留 `src/components/provider-gateway/scripts/host-ssh-shell.sh` 作为维护桥接脚本，默认 Compose 不挂载私钥，避免把 SSH 路径误用为调度通道。
|