Files
myrzx_bot/ranch_web/README.md
T
2026-11-11 15:35:36 +08:00

15 KiB
Raw Blame History

Web 2.0.2 运行说明

本轮 Web 发布目标 2.0.2,源码入口 main,游戏资料基线 1.9.68。桌面正式版保留 1.2.0,入口为 python -m ranch_assistant;Web 使用独立依赖与数据根。

Web 采用 FastAPI / Uvicorn 和原生 HTML/CSS/ES 模块,无 Node、npm 或前端编译步骤,不安装 PySide6。页面和策略能力沿用现有核心,详细业务范围与原有限制见 桌面使用说明。多浏览器连接同一个管理员工作台;一个服务实例内,各账号独立线程并行,同一账号操作串行。

迁移清单

  • 原15页:登录、培育室、背包、牧场、每日事务、自动孵蛋、自动主线、战斗记录、自动赠礼、自动委托、自动探险、自动扫荡、数据分析、执行计划、收益资料。
  • 保留账号页签、顶部数值与统一启停、可调日志;规则自动保存,配置与统计按账号/角色隔离,每次成功登录后自动执行已配置且已勾选的功能,可在顶部停止。
  • Windows Python 启动与离线演示;Web 导入链和依赖不使用 Qt,无 Node 构建步骤。
  • 提供 Linux Docker 与稳定 2.x 受控更新、停机备份及失败回滚脚本;历史 Linux Docker 部署、持久化权限、健康检查和定时更新检查烟测见下文。
  • 本轮发布目标为 2.0.2,保留桌面兼容;战斗模拟为近似模型,特殊关卡并非全部支持,真实游戏 API 验收范围不因版本号变更而扩大。
  • 2.0.2 提供九个功能页的账号分类日志面板,保留总日志与调试入口;页面和分类对应关系见 产品说明,验证范围见 发布说明。

Windows 本地运行

使用 Python 3.12+,在项目根目录执行(本机已安装 3.13):

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,也不要指向桌面私有目录:

.\Start_Ranch_Web.cmd --demo --data-dir "$env:TEMP\ranch-web-demo-new" --no-browser

健康检查 GET /api/health 不访问游戏 API。关闭终端时使用 Ctrl+C,让应用正常关闭账号队列。手动选服、恢复会话及自动重登成功读取角色后,均默认开启策略,只执行已勾选的功能,子功能不会全选。顶部“停止”暂停策略,仍保留状态监控;可用“开启”继续。导入配置只替换规则并停止执行,下次成功登录仍会自动开启;服务重启后未成功登录时不直接执行。

后台运行与断线处理

关闭网页或退出 Web 管理登录不会停止服务器上的账号监控和已开启策略。账号监控和策略执行由服务端管理;“停止”策略后仍保留状态监控,退出游戏账号或停止服务后结束监控。

账号状态区分游戏在线、临时故障重试、游戏登录过期和未连接,显示最后成功通信时间及具体原因。临时网络故障采用退避后的只读状态检查;无法确认的操作保留核对记录,不自动重复提交。游戏会话失效后停止策略和游戏轮询,按自动重登录设置等待处理,或在登录页手动恢复;成功登录后自动执行已配置且已勾选的功能,可在顶部停止。仅获取区服候选、候选角色验证失败或会话恢复失败,均不显示为登录成功。

服务重启会保留配置与加密会话;未启用自动重登录时,需要手动恢复会话。普通运行日志在各账号目录中限量持久保存,服务重启后仍可查看;调试请求详情仅在当前进程中按原有上限缓存。页面展示旧角色数据时会标注缓存状态,不把页面刷新视作游戏连接成功。

分类日志(2.0.2)

登录、每日事务、牧场、自动孵蛋、自动主线、自动赠礼、自动委托、自动探险和自动扫荡均提供当前账号的分类日志面板,底部总日志与调试入口继续保留。同一账号使用单一共享日志拉取,不为每个功能页另开轮询;浏览器共享缓存最多保留 1200 条,各日志面板最多显示最近 600 条。这些是浏览器缓存与显示上限,不改变普通日志的服务端持久保存范围。

