crypto_monitor/manual_trading_hub/部署文档.md

# 多账户交易中控 — 部署文档（含 PM2）

本文档说明在 **Ubuntu / Linux** 上部署 **manual_trading_hub**（监控区、下单区、系统设置）的推荐步骤。功能与界面操作见 **《使用说明.md》**；环境变量说明见 **`.env.example`** 与各 `crypto_monitor_*` 的 `.env.example`。

---

## 一、部署目标

| 组件 | 作用 | 默认监听 |
|------|------|----------|
| **hub.py** | 中控 Web + API | `0.0.0.0:5100` |
| **agent.py × N** | 各账户持仓 / 紧急全平 | `127.0.0.1:15200`～`15203` |
| **crypto_monitor_*.app** | 策略、关键位、下单逻辑 | 各目录 `.env` 的 `APP_PORT` |

- 账户列表与 URL 由 **`hub_settings.json`**（网页「系统设置」保存）或内置默认维护；**不再使用** `HUB_AGENTS`。
- 四实例 Flask **无需为中控改业务代码**（已注册 `hub_bridge`）；与中控并行运行。

---

## 二、前置条件

1. **Python 3.10+**、`python3-venv`、`pip`。
2. **Node.js + npm**（用于安装 PM2）：`sudo npm i -g pm2`。
3. 各 `crypto_monitor_*` 目录已 **`cp .env.example .env`** 并填好 API 密钥。
4. 端口无冲突：`5100`、`15200`～`15203`、各实例 `APP_PORT`（5000/5001/5002/5004）。
5. 建议代码路径：`/opt/crypto_monitor/`（下文用此示例，请按实际路径替换）。

---

## 三、安装中控依赖

```bash
cd /opt/crypto_monitor/manual_trading_hub
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
# 编辑 .env：HUB_PORT、HUB_DISABLED_IDS、公网时 HUB_BRIDGE_TOKEN 等
chmod +x scripts/run_hub.sh scripts/pm2_hub.sh scripts/pm2_agents.sh
```

子代理也使用 **本目录 `.venv`** 里的 Python（与各策略 Flask 的 venv 可分开）。

---

## 四、推荐启动顺序

```
1. 子代理 agent（15200～15203）  ← PM2 或 screen
2. 各实例 Flask（APP_PORT）      ← 各目录 ecosystem.config.cjs
3. 中控 hub（5100）              ← 本目录 ecosystem.config.cjs
```

仅反代中控到公网时：Flask / agent 仍只监听 **127.0.0.1**；系统设置里 URL 填 `http://127.0.0.1:端口`。

---

## 五、PM2 托管中控（推荐）

### 5.1 进程名与文件

| 文件 | PM2 进程名 | 说明 |
|------|------------|------|
| `ecosystem.config.cjs` | `manual-trading-hub` | 仅中控 |
| `ecosystem.agents.config.cjs` | `manual-agent-binance` 等 4 个 | 可选，子代理 |

`run_hub.sh` 会加载 **`manual_trading_hub/.env`** 再执行 `hub.py`。

### 5.2 启动中控

```bash
cd /opt/crypto_monitor/manual_trading_hub

# 方式 A：直接 PM2
pm2 start ecosystem.config.cjs
pm2 save

# 方式 B：快捷脚本
bash scripts/pm2_hub.sh start
```

### 5.3 常用运维命令

```bash
pm2 status
pm2 logs manual-trading-hub --lines 200
pm2 restart manual-trading-hub
pm2 stop manual-trading-hub

# 或
bash scripts/pm2_hub.sh status
bash scripts/pm2_hub.sh logs
bash scripts/pm2_hub.sh restart
```

### 5.4 开机自启

```bash
pm2 save
pm2 startup
# 按终端提示执行一行 sudo 命令后，再 pm2 save
```

### 5.5 可选：PM2 托管四路子代理

```bash
cd /opt/crypto_monitor/manual_trading_hub
pm2 start ecosystem.agents.config.cjs
# 仅币安：
# pm2 start ecosystem.agents.config.cjs --only manual-agent-binance

bash scripts/pm2_agents.sh start   # 等价启动全部
pm2 save
```

| 进程名 | 工作目录 | PORT |
|--------|----------|------|
| manual-agent-binance | crypto_monitor_binance | 15200 |
| manual-agent-okx | crypto_monitor_okx | 15201 |
| manual-agent-gate | crypto_monitor_gate | 15202 |
| manual-agent-gate-bot | crypto_monitor_gate_bot | 15203 |

OKX 默认被 `HUB_DISABLED_IDS=1` 关闭监控，但子代理仍可启动备用。

### 5.6 与各实例 Flask 一起查看

```bash
pm2 status
# 示例同时存在：
# manual-trading-hub
# manual-agent-binance
# crypto_binance          （各目录自有 ecosystem.config.cjs）
```

---

## 六、手动启动（不用 PM2 时）

### 6.1 子代理（每账户一个终端或 screen）

