crypto_monitor/manual_trading_hub/部署文档.md

手工交易中控 — 部署文档

本文档描述在本机（以 Windows 为主）将 manual_trading_hub 部署为「多账户监控 + 紧急全平」的推荐步骤、验收方法与注意事项。功能说明与配置项详见同目录 《README.md》。

---

一、部署目标

• 本机或局域网可访问 中控页面（默认监听 0.0.0.0:5100，私网 IP 可打开；本机可用 127.0.0.1）。
• 每个需要纳入监控的交易所账户，有独立的 子代理 进程（默认端口 15200～15203，与各 crypto_monitor_* 里 Flask 的 APP_PORT 错开）。
• 策略项目 crypto_monitor_binance / crypto_monitor_okx / crypto_monitor_gate / crypto_monitor_gate_bot 无需修改代码，与中控并行运行。

---

二、前置条件

1. 已安装 Python 3.10+，且 pip 可用。
2. 各策略目录下已配置好交易所 API：在对应 crypto_monitor_* 目录执行过 cp .env.example .env 并填好密钥（与平时运行 Flask 时同一份 .env，或等价环境变量）。各项目 app.py 会读取同目录 .env 中的 APP_HOST / APP_PORT 用于 Flask；子代理使用环境变量 PORT，二者不能占用同一端口。策略目录的 .env 不在 Git 中，git pull 不会覆盖；升级前建议在各策略目录 cp .env .env.backup.$(date +%Y%m%d)。
3. 本机端口 15200～15203、5100（及你各策略 .env 里的 APP_PORT）无冲突；若被占用，须改子代理 PORT 并同步修改 HUB_AGENTS。
4. Linux 路径约定（可选）：若部署在 Ubuntu 等环境，建议将整个代码树放在 /opt/crypto_monitor/ 下（与 scripts/后台运行-Ubuntu.md 示例一致），例如策略目录为 /opt/crypto_monitor/crypto_monitor_binance、中控为 /opt/crypto_monitor/manual_trading_hub。

---

三、目录与文件

manual_trading_hub/
  agent.py           # 子代理（单账户）
  hub.py             # 中控
  requirements.txt   # Python 依赖
  static/
    index.html       # 中控前端页面
  README.md          # 说明文档
  部署文档.md        # 本文档

---

四、安装依赖

在 manual_trading_hub 目录执行：

cd manual_trading_hub
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Linux / macOS：

cd manual_trading_hub
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

后续启动 hub.py / agent.py 时，请使用同一虚拟环境中的 python，保证已安装 fastapi、uvicorn、httpx、ccxt；若各策略 .env 中配置了 SOCKS 代理（GATE_SOCKS_PROXY / BINANCE_SOCKS_PROXY / OKX_SOCKS_PROXY 等），还需 PySocks（已写入 requirements.txt，新环境 pip install -r requirements.txt 即可）。

---

五、部署步骤（推荐顺序）

步骤 1：确认策略进程（可选）

若你平时已运行各目录下的 Flask（app.py），可保持运行；中控与子代理不依赖 Flask 是否启动。

步骤 2：为每个账户启动子代理

每个账户一个终端窗口，在对应策略项目目录进入后加载环境变量，再启动 agent（路径按你仓库实际位置调整）。

示例：Binance 账户 → 子代理端口 15200（Flask 的 APP_PORT 可为 5000、5001 等，由该目录 .env 决定，二者不同即可）

cd D:\你的路径\交易复盘系统\crypto_monitor_binance
.\.venv\Scripts\Activate.ps1   # 若策略项目使用独立 venv，可在此激活
# 确保已加载 .env（若你用 dotenv-cli 等工具，在此执行）
$env:EXCHANGE="binance"
$env:PORT="15200"
$env:HOST="127.0.0.1"
python ..\manual_trading_hub\agent.py

OKX → 子代理 PORT=15201、EXCHANGE=okx；Gate → 15202、Gate-Bot → 15203，EXCHANGE=gate。

可选安全：各 agent 与中控制台设置相同随机串：

$env:CONTROL_TOKEN="你的长随机串"

子代理与中控均需设置同一 CONTROL_TOKEN。

步骤 3：启动中控

新开终端：

cd D:\你的路径\交易复盘系统\manual_trading_hub
.\.venv\Scripts\Activate.ps1
$env:HUB_HOST="0.0.0.0"
$env:HUB_PORT="5100"
# 若暂不使用 OKX，可在服务端固定关闭 id=1：
# $env:HUB_DISABLED_IDS="1"
python hub.py

控制台无报错即表示监听成功（日志级别为 warning，默认不刷屏）。

步骤 4：浏览器验收

1. 打开 http://127.0.0.1:5100/ 或 http://本机局域网IP:5100/ 。
2. 应看到与 HUB_AGENTS 配置一致的账户卡片；已启动子代理的行应能显示余额或持仓（无持仓则显示「无持仓」）。
3. 点击 立即刷新，数据应更新。
4. 取消某一行的 「参与监控」，该行应变灰且不再刷新数据；再勾选应恢复。

不建议在生产环境对实盘轻易点击「全平」做测试；若必须测试，请使用测试网或小资金账户。

---

六、接口验收（可选）

在已启动 hub 的本机 PowerShell：

