dekun/crypto_monitor
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(hub): 同步中控文档与故障实录

Browse Source 
更新使用说明、部署文档与 README，反映已移除下单区、Web 登录与 PM2 验收流程；新增常见问题.md 整理部署排障。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
dekun
2026-05-22 12:32:08 +08:00
parent 16b10e123e
commit 1ec1415e2b
7 changed files with 470 additions and 228 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+7 -5
View File
@@ -28,7 +28,7 @@ cd crypto_monitor
| `crypto_monitor_gate/` | Gate.io 永续（主号） | [部署文档.md](./crypto_monitor_gate/部署文档.md) | | `crypto_monitor_gate/` | Gate.io 永续（主号） | [部署文档.md](./crypto_monitor_gate/部署文档.md) |
| `crypto_monitor_gate_bot/` | Gate.io 永续（机器人；含趋势回调等） | [部署文档.md](./crypto_monitor_gate_bot/部署文档.md) · [趋势回调策略说明.md](./crypto_monitor_gate_bot/趋势回调策略说明.md) | | `crypto_monitor_gate_bot/` | Gate.io 永续（机器人；含趋势回调等） | [部署文档.md](./crypto_monitor_gate_bot/部署文档.md) · [趋势回调策略说明.md](./crypto_monitor_gate_bot/趋势回调策略说明.md) |
| `crypto_monitor_okx/` | OKX 永续 | [部署文档.md](./crypto_monitor_okx/部署文档.md) | | `crypto_monitor_okx/` | OKX 永续 | [部署文档.md](./crypto_monitor_okx/部署文档.md) |
| `manual_trading_hub/` | 多账户中控（监控 + 紧急全平，**不参与开仓**） | [README.md](./manual_trading_hub/README.md) · [部署文档.md](./manual_trading_hub/部署文档.md) · [scripts/后台运行-Ubuntu.md](./manual_trading_hub/scripts/后台运行-Ubuntu.md) | | `manual_trading_hub/` | 多账户中控（监控 + 紧急全平 + 登录；**不在中控网页下单**） | [README.md](./manual_trading_hub/README.md) · [使用说明.md](./manual_trading_hub/使用说明.md) · [部署文档.md](./manual_trading_hub/部署文档.md) · [常见问题.md](./manual_trading_hub/常见问题.md) |
前四列为四个 **`crypto_monitor_*`** 交易/监控应用；`manual_trading_hub` 与四者 **进程独立**，无需改四者代码即可并行使用。 前四列为四个 **`crypto_monitor_*`** 交易/监控应用；`manual_trading_hub` 与四者 **进程独立**，无需改四者代码即可并行使用。
@@ -65,9 +65,11 @@ cd crypto_monitor
## 四、与 `manual_trading_hub` 的关系（可选） ## 四、与 `manual_trading_hub` 的关系（可选）
- **中控** `hub.py`：汇总各子代理状态，提供网页与 HTTP API。 - **中控** `hub.py`（`:5100`）：多账户 **监控聚合**、**紧急全平**、系统设置；可选 **用户名+密码** 登录（反代公网时务必配置）。
- **子代理** `agent.py`：每个进程绑定一个交易所账户，默认监听 **`15200`～`15203`**，与四个 Flask 应用的 **`APP_PORT`**（如 5000、5001）**必须错开**。 - **子代理** `agent.py`：每账户一进程，默认 **`15200`～`15203`**，与四所 Flask **`APP_PORT`**（5000/5001/5002/5004）**必须错开**。
- 详细端口、`EXCHANGE`、`HUB_AGENTS` 等见 [manual_trading_hub/README.md](./manual_trading_hub/README.md)。 - **下单、关键位、趋势、复盘**：在各 `crypto_monitor_*` 原网页操作（中控监控卡片 **「实例」** / **「复盘」**）；中控**已移除下单区**。
- 账户列表由 **`hub_settings.json`**（网页「系统设置」）维护，**不再使用** `HUB_AGENTS`。
- 部署与排障：[manual_trading_hub/README.md](./manual_trading_hub/README.md)、[常见问题.md](./manual_trading_hub/常见问题.md)。
--- ---
@@ -103,7 +105,7 @@ cd crypto_monitor
3. 阅读该目录下的 **《部署文档.md》**（Ubuntu / PM2 / 代理 / 升级说明）。 3. 阅读该目录下的 **《部署文档.md》**（Ubuntu / PM2 / 代理 / 升级说明）。
4. 服务器部署完成后，按 **[备份与恢复.md](./备份与恢复.md)** 配置自动备份与 `.env` 备份习惯。 4. 服务器部署完成后，按 **[备份与恢复.md](./备份与恢复.md)** 配置自动备份与 `.env` 备份习惯。
5. 需要 **Gate 趋势回调** 规则时，阅读 [crypto_monitor_gate_bot/趋势回调策略说明.md](./crypto_monitor_gate_bot/趋势回调策略说明.md)。 5. 需要 **Gate 趋势回调** 规则时，阅读 [crypto_monitor_gate_bot/趋势回调策略说明.md](./crypto_monitor_gate_bot/趋势回调策略说明.md)。
6. 需要 **多账户一块看 + 紧急全平** 时，阅读 [manual_trading_hub](./manual_trading_hub/) 下 README 与部署文档。 6. 需要 **多账户一块看 + 紧急全平** 时，阅读 [manual_trading_hub](./manual_trading_hub/) 下 [使用说明](./manual_trading_hub/使用说明.md)、[部署文档](./manual_trading_hub/部署文档.md)；遇问题先查 [常见问题](./manual_trading_hub/常见问题.md)。
--- ---
deploy/README.md
+1
View File
@@ -83,6 +83,7 @@ bash deploy/setup_env.sh
``` ```
3. 服务器长期运行见各目录 **《部署文档.md》**（SSH SOCKS、PM2）。 3. 服务器长期运行见各目录 **《部署文档.md》**（SSH SOCKS、PM2）。
4. **多账户中控**（`manual_trading_hub`）：编辑 `manual_trading_hub/.env`（`HUB_PASSWORD`、`HUB_BRIDGE_TOKEN` 等与四实例一致），再 `pm2 start ecosystem.config.cjs`；验收 `bash manual_trading_hub/scripts/verify_hub_deploy.sh`。详见 [manual_trading_hub/部署文档.md](../manual_trading_hub/部署文档.md)、[常见问题.md](../manual_trading_hub/常见问题.md)。
## 依赖说明 ## 依赖说明
manual_trading_hub/README.md
+59 -162
View File
@@ -1,203 +1,100 @@
# 手工交易多账户中控（manual_trading_hub） # 复盘系统中控（manual_trading_hub）
> **完整操作说明见 [使用说明.md](./使用说明.md)**（监控区 / 系统设置、鉴权、四所能力与故障排查）。 > **完整说明**：[使用说明.md](./使用说明.md) · **部署**：[部署文档.md](./部署文档.md) · **故障实录**：[常见问题.md](./常见问题.md)
本目录提供多账户 **监控 + 紧急全平**。人工下单、关键位、趋势回调请在各 `crypto_monitor_*` 实例网页操作；策略与复盘仍在各实例。 多账户 **监控聚合 + 紧急全平**；**不在中控网页下单**。人工下单、关键位、趋势回调、复盘请在各 `crypto_monitor_*` 实例原网页操作（监控卡片 **「实例」** / **「复盘」** 跳转）。
--- ---
## 功能概览 ## 当前能力
| 能力 | 说明 | | 能力 | 说明 |
|------|------| |------|------|
| 监控 | 汇总各子代理的永续持仓、未实现盈亏、余额（USDT）、持仓模式等 | | 监控区 | 持仓、余额、关键位摘要、趋势计划、机器人单（只读） |
| 单账户全平 | 对某一子代理发起市价减仓，尽量平掉该所 USDT 永续仓位 | | 紧急全平 | 单户 / 全局市价减仓 |
| 全局全平 | 对当前「已开启监控」的子代理依次发起全平 | | 系统设置 | `hub_settings.json` 管理四所 URL、启用状态、监控能力 |
| 关闭某账户 | 网页上取消「参与监控」，或环境变量 `HUB_DISABLED_IDS`；被关闭的不轮询、不参与全局全平 | | Web 登录 | `.env` 设 `HUB_PASSWORD` 后用户名+密码保护（反代公网**务必**配置） |
| ~~下单区~~ | **已移除**（避免与实例重复、减少故障面） |
--- ---
## 架构说明 ## 架构
``` ```
浏览器 → 中控 hub.py（默认监听 0.0.0.0:5100，私网可访问；本机仍可用 127.0.0.1） 浏览器 → hub.py (:5100) 监控 / 设置 / 登录
↓ HTTP ├→ agent.py × N (:15200～15203) 持仓、全平
子代理 agent.py × N（默认 127.0.0.1:15200～15203，与 Flask 的 APP_PORT 错开） └→ 各 Flask (:5000/5001/5002/5004) /api/hub/monitor 只读聚合
↓ ccxt
各交易所 API
``` ```
- **中控（hub）**：读配置、并行请求各子代理 `/status`；全平时转发 `POST /emergency/close-all`。 - 账户列表：**系统设置** 或默认 `settings_store.py`（不再使用环境变量 `HUB_AGENTS`）。
- **子代理（agent）**：每个进程绑定一个交易所 API Key，只做只读状态 + 紧急平仓；与 `crypto_monitor_*` 里的 Flask **独立进程**，互不影响日常手工/策略操作。 - 四实例须注册 **hub_bridge**（仓库根 `hub_bridge.py`）；PM2 建议 `PYTHONPATH=..`。
### 与四个 `crypto_monitor_*` 目录的关系（已对照 `app.py`）
各策略项目在**本目录**用 **`.env`**（由 **`cp .env.example .env`** 生成，勿提交 Git；`git pull` 不覆盖）加载配置（`load_env_file`），并用其中的 **`APP_HOST` / `APP_PORT`** 启动 **Flask 网页**（`app.py` 里 `HOST`、`PORT`）。这是你在浏览器里打开策略/监控后台用的端口，例如 `APP_PORT=5001`。
子代理 **不用 `APP_PORT`**，而是用环境变量 **`PORT`**（FastAPI/uvicorn 监听）。若子代理与 Flask 抢同一端口，后启动的会起不来，因此中控默认把子代理配在 **`15200`～`15203`**，与常见 `5000` 段 Flask 配置**错开**。
| 子代理 `PORT`（建议） | 对应策略目录 | `EXCHANGE` |
|----------------------|--------------|------------|
| 15200 | `crypto_monitor_binance` | `binance` |
| 15201 | `crypto_monitor_okx` | `okx` |
| 15202 | `crypto_monitor_gate` | `gate` |
| 15203 | `crypto_monitor_gate_bot` | `gate` |
Flask 仍可继续用 `APP_HOST=0.0.0.0` 方便云服务器外网访问；**子代理**建议 **`HOST=127.0.0.1`**。中控默认 `HUB_HOST=0.0.0.0` 便于局域网打开页面；若只给自己用，设 `HUB_HOST=127.0.0.1` 或 `HUB_TRUST_LAN=0`。
--- ---
## 依赖 ## 快速启动（Linux / PM2）
- Python 3.10+（与仓库其他项目相近即可）
- 见 `requirements.txt`：`fastapi`、`uvicorn`、`httpx`、`ccxt`
安装：
```bash ```bash
cd manual_trading_hub cd /opt/crypto_monitor/manual_trading_hub
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt pip install -r requirements.txt
cp .env.example .env
# 编辑 .env：HUB_PASSWORD、HUB_BRIDGE_TOKEN、HUB_PUBLIC_ORIGIN 等
pm2 start ecosystem.config.cjs # 4 agent + hub
pm2 save
bash scripts/verify_hub_deploy.sh
curl -s http://127.0.0.1:5100/api/ping
``` ```
建议使用独立虚拟环境，避免与全局包冲突。 浏览器：`http://<本机IP>:5100/monitor`（已设密码则先 `/login`）。
--- ---
## 快速启动（本机） ## 中控 `.env` 要点
### 1. 启动子代理（每个账户一个终端） | 变量 | 说明 |
|------|------|
| `HUB_PASSWORD` / `HUB_USERNAME` | 非空密码即启用登录 |
| `HUB_BRIDGE_TOKEN` | 与四实例一致 |
| `HUB_DISABLED_IDS` | 默认 `1` 关闭 OKX |
| `HUB_PUBLIC_ORIGIN` | 其它设备打开复盘/实例外链（替换 127.0.0.1） |
| `HUB_COOKIE_SECURE` | HTTPS 反代建议 `true` |
在**对应策略目录**下加载该目录已有 `.env`（含 API 密钥与可选代理），再启动 agent，避免密钥分散维护两套。 详见 [.env.example](./.env.example)。
**Binance（子代理端口 15200，与 Flask APP_PORT 无关）**
```powershell
cd ..\crypto_monitor_binance
$env:EXCHANGE="binance"
$env:PORT="15200"
$env:HOST="127.0.0.1"
python ..\manual_trading_hub\agent.py
```
**OKX（15201）**
```powershell
cd ..\crypto_monitor_okx
$env:EXCHANGE="okx"
$env:PORT="15201"
python ..\manual_trading_hub\agent.py
```
**Gate / Gate-Bot（15202 / 15203）**
```powershell
$env:EXCHANGE="gate"
$env:PORT="15202" # Gate-Bot 用 15203
python ..\manual_trading_hub\agent.py
```
### 2. 启动中控
```powershell
cd manual_trading_hub
$env:HUB_HOST="0.0.0.0"
$env:HUB_PORT="5100"
# 可选：自定义各账户卡片标题（顺序与默认 HUB_AGENTS 一致：15200→15201→15202→15203）
# $env:HUB_AGENT_NAMES="币安主号,OKX,Gate主号,Gate机器人"
python hub.py
```
浏览器打开：**http://127.0.0.1:5100/** 或 **http://本机局域网IP:5100/**
--- ---
## 子代理（agent）环境变量 ## 子代理（agent）
| 变量 | 含义 | 默认 | 每所策略目录单独进程，`EXCHANGE` + `PORT`（15200～15203），密钥来自**该目录 `.env`**。PM2 经 `scripts/run_agent.sh` 启动（自动 `source .env`、去 CRLF）。
|------|------|------|
| `EXCHANGE` | `binance` / `okx` / `gate` | `binance` |
| `HOST` | 监听地址 | `127.0.0.1` |
| `PORT` | 子代理监听端口（勿与 Flask 的 `APP_PORT` 相同） | `15200` |
| `CONTROL_TOKEN` | 若设置，请求须带头 `X-Control-Token` | 空 |
**Binance**：`BINANCE_API_KEY`、`BINANCE_API_SECRET`；可选 `BINANCE_POSITION_MODE`（`hedge`/`oneway`）、`BINANCE_MARGIN_MODE`；代理 `BINANCE_SOCKS_PROXY` 或 `BINANCE_HTTP_PROXY` / `HTTPS_PROXY`。`/status` 的 `balance_usdt` 为 **U 本位永续合约**账户 USDT（与 `crypto_monitor_binance` 合约口径一致，非现货钱包）。 | PORT | 目录 |
|------|------|
**OKX**：`OKX_API_KEY`、`OKX_API_SECRET`、`OKX_API_PASSPHRASE`；可选 `OKX_TD_MODE`、`OKX_POS_MODE`；代理 `OKX_SOCKS_PROXY` 等。 | 15200 | crypto_monitor_binance |
| 15201 | crypto_monitor_okx |
**Gate**：`GATE_API_KEY`、`GATE_API_SECRET`；可选 `GATE_TD_MODE`、`GATE_POS_MODE`；代理 `GATE_SOCKS_PROXY` 等。 | 15202 | crypto_monitor_gate |
| 15203 | crypto_monitor_gate_bot |
--- ---
## 中控（hub）环境变量 ## 运维脚本
| 变量 | 含义 | 默认 | | 脚本 | 作用 |
|------|------|------| |------|------|
| `HUB_HOST` | 监听地址 | `0.0.0.0`（局域网可连）；`127.0.0.1` 仅本机 | | [scripts/fix_hub_deps.sh](./scripts/fix_hub_deps.sh) | 安装/更新 venv 依赖 |
| `HUB_PORT` | 监听端口 | `5100` | | [scripts/verify_hub_deploy.sh](./scripts/verify_hub_deploy.sh) | 验收代码版本与 ping |
| `HUB_AGENTS` | 子代理 base URL，逗号分隔 | `http://127.0.0.1:15200` … `15203` | | [scripts/fix_env_crlf.sh](./scripts/fix_env_crlf.sh) | 修复 .env 的 Windows 换行 |
| `HUB_AGENT_NAMES` | 与 `HUB_AGENTS` **顺序一一对应**的卡片显示名（逗号分隔）。不设则用内置默认名。改后需重启 hub，**所有访问该中控的浏览器**显示一致 | 内置与四目录对应的英文标签 | | [scripts/pm2_hub.sh](./scripts/pm2_hub.sh) | PM2 启停 hub+agent |
| `HUB_DISABLED_IDS` | 不参与监控与全局全平的账户 `id`，逗号分隔（如暂不用 OKX 写 `1`） | 空 | | [scripts/后台运行-Ubuntu.md](./scripts/后台运行-Ubuntu.md) | screen / systemd |
| `HUB_TRUST_LAN` | 默认 `true`；设为 `0`/`false`/`off` 则仅允许本机 IP 访问中控 | 开 |
| `CONTROL_TOKEN` | 与子代理一致时，中控代发 `X-Control-Token` | 空 |
--- ---
## 网页操作说明 ## 文档索引
- **立即刷新 / 自动刷新**：拉取最新汇总；自动刷新默认约 3 秒一轮（仅请求已开启监控的账户）。 | 文档 | 内容 |
- **账户显示名**：在运行 `hub.py` 的机器上设置环境变量 **`HUB_AGENT_NAMES`**（逗号分隔，顺序与 **`HUB_AGENTS`** 里每个子代理 URL 一致），重启中控后，任意电脑打开同一中控地址都会看到相同名称。名称里若含逗号，需整体用引号包裹或避免使用逗号。 |------|------|
- **参与监控**：勾选则参与轮询与「全局一键全平」；取消则本浏览器记住（`localStorage` 键 `manual_trading_hub_excluded`），不再请求该子代理。 | [使用说明.md](./使用说明.md) | 页面、API、环境变量、日常流程 |
- **该账户全平**：仅针对该子代理；与是否关闭「参与监控」无关（仍可直接调交易所紧急平仓）。 | [部署文档.md](./部署文档.md) | Ubuntu、PM2、反代、升级 |
- **全局一键全平**：只对当前「参与监控」且未被 `HUB_DISABLED_IDS` 关闭的账户发起全平；请求体中的 `exclude_ids` 与网页关闭状态一致。 | [常见问题.md](./常见问题.md) | 已遇到问题与处理 |
| [.env.example](./.env.example) | 环境变量模板 |
服务端 `HUB_DISABLED_IDS` 与浏览器关闭**取并集**：任一方关闭即不轮询、不进全局全平。
---
## HTTP API（访问控制与浏览器一致）
允许来源：**本机**或 **RFC1918 私网 IPv4**（与 `HUB_TRUST_LAN` 开启时一致）；`HUB_TRUST_LAN=0` 时仅本机。
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 中控页面 |
| GET | `/api/agents` | 当前配置的账户列表（id、name、url） |
| GET | `/api/snapshot` | 聚合状态；可选查询参数 `exclude_ids`（逗号分隔 id） |
| POST | `/api/close/{agent_id}` | 单账户紧急全平 |
| POST | `/api/close-all` | JSON 体可选 `{"exclude_ids":["1"]}`，与 `HUB_DISABLED_IDS` 合并 |
子代理：
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查 |
| GET | `/status` | 余额、持仓、盈亏汇总 |
| POST | `/emergency/close-all` | 市价尽量平掉 USDT 永续仓位，并尝试撤该合约挂单 |
---
## 安全与边界
- 中控默认 **监听 0.0.0.0** 并放行私网访问，便于局域网使用；**公网非私网 IP** 仍会被中间件拒绝。
- 若机器有公网 IP，请用 **防火墙** 限制 `HUB_PORT` 仅内网可进，或改为 `HUB_HOST=127.0.0.1` + `HUB_TRUST_LAN=0` 仅本机。
- 子代理建议仍用 **`HOST=127.0.0.1`**，不要对局域网暴露交易所密钥通道。
- 中控**不具备**开仓、改策略、划转账能力；全平为**市价减仓**，请谨慎操作。
- 子代理与主策略进程共用密钥时，注意权限与 IP 白名单仍按交易所要求配置。
---
## 常见问题
**1. 某一行一直连不上**
检查该端口上的 `agent.py` 是否已启动、防火墙是否放行本机回环、`.env` 密钥是否与交易所一致。
**2. 暂时不用 OKX**
网页取消该行的「参与监控」，或启动中控前设置 `HUB_DISABLED_IDS=1`（默认 OKX 的 id 为 `1`）。
**3. 策略项目要不要改？**
不需要改 `crypto_monitor_*` 代码；只需额外运行 `agent.py` 进程。
**5. 局域网里别的电脑打不开中控**
默认应已可访问：中控监听 `0.0.0.0` 且 `HUB_TRUST_LAN` 默认开启。请检查：防火墙是否放行 `HUB_PORT`；浏览器是否使用 **中控机器的局域网 IP**（不要用另一台电脑上的 `127.0.0.1`）。若你曾设置 `HUB_TRUST_LAN=0` 或 `HUB_HOST=127.0.0.1`，改回默认或删掉环境变量后重启 hub。
**Linux 常驻（PM2）**：`pm2 start ecosystem.config.cjs` 会**同时**启动 4 路子代理 + 中控 `manual-trading-hub`。详见 **《部署文档.md》**。
manual_trading_hub/scripts/后台运行-Ubuntu.md
+16 -6
View File
@@ -1,6 +1,9 @@
# Ubuntu 后台运行（中控 + 子代理） # Ubuntu 后台运行（中控 + 子代理）
各 `crypto_monitor_*` 策略目录：首次 **`cp .env.example .env`** 并编辑；**`.env` 不进 Git**，`git pull` 不覆盖。升级前建议 `cp .env .env.backup.$(date +%Y%m%d)`。子代理启动前须 **`source` 该目录 `.env`**（见下文）。 > **推荐生产**：用本目录 **`ecosystem.config.cjs`** + PM2 一次启动 4 agent + hub，见 [部署文档.md](../部署文档.md) §五。
> 故障实录：[常见问题.md](../常见问题.md)
各 `crypto_monitor_*` 策略目录：首次 **`cp .env.example .env`** 并编辑；**`.env` 不进 Git**，`git pull` 不覆盖。升级前建议 `cp .env .env.backup.$(date +%Y%m%d)`。子代理启动前须 **`source` 该目录 `.env`**（见下文；PM2 经 `run_agent.sh` 会自动处理）。
前台跑 `python agent.py` / `python hub.py` 时，关掉终端进程会结束。要**常驻后台**，可用下面三种之一（推荐 **systemd**）。 前台跑 `python agent.py` / `python hub.py` 时，关掉终端进程会结束。要**常驻后台**，可用下面三种之一（推荐 **systemd**）。
@@ -28,7 +31,11 @@ chmod +x manual_trading_hub/scripts/stop_hub_screen.sh
### 局域网内其他电脑访问中控 ### 局域网内其他电脑访问中控
中控 **默认** `HUB_HOST=0.0.0.0`、`HUB_TRUST_LAN=开启`，同一局域网内可用 `http://<中控机局域网IP>:5100/` 打开页面（本机仍可用 `http://127.0.0.1:5100/`）。请确保防火墙放行端口，例如：`sudo ufw allow 5100/tcp`。 中控 **默认** `HUB_HOST=0.0.0.0`、`HUB_TRUST_LAN=开启`，同一局域网内可用 `http://<中控机局域网IP>:5100/monitor` 打开（本机 `http://127.0.0.1:5100/`）。请确保防火墙放行端口，例如：`sudo ufw allow 5100/tcp`。
- 若 `.env` 设置了 **`HUB_PASSWORD`**，须先访问 `/login`（用户名见 `HUB_USERNAME`，默认 `admin`）。
- **公网** 建议只经 **HTTPS 反代** 访问，勿把 5100 直接暴露公网；详见 [部署文档.md](../部署文档.md) §八。
- 若 **域名 HTTPS 能登录、内网 IP:5100 HTTP 不能**，见 [常见问题.md](../常见问题.md) §2.1（Cookie Secure）。
若改为 **仅本机** 访问：`HUB_HOST=127.0.0.1` 或 `HUB_TRUST_LAN=0`，重启 hub。 若改为 **仅本机** 访问：`HUB_HOST=127.0.0.1` 或 `HUB_TRUST_LAN=0`，重启 hub。
@@ -171,14 +178,17 @@ ExecStart=/bin/bash -lc 'set -a; source YOUR_REPO/crypto_monitor_binance/.env; s
应看到 `…/manual_trading_hub/.venv/bin/python` 与 `…/manual_trading_hub/agent.py`。若用的是系统 `python3`，要么在**同一解释器环境**里装依赖，要么改为用 `start_agents_3screen.sh` 启动（脚本内写死 `VENV_PY`）。 应看到 `…/manual_trading_hub/.venv/bin/python` 与 `…/manual_trading_hub/agent.py`。若用的是系统 `python3`，要么在**同一解释器环境**里装依赖，要么改为用 `start_agents_3screen.sh` 启动（脚本内写死 `VENV_PY`）。
5. **中控某账户一直红 / 非 JSON** 5. **中控某账户一直红 / 非 JSON**
对应该端口的 agent 未启动，或 `HUB_AGENTS` 与 agent 的 `PORT` 不一致。本机先测： 对应该端口的 agent 未启动，或 **系统设置** 里 Agent URL 与 `PORT`（15200～15203）不一致。本机先测：
`curl -sS http://127.0.0.1:1520x/status | head -c 400` `curl -sS http://127.0.0.1:1520x/status | head -c 400`
再看 `logs/mt-agent-*.log`。 再看 `logs/mt-agent-*.log` 或 `pm2 logs manual-agent-*`。
6. **子代理端口与 Flask 冲突** 6. **PM2 日志仍见 `api_trade_key` / 添加关键位 SyntaxError**
多为旧版 hub 或未重启。`git pull` → `bash scripts/fix_hub_deps.sh` → `bash scripts/verify_hub_deploy.sh` → `pm2 restart manual-trading-hub`。中控**已移除下单区**，关键位请在监控卡片 **「实例」** 进各 Flask 操作。详见 [常见问题.md](../常见问题.md) §1。
7. **子代理端口与 Flask 冲突**
agent 使用环境变量 **`PORT`**（脚本里 15200、15202、15203）；各策略 `.env` 里的 **`APP_PORT`** 给 Flask。二者**不能**相同。 agent 使用环境变量 **`PORT`**（脚本里 15200、15202、15203）；各策略 `.env` 里的 **`APP_PORT`** 给 Flask。二者**不能**相同。
7. **systemd 下改依赖或 `.env` 后** 8. **systemd 下改依赖或 `.env` 后**
与 screen 相同：`pip install` 或改 `EnvironmentFile` 后需 **`systemctl restart <unit>`**，否则仍是旧进程。 与 screen 相同：`pip install` 或改 `EnvironmentFile` 后需 **`systemctl restart <unit>`**，否则仍是旧进程。
--- ---
manual_trading_hub/使用说明.md
+74 -23
View File
@@ -24,14 +24,14 @@
### 1.1 四账户默认配置 ### 1.1 四账户默认配置
| id | 名称 | Flask | Agent | 能力 | 默认启用 | | id | 名称 | Flask | Agent | 监控能力（设置页勾选） | 默认启用 |
|----|------|-------|-------|------|----------| |----|------|-------|-------|------------------------|----------|
| 0 | 币安 | :5001 | :15200 | 下单、关键位 | 是 | | 0 | 币安 | :5001 | :15200 | 关键位 | 是 |
| 1 | OKX | :5004 | :15201 | 下单、关键位 | **否**（`HUB_DISABLED_IDS=1`） | | 1 | OKX | :5004 | :15201 | 关键位 | **否**（`HUB_DISABLED_IDS=1`） |
| 2 | Gate 训练 | :5000 | :15202 | 下单、关键位 | 是 | | 2 | Gate 训练 | :5000 | :15202 | 关键位 | 是 |
| 3 | Gate 趋势 | :5002 | :15203 | **下单、趋势回调**（无关键位 Tab） | 是 | | 3 | Gate 趋势 | :5002 | :15203 | 趋势计划 | 是 |
- **Gate 趋势户**：保留 **人工下单** 与 **趋势回调**；监控区可看到运行中的趋势计划，但 **不展示关键位**（capabilities 无 `key`）。 - **Gate 趋势户**：监控区展示**趋势计划**；**不展示关键位**（capabilities 无 `key`）。人工下单、趋势回调、关键位均在各实例网页操作。
- **OKX**：默认关闭；需要时在「系统设置」勾选启用，并去掉环境变量 `HUB_DISABLED_IDS` 中的 `1`。 - **OKX**：默认关闭；需要时在「系统设置」勾选启用，并去掉环境变量 `HUB_DISABLED_IDS` 中的 `1`。
### 1.2 实例侧改动（最小） ### 1.2 实例侧改动（最小）
@@ -75,7 +75,25 @@ $env:HUB_DISABLED_IDS="1" # 默认即关闭 OKX（id=1）
与设置页「启用」取 **与** 关系：环境变量强制关闭时，网页勾选框会灰掉且无法启用。 与设置页「启用」取 **与** 关系：环境变量强制关闭时，网页勾选框会灰掉且无法启用。
### 2.4 配置文件 ### 2.4 Web 登录（反代公网强烈建议）
在 `manual_trading_hub/.env` 中配置：
| 变量 | 说明 |
|------|------|
| `HUB_USERNAME` | 登录用户名；未设且已设密码时默认为 `admin` |
| `HUB_PASSWORD` | **非空即启用登录**；所有页面与 API（除登录页、`/api/ping`、`/assets`）须先登录 |
| `HUB_SESSION_SECRET` | 会话签名密钥（建议单独随机串） |
| `HUB_COOKIE_SECURE` | 建议 `true`：仅 **HTTPS** 访问时 Cookie 带 Secure；**HTTP 内网 IP:5100 仍可登录** |
| `HUB_SESSION_DAYS` | 登录保持天数，默认 `7` |
- 登录页：`http://<中控地址>:5100/login`
- 顶栏 **退出** 清除会话。
- **域名（HTTPS）** 与 **内网 IP（HTTP）** Cookie 不共用，需分别登录一次。
更多登录/Cookie 问题见 **[常见问题.md](./常见问题.md)** 第二节。
### 2.5 配置文件
- 路径：`manual_trading_hub/hub_settings.json`（在网页 **系统设置 → 保存设置** 后写入）。 - 路径：`manual_trading_hub/hub_settings.json`（在网页 **系统设置 → 保存设置** 后写入）。
- 未保存前使用 `settings_store.py` 内置默认四所地址。 - 未保存前使用 `settings_store.py` 内置默认四所地址。
@@ -139,7 +157,15 @@ python hub.py
- 监控区：http://127.0.0.1:5100/monitor - 监控区：http://127.0.0.1:5100/monitor
- 系统设置：http://127.0.0.1:5100/settings - 系统设置：http://127.0.0.1:5100/settings
- （旧链接 `/trade` 会自动跳转到监控区） - 登录页：http://127.0.0.1:5100/login（已设 `HUB_PASSWORD` 时）
- 旧链接 `/trade` 会自动跳转到 `/monitor`
验收（无需登录）：
```bash
curl -s http://127.0.0.1:5100/api/ping
# 应含 "build":"20260521-no-trade-ui", "trade_ui":false
```
--- ---
@@ -153,8 +179,8 @@ python hub.py
| **机器人持仓** | 来自实例 `/api/hub/monitor` 的 `order_monitors`（active） | | **机器人持仓** | 来自实例 `/api/hub/monitor` 的 `order_monitors`（active） |
| **关键位** | 仅 `capabilities` 含 `key` 的户；展示门控摘要（`/api/price_snapshot`） | | **关键位** | 仅 `capabilities` 含 `key` 的户；展示门控摘要（`/api/price_snapshot`） |
| **趋势计划** | 仅 Gate 趋势户；`trend_pullback_plans` active | | **趋势计划** | 仅 Gate 趋势户；`trend_pullback_plans` active |
| **实例 / 复盘** | 「实例」打开该户 Flask 首页；「复盘」打开 `/records`。**中控不做下单与复盘编辑**。若配置 **`HUB_PUBLIC_ORIGIN`**，外链会把 `127.0.0.1` 换成内网 IP | | **实例 / 复盘** | 「实例」→ 该户 Flask（**下单、关键位、趋势**均在此操作）；「复盘」→ `/records`。若配置 **`HUB_PUBLIC_ORIGIN`**，外链替换 `127.0.0.1` |
| **关键位** | 来自实例 `/api/hub/monitor` + `/api/price_snapshot`（须 Flask 已启动）；无记录或 Flask 未连通时卡片会提示原因；**Gate 趋势户**无关键位 | | **关键位列表** | 来自 `/api/hub/monitor` + `/api/price_snapshot`；Flask 未连通时卡片提示原因；**Gate 趋势户**无关键位块 |
| **该户全平** | `POST` 子代理 `/emergency/close-all`，仅平该 API Key 仓位 | | **该户全平** | `POST` 子代理 `/emergency/close-all`，仅平该 API Key 仓位 |
| **全局紧急全平** | 对所有已启用户依次全平（不含 `HUB_DISABLED_IDS` 强制关闭的 id） | | **全局紧急全平** | 对所有已启用户依次全平（不含 `HUB_DISABLED_IDS` 强制关闭的 id） |
| **自动刷新** | 默认每 5 秒请求 `/api/monitor/board` | | **自动刷新** | 默认每 5 秒请求 `/api/monitor/board` |
@@ -211,8 +237,11 @@ python hub.py
| GET | `/api/auth/status` | 是否需登录、是否已登录 | | GET | `/api/auth/status` | 是否需登录、是否已登录 |
| POST | `/api/auth/login` | body `{"username":"...","password":"..."}` | | POST | `/api/auth/login` | body `{"username":"...","password":"..."}` |
| POST | `/api/auth/logout` | 退出 | | POST | `/api/auth/logout` | 退出 |
| GET | `/api/ping` | 版本与健康检查（**免登录**） |
实例侧（中控只读调用 `/api/hub/monitor` 等；下单请在实例网页）： 已移除的 `/api/trade/*` 若被旧缓存页面请求，返回 **410** 并提示前往各实例网页。
实例侧（中控只读；下单/关键位/趋势在实例网页）：
| 路径 | 说明 | | 路径 | 说明 |
|------|------| |------|------|
@@ -235,7 +264,7 @@ python hub.py
| `HUB_USERNAME` | `admin` | 登录用户名（仅当已设密码时生效） | | `HUB_USERNAME` | `admin` | 登录用户名（仅当已设密码时生效） |
| `HUB_PASSWORD` | （空） | 非空即启用 Web 登录 | | `HUB_PASSWORD` | （空） | 非空即启用 Web 登录 |
| `HUB_SESSION_SECRET` | 用户名+密码 | 会话 Cookie 签名密钥 | | `HUB_SESSION_SECRET` | 用户名+密码 | 会话 Cookie 签名密钥 |
| `HUB_COOKIE_SECURE` | `false` | HTTPS 反代时设 `true` | | `HUB_COOKIE_SECURE` | `false` | HTTPS 反代建议 `true`（仅 HTTPS 发 Secure Cookie，HTTP 内网 IP 仍可登） |
| `HUB_SESSION_DAYS` | `7` | 登录保持天数 | | `HUB_SESSION_DAYS` | `7` | 登录保持天数 |
### 子代理 agent.py ### 子代理 agent.py
@@ -266,19 +295,28 @@ python hub.py
--- ---
## 9. 故障排查 ## 9. 故障排查（速查）
完整实录（含 `api_trade_key`、`multipart`、git 版本、PM2 等）见 **[常见问题.md](./常见问题.md)**。
| 现象 | 可能原因 | 处理 | | 现象 | 可能原因 | 处理 |
|------|----------|------| |------|----------|------|
| 监控卡片「子代理不可用」 | agent 未启动或端口错 | 检查 Agent URL、启动 agent | | 监控卡片「子代理不可用」 | agent 未启动或端口错 | 检查 Agent URL；`pm2 restart` agent |
| 无关键位/趋势信息 | Flask 未启动或令牌错误 | 启动 app.py；核对 `HUB_BRIDGE_TOKEN` | | 无关键位/趋势信息 | Flask 未起或 hub_bridge 未加载 | 启动 `crypto_*`；`curl .../api/hub/ping` |
| 全平 401 | 子代理 `CONTROL_TOKEN` 与中控不一致 | 中控用 `X-Control-Token` 转发，需与 agent 一致 | | 全平 401 | `CONTROL_TOKEN` 与中控不一致 | 与 `HUB_BRIDGE_TOKEN` 对齐 |
| OKX 始终灰色 | `HUB_DISABLED_IDS=1` | 清空该环境变量并在设置页启用 | | OKX 始终灰色 | `HUB_DISABLED_IDS=1` | 改掉环境变量并在设置页启用 |
| 无关键位块 | 该户 capabilities 无 `key` | 正常；Gate 趋势户无关键位 | | 打开即跳转登录 | 已设 `HUB_PASSWORD` | 正常；访问 `/login` |
| 局域网无法打开中控 | 防火墙 / `HUB_TRUST_LAN=0` | 放行端口或恢复默认信任私网 | | 域名能登、IP:5100 不能 | Secure Cookie + HTTP | 见常见问题 §2.1；或分别登录 |
| 打开即跳转登录 | 已设 `HUB_PASSWORD` | 正常；输入密码后 7 天内免登（可改 `HUB_SESSION_DAYS`） | | 添加关键位报错 / SyntaxError | 旧前端或旧 hub 代码 | 强刷浏览器；`git pull` + `verify_hub_deploy.sh` |
| 域名能登录、IP:5100 不能 | `HUB_COOKIE_SECURE=true` 且用 http 访问 IP | 已改为仅 HTTPS 才发 Secure Cookie；或 IP 用 http、域名用 https 各登一次 | | `curl /api/ping` 非 JSON | hub 未启动 | `pm2 restart manual-trading-hub` |
| 登录后仍 401 | Cookie 未带上 | 反代需传 `X-Forwarded-Proto: https`；勿混用不同主机名的 Cookie |
**运维脚本**（在 `manual_trading_hub` 目录执行）：
| 脚本 | 作用 |
|------|------|
| `scripts/fix_hub_deps.sh` | 安装依赖（含 `python-multipart`） |
| `scripts/verify_hub_deploy.sh` | 检查代码版本与 ping |
| `scripts/fix_env_crlf.sh` | 修复 `.env` 的 CRLF 导致 agent 起不来 |
手动探测实例桥接： 手动探测实例桥接：
@@ -326,3 +364,16 @@ pm2 save && pm2 startup
5. 异常行情 → 单户全平或全局紧急全平。 5. 异常行情 → 单户全平或全局紧急全平。
如有新交易所，在 **系统设置** 添加一行并勾选能力，无需修改 hub.py 源码（需该所有 Flask 注册 `hub_bridge` 且 agent 已部署）。 如有新交易所，在 **系统设置** 添加一行并勾选能力，无需修改 hub.py 源码（需该所有 Flask 注册 `hub_bridge` 且 agent 已部署）。
---
## 12. 文档索引
| 文档 | 内容 |
|------|------|
| [使用说明.md](./使用说明.md) | 本文 |
| [部署文档.md](./部署文档.md) | Ubuntu / PM2 / 反代 |
| [常见问题.md](./常见问题.md) | 故障实录与排障 |
| [README.md](./README.md) | 速览 |
| [.env.example](./.env.example) | 环境变量模板 |
| [scripts/后台运行-Ubuntu.md](./scripts/后台运行-Ubuntu.md) | screen / systemd |
manual_trading_hub/常见问题.md
+232
View File
@@ -0,0 +1,232 @@
# 中控与四实例 — 常见问题实录
本文档整理部署与运行 **manual_trading_hub**（复盘系统中控）及四所 `crypto_monitor_*` 时**实际遇到过**的问题与处理办法。操作步骤仍以 [使用说明.md](./使用说明.md)、[部署文档.md](./部署文档.md) 为准。
---
## 一、中控进程与代码版本
### 1.1 PM2 日志仍出现 `api_trade_key`、`python-multipart` 断言
**现象**：`pm2 logs` 里报错 `File "hub.py", line 324, in api_trade_key` 或 `The python-multipart library must be installed`。
**原因**：
- 服务器上的 `hub.py` 仍是**旧版**（含已移除的「下单区」接口），或 pull 后**未重启** PM2，日志是历史残留。
- 旧版「添加关键位」会 `request.form()`，未装 `python-multipart` 时直接 500。
**处理**：
```bash
cd /opt/crypto_monitor
git pull
cd manual_trading_hub
bash scripts/fix_hub_deps.sh # 安装 python-multipart 等
bash scripts/verify_hub_deploy.sh # 应显示无 api_trade_key、含 HUB_BUILD
pm2 restart manual-trading-hub
curl -s http://127.0.0.1:5100/api/ping
```
**正常 ping**（无需登录）应含 `"build":"20260521-no-trade-ui"`、`"trade_ui":false`。
**说明**：当前版本**已移除中控下单区**；添加关键位、人工下单、趋势回调请在监控卡片点 **「实例」** 进入各 Flask 网页。浏览器请 **Ctrl+F5** 强刷，避免旧前端缓存仍请求 `/api/trade/key`。
---
### 1.2 `curl /api/ping` 返回 `{"detail":"未登录"}`
**原因**：早期版本未把 `/api/ping` 列入免登录白名单（已修复）。
**处理**：`git pull` 后 `pm2 restart manual-trading-hub`；再测应直接返回 JSON，无需 Cookie。
---
### 1.3 `verify_hub_deploy.sh` 报 `Expecting value: line 1 column 1`
**原因**：5100 端口无进程监听（hub 未启动或已崩溃），`curl` 拿到空响应。
**处理**：
```bash
pm2 restart manual-trading-hub
sleep 2
pm2 logs manual-trading-hub --lines 30 --nostream
ss -ltn | grep 5100
bash scripts/verify_hub_deploy.sh
```
---
### 1.4 `bash scripts/fix_hub_deps.sh` 在仓库根目录找不到
**原因**：脚本在 `manual_trading_hub/scripts/` 下，不在 `/opt/crypto_monitor/scripts/`。
**处理**：
```bash
cd /opt/crypto_monitor/manual_trading_hub
bash scripts/fix_hub_deps.sh
```
---
## 二、登录与 Cookie（反代 / 域名 / 内网 IP）
### 2.1 设了密码后，域名能登录，`http://内网IP:5100` 不能
**原因**（最常见）：
- `.env` 中 `HUB_COOKIE_SECURE=true`，且用 **HTTP** 访问 IP:5100 → 浏览器**不保存**带 `Secure` 的 Cookie，表现为登录成功后又跳回登录页。
- **域名（HTTPS）** 与 **IP:5100（HTTP）** 是不同站点，Cookie **不共用**，需在 IP 上再登一次。
**处理**：
- 已支持：仅在实际 **HTTPS** 请求时发 `Secure` Cookie（读 `X-Forwarded-Proto`），HTTP 内网 IP 可正常登录。
- 反代 Nginx 需传：`proxy_set_header X-Forwarded-Proto $scheme;`
- 若仍异常：HTTPS 域名与 HTTP IP **分别登录**；或内网仅用 IP 时可注释 `HUB_COOKIE_SECURE`。
### 2.2 登录后接口仍 401
| 检查项 | 说明 |
|--------|------|
| 用户名密码 | `.env` 中 `HUB_USERNAME`（未设默认为 `admin`）、`HUB_PASSWORD` |
| 改密后 | 需重新登录；旧 Cookie 失效 |
| 混用地址 | 不要用 A 浏览器标签登域名、B 标签指望 IP 已登录 |
---
## 三、监控区无数据 / 子代理异常
### 3.1 卡片「子代理不可用」或余额为 —
| 原因 | 处理 |
|------|------|
| agent 未启动 | `pm2 restart ecosystem.config.cjs` 或 `pm2 restart manual-agent-*` |
| Agent URL 与端口不符 | 系统设置里应为 `http://127.0.0.1:15200` 等 |
| PM2 未加载策略 `.env` | 须用 `run_agent.sh` 启动（会 `source` 各目录 `.env`），勿裸跑 `agent.py` |
| `.env` 为 Windows CRLF | 日志 `$'\r': command not found` → `bash scripts/fix_env_crlf.sh` 后重启 |
验证：
```bash
curl -s http://127.0.0.1:15202/status | head -c 300
```
应 `ok: true` 且有 `balance_usdt`。
### 3.2 有持仓但无关键位 / 趋势，或提示 Flask 404
| 原因 | 处理 |
|------|------|
| 对应 `crypto_*` Flask 未启动 | `pm2 restart crypto_gate` 等 |
| 未注册 `hub_bridge` | 启动日志勿含 `[hub_bridge] ImportError`；仓库根需在 `PYTHONPATH`（各实例 `ecosystem.config.cjs` 已配 `PYTHONPATH=..`） |
| `HUB_BRIDGE_TOKEN` 不一致 | 中控 `.env` 与四实例 `.env` 设相同令牌，或实例 `APP_AUTH_DISABLED=true`（仅建议本机） |
```bash
curl -s -H "X-Hub-Token:你的令牌" http://127.0.0.1:5000/api/hub/ping
```
---
## 四、复盘链接与公网反代
### 4.1 监控里点「复盘」打开的是本机 127.0.0.1
**原因**：未设 `HUB_PUBLIC_ORIGIN`，浏览器拿到的链接仍是 Flask 本机地址。
**处理**：`manual_trading_hub/.env` 增加（示例）：
```env
HUB_PUBLIC_ORIGIN=http://192.168.8.6
```
或 `HUB_PUBLIC_HOST=192.168.8.6`。改后 `pm2 restart manual-trading-hub`。
**说明**：仅反代中控、四实例 Flask 仍只监听 127.0.0.1 时，其它电脑要能打开复盘，还须能访问各实例端口或单独反代。
### 4.2 只反代中控、不反代四实例
**可以**。中控聚合监控与全平；复盘、下单、关键位维护进各实例网页。实例 Flask/agent 建议 `127.0.0.1` + 与中控相同的 `HUB_BRIDGE_TOKEN`。
---
## 五、Gate 趋势 / 复盘相关（实例侧）
### 5.1 Gate 趋势 `/records` 或预览 500（`preview_created_at`）
**原因**：数据库缺列或查询未兼容旧库。
**处理**：`git pull` 后重启 `crypto_gate_bot`；必要时在实例目录执行一次带 `init_db` 的启动或按该目录更新文档迁移。
### 5.2 中控监控区 Gate 趋势户「无关键位」
**设计如此**：Gate 趋势户 capabilities 为趋势，不含 `key`；关键位在 Gate 训练户（`crypto_monitor_gate`）。
---
## 六、环境与配置
### 6.1 OKX 默认不显示
`HUB_DISABLED_IDS=1`（默认关 OKX）。要用 OKX：清空或改掉该变量，并在系统设置启用 id=1。
### 6.2 公网 IP 直连中控 403
`HUB_TRUST_LAN=true` 时仅允许本机 + RFC1918 私网（10/172.16/192.168）。公网 IP 直连 5100 会被拒；应走 **Nginx 反代到 127.0.0.1:5100**。
### 6.3 `.env` 修改不生效
PM2 须重启：`pm2 restart manual-trading-hub`（`run_hub.sh` 每次启动会重读 `.env`）。
### 6.4 `hub_settings.json` 与 Git
网页「系统设置」保存生成，**一般不提交 Git**。`git pull` **不会覆盖** 该文件与 `.env`。
---
## 七、功能边界（避免误用）
| 项目 | 说明 |
|------|------|
| 中控下单区 | **已移除**；勿再在中控添加关键位/人工单/趋势预览 |
| 中控能力 | 监控聚合、单户/全局紧急全平、系统设置、登录保护 |
| 下单与关键位 | 各 `crypto_monitor_*` 原网页 |
| 复盘 | 各实例 `/records`；中控仅「复盘」外链 |
| 全平 | 市价减仓，不可撤销，操作前确认 |
---
## 八、推荐排障顺序
1. `git pull` → `manual_trading_hub` 下 `bash scripts/fix_hub_deps.sh` → `bash scripts/verify_hub_deploy.sh`
2. `pm2 restart manual-trading-hub`（及 `ecosystem.config.cjs` 若 agent/Flask 也有问题）
3. `curl http://127.0.0.1:5100/api/ping` → 确认 `build` 与 `trade_ui:false`
4. 浏览器打开 `/login` 登录 → `/monitor` 强刷
5. 逐项 `curl` 子代理 `/status`、Flask `/api/hub/ping`
6. 仍不行则查 `pm2 logs manual-trading-hub`、`pm2 logs crypto_gate` 最近 50 行
---
## 九、相关脚本
| 脚本 | 作用 |
|------|------|
| `scripts/fix_hub_deps.sh` | 安装/更新中控 venv 依赖（含 python-multipart） |
| `scripts/verify_hub_deploy.sh` | 检查代码版本、multipart、ping、PM2 状态 |
| `scripts/fix_env_crlf.sh` | 去除各目录 `.env` 的 Windows 换行 |
| `scripts/run_hub.sh` | PM2 启动 hub（加载 `.env`） |
| `scripts/run_agent.sh` | PM2 启动 agent（加载策略目录 `.env`） |
| `scripts/pm2_hub.sh` | 启停/日志 hub+agent 一体 |
---
## 十、文档索引
| 文档 | 内容 |
|------|------|
| [使用说明.md](./使用说明.md) | 架构、页面、环境变量、API |
| [部署文档.md](./部署文档.md) | Ubuntu/PM2 安装与反代 |
| [README.md](./README.md) | 速览与快速启动 |
| [.env.example](./.env.example) | 中控环境变量模板 |
manual_trading_hub/部署文档.md
+81 -32
View File
@@ -1,6 +1,10 @@
# 多账户交易中控 — 部署文档（含 PM2） # 多账户交易中控 — 部署文档（含 PM2）
本文档说明在 **Ubuntu / Linux** 上部署 **manual_trading_hub**（监控区、系统设置）的推荐步骤。功能与界面操作见 **《使用说明.md》**；环境变量说明见 **`.env.example`** 与各 `crypto_monitor_*` 的 `.env.example`。 本文档说明在 **Ubuntu / Linux** 上部署 **manual_trading_hub**（复盘系统中控：监控区、系统设置、登录保护）的推荐步骤。
- 功能与界面：[使用说明.md](./使用说明.md)
- 故障实录：[常见问题.md](./常见问题.md)
- 环境变量模板：[.env.example](./.env.example)
--- ---
@@ -37,9 +41,12 @@ pip install -r requirements.txt
cp .env.example .env cp .env.example .env
# 编辑 .env：HUB_PORT、HUB_DISABLED_IDS、公网时 HUB_BRIDGE_TOKEN 等 # 编辑 .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 chmod +x scripts/run_hub.sh scripts/run_agent.sh scripts/pm2_hub.sh scripts/pm2_agents.sh
chmod +x scripts/fix_hub_deps.sh scripts/verify_hub_deploy.sh scripts/fix_env_crlf.sh
deactivate # 可选；交给 PM2 时不必保持激活 deactivate # 可选；交给 PM2 时不必保持激活
``` ```
**依赖说明**：`requirements.txt` 含 **`python-multipart`**（FastAPI 表单解析；旧版若保留下单接口时需要）。当前中控**已移除下单区**，但仍建议安装完整依赖。
说明： 说明：
- **安装依赖**：`source .venv/bin/activate` 后用 `pip install` 即可；不写 `activate` 时也可用 **`.venv/bin/pip install -r requirements.txt`**（效果相同）。 - **安装依赖**：`source .venv/bin/activate` 后用 `pip install` 即可；不写 `activate` 时也可用 **`.venv/bin/pip install -r requirements.txt`**（效果相同）。
@@ -157,27 +164,49 @@ bash scripts/run_hub.sh
## 七、浏览器验收 ## 七、浏览器验收
1. 打开 **http://127.0.0.1:5100/monitor**（局域网用本机私网 IP）。 1. **http://127.0.0.1:5100/login** — 若 `.env` 已设 `HUB_PASSWORD`，用 `HUB_USERNAME` / `HUB_PASSWORD` 登录。
2. 已启用账户应显示持仓；Flask 已起时有关键位/趋势信息。 2. **http://127.0.0.1:5100/monitor** — 已启用账户显示持仓；Flask 已起时有关键位/趋势信息。
3. **http://127.0.0.1:5100/settings** 保存后生成 `hub_settings.json`。 3. **http://127.0.0.1:5100/settings** — 保存后生成 `hub_settings.json`。
4. 在各实例 Flask 网页测试下单/关键位（中控仅监控，不下单）。 4. 监控卡片 **「实例」** — 在各 `crypto_monitor_*` 网页做下单、关键位、趋势；中控**不提供**下单表单。
接口探测： **命令行验收**（推荐）：
```bash ```bash
curl -s http://127.0.0.1:5100/api/settings | head cd /opt/crypto_monitor/manual_trading_hub
curl -s http://127.0.0.1:15200/health bash scripts/verify_hub_deploy.sh
```
应看到：`OK: 无 api_trade_key`，`HTTP 200`，JSON 含 `"build":"20260521-no-trade-ui"`。
```bash
curl -s http://127.0.0.1:5100/api/ping
curl -s http://127.0.0.1:15200/status | head -c 200
``` ```
--- ---
## 八、仅反代中控到公网（实例不反代） ## 八、仅反代中控到公网（实例不反代）
1. Nginx/Caddy 反代到 **`127.0.0.1:5100`**，配置 HTTPS。 1. Nginx/Caddy 反代到 **`127.0.0.1:5100`**，配置 **HTTPS**。
2. `hub_settings.json` 中 Flask/Agent 保持 **`http://127.0.0.1:...`**。 2. 反代需传递（登录 Cookie 正确识别 HTTPS）：
3. 四实例 **`APP_AUTH_DISABLED=false`** + 与中控相同 **`HUB_BRIDGE_TOKEN`**（见 `.env.example` 注释）。 ```nginx
4. 子代理 **`HOST=127.0.0.1`**，防火墙勿放行 `15200`～`15203`、各 `APP_PORT`。 proxy_set_header Host $host;
5. **交易复盘**：`manual_trading_hub/.env` 设 `HUB_PUBLIC_ORIGIN=http://<Ubuntu局域网IP>`；内网其它设备才能打开复盘；须能访问各实例端口（5000/5001/5002）或单独反代。 proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
```
3. `manual_trading_hub/.env` **务必设置**：
```env
HUB_USERNAME=你的用户名
HUB_PASSWORD=你的强密码
HUB_SESSION_SECRET=随机长串
HUB_COOKIE_SECURE=true
```
4. `hub_settings.json` 中 Flask/Agent 保持 **`http://127.0.0.1:...`**（中控本机调 API）。
5. 四实例 **`APP_AUTH_DISABLED=false`** + 与中控相同 **`HUB_BRIDGE_TOKEN`**。
6. 子代理 **`HOST=127.0.0.1`**；防火墙勿对公网开放 `15200`～`15203`、各 `APP_PORT`。
7. **复盘/实例外链**：`HUB_PUBLIC_ORIGIN=https://你的域名` 或内网 IP；否则其它设备点「复盘」会跳到 `127.0.0.1`。
**说明**：HTTPS 域名与 HTTP `内网IP:5100` Cookie **不共用**；内网访问 IP 需在 IP 地址再登录一次（见 [常见问题.md](./常见问题.md) §2.1）。
--- ---
@@ -190,9 +219,14 @@ curl -s http://127.0.0.1:15200/health
| `HUB_DISABLED_IDS` | `1` | 强制关闭的账户 id（OKX） | | `HUB_DISABLED_IDS` | `1` | 强制关闭的账户 id（OKX） |
| `HUB_TRUST_LAN` | `true` | 私网可访问；仅本机可 `false` | | `HUB_TRUST_LAN` | `true` | 私网可访问；仅本机可 `false` |
| `HUB_PUBLIC_ORIGIN` | 空 | 浏览器用复盘链接；如 `http://192.168.1.100`（**内网其它电脑访问中控时建议设置**） | | `HUB_PUBLIC_ORIGIN` | 空 | 浏览器用复盘链接；如 `http://192.168.1.100`（**内网其它电脑访问中控时建议设置**） |
| `HUB_BRIDGE_TOKEN` | 空 | 公网/开登录时建议配置 | | `HUB_BRIDGE_TOKEN` | 空 | 与四实例一致；公网建议配置 |
| `HUB_USERNAME` | `admin` | Web 登录用户名 |
| `HUB_PASSWORD` | 空 | 非空即启用登录 |
| `HUB_SESSION_SECRET` | — | 会话签名 |
| `HUB_COOKIE_SECURE` | `false` | HTTPS 反代建议 `true` |
| `HUB_SESSION_DAYS` | `7` | 登录保持天数 |
本地联调、实例 `APP_AUTH_DISABLED=true` 时可不配 `HUB_BRIDGE_TOKEN`。 本地联调、实例 `APP_AUTH_DISABLED=true` 时可不配 `HUB_BRIDGE_TOKEN`；本机不设 `HUB_PASSWORD` 则无需登录页。
--- ---
@@ -201,29 +235,38 @@ curl -s http://127.0.0.1:15200/health
```bash ```bash
cd /opt/crypto_monitor cd /opt/crypto_monitor
git pull git pull
cd manual_trading_hub cd manual_trading_hub
.venv/bin/pip install -r requirements.txt bash scripts/fix_hub_deps.sh
bash scripts/verify_hub_deploy.sh
pm2 restart ecosystem.config.cjs pm2 restart ecosystem.config.cjs
# 若只改了中控：pm2 restart manual-trading-hub
``` ```
- **`hub_settings.json`**、**`.env`** 不在 Git 中，`git pull` 不会覆盖。 - **`hub_settings.json`**、**`.env`** 不在 Git 中，`git pull` 不会覆盖。
- 升级前可备份：`cp hub_settings.json hub_settings.json.bak`。 - 升级前可备份：`cp hub_settings.json hub_settings.json.bak`、`cp .env .env.bak`。
**升级后自检**：`curl -s http://127.0.0.1:5100/api/ping` 须含 `"trade_ui":false`。若仍见 `api_trade_key` 报错，说明代码未更新或未重启，见 [常见问题.md](./常见问题.md) §1。
--- ---
## 十一、故障排查 ## 十一、故障排查（速查）
**完整实录**见 **[常见问题.md](./常见问题.md)**。
| 现象 | 处理 | | 现象 | 处理 |
|------|------| |------|------|
| PM2 启动后立刻退出 | `pm2 logs manual-trading-hub`；检查 `.venv`、`.env`、`run_hub.sh` 可执行 | | 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` | | `api_trade_key` / `python-multipart` | `git pull` → `bash scripts/fix_hub_deps.sh` → `verify_hub_deploy.sh` → 重启 hub |
| PM2 里 agent **errored**，日志 `$'\r': command not found` | `.env` 为 Windows **CRLF** 换行 | `bash scripts/fix_env_crlf.sh` 后 `pm2 restart ecosystem.config.cjs`（新版 `run_agent.sh` 也会自动去 `\r`） | | `verify` ping 解析失败 | hub 未起：`pm2 restart manual-trading-hub` |
| PM2 里 agent **stopped / errored**（其它） | 端口占用、无密钥、venv 缺失 | `bash scripts/check_agents.sh`；`pm2 logs manual-agent-binance --lines 80` | | 余额显示 — | agent 未加载 `.env`；`fix_env_crlf.sh`；`run_agent.sh` |
| 监控无持仓 | 子代理未起或 Agent URL 错；或交易所确实无仓 | `curl http://127.0.0.1:15200/status` | | agent `$'\r': command not found` | `bash scripts/fix_env_crlf.sh` |
| 无关键位/下单 401 | Flask 未起或 `HUB_BRIDGE_TOKEN` 不一致；或设 `APP_AUTH_DISABLED=true` | | 监控无持仓 | `curl http://127.0.0.1:15200/status` |
| 子代理 SOCKS 报错 | 在 **manual_trading_hub/.venv** 安装 `PySocks` 后 **pm2 restart** 子代理 | | 无关键位 / 401 | 启动 Flask；核对 `HUB_BRIDGE_TOKEN` / `hub_bridge` |
| 公网访问中控 403 | 反代未指向本机、或客户端非私网且 `HUB_TRUST_LAN=true`；反代改 `127.0.0.1:5100` 或在反代层鉴权 | | 域名能登、IP 不能登 | 见常见问题 §2.1（Cookie / HTTP vs HTTPS） |
| 改 `.env` 不生效 | PM2 需 `pm2 restart manual-trading-hub`（`run_hub.sh` 每次启动会重读 `.env`） | | 公网访问中控 403 | 反代到 `127.0.0.1:5100`，勿公网直连 5100 |
| 改 `.env` 不生效 | `pm2 restart manual-trading-hub` |
--- ---
@@ -239,9 +282,11 @@ pm2 restart ecosystem.config.cjs
## 十三、安全清单 ## 十三、安全清单
- [ ] 公网仅暴露反代端口，不暴露 Flask/agent 端口 - [ ] 公网仅暴露反代端口，不暴露 Flask/agent 端口
- [ ] 已设 `HUB_USERNAME` + `HUB_PASSWORD`（中控 Web 登录）
- [ ] HTTPS 反代已设 `HUB_COOKIE_SECURE=true` 且传递 `X-Forwarded-Proto`
- [ ] 公网已配置 `HUB_BRIDGE_TOKEN` + 实例关闭 `APP_AUTH_DISABLED` - [ ] 公网已配置 `HUB_BRIDGE_TOKEN` + 实例关闭 `APP_AUTH_DISABLED`
- [ ] API Key 最小权限；交易所 IP 白名单 - [ ] API Key 最小权限；交易所 IP 白名单
- [ ] 已告知操作人员「全局全平」不可撤销 - [ ] 已告知操作人员「全局全平」不可撤销；中控**不在网页下单**
--- ---
@@ -249,7 +294,11 @@ pm2 restart ecosystem.config.cjs
| 文档 | 内容 | | 文档 | 内容 |
|------|------| |------|------|
| **使用说明.md** | 三页功能、能力矩阵、鉴权说明 | | [使用说明.md](./使用说明.md) | 功能、页面、API、环境变量 |
| **README.md** | 架构速览 | | [常见问题.md](./常见问题.md) | 故障实录 |
| **.env.example** | 中控环境变量模板 | | [README.md](./README.md) | 速览 |
| **scripts/后台运行-Ubuntu.md** | screen / systemd 补充 | | [.env.example](./.env.example) | 环境变量模板 |
| [scripts/后台运行-Ubuntu.md](./scripts/后台运行-Ubuntu.md) | screen / systemd |
| `scripts/fix_hub_deps.sh` | 安装依赖 |
| `scripts/verify_hub_deploy.sh` | 部署验收 |
| `scripts/fix_env_crlf.sh` | 修复 .env 换行 |