```bash
cd /opt/crypto_monitor/crypto_monitor_binance
export EXCHANGE=binance PORT=15200 HOST=127.0.0.1
/opt/crypto_monitor/manual_trading_hub/.venv/bin/python \
  /opt/crypto_monitor/manual_trading_hub/agent.py
```

其余端口见上表；也可用 `scripts/start_agents_3screen.sh`（不含 OKX）。

### 6.2 中控

```bash
cd /opt/crypto_monitor/manual_trading_hub
bash scripts/run_hub.sh
# 或
bash scripts/start_hub_screen.sh   # screen 会话 mt-hub
```

---

## 七、浏览器验收

1. 打开 **http://127.0.0.1:5100/monitor**（局域网用本机私网 IP）。
2. 已启用账户应显示持仓；Flask 已起时有关键位/趋势信息。
3. **http://127.0.0.1:5100/settings** 保存后生成 `hub_settings.json`。
4. **http://127.0.0.1:5100/trade** 选账户测试下单（实盘慎用）。

接口探测：

```bash
curl -s http://127.0.0.1:5100/api/settings | head
curl -s http://127.0.0.1:15200/health
```

---

## 八、仅反代中控到公网（实例不反代）

1. Nginx/Caddy 反代到 **`127.0.0.1:5100`**，配置 HTTPS。
2. `hub_settings.json` 中 Flask/Agent 保持 **`http://127.0.0.1:...`**。
3. 四实例 **`APP_AUTH_DISABLED=false`** + 与中控相同 **`HUB_BRIDGE_TOKEN`**（见 `.env.example` 注释）。
4. 子代理 **`HOST=127.0.0.1`**，防火墙勿放行 `15200`～`15203`、各 `APP_PORT`。
5. 监控页「复盘」链到本机 Flask，公网浏览器通常打不开，需 VPN/内网访问实例。

---

## 九、环境变量（中控 `.env`）

| 变量 | 默认 | 说明 |
|------|------|------|
| `HUB_HOST` | `0.0.0.0` | 监听地址 |
| `HUB_PORT` | `5100` | 端口 |
| `HUB_DISABLED_IDS` | `1` | 强制关闭的账户 id（OKX） |
| `HUB_TRUST_LAN` | `true` | 私网可访问；仅本机可 `false` |
| `HUB_BRIDGE_TOKEN` | 空 | 公网/开登录时建议配置 |

本地联调、实例 `APP_AUTH_DISABLED=true` 时可不配 `HUB_BRIDGE_TOKEN`。

---

## 十、升级与回滚

```bash
cd /opt/crypto_monitor
git pull
cd manual_trading_hub
.venv/bin/pip install -r requirements.txt
pm2 restart manual-trading-hub
# 若改了 agent 依赖：
pm2 restart manual-agent-binance manual-agent-okx manual-agent-gate manual-agent-gate-bot
```

- **`hub_settings.json`**、**`.env`** 不在 Git 中，`git pull` 不会覆盖。
- 升级前可备份：`cp hub_settings.json hub_settings.json.bak`。

---

## 十一、故障排查

| 现象 | 处理 |
|------|------|
| PM2 启动后立刻退出 | `pm2 logs manual-trading-hub`；检查 `.venv`、`.env`、`run_hub.sh` 可执行 |
| 监控无持仓 | 子代理未起或 Agent URL 错；`curl http://127.0.0.1:15200/status` |
| 无关键位/下单 401 | Flask 未起或 `HUB_BRIDGE_TOKEN` 不一致；或设 `APP_AUTH_DISABLED=true` |
| 子代理 SOCKS 报错 | 在 **manual_trading_hub/.venv** 安装 `PySocks` 后 **pm2 restart** 子代理 |
| 公网访问中控 403 | 反代未指向本机、或客户端非私网且 `HUB_TRUST_LAN=true`；反代改 `127.0.0.1:5100` 或在反代层鉴权 |
| 改 `.env` 不生效 | PM2 需 `pm2 restart manual-trading-hub`（`run_hub.sh` 每次启动会重读 `.env`） |

---

## 十二、其它常驻方式

- **screen**：`scripts/start_hub_screen.sh` / `stop_hub_screen.sh`
- **systemd**：`scripts/example-systemd/manual-hub.service.example`（复制并改路径）

与 PM2 **二选一** 即可，避免同一端口启动两份 hub。

---

## 十三、安全清单

- [ ] 公网仅暴露反代端口，不暴露 Flask/agent 端口  
- [ ] 公网已配置 `HUB_BRIDGE_TOKEN` + 实例关闭 `APP_AUTH_DISABLED`  
- [ ] API Key 最小权限；交易所 IP 白名单  
- [ ] 已告知操作人员「全局全平」不可撤销  

---

## 十四、文档索引

| 文档 | 内容 |
|------|------|
| **使用说明.md** | 三页功能、能力矩阵、鉴权说明 |
| **README.md** | 架构速览 |
| **.env.example** | 中控环境变量模板 |
| **scripts/后台运行-Ubuntu.md** | screen / systemd 补充 |