Files
myrzx_bot/deploy/web/UPDATE_PROTOCOL.md
T

52 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](README.md);旧应用必须先经用户安装新宿主机更新器并升级镜像,才具有私有 Web 更新能力。
三个方法返回同一公共 DTO,示例:
```json
{
"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` 的版本不会作为镜像标签接受。