docs: document provider compose label drift

2026-06-29 17:43:09 +00:00
parent 963672ea4f
commit 10f84f4f0d
1 changed files with 2 additions and 0 deletions
@@ -174,6 +174,8 @@ D601 这类长期 WSL provider 不得因为单一路径失败被直接写成全

 `PROVIDER_UPGRADE_HOST_PROJECT_ROOT` 指向的 runtime source root 必须是可执行 `git status --short --branch`、`git fetch origin <branch>` 和 `git pull --ff-only origin <branch>` 的真实 Git checkout；无 `.git` 的源码快照不能作为 provider-gateway 升级 source truth。节点没有 GitHub 私仓凭据时，可以先把 `origin` 指向同节点受控 local bare mirror，但该 mirror 必须由有权限的 source truth 显式同步，并在 closeout 中说明 mirror 同步入口和当前 commit；不能把本地 bare mirror 的 `Already up to date` 误写成已直接跟 GitHub 同步。`provider.upgrade mode=plan` 的验收必须同时看 `plan.hostProjectRoot`、`plan.workspaceStateMount`、当前/目标 gateway 版本和最终 Compose 容器 heartbeat 字段。

+手动 bootstrap 或从旧部署迁移到 Compose 管理后，运行中的 provider-gateway 容器必须带有与 `.state/provider-<ID>.env` 中 `PROVIDER_UPGRADE_COMPOSE_PROJECT` 和 `PROVIDER_UPGRADE_SERVICE` 完全一致的 `com.docker.compose.project` / `com.docker.compose.service` label。容器名相同、镜像 tag 相同或 Docker `running` 都不能替代这个 label 验收；`provider.upgrade mode=schedule` 的 updater 会按这些 Compose labels 定位旧容器并安全替换，project 漂移会导致 updater 找不到当前 service。发现漂移时，应在节点本地用正确 `-p <compose-project>` 和同一 env/compose 文件重建一次，再执行标准 `provider.upgrade mode=schedule` 复验。
+
 如果节点已有专用 Compose，优先用节点本地 Compose 手动重建一次：`docker compose --env-file .state/provider-<ID>.env -f <compose-file> -p <compose-project> up -d --no-deps --build --force-recreate provider-gateway`。这条命令必须在节点本地终端、节点自有 Web terminal、系统计划任务或 detached shell 中执行；不得通过正在被重建的 UniDesk provider-gateway 自己提供的 SSH 透传同步执行，否则旧 provider 容器停止时会切断 SSH client，可能导致重建中断在旧容器已停、新容器未起的状态。若只能通过 UniDesk 触达该节点，必须使用 `provider.upgrade mode=schedule` 的 detached updater，或先用节点本地 `nohup`/systemd 启动一个不依赖当前 provider 容器生命周期的重建脚本。老版 `docker-compose` 可能在重建已存在容器时因为 `ContainerConfig` 兼容问题失败；此时只能移除目标 provider-gateway 容器后重新 `up -d --no-deps provider-gateway`，不得执行 `down -v`、`docker volume rm` 或任何会影响 database 命名卷的命令。如果节点当前只有 `docker run` 部署，则先构建镜像 `docker build -f src/components/provider-gateway/Dockerfile -t unidesk_provider-gateway:<id> .`，再以固定容器名重建：使用 `--restart always --pid host`，挂载 `/var/run/docker.sock:/var/run/docker.sock`、`/home/ubuntu/unidesk:/workspace:ro`、节点日志目录到 `/var/log/unidesk`，如需 WSL SSH 维护桥还要把只读私钥目录挂载到 `/run/host-ssh`，并使用同一个 `.state/provider-<ID>.env` 启动。无论 Compose 还是 `docker run`，容器名和镜像 tag 都必须带 Provider ID，便于 Docker 状态页、进程资源表、任务历史和节点本地排障互相对应。

 手动升级完成后的判定标准固定为主 server 可观测结果，而不是节点容器 `running`：访问公网 frontend `http://74.48.78.17:18081/`，确认该 Provider 在线；随后在任意装有本仓库且 `config.json` 含正确 frontend 登录凭据的计算节点上执行 `bun scripts/cli.ts --main-server-ip 74.48.78.17 debug dispatch <PROVIDER_ID> provider.upgrade --mode schedule --wait-ms 300000`，确认任务 `succeeded` 且 result 包含最终 Compose 容器 `containerId`、目标 gateway `version`、`restartPolicy=always`、`pidMode=host` 和新的 `heartbeatTimestamp`；最后再次查看 frontend 或执行 `bun scripts/cli.ts --main-server-ip 74.48.78.17 debug health`，确认节点重连、指标恢复、labels 中 `host.ssh` 能力存在。每个 provider-gateway 手动升级后都必须用 remote CLI 再执行 `bun scripts/cli.ts --main-server-ip 74.48.78.17 debug dispatch <PROVIDER_ID> host.ssh --wait-ms 15000` 和 `bun scripts/cli.ts --main-server-ip 74.48.78.17 ssh <PROVIDER_ID> hostname`，验证维护桥没有在升级后丢失；该 remote CLI 默认走公网 frontend，不需要指定 `--main-server-key`。