# 多账户交易中控 — 部署文档（含 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
source .venv/bin/activate          # 激活 venv（当前终端后续 pip/python 走虚拟环境）
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/run_agent.sh scripts/pm2_hub.sh scripts/pm2_agents.sh
deactivate                         # 可选；交给 PM2 时不必保持激活
```

说明：

- **安装依赖**：`source .venv/bin/activate` 后用 `pip install` 即可；不写 `activate` 时也可用 **`.venv/bin/pip install -r requirements.txt`**（效果相同）。
- **PM2 启动**：由 `scripts/run_hub.sh` 固定调用 **`.venv/bin/python`**，**不依赖**你是否在 shell 里激活过 venv。

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

---

## 四、推荐启动顺序

```
1. 各实例 Flask（APP_PORT）      ← 各 crypto_monitor_* 目录 ecosystem.config.cjs
2. 中控 + 子代理（5100 + 15200～15203）  ← 本目录一条 PM2 命令同时启动
```

**`ecosystem.config.cjs` 会一次拉起 4 个 agent + 1 个 hub**，无需再单独 `pm2 start` 子代理。

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

---

## 五、PM2 托管（hub + agent 一起启动，推荐）

### 5.1 一条命令启动全部

| 文件 | 包含进程 |
|------|----------|
| `ecosystem.config.cjs` | `manual-agent-binance` / `okx` / `gate` / `gate-bot` + **`manual-trading-hub`** |

`run_hub.sh` 加载 **`manual_trading_hub/.env`** 后执行 `hub.py`；各 agent 经 **`run_agent.sh`** 在对应策略目录加载 **`.env`**（含 API 密钥），再执行 `agent.py`。

```bash
cd /opt/crypto_monitor/manual_trading_hub
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

pm2 start ecosystem.config.cjs    # 5 个进程一起起
pm2 save

# 或
bash scripts/pm2_hub.sh start
```

### 5.2 PM2 进程一览

| 进程名 | 工作目录 | 端口/说明 |
|--------|----------|-----------|
| manual-agent-binance | crypto_monitor_binance | agent `15200` |
| manual-agent-okx | crypto_monitor_okx | agent `15201` |
| manual-agent-gate | crypto_monitor_gate | agent `15202` |
| manual-agent-gate-bot | crypto_monitor_gate_bot | agent `15203` |
| manual-trading-hub | manual_trading_hub | hub `5100` |

OKX 子代理会启动，但中控默认 `HUB_DISABLED_IDS=1` 不参与监控；不用 OKX 可 `pm2 stop manual-agent-okx`。

### 5.3 常用运维命令

```bash
pm2 status
pm2 logs manual-trading-hub --lines 200
pm2 restart ecosystem.config.cjs     # 重启 hub + 全部 agent

bash scripts/pm2_hub.sh restart      # 同上
bash scripts/pm2_hub.sh stop
bash scripts/pm2_hub.sh logs
```

仅重启中控、不动 agent：

```bash
pm2 restart manual-trading-hub
```

仅重启子代理：

```bash
pm2 restart manual-agent-binance manual-agent-gate manual-agent-gate-bot
# 或
bash scripts/pm2_agents.sh restart
```

### 5.4 开机自启

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

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

```bash
pm2 status
# 示例同时存在：
# manual-trading-hub、manual-agent-*
# crypto_binance / crypto_gate …（各策略目录自有 ecosystem.config.cjs）
```

---

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

需**分别**起 agent 与 hub（与 PM2 合并启动不同）：

```bash
# 子代理：scripts/start_agents_3screen.sh 或每目录手动 agent.py
# 中控：
cd /opt/crypto_monitor/manual_trading_hub
bash scripts/run_hub.sh
```

---

## 七、浏览器验收

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 ecosystem.config.cjs
```

- **`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` 可执行 |
| 余额显示 —、无报错 | 子代理未加载策略目录 `.env`（旧版 PM2 直接跑 agent.py） | 更新代码后 `pm2 restart ecosystem.config.cjs`；`curl http://127.0.0.1:15200/status` 应 `ok:true` 且有 `balance_usdt` |
| PM2 里 agent **stopped**（hub 仍 online） | 启动失败：端口占用、无 `.env`/密钥、`run_agent.sh` 无执行权限、venv 缺失 | `pm2 logs manual-agent-binance --lines 80`；`chmod +x scripts/run_agent.sh`；`ss -tlnp \| grep 15200` |
| 监控无持仓 | 子代理未起或 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 补充 |