Files
myrzx_bot/ranch_web/README.md
T

115 lines
9.4 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 开发运行
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 方案](DESIGN.md)。
## 迁移清单
- [x] 原15页:登录、培育室、背包、牧场、每日事务、自动孵蛋、自动主线、战斗记录、自动赠礼、自动委托、自动探险、自动扫荡、数据分析、执行计划、收益资料。
- [x] 用分组侧栏和账号选择器替代桌面式横向标签;增加总览、账号管理与系统入口。当前账号资源和启停明确可见,规则自动保存,配置与统计按账号/角色隔离。
- [x] Windows Python 启动与离线演示;仓库包含已构建前端,普通运行无需 Node。修改前端需 Node 22 和 npm 构建;生产镜像运行阶段不含 Node。
- [x] 提供 Linux Docker 与稳定 2.x 受控更新、停机备份及失败回滚脚本;已完成 Linux Docker 部署、持久化权限、健康检查和定时更新检查烟测。
- [x] 开发版本为 `2.0.0.dev1`,保留桌面兼容,不等同正式发布或真实游戏 API 验收。
## 前端开发与构建
正常运行可直接使用 Python 启动脚本。修改界面后,在项目根目录执行:
```console
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):
```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,让应用正常关闭账号队列。重启、恢复会话或导入策略后仍需手动开启运行。
## 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,应用根文件系统只读;健康检查及 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个后端模块,避免发现并混入浏览器测试:
```console
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,属于验证依赖:
```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 或生产升级/回滚验收。
## 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` 指定路径)。