Files
myrzx_bot/ranch_web/README.md
T

9.4 KiB
Raw Blame History

Web 2 开发运行

Web 包版本 2.0.0.dev1,游戏资料基线 1.9.68,开发分支 develop/v2.0.0。当前正式桌面版仍为 1.2.0;Web 未合并 main、未发布正式版本。桌面入口 python -m ranch_assistant 保留,Web 使用独立依赖与数据根。

Web 采用 Vue 3 + Vite 前端和 FastAPI / Uvicorn 后端,运行时不安装 PySide6。界面重新组织为侧边导航、顶部账号范围、面包屑和内容区;总览与账号管理面向全部账号,业务与策略面向当前账号。现有策略核心与业务校验继续复用,各账号独立运行,同一账号操作串行。设计与交互规范见 UX 方案。

迁移清单

  • 原15页:登录、培育室、背包、牧场、每日事务、自动孵蛋、自动主线、战斗记录、自动赠礼、自动委托、自动探险、自动扫荡、数据分析、执行计划、收益资料。
  • 用分组侧栏和账号选择器替代桌面式横向标签;增加总览、账号管理与系统入口。当前账号资源和启停明确可见,规则自动保存,配置与统计按账号/角色隔离。
  • Windows Python 启动与离线演示;仓库包含已构建前端,普通运行无需 Node。修改前端需 Node 22 和 npm 构建;生产镜像运行阶段不含 Node。
  • 提供 Linux Docker 与稳定 2.x 受控更新、停机备份及失败回滚脚本;已完成 Linux Docker 部署、持久化权限、健康检查和定时更新检查烟测。
  • 开发版本为 2.0.0.dev1,保留桌面兼容,不等同正式发布或真实游戏 API 验收。

前端开发与构建

正常运行可直接使用 Python 启动脚本。修改界面后,在项目根目录执行:

npm --prefix frontend ci
npm --prefix frontend run build
python -B -m ranch_web --no-browser

源码位于 frontend/,构建输出至 ranch_web/static/console/ 并更新工作台 HTML 入口。Docker 使用独立 Node 构建阶段,最终容器仅包含 Python 与同源静态文件。静态路径支持 RANCH_WEB_BASE_PATH,不使用外部 CDN。

长表默认分页,排序针对当前筛选后的完整数据;只渲染可见页面,后台浏览器减少查询。配置与状态按账号隔离,导航不自动开启策略。单账号“开启/停止”与各策略启用开关分别表达执行状态和参与运行的规则。

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,让应用正常关闭账号队列。重启、恢复会话或导入策略后仍需手动开启运行。

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,应用根文件系统只读;健康检查及 FRP 转发返回 HTTP 200,Edge 管理登录后可访问 15 个功能页且无 JavaScript 错误,更新定时器已启用并成功完成首次 GitHub 检查。此部署烟测记录对应独立管理登录页调整前的版本;调整后的本地验证见下文,重新部署验收待完成,真实游戏 API 尚未验收。

Web 检查固定官方 GitHub Releases 的稳定 v2.x.y,跳过桌面 1.x、未来 3.x、草稿和预发布。开发版本 2.0.0.dev1 可升级至同数字的正式 v2.0.0;没有正式 Web 2 发布时明确显示暂无更新。Windows 默认仅检查;Web “更新”按钮仅在宿主机显式启用并有有效只读心跳时可提交 pending 请求,安装、备份和回滚由宿主机执行。默认定时检查只通知,自动安装需操作者 opt-in。

离线验证

独立管理登录页调整后的完整非浏览器后端验证为 201项:200通过、1跳过(Windows符号链接权限),0失败/错误,用时26.994秒。以下命令显式列出全部10个后端模块,避免发现并混入浏览器测试:

python -B -m unittest ranch_web.tests.test_base_path 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

独立管理登录页调整后的浏览器验证为 30项全部通过(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 或生产升级/回滚验收。

Vue 控制台改版验证(2026-11-11)

  • 后端201项:200通过、1项Windows符号链接权限跳过;浏览器30项全部通过,保留原23项并新增路由、账号范围、分页与响应式回归。
  • npm --prefix frontend run check 与 npm --prefix frontend run build 通过;npm --prefix frontend test 的24项控制器和表格测试通过。
  • 覆盖账号切换、浏览器前进后退/刷新、自动保存与冲突、停止取消尚未发出的启动请求、独立管理登录、登录过期、前缀保留/剥离代理和脱敏日志详情。
  • 本机相同1000行离线表格:实际渲染1000行降为50行,输入控件3000个降为150个。此记录衡量DOM负担,不代表真实账号全链路耗时。
  • 主要功能页1440px与手机390px截图检查通过,没有整个页面横向溢出。宽表在自身容器内滚动;监控与业务规则不因界面刷新而改变。

测试使用临时演示与fixture,不使用真实游戏账号。上述命令需要Node22;表格浏览器测试另需Python Playwright和系统Chromium(可用 RANCH_WEB_BROWSER 指定路径)。