面板支持文字搜索和级别筛选,可独立隐藏、清空显示或下载日志;下载遵循当前账号、本页清空范围及筛选条件。清空一个面板不清空总日志或其他面板,也不删除服务端历史记录。阅读历史时可暂停跟随;向上滚动会暂停自动跟随,点击“跟随最新”可回到底部。底部总日志保留独立的清空、下载与跟随控制。

分类随普通日志记录持久保存。孵蛋/牧场整理策略中的自动喂养、出售、收取及其暂停记录归入自动孵蛋(hatching);手动牧场操作和自动潜能突破归入牧场(ranch)。动作来源上下文优先于通用文字前缀,因此源自孵蛋策略的“暂停喂养”仍属于孵蛋日志。

没有分类字段的旧记录,仅在各片段均有明确前缀且一致指向同一类别时保守推断归属;不拆分旧记录,也不根据偶然出现的功能词猜测。混合类别、未知前缀及无法识别的分类保留为常规(general)记录,可在总日志和登录面板查看;登录面板同时包含登录与常规日志。

掉线后自动重新登录

在“登录”页开启“掉线后自动重新登录”,设置等待时长,默认 30 分钟,修改后自动保存。该开关默认关闭,各账号独立配置。使用前请在游戏登录时勾选“记住账号和密码”,并成功进入目标区服;密码仍由服务端加密保存。

登录偏好保存在本账号中,进入其他区服或退出登录后仍保留设置;便携策略导入导出不携带、也不覆盖该登录偏好。

检测到掉线后,服务端按等待时长重新进行账号密码登录,回到原区服、原角色。登录页显示安排时间及执行结果,关闭浏览器不影响计时。临时网络故障的只读恢复检查继续运行,连接提前恢复后会取消重登录计划。重登录失败后按配置时长等待下一次尝试;缺少保存的密码或目标角色时会显示具体原因。

开启此功能且保留有效登录记录时,服务重启也会先等待所设时长,再尝试重登录;等待及失败阶段不执行策略。主动退出、清除登录记录或移除账号会取消自动计划。重登录成功读取原区服、原角色后,恢复状态监控并默认开启策略,自动执行已勾选功能,可点击顶部“停止”暂停。

Linux Python 与环境变量

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 部署与受控在线更新。镜像使用 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.2 的验收结论。

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 认证的部署,可在 2.0.2 稳定 Release 和正式镜像就绪、宿主机心跳有效后,直接通过“帮助 → 检查版本更新…”升级 2.0.2,无需重复初始化或替换宿主机更新器。升级完成后刷新网页以加载新版界面。安装结果以宿主机健康检查为准;首次配置仅供尚未初始化的宿主机参考。

离线验证

2.0.2 发布验证

后端独立回归 309 项:306 通过、3 项因 Windows 权限或符号链接限制跳过,0 失败、0 错误;完整浏览器回归 52 项全部通过,0 跳过、0 失败,包含 9 项分类日志测试及相关 6 项回归方法,不另行累加。源码哈希一致性检查及差异检查通过;2.0.2 独立宿主机更新器仅依赖 Python 标准库,版本、dry-run、校验和及发布版本门禁校验通过。完整范围见 发布说明。

历史验证记录(不计入 2.0.2)

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 项全部通过(本轮未重跑);独立故障重放四组通过。行为与证据边界见 连接修复说明。现有后端命令追加 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个后端模块,避免发现并混入浏览器测试:

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,属于验证依赖:

python -B -m unittest ranch_web.tests.browser.test_workbench_browser ranch_web.tests.browser.test_admin_login_browser -v

子路径浏览器回归(临时离线演示,覆盖保留与移除前缀的代理):

python -B -m unittest ranch_web.tests.browser.test_base_path_browser -v

上述离线验证使用临时目录、fake transport / GitHub / Docker 或内置离线演示,不读取私有账户,不访问真实游戏 API。停止取消、配置并发保存、视图索引清理、子页字段保留和并发认证限流的已报问题均已修复并复核。Linux Docker 部署烟测见上文;离线测试及部署烟测均不等同于真实游戏 API 或生产升级/回滚验收。