# 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、生产更新器或真实游戏服务器实机验收通过。