156 lines
18 KiB
Markdown
156 lines
18 KiB
Markdown
# Web 2.0.12 运行说明
|
||
|
||
Web **2.0.12**,源码发布入口 `main`,游戏资料基线 **1.9.68**。桌面正式版保留 **1.2.0**,入口为 `python -m ranch_assistant`;Web 使用独立依赖与数据根。自动委托提供当前委托与每日记录,功能和历史验证状态见 [2.0.8 发布说明](../analysis/RELEASE_2_0_8.md)。
|
||
|
||
2.0.12 修复扫荡触发隐藏关卡后的接续:完整入场响应与原始队伍快照等原始输入均已保存且可验证时,新记录或可恢复旧记录才按 `stageEvent.hideStageId` 构建隐藏关卡难度1的战斗,自动战斗且无需手动确认,不再发送第二次 `stageStart`,战后使用隐藏 ID 结算。旧记录即使能从 trace 找回隐藏 ID,缺少原始队伍也保留中文待核对状态,不用当前属性替代原始属性,不发送游戏写请求。现场旧 `0211 / 3` pending 的原始响应已被日志轮转覆盖,隐藏 ID 无法还原;仅对符合精确四字段 legacy 形态、严格确认已入场且未结算的这类旧阶段,保留证据、本地归档为未完成并放弃,不提交胜负或重发入场,让后续策略继续。归档不等于服务端已结算,本版未在生产打通当前这场战斗,见 [本版发布说明](../analysis/RELEASE_2_0_12.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.12**,无需先安装 2.0.2、重复初始化或替换宿主机更新器。升级完成后刷新网页以加载新版界面,底部日志默认收起。安装结果以宿主机健康检查为准;首次配置仅供尚未初始化的宿主机参考。
|
||
|
||
## 离线验证
|
||
|
||
本版共 **491 项唯一仓库测试:489 通过、2 项 Windows 预期跳过,0 失败 / 错误**,见 [2.0.12 发布说明](../analysis/RELEASE_2_0_12.md#验证)。镜像工作流在安装测试依赖后,独立执行隐藏关卡 handoff、battles、engine 三个专用回归模块;通过 `ranch_web/requirements-test.txt` 安装 HTTPX 的修复继续保留。2.0.11 的测试结果见 [历史发布说明](../analysis/RELEASE_2_0_11.md#验证),不计入本版。以下为继续保留的子进程传输、战斗恢复、能力展示、Web 生命周期、恢复契约及状态 API 回归命令:
|
||
|
||
```console
|
||
python -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
|
||
```
|
||
|
||
2.0.9 的历史验证见 [历史发布说明](../analysis/RELEASE_2_0_9.md#验证),不计入本版。
|
||
|
||
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 或生产升级/回滚验收。
|