178 lines
17 KiB
Markdown
178 lines
17 KiB
Markdown
# Web 2 Linux Docker 部署与更新
|
||
|
||
当前应用及更新示例为 `v2.0.9`。下文首次初始化章节保留 2.0.1 流程及历史版本示例。游戏资料基线为 `1.9.68`,桌面版保留 `1.2.0`。镜像流水线成功、Git tag 与 GitHub Release 是不同的发布步骤:在线更新必须等对应镜像及非草稿、非预发布的 Release 均发布后才能使用。私有仓库未获授权返回 404 属于访问失败,不代表没有版本;只有成功读取列表且没有稳定 2.x 时才显示“暂无正式版”。
|
||
|
||
2.0.9 仅整理设置页重复运行提示,21项相关测试通过;以下历史结果不计入本补丁,见 [本版发布说明](../../analysis/RELEASE_2_0_9.md)。
|
||
|
||
已在 2.0.1 完成私有仓库和 GHCR 认证的部署,稳定 Release 与正式镜像发布后,可直接通过“帮助 → 检查版本更新…”升级,无需先安装 2.0.2、重复初始化或替换宿主机更新器。尚未接入私有在线更新的宿主机才需参考下文“已有宿主机首次初始化”。
|
||
|
||
2.0.8 自动委托提供“当前委托 / 每日记录”,合格候选跨城市按20→15→10排序并说明回退原因;历史按角色、北京时间自然日持久保存,最近90天、每角色最多5000条事件。静态预计奖励与领奖回包确认金额分开,旧历史仅回填本地任务 journal 可证实的部分;运行详情使用原单一底部分类日志。2.0.7 高等级主培养与资质备用修复继续生效,详见 [2.0.8 发布说明](../../analysis/RELEASE_2_0_8.md)。
|
||
|
||
## 容器与持久化
|
||
|
||
需要 Linux、Docker Engine、带 `up --wait --wait-timeout` 和 `pull --policy` 的 Docker Compose v2。宿主机更新器另需 Python 3.12+(仅标准库)。镜像使用 Python 3.12,无 PySide6、Node 或 npm,单服务、单 Uvicorn worker;账号由应用内独立线程并行。
|
||
|
||
将审核后的 `main` 项目源码放在 `/opt/ranch-web`,项目、Python 源码、Compose 及部署配置由 root 持有,且禁止其他用户写入。以下路径适用于全新部署,持久化账号目录使用单独的 UID/GID 10001:
|
||
|
||
```sh
|
||
cd /opt/ranch-web
|
||
sudo install -d -m 0700 -o 10001 -g 10001 /opt/ranch-web/data
|
||
sudo install -d -m 0755 -o root -g root /opt/ranch-web/updater-control
|
||
sudo install -m 0600 -o root -g root deploy/web/web.env.example .env
|
||
sudo install -m 0600 -o root -g root deploy/web/image.env.example .image.env
|
||
sudoedit .env .image.env
|
||
```
|
||
|
||
在 `.env` 填入独立的 `RANCH_WEB_PASSWORD`,这是 Web 管理密码,不是游戏密码;`.image.env` 的目标示例为 `RANCH_WEB_IMAGE=ghcr.io/attilanet/myrzx_bot-web:v2.0.9`,需确认对应镜像已发布后再 pull。Compose 默认只发布到宿主机 `127.0.0.1:8765`,容器内监听 `0.0.0.0:8765` 并强制管理密码。使用域名反代时,同时配置 `RANCH_WEB_ALLOWED_HOSTS` 与 `RANCH_WEB_ALLOWED_ORIGINS`;TLS 入口设置 `RANCH_WEB_SECURE_COOKIE=true`。代理保留正确的 Host,写请求依赖来源校验。
|
||
|
||
`/opt/ranch-web/data` 挂到容器 `/data`,包括账号、加密会话与密钥、配置、委托历史、SQLite 统计和更新请求;独立于桌面数据。心跳控制目录独立只读挂到 `/run/ranch-updater`。使用 bind mount 的目录必须预先创建,Compose 不会悄悄创建 root 所有、容器无法写入的目录。默认容器用户 `10001:10001`,根文件系统只读,临时文件写到 `/tmp`。不要对现有账号目录重新初始化密钥。
|
||
|
||
正式版本启动:
|
||
|
||
```sh
|
||
sudo sh deploy/web/compose.sh pull --policy always web
|
||
sudo sh deploy/web/compose.sh up -d --no-build --wait --wait-timeout 180 web
|
||
sudo sh deploy/web/compose.sh ps
|
||
curl --fail http://127.0.0.1:8765/api/health
|
||
```
|
||
|
||
脚本固定读取 `.env` 与 `.image.env`,相当于 `docker compose --project-name ranch-web --env-file .env --env-file .image.env --file compose.yaml ...`。更新器会持久化已选镜像到 `.image.env`,之后也应通过此脚本启动,以免误用默认镜像版本。
|
||
|
||
私有 GHCR 包由用户先在宿主机为运行更新器的 root 用户配置一次 `docker login ghcr.io --password-stdin`,见下文。仓库与镜像可以保持私有;registry 凭据由宿主机 Docker 管理,不交给 Web 容器,也不从开发机迁移。
|
||
|
||
若仅在 Linux 上验证审核后的 `main` 源码,可在本地构建后启动;这不会发布镜像,也不要求远端已有对应镜像:
|
||
|
||
```sh
|
||
sudo sh deploy/web/compose.sh build web
|
||
sudo sh deploy/web/compose.sh up -d --no-build --pull never --wait --wait-timeout 180 web
|
||
```
|
||
|
||
停止使用 `sudo sh deploy/web/compose.sh stop --timeout 120 web`。容器 SIGTERM 经应用 lifespan 关闭账号队列;Compose 给出 120 秒退出时间。保持单实例,不要用多个 worker、replica 或 `--scale web=...` 共享同一 `/data`。
|
||
|
||
## 手动检查与更新
|
||
|
||
Web 只读检查官方 GitHub Releases;默认只接受 `v2.MINOR.PATCH`,跳过草稿、预发布、1.x、3.x 和非法标签。数字不含前导零。`2.0.0.dev1 → v2.0.0` 可升级,`2.0.0 → v2.0.0` 不升级,拒绝降级。网络失败会明确显示检查失败,不使用虚构版本或下载脚本。
|
||
|
||
### 已完成 2.0.1 初始化的宿主机
|
||
|
||
稳定 Release 与正式镜像发布后,用户打开“帮助 → 检查版本更新…”,检查到 2.0.9 后手动提交更新请求,可从 2.0.1 直接安装。现有私有仓库认证、GHCR 登录与宿主机更新器继续使用;Web 按钮仍要求有效心跳及 `accept_web_requests=true`。请求显示 `pending` 只表示已提交,宿主机完成备份、安装及健康检查后才确认成功;升级完成后刷新网页以加载新版界面,底部日志默认收起。Windows 或未启用执行器时仍仅可检查版本。自动安装默认关闭。
|
||
|
||
### 全新宿主机安装
|
||
|
||
全新安装时,先安装 root 持有的配置,并准备独立更新器(示例的自动化开关默认关闭):
|
||
|
||
```sh
|
||
sudo install -m 0600 -o root -g root deploy/web/updater.example.toml /etc/ranch-web-updater.toml
|
||
python3 -B tools/build_web_updater.py --output /tmp/updater.pyz
|
||
sudo install -m 0644 -o root -g root /tmp/updater.pyz /opt/ranch-web/updater.pyz
|
||
python3 -B /opt/ranch-web/updater.pyz --version
|
||
```
|
||
|
||
也可从对应 Release 下载 `updater.pyz` 及 `SHA256SUMS`,核对后安装,宿主机不需要完整 Python 源码或 pip 依赖。构建器只打包 `__main__.py`、`updater.py`、`ranch_web/__init__.py`、`ranch_web/updates.py`,版本取构建时的 `ranch_web.__version__`;维护者为新 Release 生成对应版本资产,不意味着已安装的宿主机更新器必须随应用版本一起替换。原有 `python3 -B deploy/web/updater.py ...` CLI 仍可运行,本文的 service 默认使用 `/opt/ranch-web/updater.pyz`。
|
||
|
||
### 已有宿主机首次初始化(用户自行执行)
|
||
|
||
以下保留 2.0.1 引入私有在线更新时的初始化流程,仅供尚未初始化的宿主机参考;已完成私有仓库和 GHCR 认证的部署无需重做。本节的历史资产示例为 `v2.0.7`,第4步的 `v2.0.1` 是首次初始化的历史应用目标。当前应用升级须确认对应发布物就绪,再按上文步骤执行。
|
||
|
||
前提是原有 `/opt/ranch-web` Compose 部署、数据目录及 `/etc/ranch-web-updater.toml` 均已存在,配置仍由 root 持有。保留原有数据和配置,不重新初始化密钥;数据目录由 `10001:10001` 持有。以下仅初始化在线更新器,不需要复制项目源码或 Compose。
|
||
|
||
1. 用户登录有私有仓库读取权限的 GitHub 账号,历史资产示例从 [2.0.7 Release](https://github.com/attilanet/myrzx_bot/releases/tag/v2.0.7) 下载 `updater.pyz` 和 `SHA256SUMS`,放到宿主机临时目录。确认 Release 已发布且镜像可读取,在下载目录执行 `sha256sum -c SHA256SUMS` 后安装:
|
||
|
||
```sh
|
||
sudo install -m 0644 -o root -g root updater.pyz /opt/ranch-web/updater.pyz
|
||
python3 -B /opt/ranch-web/updater.pyz --help
|
||
python3 -B /opt/ranch-web/updater.pyz --version
|
||
python3 -B /opt/ranch-web/updater.pyz --config /etc/ranch-web-updater.toml --apply v2.0.7 --dry-run
|
||
```
|
||
|
||
`--version` 应显示 `ranch-web-updater 2.0.7`;`--help`、`--version` 和 `--dry-run` 均不联网、不读取 Token、不调用 Docker,dry-run 不创建文件。Python 需为 3.12+。
|
||
|
||
2. 用户创建只授予本仓库 Contents **read** 的 fine-grained GitHub Token,用交互终端输入;值不出现在 argv、shell 历史或更新状态中:
|
||
|
||
```sh
|
||
sudo python3 -B /opt/ranch-web/updater.pyz --config /etc/ranch-web-updater.toml --set-github-token
|
||
```
|
||
|
||
该命令只在本机原子保存 `<data_dir>/update-github-token`,不联网验证。默认宿主机路径 `/opt/ranch-web/data/update-github-token`,权限 `0600`、所有者 `10001:10001`;容器通过现有 `/data` 挂载读取同一文件 `/data/update-github-token`。文件为单个 ASCII Token(可带末尾换行、总长最多 4096 字节),拒绝软链接、硬链接及 POSIX 下非 `0600` 文件。更新器只向固定 `https://api.github.com/repos/attilanet/myrzx_bot/releases` 发送 Authorization,禁止重定向;错误、DTO 与日志不输出 Token。
|
||
|
||
默认文件不存在时继续匿名访问,兼容公共仓库。可显式设置环境变量 `RANCH_WEB_UPDATE_GITHUB_TOKEN_FILE` 为绝对**文件路径**,不可填 Token;显式路径缺失或文件不安全会失败,不会回退匿名。宿主机和容器的覆盖路径需各自可见,现有 Compose 不透传这个可选环境变量,通常应直接用默认共享文件。不要将 Token 写入 TOML、请求 JSON 或 Web 表单。[GitHub Releases 权限说明](https://docs.github.com/en/rest/releases/releases#list-releases)
|
||
|
||
3. GHCR 使用另一份凭据:有镜像读取权限的用户创建 PAT **classic**,授予 `read:packages`(组织要求时授权 SSO)。Releases 的 fine-grained Token 不保证能用于 Docker。以下 Bash 命令由用户在宿主机终端执行一次,Token 通过 stdin 传给 root 的 Docker,不放入命令参数:
|
||
|
||
```bash
|
||
sudo -v
|
||
read -r -p 'GitHub username: ' ranch_ghcr_user
|
||
read -r -s -p 'GHCR read:packages PAT (hidden): ' ranch_ghcr_pat
|
||
printf '\n'
|
||
printf '%s' "$ranch_ghcr_pat" | sudo docker --context default login ghcr.io --username "$ranch_ghcr_user" --password-stdin
|
||
unset ranch_ghcr_pat ranch_ghcr_user
|
||
```
|
||
|
||
Docker 保存的宿主机登录配置供更新器拉镜像使用;不要复制开发机的 Git/registry 凭据,也不要把 Docker 凭据放进 GitHub Token 文件或 Web 容器。[GHCR 官方认证说明](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
|
||
|
||
4. 使用新包先检查再由用户明确发起在线更新。以下 `--apply v2.0.1` 仅保留首次初始化的历史示例,不是本轮 2.0.9 升级命令:
|
||
|
||
```sh
|
||
sudo python3 -B /opt/ranch-web/updater.pyz --config /etc/ranch-web-updater.toml --check
|
||
sudo python3 -B /opt/ranch-web/updater.pyz --config /etc/ranch-web-updater.toml --apply v2.0.1
|
||
```
|
||
|
||
新更新器会独立复验官方 Release、严格版本递增、固定官方镜像,并执行原有备份、健康检查与失败回滚。旧 Web 即使尚不能查询私有发布,此命令仍可启动更新;更新到含新私有支持的镜像后,Web 的检查/请求才会读取共享 Token。只有 tag 或镜像、尚无 2.x Release 时仍不能更新;不要把旧页面的匿名 404 当成“已是最新”。
|
||
|
||
5. 让原有 systemd timer 执行新包。用户运行 `sudo systemctl edit ranch-web-updater.service`,只添加一次覆盖:
|
||
|
||
```ini
|
||
[Service]
|
||
ExecStart=
|
||
ExecStart=/usr/bin/python3 -B /opt/ranch-web/updater.pyz --config /etc/ranch-web-updater.toml --run
|
||
```
|
||
|
||
随后执行:
|
||
|
||
```sh
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now ranch-web-updater.timer
|
||
sudo systemctl start ranch-web-updater.service
|
||
```
|
||
|
||
原有 service 的 root、目录保护和 Docker 登录访问保持有效。新包成功初始化后,未来 Web 请求及 timer 都使用相同私有查询逻辑;未来要升级独立更新器本身时,仍由用户下载并替换受信任的 `updater.pyz`。`auto_apply=false` 继续默认关闭,允许 Web 按钮需另外显式设置 `accept_web_requests=true`。
|
||
|
||
`--apply` 不传版本时选比运行中版本更新的最新稳定 2.x。手动操作和定时任务共享排他锁。执行器固定官方仓库及镜像地址,重新查询 Releases 验证来源;Web 即使伪造 `update-request.json` 也不能指定命令、下载地址、路径或第三方镜像。
|
||
|
||
执行顺序:旧容器运行期间先 `compose pull --policy always web`;拉取失败则保持旧服务。然后停服,确认所有容器写入停止,为完整数据目录创建一致的快照(包含 SQLite 文件及 WAL、加密密钥);最后用新镜像 `compose up -d --no-build --pull never --wait --wait-timeout 180 web`。镜像已有 `/api/health` healthcheck,检查成功后才记录更新完成。
|
||
|
||
新服务健康失败时,更新器停止失败容器、恢复更新前数据、用旧镜像的准确本地 image ID 启动并检查健康。失败版本数据移入 `failed-data/`,快照保存在 `backups/`,均不自动删除。快照包含默认共享 Token 文件以及应用密钥,快照文件权限为 0600、备份目录 0700;不会打印账号数据、密钥、Compose 环境或容器日志。回滚也失败时保留恢复事务,下一次更新器运行会先恢复,需操作者检查服务状态。镜像拉取和停机发生在宿主机;Web 容器没有 Docker socket。
|
||
|
||
## 定时检查、Web 按钮与自动更新
|
||
|
||
全新部署确认已按上文生成或下载安装 `/opt/ranch-web/updater.pyz` 后,再安装以下 service;已有部署使用上文的一次性 override。
|
||
|
||
```sh
|
||
sudo install -m 0644 deploy/web/ranch-web-updater.service /etc/systemd/system/
|
||
sudo install -m 0644 deploy/web/ranch-web-updater.timer /etc/systemd/system/
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now ranch-web-updater.timer
|
||
sudo systemctl start ranch-web-updater.service
|
||
```
|
||
|
||
定时器每五分钟维护一次心跳;官方版本默认每小时检查一次。`auto_apply=false` 只显示可用更新,不主动更新。页面更新按钮还需操作者在 `/etc/ranch-web-updater.toml` 设置 `accept_web_requests=true`,再启动一次 service 刷新心跳;只有此时 Web 的 `can_apply` 才为 true。Web 点击后返回 `pending`,定时器独立验证并消费请求;这属于用户手动请求,不依赖 `auto_apply`。
|
||
|
||
若希望检测到新稳定版便自动安装,操作者显式设置 `auto_apply=true`;这可能在下次运行时开始升级。停用 Web 按钮或自动更新后,同样启动一次 service 刷新状态。停止 timer 后,15 分钟有效期到期的心跳会让 Web 显示执行器失效。可以用 `systemctl status ranch-web-updater.timer` 与 `journalctl -u ranch-web-updater.service` 查看脱敏状态。
|
||
|
||
Windows 或未安装执行器的 Docker 部署仍能检查版本,但按钮会显示“仅可检查更新”,不会伪装更新完成。公共 DTO、心跳、去重与请求字段见 [UPDATE_PROTOCOL.md](UPDATE_PROTOCOL.md)。
|
||
|
||
## CI 与验证范围
|
||
|
||
[web-image.yml](../../.github/workflows/web-image.yml) 仅对官方仓库的严格稳定 `v2.x.y` tag 推送 `ghcr.io/attilanet/myrzx_bot-web:v2.x.y`;校验 `ranch_web.__version__` 必须与 tag 一致,不能只改变镜像 label。PR 与手动运行只测试、构建,不推送。开发分支 push 不触发正式镜像发布,也没有 `latest` 滚动升级通道。CI 执行更新器、私有凭据和独立包回归,并在无外网容器中检查 healthcheck、非 root 数据写权限、无 Qt 和正常停止;镜像发布状态以对应 tag 的工作流结果为准。
|
||
|
||
2.0.8 共验证739项独立测试:736通过、3项 Windows 跳过;其中非浏览器662项(659通过、3跳过),浏览器77项全部验证通过,详见 [发布说明](../../analysis/RELEASE_2_0_8.md#验证)。2.0.7 结果保留在 [历史发布说明](../../analysis/RELEASE_2_0_7.md#验证)。以下命令可复现本地更新器构建与离线检查;历史 Windows 离线验证与 Linux 部署烟测见 [Web 运行说明](../../ranch_web/README.md#离线验证),不计入本版验收。可在无 Docker 的机器上构建临时更新器资产并打印计划;`--dry-run` 不联网、不读取凭据、不调用 Docker,也不写文件:
|
||
|
||
```sh
|
||
python -B tools/build_web_updater.py --output test-artifacts/releases/v2.0.9/updater.pyz
|
||
python -B test-artifacts/releases/v2.0.9/updater.pyz --version
|
||
python -B test-artifacts/releases/v2.0.9/updater.pyz --config deploy/web/updater.example.toml --apply v2.0.9 --dry-run
|
||
python -B -m unittest ranch_web.tests.test_updates ranch_web.tests.test_web_updater ranch_web.tests.test_private_updates ranch_web.tests.test_web_updater_package -v
|
||
```
|
||
|
||
命令参数依据 [Compose up](https://docs.docker.com/reference/cli/docker/compose/up/)、[Compose pull](https://docs.docker.com/reference/cli/docker/compose/pull/);发布权限与 GHCR 认证依据 [GitHub 镜像发布流程](https://docs.github.com/en/actions/tutorials/publish-packages/publish-docker-images)。检查使用 [GitHub Releases 列表 API](https://docs.github.com/en/rest/releases/releases#list-releases),不依赖可能指向桌面版的 `/latest`。
|