Files
myrzx_bot/ranch_web/README.md
T

78 lines
5.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 采用 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.0.dev1`,保留桌面兼容,不等同正式发布或真实游戏 API 验收。
## 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_UPDATER_DIR` | 受控宿主机心跳目录;本地默认不设置 |
账号密钥、加密凭据、会话、配置和统计保留在服务端数据目录,不写入浏览器 localStorage。管理登录使用 HttpOnly / SameSite cookie,写请求校验 Origin。不要启动多个 Uvicorn worker 或多个服务实例共享同一数据根。
## Docker 与在线更新
完整步骤见 [Linux Docker 部署与受控更新](../deploy/web/README.md)。镜像使用 UID/GID 10001,持久化 `/data`,内置 `/api/health` healthcheck,正常退出宽限 120 秒,不挂载 Docker socket。
Web 检查固定官方 GitHub Releases 的稳定 `v2.x.y`,跳过桌面 1.x、未来 3.x、草稿和预发布。开发版本 `2.0.0.dev1` 可升级至同数字的正式 `v2.0.0`;没有正式 Web 2 发布时明确显示暂无更新。Windows 默认仅检查;Web “更新”按钮仅在宿主机显式启用并有有效只读心跳时可提交 `pending` 请求,安装、备份和回滚由宿主机执行。默认定时检查只通知,自动安装需操作者 opt-in。
## 离线验证
最终非浏览器后端验证 **185项:184通过、1跳过(Windows符号链接权限),0失败/错误**。以下完整命令显式列出后端模块,避免发现并混入浏览器测试:
```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
```
浏览器 **13项通过,JS/CSP错误为0**;另在新 Edge 进程验证15页、主线策略与孵蛋子页切换、未配置执行器时禁用更新按钮。浏览器测试需要 Python Playwright 和可用的 Edge,属于验证依赖:
```console
python -B -m unittest ranch_web.tests.browser.test_workbench_browser -v
```
全部验证使用临时目录、fake transport / GitHub / Docker 或内置离线演示,不读取私有账户,不访问真实游戏 API。停止取消、配置并发保存、视图索引清理、子页字段保留和并发认证限流的已报问题均已修复并复核。当前 Windows 无 Docker;上述结果不代表 Linux Docker、生产更新器或真实游戏服务器实机验收通过。