# 中控与四实例 — 常见问题实录

本文档整理部署与运行 **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.3 Gate 子代理「一会正常、一会连不上」（仅 Gate 两户）

| 现象 | 说明 |
|------|------|
| 中控 LINK 2/4，仅 Gate 红 | 本机 `15202`/`15203` 在 PM2 重启间隙连不上 |
| 日志 `$'\r': command not found` | `crypto_monitor_gate*` 的 `.env` 为 Windows CRLF |
| `curl` 有时通有时不通 | 与 Gate 外网无关，先修 CRLF 并重建 agent |

**修复**（服务器）：

```bash
cd /opt/crypto_monitor
sed -i 's/\r$//' crypto_monitor_gate/.env crypto_monitor_gate_bot/.env
bash manual_trading_hub/scripts/fix_env_crlf.sh
cd manual_trading_hub && pm2 restart manual-agent-gate manual-agent-gate-bot
# 仍反复重启时：pm2 delete 后按 ecosystem.config.cjs 重新 start（见部署文档 §5.6）
```

修好后 `pm2 describe manual-agent-gate` 的 **restarts** 应不再疯涨；`pm2 flush manual-agent-gate` 可清掉旧 CRLF 日志。

**若子代理已绿但挂委托失败**：再查 `GATE_SOCKS_PROXY`、API 权限、止损止盈价格是否合理（与各实例策略页相同 `.env` 参数）。

### 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 趋势户通常只勾 **监控趋势计划**，不勾关键位；关键位在 Gate 训练户。四所 **策略交易** 均在各实例 `/strategy`，与中控勾选无关。增加 Gate 子账户见 [使用说明.md](./使用说明.md) **§4.3**。

---

## 六、环境与配置

### 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) | 中控环境变量模板 |