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

更新使用说明、部署文档与 README，反映已移除下单区、Web 登录与 PM2 验收流程；新增常见问题.md 整理部署排障。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-22 12:32:08 +08:00
parent 16b10e123e
commit 1ec1415e2b
7 changed files with 470 additions and 228 deletions
@@ -1,6 +1,10 @@
 # 多账户交易中控 — 部署文档（含 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
 # 编辑 .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/fix_hub_deps.sh scripts/verify_hub_deploy.sh scripts/fix_env_crlf.sh
 deactivate                         # 可选；交给 PM2 时不必保持激活
 ```

+**依赖说明**：`requirements.txt` 含 **`python-multipart`**（FastAPI 表单解析；旧版若保留下单接口时需要）。当前中控**已移除下单区**，但仍建议安装完整依赖。
+
 说明：

 - **安装依赖**：`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）。
-2. 已启用账户应显示持仓；Flask 已起时有关键位/趋势信息。
-3. **http://127.0.0.1:5100/settings** 保存后生成 `hub_settings.json`。
-4. 在各实例 Flask 网页测试下单/关键位（中控仅监控，不下单）。
+1. **http://127.0.0.1:5100/login** — 若 `.env` 已设 `HUB_PASSWORD`，用 `HUB_USERNAME` / `HUB_PASSWORD` 登录。
+2. **http://127.0.0.1:5100/monitor** — 已启用账户显示持仓；Flask 已起时有关键位/趋势信息。
+3. **http://127.0.0.1:5100/settings** — 保存后生成 `hub_settings.json`。
+4. 监控卡片 **「实例」** — 在各 `crypto_monitor_*` 网页做下单、关键位、趋势；中控**不提供**下单表单。

-接口探测：
+**命令行验收**（推荐）：

 ```bash
-curl -s http://127.0.0.1:5100/api/settings | head
-curl -s http://127.0.0.1:15200/health
+cd /opt/crypto_monitor/manual_trading_hub
+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。
-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. **交易复盘**：`manual_trading_hub/.env` 设 `HUB_PUBLIC_ORIGIN=http://<Ubuntu局域网IP>`；内网其它设备才能打开复盘；须能访问各实例端口（5000/5001/5002）或单独反代。
+1. Nginx/Caddy 反代到 **`127.0.0.1:5100`**，配置 **HTTPS**。
+2. 反代需传递（登录 Cookie 正确识别 HTTPS）：
+   ```nginx
+   proxy_set_header Host $host;
+   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_TRUST_LAN` | `true` | 私网可访问；仅本机可 `false` |
 | `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
 cd /opt/crypto_monitor
 git pull
+
 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 manual-trading-hub
 ```

 - **`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` 可执行 |
-| 余额显示 —、无报错 | 子代理未加载策略目录 `.env`（旧版 PM2 直接跑 agent.py） | 更新代码后 `pm2 restart ecosystem.config.cjs`；`curl http://127.0.0.1:15200/status` 应 `ok:true` 且有 `balance_usdt` |
-| 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`） |
-| PM2 里 agent **stopped / errored**（其它） | 端口占用、无密钥、venv 缺失 | `bash scripts/check_agents.sh`；`pm2 logs manual-agent-binance --lines 80` |
-| 监控无持仓 | 子代理未起或 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`） |
+| PM2 启动后立刻退出 | `pm2 logs manual-trading-hub`；检查 `.venv`、`.env`、`run_hub.sh` |
+| `api_trade_key` / `python-multipart` | `git pull` → `bash scripts/fix_hub_deps.sh` → `verify_hub_deploy.sh` → 重启 hub |
+| `verify` ping 解析失败 | hub 未起：`pm2 restart manual-trading-hub` |
+| 余额显示 — | agent 未加载 `.env`；`fix_env_crlf.sh`；`run_agent.sh` |
+| agent `$'\r': command not found` | `bash scripts/fix_env_crlf.sh` |
+| 监控无持仓 | `curl http://127.0.0.1:15200/status` |
+| 无关键位 / 401 | 启动 Flask；核对 `HUB_BRIDGE_TOKEN` / `hub_bridge` |
+| 域名能登、IP 不能登 | 见常见问题 §2.1（Cookie / HTTP vs HTTPS） |
+| 公网访问中控 403 | 反代到 `127.0.0.1:5100`，勿公网直连 5100 |
+| 改 `.env` 不生效 | `pm2 restart manual-trading-hub` |

 ---

@@ -239,9 +282,11 @@ pm2 restart ecosystem.config.cjs
 ## 十三、安全清单

 - [ ] 公网仅暴露反代端口，不暴露 Flask/agent 端口  
+- [ ] 已设 `HUB_USERNAME` + `HUB_PASSWORD`（中控 Web 登录）  
+- [ ] HTTPS 反代已设 `HUB_COOKIE_SECURE=true` 且传递 `X-Forwarded-Proto`  
 - [ ] 公网已配置 `HUB_BRIDGE_TOKEN` + 实例关闭 `APP_AUTH_DISABLED`  
 - [ ] API Key 最小权限；交易所 IP 白名单  
- [ ] 已告知操作人员「全局全平」不可撤销  
+- [ ] 已告知操作人员「全局全平」不可撤销；中控**不在网页下单**  

 ---

@@ -249,7 +294,11 @@ pm2 restart ecosystem.config.cjs

 | 文档 | 内容 |
 |------|------|
-| **使用说明.md** | 三页功能、能力矩阵、鉴权说明 |
-| **README.md** | 架构速览 |
-| **.env.example** | 中控环境变量模板 |
-| **scripts/后台运行-Ubuntu.md** | screen / systemd 补充 |
+| [使用说明.md](./使用说明.md) | 功能、页面、API、环境变量 |
+| [常见问题.md](./常见问题.md) | 故障实录 |
+| [README.md](./README.md) | 速览 |
+| [.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 换行 |