Files
myrzx_bot/deploy/web/README.md
T
AttilaNet e26d37e9c5 revert: restore the original pre-redesign web console
Revert 688aad3, 39ac03a, c84dc36, and ff6a828 in reverse chronological order. Restore the exact tracked tree from 99aff42 while preserving history.

Validation: 29 authentication and base-path tests passed offline. All 23 prior UI browser tests ran in system Edge: 22 passed initially; the fake-login test passed on an unchanged isolated retry. Live game HTTP was blocked throughout browser validation.
2026-11-11 10:08:02 +08:00

92 lines
8.5 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 Linux Docker 部署与更新
本目录对应 `develop/v2.0.0`、`2.0.0.dev1`,当前仍是开发版本。以下正式镜像命令仅在官方发布对应稳定 `v2.x.y` 后可用;没有 Web 2 正式发布时,更新检查明确返回“暂无正式版”,不会安装旧桌面 1.2.0。开发分支不发布稳定镜像,不自动更新服务器。
## 容器与持久化
需要 Linux、Docker Engine、带 `up --wait --wait-timeout` 和 `pull --policy` 的 Docker Compose v2。宿主机更新器另需 Python 3.12+(仅标准库)。镜像使用 Python 3.12,无 PySide6、Node 或 npm,单服务、单 Uvicorn worker;账号由应用内独立线程并行。
将审核后的项目源码放在 `/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.0`。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`,之后也应通过此脚本启动,以免误用默认开发镜像。
GitHub 首次创建 GHCR 包可能为私有;仓库管理员可将 `myrzx_bot-web` 包设为 Public。私有包部署需操作者先在宿主机执行 `sudo docker login ghcr.io`,使用具备 `read:packages` 的凭据;不要把 registry 凭据交给 Web 容器。[GHCR 官方文档](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
若目前只在 Linux 上验证开发分支,将 `.image.env` 保持 `:dev`,本地构建后启动;这不会发布镜像:
```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` 不升级,拒绝降级。网络失败会明确显示检查失败,不使用虚构版本或下载脚本。
先安装 root 持有的配置(示例的所有自动化开关默认关闭):
```sh
sudo install -m 0600 -o root -g root deploy/web/updater.example.toml /etc/ranch-web-updater.toml
sudo python3 -B deploy/web/updater.py --config /etc/ranch-web-updater.toml --check
sudo python3 -B deploy/web/updater.py --config /etc/ranch-web-updater.toml --apply v2.0.0
```
`--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/`,均不自动删除。快照文件权限为 0600、备份目录 0700;不会打印账号数据、密钥、Compose 环境或容器日志。回滚也失败时保留恢复事务,下一次更新器运行会先恢复,需操作者检查服务状态。镜像拉取和停机发生在宿主机;Web 容器没有 Docker socket。
## 定时检查、Web 按钮与自动更新
```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 和正常停止;本轮没有触发 CI 或发布。
本机 Windows 没有 Docker,已能执行的验证是离线单元测试、临时数据的备份/回滚测试、启动脚本语法与配置静态核对、更新器 dry-run;不代表 Linux/Docker 实机验证通过。可在无 Docker 的机器上只打印计划(不联网、不写文件):
```sh
python -B deploy/web/updater.py --config deploy/web/updater.example.toml --apply v2.0.0 --dry-run
python -B -m unittest ranch_web.tests.test_updates ranch_web.tests.test_web_updater -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`。