Files
myrzx_bot/deploy/web/UPDATE_PROTOCOL.md

5.7 KiB
Raw Permalink Blame History

Web 2 更新接口(协议 1)

供 API、前端、宿主机更新器与 Main 集成。ranch_web.updates.UpdateService(root, current_version) 只依赖 Python 标准库;构造和 status() 不联网,check() 访问固定官方 GitHub Releases,request_update(version=None) 再次联网验证后仅提交文件请求。宿主机 HostUpdater.apply() 独立再次验证发布。API 可在线程池中调用检查,不能在事件循环里等待网络。

  • 固定仓库:attilanet/myrzx_bot;固定镜像:ghcr.io/attilanet/myrzx_bot-web。
  • 唯一可选发布 tag:v2.MINOR.PATCH(十进制、不许前导零、无任何后缀)。草稿、预发布、1.x、3.x、dev 分支全部跳过;按版本数值比较,不信任 GitHub latest 排序。
  • root 为 Web 数据根(Docker /data),文件为 update-check.json、update-request.json、updater-status.json。账号数据与这些控制文件隔离。
  • RANCH_WEB_UPDATER_DIR 指向宿主机心跳目录,Docker 固定 /run/ranch-updater,只读挂载,与 /data 分离。没有有效 capability.json 时 can_apply=false,仅检查可用;Windows 默认如此。
  • 心跳由宿主机定时任务写入,含 protocol=1, executor_id, enabled, auto_apply, heartbeat_at, expires_at。执行器配置默认 accept_web_requests=false, auto_apply=false,操作者必须显式启用 Web 请求。心跳有效期 15 分钟、timer 每 5 分钟运行。
  • update-request.json 仅含 protocol=1, request_id(32 位小写十六进制)、executor_id、version(官方 tag)、requested_at(UTC ISO 8601)。禁止镜像地址、命令、下载地址或路径。宿主机再次联网验证 tag、版本单调递增并去重;Web 写文件不等于部署成功。

私有发布凭据只来自服务端 <root>/update-github-token,宿主机使用配置中的 data_dir;Docker 默认通过既有挂载共享同一文件。POSIX 权限必须为 0600,普通文件、非软/硬链接、最多 4096 字节;部署所有者为 10001:10001。可选 RANCH_WEB_UPDATE_GITHUB_TOKEN_FILE 仅接受绝对文件路径,显式无效路径直接失败。未提供覆盖且默认文件缺失时保持匿名公共访问;不读取 Git 凭据、不接收原始 Token 环境变量/TOML/Web 参数。低层 github_releases(data_dir=None) 保留无参数公共调用形式,服务与宿主机均传入自己的数据目录,每次查询重新读文件。

GitHub Authorization 只发往固定 https://api.github.com/repos/attilanet/myrzx_bot/releases,不跟随任何重定向。401/403/404 为 check_failed,固定 message/error 提醒检查私有仓库访问权限;凭据文件失效同样返回 check_failed 与固定文件权限提示,不能当作 no_release。本地 update-check.json 可记录白名单 failure 代码 access_denied/token_file_invalid/check_failed;公共 DTO 字段和协议号不变,不返回 Token、Token 路径、响应原文或原始异常。request_update 与宿主机复验遇到访问失败则拒绝请求/更新,保持原服务。

GitHub Releases 可使用限定仓库、Contents read 的 fine-grained Token;GHCR 由用户另用 PAT classic 的 read:packages 权限通过 docker login --password-stdin 配置。两份凭据分别管理,不假定 fine-grained Token 能拉私有镜像。独立 updater.pyz 构建/运行 CLI 及已有宿主机的一次性初始化、systemd override 见 README.md;旧应用必须先经用户安装新宿主机更新器并升级镜像,才具有私有 Web 更新能力。

三个方法返回同一公共 DTO,示例:

{
  "current_version": "2.0.0.dev1",
  "latest_version": "v2.0.0",
  "available": true,
  "checked_at": "2026-11-10T00:00:00Z",
  "release_url": "https://github.com/attilanet/myrzx_bot/releases/tag/v2.0.0",
  "channel": "stable-2.x",
  "repository": "attilanet/myrzx_bot",
  "status": "available",
  "message": "发现稳定 Web 2 更新。",
  "error": null,
  "can_apply": false,
  "executor": {
    "configured": false,
    "enabled": false,
    "auto_apply": false,
    "state": "unconfigured",
    "heartbeat_at": null
  },
  "request": null,
  "host_status": null
}

status:unchecked / no_release / up_to_date / available / check_failed / unavailable / pending / applying / succeeded / rolled_back / failed。仅成功读取列表且无 2.x 正式版时 latest_version=null, available=false, status=no_release,不可退到桌面 1.2。镜像构建成功或存在 tag 均不能替代正式 Release。

提交成功返回 status=pending,request={request_id,version,requested_at,status:"pending"};前端应显示“等待宿主机”,定时 GET 状态。宿主机结果 host_status={request_id,status,version,updated_at,error},错误是固定脱敏说明,不含原始异常、文件路径或子进程输出。request_update 在缺少执行器时返回 status=unavailable 和具体 message;非法/非官方/倒退版本抛 ValueError,API 映射 400。API /apply 的 HTTP 接受响应不应宣称已经升级;更新完成由宿主机健康检查决定。

启动约定(对齐 API owner 已落地的 config.py):python -m ranch_web,读取 RANCH_WEB_HOST(默认 127.0.0.1)、RANCH_WEB_PORT(默认 8765)、RANCH_WEB_DATA_DIR(默认 local_state/ranch_web)、RANCH_WEB_PASSWORD。Docker 设置 HOST=0.0.0.0, DATA_DIR=/data,只运行一个 Uvicorn worker,正常 SIGTERM 经 lifespan 关闭 manager。

API 已在更新 DTO 专用上下文按以上限定字段保留公共 request、request_id;全局游戏凭据脱敏保持有效。按钮传 latest_version 的完整 v2.x.y,无 v 的版本不会作为镜像标签接受。