Files
myrzx_bot/deploy/web/UPDATE_PROTOCOL.md
T

3.7 KiB
Raw Blame History

Web 2 更新接口(协议 1)

供 API、前端、宿主机更新器与 Main 集成。ranch_web.updates.UpdateService(root, current_version) 只依赖 Python 标准库;构造和 status() 不联网,check() 才访问固定官方 GitHub Releases,request_update(version=None) 仅提交文件请求。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 写文件不等于部署成功。

三个方法返回同一公共 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。

提交成功返回 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 的版本不会作为镜像标签接受。