某鱼超级管家本地部署操作手册
某鱼超级管家（xianyu-super-butler v3.1.0）是一款面向某鱼卖家的多账号自动化管理系统，支持账号托管、自动发货、自动回复、商品同步、经营看板等功能。本手册介绍如何通过离线部署包在本地 Windows 环境完成安装、配置与运行，全程无需联网下载依赖。
一、部署包说明
1.1 包内容
部署包 xianyu-super-butler-deploy.zip 解压后得到以下目录结构：
| 名称 | 说明 |
|---|---|
| install.bat | 一键离线安装脚本（包根目录） |
| start.bat | 服务启动脚本（包根目录） |
| project/ | 项目源码（含已构建的前端页面 static/） |
| wheels/ | Python 依赖离线安装包（79 个包） |
| browser/ | Playwright Chromium 浏览器资源（含 headless shell、ffmpeg、winldd） |
| installer/ | Python 3.13.13 安装程序（本机无 Python 时自动静默安装） |
| 部署说明.txt | 快速部署摘要 |
1.2 系统要求
| 项目 | 要求 |
|---|---|
| 操作系统 | Windows 10 / 11 64 位 |
| CPU | x86_64 架构 |
| 磁盘空间 | ≥ 3 GB（虚拟环境约 500 MB + 浏览器约 685 MB + 数据库与日志） |
| 内存 | ≥ 4 GB（推荐 8 GB） |
| Python | 3.11 及以上（3.11/3.12/3.13/3.14 均可；无 Python 时安装包自动安装 3.13.13） |
| 网络 | 安装全程离线；首次登录某鱼账号需正常联网 |
二、快速部署（三步完成）
2.1 解压部署包
将 xianyu-super-butler-deploy.zip 解压到本地目录。
重要：推荐解压到不含中文和空格的目录，例如 C:\xianyu-butler，以避免 Windows 路径过长导致安装失败。
2.2 运行安装脚本
双击运行包根目录下的 install.bat，脚本依次执行以下步骤：
- 检测 Python：自动查找本机已安装的 Python 3.11+；若不存在，静默安装包内自带的 Python 3.13.13；
- 创建虚拟环境：在 project.venv 下创建独立 Python 环境；
- 离线安装依赖：从本地 wheels/ 目录离线安装全部 Python 依赖（约 79 个包），不联网；
- 部署浏览器：将 Playwright Chromium 浏览器资源复制到系统用户目录 %LOCALAPPDATA%\ms-playwright。
看到「Installation completed successfully!」即安装完成。整个过程约 5--15 分钟，取决于磁盘速度。
2.3 启动服务
双击 start.bat，窗口显示服务启动信息后，用浏览器访问：
· 管理页面：http://localhost:8080
· 默认账号：admin / admin123
登录后请立即在「设置」中修改默认密码。
三、手动安装方式（备选）
当您希望自行控制安装过程，或安装脚本因特殊环境失败时，可手动执行以下步骤。以下命令请在解压后的 project 目录内运行。
3.1 准备 Python 环境
python -m venv .venv
.venv\Scripts\python.exe -m pip install --upgrade pip
3.2 离线安装依赖
.venv\Scripts\python.exe -m pip install --no-index --find-links=..\wheels -r requirements.txt
注意：--find-links 路径应使用正斜杠（../wheels 写成 C:/path/wheels 形式）或放在 --no-index 之后由 pip 直接索引目录；若提示「Location ... is ignored」，请改用正斜杠表示的绝对路径。
3.3 部署浏览器
set PW_DIR=%LOCALAPPDATA%\ms-playwright
if not exist "%PW_DIR%" mkdir "%PW_DIR%"
xcopy /e /i /y ..\browser\chromium-1223 "%PW_DIR%\chromium-1223"
xcopy /e /i /y ..\browser\chromium_headless_shell-1223 "%PW_DIR%\chromium_headless_shell-1223"
xcopy /e /i /y ..\browser\ffmpeg-1011 "%PW_DIR%\ffmpeg-1011"
xcopy /e /i /y ..\browser\winldd-1007 "%PW_DIR%\winldd-1007"
3.4 启动服务
.venv\Scripts\python.exe Start.py
四、配置说明
4.1 服务配置（global_config.yml）
服务主配置文件位于 project/global_config.yml，常用配置项：
| 配置项 | 默认值 | 说明 |
|---|---|---|
| AUTO_REPLY.api.port | 8080 | Web 服务端口，修改后管理页面地址同步变化 |
| AUTO_REPLY.api.host | 0.0.0.0 | 监听地址，0.0.0.0 支持局域网 IP 访问 |
| AUTO_REPLY.enabled | true | 是否启用自动回复 |
| AUTO_REPLY.api.enabled | false | 是否启用 API 回复接口 |
| ITEM_SYNC.interval | 600 | 商品自动同步间隔（秒） |
| LOG_CONFIG.level | INFO | 日志级别 |
4.2 环境变量（.env）
如需调整数据库密码等启动参数，可参照 .env.example 创建 .env 文件后按需修改；Docker 部署时才涉及，源码运行时使用默认设置即可。
4.3 数据目录
| 目录 | 内容 |
|---|---|
| project/data/ | SQLite 数据库（账号、订单、商品、卡密等业务数据），首次启动自动创建 |
| project/logs/ | 运行日志（按天轮转，保留 7 天） |
| project/backups/ | 数据库自动备份 |
| %LOCALAPPDATA%\ms-playwright | Chromium 浏览器运行目录 |
备份数据：定期备份 project/data/ 目录即可完整保留业务数据。
五、服务管理
5.1 启动
· 方式一：双击 start.bat（保持窗口开启，关闭窗口即停止服务）；
· 方式二：在 project 目录执行 .venv\Scripts\python.exe Start.py。
5.2 停止
直接关闭 start.bat 的命令行窗口即可；服务停止会保留全部数据。
5.3 服务自检
在服务已启动的状态下，浏览器访问 http://localhost:8080/health，返回 {"status":"healthy",...} 表示服务运行正常；http://localhost:8080/docs 为 API 接口文档。
5.4 卸载
删除部署包解压目录、%LOCALAPPDATA%\ms-playwright 下相关浏览器目录即可；如需彻底清理，一并删除 project/data/ 中的数据库文件（会丢失业务数据，请先备份）。
六、常见问题排查
| 现象 | 原因与解决办法 |
|---|---|
| 安装时报「文件名或扩展名太长」（WinError 206） | 解压路径过深触发 Windows 260 字符路径限制。将部署包解压到短路径（如 C:\xianyu-butler）后重新安装 |
| 依赖安装提示「Location ... is ignored」 | --find-links 接受了反斜杠路径但 pip 无法识别。改用正斜杠绝对路径（如 --find-links=C:/xianyu-butler/wheels），或直接使用 install.bat 一键安装 |
| 启动时报端口 8080 被占用（WinError 10048） | 已有实例在运行（重复启动）或端口被其他程序占用。关闭旧窗口，或修改 global_config.yml 中 port 后重启 |
| 滑块验证 / 人机验证失败 | 平台风控限制，自动化验证不保证 100% 成功；失败时可按页面提示转人工验证，或在账号页处理 |
| 登录提示海外 IP 风险 | 请使用国内网络环境运行；海外出口 IP 会增加某鱼账号风控概率 |
| 数据库升级卡住或数据异常 | 停止服务后备份 project/data/，删除异常数据库文件后重启（服务会重建空库，需重新添加账号） |
| 页面样式异常 | 刷新浏览器缓存（Ctrl+F5）；确认 project/static/ 目录完整（前端已随包构建，无需重新编译） |
七、注意事项
- 账号安全：首次登录后请立即修改默认密码（admin / admin123）；不要将本机数据目录分享给他人；
- 平台合规：请遵守某鱼平台用户规则，本工具仅用于合法合规的自动化经营场景；滑块与人机验证受平台风控约束，请合理使用；
- 部署环境：请勿将本项目部署到共享托管平台（README 明确警示），本地部署为推荐方式；
- 数据备份：建议每周备份 project/data/ 目录；
- 版本更新：项目为 AGPL-3.0 开源协议，更新请关注上游 GitHub 仓库（23Star/xianyu-super-butler）Release 说明；
- 风险提示：自动化操作存在被平台限制的风险，请控制使用频率，重要账号慎用全自动功能。