docs: record provider upgrade source truth

2026-06-29 13:11:22 +00:00
parent ab1e9bf5c4
commit e6f9ebf227
2 changed files with 4 additions and 0 deletions
@@ -172,6 +172,8 @@ D601 这类长期 WSL provider 不得因为单一路径失败被直接写成全

 如果节点固定 UniDesk 仓库存在并行未提交修改或落后太多，不能为了 provider-gateway 恢复而 stash、reset 或把脏工作区作为构建真相。应在同一节点的固定仓库下从最新 remote 创建独立 clean runtime worktree，例如 `/home/ubuntu/unidesk/.worktree/provider-gateway-<ID>-runtime`，把节点本地 `.state/provider-<ID>.env`、`provider-<ID>.yml` 和必要的本地 Dockerfile/Compose 运行态指向该 worktree，并把 `PROVIDER_UPGRADE_HOST_PROJECT_ROOT` 改为该 clean worktree。bootstrap 成功后仍必须立刻执行标准 `provider.upgrade mode=schedule` 和 Host SSH/`trans` 原入口验收；clean runtime worktree 是恢复固定 repo 隔离性的手段，不是新的长期 source truth。

+`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 字段。
+
 如果节点已有专用 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`。