Files
myrzx_bot/ranch_web/README.md
T

152 lines
17 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.0.9 运行说明
Web **2.0.9**,源码发布入口 `main`,游戏资料基线 **1.9.68**。桌面正式版保留 **1.2.0**,入口为 `python -m ranch_assistant`;Web 使用独立依赖与数据根。自动委托提供当前委托与每日记录,功能和历史验证状态见 [2.0.8 发布说明](../analysis/RELEASE_2_0_8.md)。
2.0.9 清理重复运行提示,补齐委托资源准备、默认快速战斗及正常潜能误报修复。委托明确显示中文未接取原因,成熟魔物需求联动购蛋、孵化;按剩余步骤备料,遵守预算、需求缺口及魔物保护设置。详情继续使用原单一底部分类日志,见 [本版发布说明](../analysis/RELEASE_2_0_9.md)。
正常执行默认使用现有内置实验运行时入口的快速 HP/DPS 模型,保留现有伤害配置,无需选择新模式;逐帧实现仅供研发。模型按双方属性、血量、每秒伤害、时间与目标估算胜利、战败或超时,仍有机制简化,不保证全部关卡可通关或与客户端结果一致。
Web 采用 FastAPI / Uvicorn 和原生 HTML/CSS/ES 模块,无 Node、npm 或前端编译步骤,不安装 PySide6。页面和策略能力沿用现有核心,详细业务范围与原有限制见 [桌面使用说明](../ranch_assistant/README.md)。多浏览器连接同一个管理员工作台;一个服务实例内,各账号独立线程并行,同一账号操作串行。
## 迁移清单
- [x] 原15页:登录、培育室、背包、牧场、每日事务、自动孵蛋、自动主线、战斗记录、自动赠礼、自动委托、自动探险、自动扫荡、数据分析、执行计划、收益资料。
- [x] 保留账号页签、顶部数值与统一启停、可调日志;规则自动保存,配置与统计按账号/角色隔离,未手动停止时,成功登录后自动执行已配置且已勾选的功能;手动暂停跨重登保留,可在顶部开启。
- [x] Windows Python 启动与离线演示;Web 导入链和依赖不使用 Qt,无 Node 构建步骤。
- [x] 提供 Linux Docker 与稳定 2.x 受控更新、停机备份及失败回滚脚本;历史 Linux Docker 部署、持久化权限、健康检查和定时更新检查烟测见下文。
- [x] `2.0.8` 自动委托当前 / 每日记录、持久化历史及奖励证据区分;739项独立测试中736通过、3项 Windows 跳过,浏览器77项全部验证通过。战斗模拟仍为近似模型,特殊关卡并非全部支持。
- 沿用 2.0.7 的同种重复培养修复:主培养与资质备用分离,自动喂养、赠礼和潜能突破仅作用于主培养,启用种类固定主培养1只与更优备用最多1只。详见 [2.0.7 发布说明](../analysis/RELEASE_2_0_7.md)。
- 2.0.3 修复 2.0.2 日志布局:所有页签复用原有底部日志区,按当前账号与功能筛选,默认收起;操作约定见 [产品说明](PRODUCT.md#203-底部分类日志),验收结果见 [发布说明](../analysis/RELEASE_2_0_3.md#验证)。
## 自动委托(2.0.8)
- “当前委托”查看任务、原始候选和选择 / 回退原因;城市锁定候选显示不可接取。策略允许且满足城市、次数、资源和步骤条件的候选,跨城市按预计氪金20→15→10排序,日志说明高档不可用的原因。
- “每日记录”按账号、区服、角色及北京时间(UTC+8)自然日查询接取、推进、领奖与待核对事件。历史持久保存,刷新或重启后可查;每角色保留最近90天、最多5000条事件。
- 预计氪金来自静态任务配置,已确认氪金仅取确认成功的领奖回包 `response.reward.ke`;金额缺失显示“未确认”。接取、推进、旧完成标记和预计数额不作为实际奖励证据。
- 旧历史仅从本地任务 journal 可证实的操作部分回填,不推造缺失的过去。业务历史之外的运行详情继续使用原单一底部“自动委托”分类日志。完整行为见 [发布说明](../analysis/RELEASE_2_0_8.md)。
## Windows 本地运行
使用 Python 3.12+,在项目根目录执行(本机已安装 3.13):
```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`,本机无需管理密码。启动脚本优先使用 `.venv-web`,否则使用 PATH 中的 `python`。也可直接运行 `python -B -m ranch_web`;安装依赖时务必选择同一解释器。首启不自动创建或登录游戏账号。
离线演示请指定全新目录,仅使用 fake / 内置演示,不连接真实游戏 API,也不要指向桌面私有目录:
```powershell
.\Start_Ranch_Web.cmd --demo --data-dir "$env:TEMP\ranch-web-demo-new" --no-browser
```
健康检查 `GET /api/health` 不访问游戏 API。关闭终端时使用 Ctrl+C,让应用正常关闭账号队列。手动选服、恢复会话及自动重登成功读取角色后,默认执行已勾选功能,子功能不会全选;用户手动“停止”则继续保持暂停,点击“开启”恢复。启停选择跨掉线、重登和服务重启保存,导入策略保留该选择;停止策略后仍保留状态监控。
### 后台运行与断线处理
关闭网页或退出 Web 管理登录不会停止服务器上的账号监控和已开启策略。账号监控、重登及策略执行都由服务端管理。手动“停止”只暂停策略,连接监控与掉线重登继续;该暂停在重新登录和服务重启后仍保留,点击“开启”恢复。
临时网络故障采用退避后的只读状态检查,确认角色连接恢复后自动继续原先启用的策略。会话失效时按登录页等待时长自动重新登录。账号状态区分用户暂停、临时恢复和请求待核对,心跳成功不等于策略已经运行;日志保留失败原因及恢复结果。未确认的消耗请求仍保留核对记录,不自动重复提交。
服务重启会保留配置、加密会话及启停选择,并自动恢复有登录记录的账号。只有清除登录记录或移除账号才取消持续自动登录;缺少密码、区服或原角色信息时显示具体原因。运行日志按账号限量持久保存,旧角色数据会标注缓存状态。
### 底部分类日志(2.0.3)
所有功能页只复用原有可调高度的底部日志区及工具栏,切换页签后按当前账号、当前功能筛选。取消总日志/全部模式及功能页内嵌日志框,调试入口保留。培育室查看孵蛋日志;其他只读页无对应执行日志时显示为空,不补入无关日志。功能对应关系见 [产品说明](PRODUCT.md#203-底部分类日志)。
顶部右侧是唯一的日志显示/隐藏入口。每次整页刷新(F5)或重新进入工作台均默认收起,即使旧配置为显示也不自动展开;配置/状态刷新及调试模式不展开日志。同一浏览器会话内,显隐按账号保留,手动展开后切换功能页保持展开,隐藏后切页仍保持隐藏。
搜索、清空显示、下载、跟随/暂停及滚动位置按账号、页签隔离。清空只影响当前范围的显示,不删除服务端历史;下载遵循相同的清空范围与搜索条件。向上滚动可暂停跟随,点击“跟随最新”回到底部;切换账号或功能页不会串用其他上下文的日志或操作状态。同一账号共用日志拉取,浏览器缓存最多 1200 条,底部最多显示最近 600 条。
已有分类与保守旧记录推断沿用原实现。孵蛋/牧场整理策略中的自动喂养、出售、收取及暂停归入孵蛋;手动牧场操作与自动潜能突破归入牧场。登录仅显示登录日志,排除常规、混合旧记录及赠礼日志;无法明确归属当前功能的记录不回退为全部显示。
手动刷新成功时仅显示简短状态,详细日志只在原底部日志区查看,不弹出诊断提示或大段浮动消息,也不自动展开日志;错误与登录认证反馈沿用原有行为。
### 掉线后自动重新登录
登录成功并保存原区服、原角色后,自动保持登录;“登录”页只需设置重登等待时长,默认 **30 分钟**,可改为 **10 分钟**,每账号独立保存。请勾选“记住账号和密码”,密码由服务端加密保存。旧版关闭的自动重登开关不再阻止已保存账号恢复登录。
掉线后从首次失败开始计时;普通只读重试不会延后重登时间。密码重登失败后按同一时长继续尝试,登录成功后仅执行原有已勾选功能;如果你手动停止过策略,则继续保持暂停。关闭浏览器不影响计时,退出游戏连接仍会安排恢复;彻底取消请清除登录记录或删除账号。
登录偏好与策略启停不随便携策略导入导出,避免在其他账号误用。后台保留未确认请求证据,恢复连接不会重放这些请求。
## Linux Python 与环境变量
```sh
python3 -m venv .venv-web
.venv-web/bin/python -m pip install -r ranch_web/requirements.txt
sh start-web.sh --no-browser
```
| 设置 | 默认 / 用途 |
| --- | --- |
| `RANCH_WEB_HOST` | `127.0.0.1`;非 loopback 必须设置管理密码 |
| `RANCH_WEB_PORT` | `8765` |
| `RANCH_WEB_DATA_DIR` | 项目下 `local_state/ranch_web`;Docker 固定 `/data` |
| `RANCH_WEB_PASSWORD` | 独立的 Web 管理密码,不是游戏密码 |
| `RANCH_WEB_PASSWORD_HASH` | 可替代明文管理密码,格式与生成函数见 `config.py` |
| `RANCH_WEB_ALLOWED_HOSTS` | 明确的额外域名/IP,无通配符 |
| `RANCH_WEB_ALLOWED_ORIGINS` | 明确的额外 http(s) 来源,逗号分隔 |
| `RANCH_WEB_SECURE_COOKIE` | HTTPS 反代时设 `true` |
| `RANCH_WEB_BASE_PATH` | 默认空(根路径);子路径示例 `/ranch`,不带末尾 `/` |
| `RANCH_WEB_UPDATER_DIR` | 受控宿主机心跳目录;本地默认不设置 |
账号密钥、加密凭据、会话、配置和统计保留在服务端数据目录,不写入浏览器 localStorage。管理登录使用 HttpOnly / SameSite cookie,写请求校验 Origin。不要启动多个 Uvicorn worker 或多个服务实例共享同一数据根。
配置管理密码后,未登录访问 `/`、工作台 HTML 或脚本会由服务端转到独立 `/login` 页面;登录前不加载工作台。管理 cookie 使用配置的子路径(根路径部署为 `Path=/`),登录和退出均清理旧版 cookie;退出管理登录或会话失效后,页面隐藏工作台并返回登录页。登录页和工作台 HTML 使用 `Cache-Control: no-store`,本机未配置密码时仍保留 loopback 免密模式。
子路径反代示例:设置 `RANCH_WEB_BASE_PATH=/ranch`,从 `https://example.com/ranch/` 访问;登录页、静态资源、API 与退出跳转均使用此前缀。代理可保留此前缀或转发时移除一次此前缀。允许的 Host 使用 `example.com`,Origin 使用 `https://example.com`(不含路径);HTTPS 同时设置 `RANCH_WEB_SECURE_COOKIE=true`。容器健康检查继续使用 `/api/health`。省略 `RANCH_WEB_BASE_PATH` 时沿用根路径部署。
## Docker 与在线更新
完整步骤、已有部署更新与首次私有更新器初始化见 [Linux Docker 部署与受控在线更新](../deploy/web/README.md)。镜像使用 UID/GID 10001,持久化 `/data`,内置 `/api/health` healthcheck,正常退出宽限 120 秒,不挂载 Docker socket。
历史部署烟测(独立管理登录页调整前):曾在 Ubuntu 24.04、Docker 29.8、Compose 5.5、Python 3.12 环境完成镜像构建和部署烟测,UID 10001 数据目录权限为 0700、密钥为 0600,应用根文件系统只读;健康检查及转发返回 HTTP 200,Edge 管理登录后可访问 15 个功能页且无 JavaScript 错误,更新定时器已启用并成功完成首次 GitHub 检查。当时后续登录页调整仅记录了本地验证,重新部署与真实游戏 API 验收尚未完成;此历史状态及烟测结果均不作为 2.0.3 的验收结论。
Web 检查固定官方 GitHub Releases 的稳定 `v2.x.y`,跳过桌面 1.x、未来 3.x、草稿和预发布。开发版本 `2.0.0.dev1` 可升级至同数字的正式 `v2.0.0`;没有正式 Web 2 发布时明确显示暂无更新。Windows 默认仅检查;Web “更新”按钮仅在宿主机显式启用并有有效只读心跳时可提交 `pending` 请求,安装、备份和回滚由宿主机执行。默认定时检查只通知,自动安装需操作者 opt-in。
已在 **2.0.1** 完成私有仓库和 GHCR 认证的部署,稳定 Release 和正式镜像就绪、宿主机心跳有效后,可直接通过“帮助 → 检查版本更新…”升级 **2.0.9**,无需先安装 2.0.2、重复初始化或替换宿主机更新器。升级完成后刷新网页以加载新版界面,底部日志默认收起。安装结果以宿主机健康检查为准;首次配置仅供尚未初始化的宿主机参考。
## 离线验证
2.0.9 快速模型的输入预检覆盖358/358份主线与委托战斗配置。当前卡点的真实账号离线样本预计战斗5秒,直接计算约1.2毫秒,含隔离进程启动与检查约0.21秒;8个20氪金委托战斗的离线结果为5胜3败,见 [本版发布说明](../analysis/RELEASE_2_0_9.md#验证)。
617项唯一回归用例中615项通过,2项因Windows环境跳过;另有8项界面浏览器测试通过。多步骤采购循环已经修复并独立复核。本轮未在线提交游戏结算或手动部署X99。
2.0.8 共验证739项独立测试:736通过、3项 Windows 跳过;其中非浏览器662项(659通过、3跳过),浏览器77项全部验证通过。分组结果与证据见 [发布说明](../analysis/RELEASE_2_0_8.md#验证)。2.0.7 的结果保留在 [历史发布说明](../analysis/RELEASE_2_0_7.md#验证),以下历史记录也不计入本版验收。
### 历史验证记录(不计入 2.0.8)
2.0.2 验证记录见 [历史发布说明](../analysis/RELEASE_2_0_2.md#验证)。
2.0.1 发布回归:后端及更新器 **297 项中 294 通过、3 项因 Windows 权限或软链接限制跳过**,浏览器 **43 项全部通过**。更新器专项命令增加 `ranch_web.tests.test_private_updates ranch_web.tests.test_web_updater_package`;Linux 镜像工作流也执行这两项模块,验证独立包、私有认证与容器健康。
自动重登录功能回归:后端及登录链路 **267 项中 266 通过、1 项因 Windows 符号链接权限跳过**,浏览器 **39 项全部通过**;另以禁止外部网络的合成账号完成 24 项独立审核。后端命令增加 `ranch_web.tests.test_auto_relogin ranch_assistant.tests.test_debug`,浏览器命令增加 `ranch_web.tests.browser.test_auto_relogin_browser.AutoReloginBrowserTests ranch_web.tests.browser.test_auto_relogin_browser.AutoReloginSchemaTests`。
2.0.0 发布整理本轮仅调整版本元数据,API 策略与行为未改;完整 Web 后端回归 **246 项:245 通过、1 项因 Windows 符号链接权限跳过、0 失败**。以下保留此前功能提交及开发阶段的验证记录。
前一功能提交的后台连接与日志修复:Web 后端 **245 项中 244 通过、1 项因 Windows 符号链接权限跳过**,浏览器 **31 项全部通过(本轮未重跑)**;独立故障重放四组通过。行为与证据边界见 [连接修复说明](../analysis/WEB_CONNECTION_FIX.md)。现有后端命令追加 `ranch_web.tests.test_base_path ranch_web.tests.test_activity ranch_web.tests.test_connection_state`,浏览器命令追加 `ranch_web.tests.browser.test_base_path_browser ranch_web.tests.browser.test_connection_browser.ConnectionBrowserTests` 可覆盖该功能回归。
独立管理登录页调整后的完整非浏览器后端验证为 **193项:192通过、1跳过(Windows符号链接权限),0失败/错误,用时26.994秒**。以下命令显式列出全部10个后端模块,避免发现并混入浏览器测试:
```console
python -B -m unittest ranch_web.tests.test_api ranch_web.tests.test_auth ranch_web.tests.test_scheduler ranch_web.tests.test_service ranch_web.tests.test_store ranch_web.tests.test_updates ranch_web.tests.test_web_integration ranch_web.tests.test_web_policies ranch_web.tests.test_web_updater ranch_web.tests.test_web_views_actions -v
```
独立管理登录页调整后的浏览器验证为 **21项全部通过(13项原有工作台、7项密码保护登录、1项本机免密),JS/CSP错误为0**,覆盖独立登录页、工作台访问门禁、退出、会话失效和原有功能。浏览器测试需要 Python Playwright 和可用的 Edge,属于验证依赖:
```console
python -B -m unittest ranch_web.tests.browser.test_workbench_browser ranch_web.tests.browser.test_admin_login_browser -v
```
子路径浏览器回归(临时离线演示,覆盖保留与移除前缀的代理):
```console
python -B -m unittest ranch_web.tests.browser.test_base_path_browser -v
```
上述离线验证使用临时目录、fake transport / GitHub / Docker 或内置离线演示,不读取私有账户,不访问真实游戏 API。停止取消、配置并发保存、视图索引清理、子页字段保留和并发认证限流的已报问题均已修复并复核。Linux Docker 部署烟测见上文;离线测试及部署烟测均不等同于真实游戏 API 或生产升级/回滚验收。