# 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 写文件不等于部署成功。 私有发布凭据只来自服务端 `/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` 的版本不会作为镜像标签接受。