46 lines
3.7 KiB
Markdown
46 lines
3.7 KiB
Markdown
# 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,示例:
|
||
|
||
```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。
|
||
|
||
提交成功返回 `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` 的版本不会作为镜像标签接受。
|