docs: preserve project context and Gitea handoff
This commit is contained in:
@@ -0,0 +1,288 @@
|
||||
# 运维、验证与 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、是否发布或部署、仍需用户做什么。离线结果和生产结果分开写;遇到不确定的请求状态,保留证据并说明不能安全自动做的部分,而不是为了“全部完成”伪造结果。
|
||||
Reference in New Issue
Block a user