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+(仅标准库)。镜像采用 Node 22 构建 Vue 前端,运行阶段仅使用 Python 3.12,无 PySide6、Node 或 npm,单服务、单 Uvicorn worker;账号由应用内独立线程并行。构建需要完整 frontend/ 和 ranch_web/static/ 源码;账号目录不参与构建。
将审核后的项目源码放在 /opt/ranch-web,项目、Python 源码、Compose 及部署配置由 root 持有,且禁止其他用户写入。以下路径适用于全新部署,持久化账号目录使用单独的 UID/GID 10001:
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。不要对现有账号目录重新初始化密钥。
正式版本启动:
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 官方文档
若目前只在 Linux 上验证开发分支,将 .image.env 保持 :dev,本地构建后启动;这不会发布镜像:
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 持有的配置(示例的所有自动化开关默认关闭):
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 按钮与自动更新
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。
CI 与验证范围
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 的机器上只打印计划(不联网、不写文件):
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、Compose pull;发布权限与 GHCR 认证依据 GitHub 镜像发布流程。检查使用 GitHub Releases 列表 API,不依赖可能指向桌面版的 /latest。