16 KiB
运维、验证与 Git 交接
更新日期:2026-11-16(Asia/Shanghai)
项目背景见 PROJECT_CONTEXT.md。本文件供新窗口的维护代理直接操作,不保存密码或 Token 明文。
本机仓库与基本约束
真实项目根目录:
C:\Users\11789\Documents\Projects\Codex_ws\myrzx_bot
宿主环境有时仍把 cwd 显示成旧的 myrzx_fang;所有命令显式设置上述 workdir,不要在旧目录另建副本。
- Windows PowerShell,本机 Python 3.13;项目要求 Python 3.12+。命令统一使用
python -X utf8 -B或.venv-web\Scripts\python.exe -X utf8 -B,避免 pyc 和控制台编码干扰。 - 当前发布基线:
main、tagv2.0.12、提交a9b5f73552bf87efe65b4f0d6fd878bcb14dfbc9。新会话先重新查询,不假定仍是此 SHA。 - Git 提交身份:
AttilaNet <zbolink@foxmail.com>。用户允许私有仓库存放运维信息;本次交接文档只保存凭据位置,密码、Token 等真实值从既有私有文件读取,未复制进文档。 - 用户自有、未跟踪的
ranch-policies-1.2.0.dev1.json不要修改或暂存。 local_state/、test-artifacts/、凭据、日志、数据库、APK 等由.gitignore排除;不要用git add -f把它们带入文档提交。- 当前没有正在开发的 feature。开始新修复前检查
git status --short、git log -1、git branch --show-current和 remote,避免覆盖用户改动。
建议的只读开工检查:
git status --short
git branch --show-current
git log -1 --oneline
git remote -v
git diff --check
本地运行
首次准备 Web:
py -3 -m venv .venv-web
.\.venv-web\Scripts\python.exe -m pip install -r ranch_web\requirements.txt
.\Start_Ranch_Web.cmd
默认访问 http://127.0.0.1:8765。也可在项目根目录执行:
python -X utf8 -B -m ranch_web
Linux/macOS 源码启动使用 sh start-web.sh。Web 不需要 Node/npm、PySide6 或 APK 工具;本地数据默认在 local_state/ranch_web。
桌面历史版仍可用 Start_Ranch_Helper.cmd 或 python -B -m ranch_assistant,依赖见 ranch_assistant/requirements.txt。桌面和 Web 数据根不同,不要混用或同时操作同一游戏账号来“对比测试”。
测试策略
优先运行与修改范围对应的确定性离线测试,再按共享核心的影响扩大范围。测试使用临时目录、fake transport/client、合成账号和离线 HTTP 服务;禁止真实游戏写请求。浏览器测试可用 loopback,但不能把 loopback 白名单变成公网访问。
常用依赖和静态检查
python -X utf8 -B -m pip install -r ranch_web\requirements-test.txt
python -X utf8 -B -m compileall -q ranch_assistant ranch_web
git diff --check
requirements-test.txt 包含运行依赖和 HTTPX;CI 曾缺少 HTTPX,这一安装步骤不能删。若已有 .venv-web,优先用其中的 Python。浏览器测试另需 Python Playwright 和 Edge;可用 RANCH_WEB_BROWSER 指定 msedge.exe,默认路径是 C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe。
通用离线回归
python -X utf8 -B -m unittest discover -s ranch_assistant\tests -p "test_*.py" -v
python -X utf8 -B -m unittest discover -s ranch_web\tests -p "test_*.py" -v
后一条可能包含依赖 Playwright/Edge 的浏览器模块;缺少可选依赖时的 skip 要与真正通过分开报告。正式验收需明确列出实际运行的模块、去重后的测试数和 skip 原因,不能把多轮结果简单相加。
最近修复的定向命令
隐藏关卡接续与恢复:
python -X utf8 -B -m unittest `
ranch_assistant.tests.test_sweep_hidden_handoff `
ranch_assistant.tests.test_sweep_hidden_battles `
ranch_assistant.tests.test_sweep_hidden_engine -v
Linux 战斗子进程输入、恢复和页面能力:
python -X utf8 -B -m unittest `
ranch_assistant.tests.test_battle_worker_transport `
ranch_assistant.tests.test_battle_recovery `
ranch_assistant.tests.test_battle_capability_presentation `
ranch_web.tests.test_lifecycle_recovery `
ranch_web.tests.test_battle_recovery_contract `
ranch_web.tests.test_status_recovery_api -v
自动登录、持久运行意愿和连接状态:
python -X utf8 -B -m unittest `
ranch_web.tests.test_run_intent `
ranch_web.tests.test_scheduler_recovery `
ranch_web.tests.test_auto_relogin `
ranch_web.tests.test_connection_state -v
主培养、委托和快速模型:
python -X utf8 -B -m unittest `
ranch_assistant.tests.test_species_retention_limits `
ranch_assistant.tests.test_primary_cultivation `
ranch_assistant.tests.test_primary_resource_admission `
ranch_assistant.tests.test_commission_history `
ranch_assistant.tests.test_commission_priority `
ranch_assistant.tests.test_commission_procurement `
ranch_assistant.tests.test_battle_quick `
ranch_assistant.tests.test_snapshot_potential_anomalies -v
UI 修改至少覆盖对应浏览器模块,例如:
python -X utf8 -B -m unittest `
ranch_web.tests.browser.test_workbench_browser `
ranch_web.tests.browser.test_admin_login_browser `
ranch_web.tests.browser.test_connection_browser `
ranch_web.tests.browser.test_auto_relogin_browser -v
分类日志、安静 UI 和子路径分别使用 ranch_web.tests.browser.test_task_logs_browser、ranch_web.tests.browser.test_quiet_ui_browser、ranch_web.tests.browser.test_base_path_browser。先看当前测试名称,不要盲抄历史命令。
战斗恢复的必测边界
修改 battles.py、engine.py、battle_simulator.py 或 Web 生命周期时,至少验证:
- 已确认入场后本地崩溃/超时,不会再次
stageStart。 - 原始输入齐全时只重跑本地计算一次;保存的完成结果可续交一次。
- 缺原始队伍输入的旧隐藏记录不会用当前属性补算。
- 已发送的未知
battleEnd、记录、探险、突破或任务写请求不重放。 - 手动 Stop、账号代际变化和来源策略关闭都阻止新写,且不误改持久运行意愿。
- 恢复只处理 pending,不夹带其他策略;多账号状态完全隔离。
- Windows 测试不能替代 Linux 管道语义。涉及子进程 stdin/stdout 时,用 Linux/Python 3.12 的离线进程测试或 CI 镜像验证。
生产部署现状
用户入口:
https://witchercheung.cn/myrzx_bot
生产在用户的 X99 内网 Ubuntu 服务器,Docker 容器经已有 FRP/反向代理暴露;不要改动 FRP 或其他服务。
| 项目 | 已知配置 |
|---|---|
| SSH 入口 | ssh -tt -p 50022 witcher@120.78.82.189;已有 SSH key 可登录。该地址转发到内网 X99。 |
| X99 内网地址 | 192.168.31.187,Ubuntu 24.04、Python 3.12。上次诊断记录 Docker 29.8.0、Compose 5.5.1;使用前核对当前版本。 |
| 源码/Compose | /opt/ranch-web |
| 持久数据 | /opt/ranch-web/data,UID/GID 10001:10001,目录 0700;含账号、密钥、配置、统计、历史和更新请求。 |
| 容器/项目 | ranch-web-web-1 / Compose project ranch-web |
| 端口 | 生产发布 127.0.0.1:58765 → 容器 8765,经现有 FRP/反代访问;不要误用旧的 57865。 |
| 容器安全 | 非 root、只读根文件系统、单 Uvicorn worker、restart unless-stopped;不挂 Docker socket。 |
| 配置 | /opt/ranch-web/.env 和 .image.env root 0600;不得用仓库示例覆盖。 |
| Web 安全 | base path /myrzx_bot,Host/Origin 白名单,Secure + HttpOnly 管理 cookie;未登录不得暴露工作台。 |
| 更新器 | /opt/ranch-web/updater.pyz,配置 /etc/ranch-web-updater.toml,备份在 /opt/ranch-web/backups,失败数据在 /opt/ranch-web/failed-data。 |
| 更新控制 | accept_web_requests=true、auto_apply=false;timer 维护心跳,官方版本每小时检查,安装由用户从 Web 发起。 |
sudo 需要交互凭据时先在已验证的 sudo 提示下输入;不得把密码放进命令参数、脚本、日志或 Markdown。已有 SSH key 不代表免密 sudo。
常用只读检查(确有需要时):
sudo sh /opt/ranch-web/deploy/web/compose.sh ps
curl --fail http://127.0.0.1:58765/api/health
sudo systemctl status ranch-web-updater.timer
sudo journalctl -u ranch-web-updater.service --no-pager -n 80
生产检查优先使用管理 API 的 GET 和既有调试记录;不要为“测试一下”刷新关卡、开启策略、领奖励、打战斗、删除账号或重置 pending。管理登录/退出本身会写管理会话,仍需遵守用户授权。
凭据位置与读取规则
本机以下文件均位于忽略目录。本次文档只记录位置和用途;需要认证时从既有私有文件读取真实值,按用户最新授权处理私有仓库内容。
| 文件 | 用途与规则 |
|---|---|
local_state/deployment_x99/access.private.json |
Web 管理入口元数据和 web_password。读取到内存供管理登录使用,不打印、不复制到文档、不提交。该文件不保证记录的应用版本是最新版。 |
local_state/deployment_x99/update_credentials.private.json |
私有 GitHub/GHCR 更新凭据,ghcr_username 缺省时历史脚本使用 AttilaNet。只在内存中读取,不能打印认证头或写入仓库。 |
/opt/ranch-web/data/update-github-token(服务器) |
私有 GitHub Release 只读 Token 文件,预期 0600、UID/GID 10001;容器内同文件为 /data/update-github-token。不要读取到聊天输出。 |
| root 的 Docker GHCR 登录配置(服务器) | 由宿主机 docker login ghcr.io --password-stdin 管理。不要复制开发机凭据,也不要把 registry Token 交给 Web 容器。 |
不要在文档里虚构“SSH 密码保存文件”。如果某凭据不在上述真实位置,先检查已有安全存储或让用户通过私密文件提供;不要要求把密码贴到聊天中。
在线更新与发布
用户升级
现有 X99 已配置私有 GitHub Release + GHCR 通道。新版本正式镜像和稳定 Release 都核验后,用户打开 “帮助 → 检查版本更新…”,手动提交更新;宿主机执行备份、拉取、停止、切换、健康检查及失败回滚。pending 只代表请求已排队,成功以宿主机状态为准。完成后用户刷新网页加载新静态资源。
除非用户再次明确要求,维护代理只发布版本,不手动 SSH 部署 X99、不代替用户点击在线更新。
当前发布链仍是 GitHub
截至 2.0.12:
- 正式发布仓库:
AttilaNet/myrzx_bot(GitHub 私有)。 - Actions:
.github/workflows/web-image.yml,稳定v2.x.ytag 构建并推ghcr.io/attilanet/myrzx_bot-web:v2.x.y。 - 更新器只接受官方 GitHub Releases 的稳定 2.x,严格递增并校验固定镜像;tag、镜像和 Release 缺一不可。
deploy/web/updater.py、ranch_web/updates.py、.github/workflows/web-image.yml固定 GitHub owner/repo、API 或 GHCR 地址;忽略目录中的历史test-artifacts/publish_web_*.py发布辅助也按 GitHub 流程编写,使用前必须重新审查。
本次 Gitea remote 迁移没有修改上述任何发布端点。 如果 GitHub 仓库以后不可写或 Actions/Release 被删除,现有在线发布会失败;只推 Gitea tag 不会生成 GHCR 镜像,也不会让 X99 发现更新。迁移到 Gitea Releases/Actions/Container Registry 是独立项目,必须先设计认证、镜像命名、更新器来源固定、回滚与兼容,再改代码和部署文档。
发布检查清单
-
在干净基线上完成实现与审查;确认版本号、README、部署说明和
analysis/RELEASE_X_Y_Z.md与最终范围一致。 -
运行适当回归和浏览器测试,记录唯一测试数及预期 skip;
git diff --check,检查待提交文件和敏感信息。 -
保留用户未跟踪文件,明确暂存公开源码/文档,不用
git add .横扫私有产物。 -
用授权身份提交;需要合入
main时使用正常 merge,不强推、不改已发布 tag。 -
创建与
ranch_web.__version__一致的v2.x.yannotated tag,推送到实际承担发布的 remote。当前发布链仍需要 GitHub,不能因 Gitea 名为origin就误以为推 Gitea 足够。 -
等稳定 tag 的 Actions 成功,核验 GHCR 镜像 version/revision label 与精确 main SHA。
-
构建
updater.pyz:python -X utf8 -B tools\build_web_updater.py --output test-artifacts\releases\vX.Y.Z\updater.pyz生成 ASCII/LF 的
SHA256SUMS,比较包内源码与精确提交 blob,再上传 GitHub Release。发布必须是非草稿、非预发布。 -
独立核对 Release、资产摘要、main/tag SHA、镜像 digest 和源码版本。最后才按明确授权清理旧 Release/tag/分支;先备份且不得用仅面向 GitHub 的旧 helper 去删除 Gitea 同名 ref。
-
告知用户可在线更新,但不声称生产已恢复,直到用户安装并反馈。
历史发布辅助位于忽略的 test-artifacts/,可能不存在于新机器,也可能绑定旧版本号。使用前审查,不要直接运行旧 --apply、cleanup 或 deploy 脚本。
Git remote 迁移到 Gitea
已完成的迁移
用户已有的私有 Gitea 仓库:
https://gitea.witchercheung.cn/witcher/myrzx_bot.git
迁移前本机同时存在:
gitea https://gitea.witchercheung.cn/witcher/myrzx_bot.git
origin https://github.com/AttilaNet/myrzx_bot.git
父任务已执行 git remote remove origin 删除旧 GitHub remote,再执行 git remote rename gitea origin。现在唯一的 origin 是上述 Gitea URL;git ls-remote 已确认 Gitea main 和 HEAD 在应用基线 a9b5f73552bf87efe65b4f0d6fd878bcb14dfbc9。迁移前 Git 配置备份在忽略目录:
local_state/context_handoff/git-config.before-origin-migration.2026-11-16.private
本次没有删除 GitHub 网站仓库,也没有把在线更新迁到 Gitea。只推 main 的交接文档提交,不推 v2.0.12 或其他 tag,不迁移 Release、CI、GHCR。 Gitea 在文档提交前尚无 v2.0.12 tag。
文档推送与后续核对
父任务负责暂存、提交和推送文档。先检查工作区与远端实际状态,确认 Gitea 认证可用。Gitea 为私有仓库,推送若要求认证,应使用已有凭据管理器或用户提供的私有凭据,不把密码写进 remote URL、命令输出或文档。
git remote -v
git ls-remote origin
git branch --set-upstream-to=origin/main main
git push origin main
git rev-parse HEAD
git ls-remote origin refs/heads/main
git status --short --branch
不要重复执行 remove/rename,也不要执行 git push --tags。推送后核对本地 HEAD 与 Gitea main 完全一致。是否推送其他历史分支留待用户另行要求,不要为了“同步全部”把私有实验分支或旧引用无差别上传。
迁移后应满足:
- 本机仅有目标 Gitea
origin(除非用户另有 remote),URL 不含内嵌密码。 main跟踪origin/main,文档提交在 Gitea 可见,工作区除用户原有策略 JSON 外无意外改动。- GitHub 网站仓库没有被
git remote remove删除;该命令只删除本地 remote 配置。 - 文档明确保留“更新发布仍依赖 GitHub/GHCR”的限制。不要运行旧 cleanup helper 删除 Gitea 的 tag 或分支。
如要把后续发布也迁到 Gitea,先另开任务:决定 Gitea Actions/其他 CI、容器 registry、Release API、认证与 X99 updater 配置,并为旧 GitHub 通道保留可回滚方案。未完成前继续发布必须显式说明 GitHub 发布 remote/流程,不能只看本地 origin 名称。
新会话收尾模板
完成工作后简洁报告:实际改动、关键根因、运行了哪些测试及 skip、提交/远端 SHA、是否发布或部署、仍需用户做什么。离线结果和生产结果分开写;遇到不确定的请求状态,保留证据并说明不能安全自动做的部分,而不是为了“全部完成”伪造结果。