Files

289 lines
16 KiB
Markdown
Raw Permalink 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.
# 运维、验证与 Git 交接
更新日期:2026-11-16(Asia/Shanghai)\
项目背景见 [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md)。本文件供新窗口的维护代理直接操作,不保存密码或 Token 明文。
## 本机仓库与基本约束
真实项目根目录:
```text
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`、tag `v2.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,避免覆盖用户改动。
建议的只读开工检查:
```powershell
git status --short
git branch --show-current
git log -1 --oneline
git remote -v
git diff --check
```
## 本地运行
首次准备 Web:
```powershell
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`。也可在项目根目录执行:
```powershell
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 白名单变成公网访问。
### 常用依赖和静态检查
```powershell
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`。
### 通用离线回归
```powershell
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 原因,不能把多轮结果简单相加。
### 最近修复的定向命令
隐藏关卡接续与恢复:
```powershell
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 战斗子进程输入、恢复和页面能力:
```powershell
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
```
自动登录、持久运行意愿和连接状态:
```powershell
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
```
主培养、委托和快速模型:
```powershell
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 修改至少覆盖对应浏览器模块,例如:
```powershell
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 生命周期时,至少验证:
1. 已确认入场后本地崩溃/超时,不会再次 `stageStart`。
2. 原始输入齐全时只重跑本地计算一次;保存的完成结果可续交一次。
3. 缺原始队伍输入的旧隐藏记录不会用当前属性补算。
4. 已发送的未知 `battleEnd`、记录、探险、突破或任务写请求不重放。
5. 手动 Stop、账号代际变化和来源策略关闭都阻止新写,且不误改持久运行意愿。
6. 恢复只处理 pending,不夹带其他策略;多账号状态完全隔离。
7. Windows 测试不能替代 Linux 管道语义。涉及子进程 stdin/stdout 时,用 Linux/Python 3.12 的离线进程测试或 CI 镜像验证。
## 生产部署现状
用户入口:
```text
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。
常用只读检查(确有需要时):
```sh
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.y` tag 构建并推 `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 是独立项目,必须先设计认证、镜像命名、更新器来源固定、回滚与兼容,再改代码和部署文档。
### 发布检查清单
1. 在干净基线上完成实现与审查;确认版本号、README、部署说明和 `analysis/RELEASE_X_Y_Z.md` 与最终范围一致。
2. 运行适当回归和浏览器测试,记录唯一测试数及预期 skip;`git diff --check`,检查待提交文件和敏感信息。
3. 保留用户未跟踪文件,明确暂存公开源码/文档,不用 `git add .` 横扫私有产物。
4. 用授权身份提交;需要合入 `main` 时使用正常 merge,不强推、不改已发布 tag。
5. 创建与 `ranch_web.__version__` 一致的 `v2.x.y` annotated tag,推送到**实际承担发布的 remote**。当前发布链仍需要 GitHub,不能因 Gitea 名为 `origin` 就误以为推 Gitea 足够。
6. 等稳定 tag 的 Actions 成功,核验 GHCR 镜像 version/revision label 与精确 main SHA。
7. 构建 `updater.pyz`:
```powershell
python -X utf8 -B tools\build_web_updater.py --output test-artifacts\releases\vX.Y.Z\updater.pyz
```
生成 ASCII/LF 的 `SHA256SUMS`,比较包内源码与精确提交 blob,再上传 GitHub Release。发布必须是非草稿、非预发布。
8. 独立核对 Release、资产摘要、main/tag SHA、镜像 digest 和源码版本。最后才按明确授权清理旧 Release/tag/分支;先备份且不得用仅面向 GitHub 的旧 helper 去删除 Gitea 同名 ref。
9. 告知用户可在线更新,但不声称生产已恢复,直到用户安装并反馈。
历史发布辅助位于忽略的 `test-artifacts/`,可能不存在于新机器,也可能绑定旧版本号。使用前审查,不要直接运行旧 `--apply`、cleanup 或 deploy 脚本。
## Git remote 迁移到 Gitea
### 已完成的迁移
用户已有的私有 Gitea 仓库:
```text
https://gitea.witchercheung.cn/witcher/myrzx_bot.git
```
迁移前本机同时存在:
```text
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 配置备份在忽略目录:
```text
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、命令输出或文档。
```powershell
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、是否发布或部署、仍需用户做什么。离线结果和生产结果分开写;遇到不确定的请求状态,保留证据并说明不能安全自动做的部分,而不是为了“全部完成”伪造结果。