Invoke-RestMethod "http://127.0.0.1:5100/api/agents"
Invoke-RestMethod "http://127.0.0.1:5100/api/snapshot"

子代理单测（需 agent 已启动）：

Invoke-RestMethod "http://127.0.0.1:15200/health"
Invoke-RestMethod "http://127.0.0.1:15200/status"

若启用了 CONTROL_TOKEN，需加请求头（PowerShell 示例）：

$h = @{ "X-Control-Token" = "你的长随机串" }
Invoke-RestMethod "http://127.0.0.1:15200/status" -Headers $h

---

七、自定义端口与账户数量

仅部署 3 个账户时，可只启动 3 个 agent，并设置：

$env:HUB_AGENTS="http://127.0.0.1:15200,http://127.0.0.1:15202,http://127.0.0.1:15203"
$env:HUB_AGENT_NAMES="Binance,Gate,Gate-Bot"

HUB_AGENT_NAMES 与 URL 数量、顺序一一对应。

---

八、常驻运行（可选）

不必一直开着终端。 Ubuntu 下可用 tmux 脱离、nohup &、或 systemd（推荐：崩溃自启、可开机启动）。

详细命令、**常见问题（screen / PySocks / 重启）**与 systemd 单元示例见：

• manual_trading_hub/scripts/后台运行-Ubuntu.md
• manual_trading_hub/scripts/example-systemd/*.service.example（改路径后复制到 /etc/systemd/system/）

Windows 可将 hub.py 与各 agent.py 写入「启动」文件夹，或使用 NSSM / 任务计划程序 在登录后启动；注意工作目录与环境变量要在任务里写全。

---

九、升级与回滚

• 升级：在仓库根目录 git pull 后，于 manual_trading_hub 重新 pip install -r requirements.txt（若依赖有变）。各策略目录 .env 不会被 pull 覆盖；若 .env.example 有新增变量，请对照模板手动补进你的 .env。
• 升级前备份（推荐）：在每个用到的 crypto_monitor_* 目录执行 cp .env .env.backup.$(date +%Y%m%d)。
• 回滚：恢复上一版本代码与依赖；配置在各策略 .env 与浏览器 localStorage，无中控数据库。

---

十、故障排查

10.1 现象速查表

现象	可能原因	处理
页面打不开	中控未启动或端口错	检查 HUB_PORT、防火墙、是否用 127.0.0.1 访问
某账户一直报错	子代理未启动或端口不一致	核对 HUB_AGENTS 与该 agent 的 PORT
中控 JSON 报错 / Expecting value	子代理未启动、返回非 JSON、或端口错	本机 curl http://127.0.0.1:1520x/status；确认 agent 已起且端口与 HUB_AGENTS 一致
401 / 连不上子代理	CONTROL_TOKEN 不一致	中控与子代理设为同一令牌，或全部去掉令牌
有密钥仍报缺密钥	启动 agent 时未加载策略目录的 .env	在对应目录启动，或手动 export 全部密钥变量
/status 里 ok:false，文案含 pysocks / SOCKS	使用 SOCKS 代理但未装 PySocks	在 manual_trading_hub/.venv 执行 pip install PySocks 或 pip install -r requirements.txt
已安装 PySocks，/status 仍报同样 pysocks 文案	子代理进程未重启	子代理是常驻进程，仅 pip 不会替换已运行进程；退出对应 screen / systemd 单元后重新拉起（Ubuntu 见 scripts/后台运行-Ubuntu.md §四）
跑 start_agents_3screen.sh 无新会话	screen 会话已存在被脚本跳过	先 stop_agents_3screen.sh，或 screen -S mt-agent-xxx -X quit 后再启动
子代理行为异常、依赖已装仍报错	实际用的不是 hub 的 venv	ps aux 查看命令行，应为 /opt/crypto_monitor/manual_trading_hub/.venv/bin/python …/manual_trading_hub/agent.py（路径按你机器实际根目录调整）；否则在当前使用的解释器对应环境中装依赖，或改用官方脚本启动
子代理端口与 Flask 抢端口	PORT 与策略目录 .env 的 APP_PORT 相同	子代理用 15200～15203（或自改），Flask 继续用 APP_PORT，二者勿重复
全平失败	持仓模式、精度、交易所维护	看返回 JSON 中 errors 字段；对照交易所 App

10.2 依赖或代码更新后

• pip install -r requirements.txt 或单独 pip install 之后：须重启受影响的 hub、各子代理 进程，变更才会生效。
• 拉取新版本代码后：同样重启进程；若曾遇 'function' object has no attribute load_markets' 等旧版 agent 异常，升级后重启子代理即可。

---

十一、安全清单（部署前自检）

• 若机器暴露在公网，已用防火墙限制 HUB_PORT 或已改为 HUB_HOST=127.0.0.1 / HUB_TRUST_LAN=0 仅本机。
• API Key 权限最小化；生产环境建议启用 IP 白名单。
• CONTROL_TOKEN 已设为足够长的随机串（若启用）。
• 已告知实际操作人员：全局全平不可撤销。

---

十二、与说明文档的关系

• 《README.md》：产品能力、架构、环境变量表、API 简表、常见问题。
• 《部署文档.md》：按步骤安装、启动、验收与运维注意（本文）。

两处如有端口/变量不一致，以当前代码与 README 中的表格为准。