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

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

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -28,7 +28,7 @@ cd crypto_monitor
 | `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_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` 与四者 **进程独立**，无需改四者代码即可并行使用。
 
@@ -65,9 +65,11 @@ cd crypto_monitor
 
 ## 四、与 `manual_trading_hub` 的关系（可选）
 
-- **中控** `hub.py`：汇总各子代理状态，提供网页与 HTTP API。  
-- **子代理** `agent.py`：每个进程绑定一个交易所账户，默认监听 **`15200`～`15203`**，与四个 Flask 应用的 **`APP_PORT`**（如 5000、5001）**必须错开**。  
-- 详细端口、`EXCHANGE`、`HUB_AGENTS` 等见 [manual_trading_hub/README.md](./manual_trading_hub/README.md)。
+- **中控** `hub.py`（`:5100`）：多账户 **监控聚合**、**紧急全平**、系统设置；可选 **用户名+密码** 登录（反代公网时务必配置）。  
+- **子代理** `agent.py`：每账户一进程，默认 **`15200`～`15203`**，与四所 Flask **`APP_PORT`**（5000/5001/5002/5004）**必须错开**。  
+- **下单、关键位、趋势、复盘**：在各 `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 / 代理 / 升级说明）。  
 4. 服务器部署完成后，按 **[备份与恢复.md](./备份与恢复.md)** 配置自动备份与 `.env` 备份习惯。  
 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

@@ -83,6 +83,7 @@ bash deploy/setup_env.sh
    ```
 
 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

@@ -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_DISABLED_IDS`；被关闭的不轮询、不参与全局全平 |
+| 监控区 | 持仓、余额、关键位摘要、趋势计划、机器人单（只读） |
+| 紧急全平 | 单户 / 全局市价减仓 |
+| 系统设置 | `hub_settings.json` 管理四所 URL、启用状态、监控能力 |
+| Web 登录 | `.env` 设 `HUB_PASSWORD` 后用户名+密码保护（反代公网**务必**配置） |
+| ~~下单区~~ | **已移除**（避免与实例重复、减少故障面） |
 
 ---
 
-## 架构说明
+## 架构
 
 ```
-浏览器  →  中控 hub.py（默认监听 0.0.0.0:5100，私网可访问；本机仍可用 127.0.0.1）
-              ↓ HTTP
-        子代理 agent.py × N（默认 127.0.0.1:15200～15203，与 Flask 的 APP_PORT 错开）
-              ↓ ccxt
-           各交易所 API
+浏览器 → hub.py (:5100)  监控 / 设置 / 登录
+            ├→ agent.py × N (:15200～15203)  持仓、全平
+            └→ 各 Flask (:5000/5001/5002/5004)  /api/hub/monitor 只读聚合
 ```
 
-- **中控（hub）**：读配置、并行请求各子代理 `/status`；全平时转发 `POST /emergency/close-all`。
-- **子代理（agent）**：每个进程绑定一个交易所 API Key，只做只读状态 + 紧急平仓；与 `crypto_monitor_*` 里的 Flask **独立进程**，互不影响日常手工/策略操作。
-
-### 与四个 `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`。
+- 账户列表：**系统设置** 或默认 `settings_store.py`（不再使用环境变量 `HUB_AGENTS`）。
+- 四实例须注册 **hub_bridge**（仓库根 `hub_bridge.py`）；PM2 建议 `PYTHONPATH=..`。
 
 ---
 
-## 依赖
-
-- Python 3.10+（与仓库其他项目相近即可）
-- 见 `requirements.txt`：`fastapi`、`uvicorn`、`httpx`、`ccxt`
-
-安装：
+## 快速启动（Linux / PM2）
 
 ```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
+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，避免密钥分散维护两套。
-
-**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/**
+详见 [.env.example](./.env.example)。
 
 ---
 
-## 子代理（agent）环境变量
+## 子代理（agent）
 
-| 变量 | 含义 | 默认 |
-|------|------|------|
-| `EXCHANGE` | `binance` / `okx` / `gate` | `binance` |
-| `HOST` | 监听地址 | `127.0.0.1` |
-| `PORT` | 子代理监听端口（勿与 Flask 的 `APP_PORT` 相同） | `15200` |
-| `CONTROL_TOKEN` | 若设置，请求须带头 `X-Control-Token` | 空 |
+每所策略目录单独进程，`EXCHANGE` + `PORT`（15200～15203），密钥来自**该目录 `.env`**。PM2 经 `scripts/run_agent.sh` 启动（自动 `source .env`、去 CRLF）。
 
-**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` 合约口径一致，非现货钱包）。
-
-**OKX**：`OKX_API_KEY`、`OKX_API_SECRET`、`OKX_API_PASSPHRASE`；可选 `OKX_TD_MODE`、`OKX_POS_MODE`；代理 `OKX_SOCKS_PROXY` 等。
-
-**Gate**：`GATE_API_KEY`、`GATE_API_SECRET`；可选 `GATE_TD_MODE`、`GATE_POS_MODE`；代理 `GATE_SOCKS_PROXY` 等。
+| PORT | 目录 |
+|------|------|
+| 15200 | crypto_monitor_binance |
+| 15201 | crypto_monitor_okx |
+| 15202 | crypto_monitor_gate |
+| 15203 | crypto_monitor_gate_bot |
 
 ---
 
-## 中控（hub）环境变量
+## 运维脚本
 
-| 变量 | 含义 | 默认 |
-|------|------|------|
-| `HUB_HOST` | 监听地址 | `0.0.0.0`（局域网可连）；`127.0.0.1` 仅本机 |
-| `HUB_PORT` | 监听端口 | `5100` |
-| `HUB_AGENTS` | 子代理 base URL，逗号分隔 | `http://127.0.0.1:15200` … `15203` |
-| `HUB_AGENT_NAMES` | 与 `HUB_AGENTS` **顺序一一对应**的卡片显示名（逗号分隔）。不设则用内置默认名。改后需重启 hub，**所有访问该中控的浏览器**显示一致 | 内置与四目录对应的英文标签 |
-| `HUB_DISABLED_IDS` | 不参与监控与全局全平的账户 `id`，逗号分隔（如暂不用 OKX 写 `1`） | 空 |
-| `HUB_TRUST_LAN` | 默认 `true`；设为 `0`/`false`/`off` 则仅允许本机 IP 访问中控 | 开 |
-| `CONTROL_TOKEN` | 与子代理一致时，中控代发 `X-Control-Token` | 空 |
+| 脚本 | 作用 |
+|------|------|
+| [scripts/fix_hub_deps.sh](./scripts/fix_hub_deps.sh) | 安装/更新 venv 依赖 |
+| [scripts/verify_hub_deploy.sh](./scripts/verify_hub_deploy.sh) | 验收代码版本与 ping |
+| [scripts/fix_env_crlf.sh](./scripts/fix_env_crlf.sh) | 修复 .env 的 Windows 换行 |
+| [scripts/pm2_hub.sh](./scripts/pm2_hub.sh) | PM2 启停 hub+agent |
+| [scripts/后台运行-Ubuntu.md](./scripts/后台运行-Ubuntu.md) | screen / systemd |
 
 ---
 
-## 网页操作说明
+## 文档索引
 
-- **立即刷新 / 自动刷新**：拉取最新汇总；自动刷新默认约 3 秒一轮（仅请求已开启监控的账户）。
-- **账户显示名**：在运行 `hub.py` 的机器上设置环境变量 **`HUB_AGENT_NAMES`**（逗号分隔，顺序与 **`HUB_AGENTS`** 里每个子代理 URL 一致），重启中控后，任意电脑打开同一中控地址都会看到相同名称。名称里若含逗号，需整体用引号包裹或避免使用逗号。
-- **参与监控**：勾选则参与轮询与「全局一键全平」；取消则本浏览器记住（`localStorage` 键 `manual_trading_hub_excluded`），不再请求该子代理。
-- **该账户全平**：仅针对该子代理；与是否关闭「参与监控」无关（仍可直接调交易所紧急平仓）。
-- **全局一键全平**：只对当前「参与监控」且未被 `HUB_DISABLED_IDS` 关闭的账户发起全平；请求体中的 `exclude_ids` 与网页关闭状态一致。
-
-服务端 `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》**。
+| 文档 | 内容 |
+|------|------|
+| [使用说明.md](./使用说明.md) | 页面、API、环境变量、日常流程 |
+| [部署文档.md](./部署文档.md) | Ubuntu、PM2、反代、升级 |
+| [常见问题.md](./常见问题.md) | 已遇到问题与处理 |
+| [.env.example](./.env.example) | 环境变量模板 |

manual_trading_hub/scripts/后台运行-Ubuntu.md

@@ -1,6 +1,9 @@
 # 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**）。
 
@@ -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。
 
@@ -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`）。
 
 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`  
-   再看 `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。二者**不能**相同。
 
-7. **systemd 下改依赖或 `.env` 后**  
+8. **systemd 下改依赖或 `.env` 后**  
    与 screen 相同：`pip install` 或改 `EnvironmentFile` 后需 **`systemctl restart <unit>`**，否则仍是旧进程。
 
 ---

manual_trading_hub/使用说明.md

@@ -24,14 +24,14 @@
 
 ### 1.1 四账户默认配置
 
-| id | 名称 | Flask | Agent | 能力 | 默认启用 |
-|----|------|-------|-------|------|----------|
-| 0 | 币安 | :5001 | :15200 | 下单、关键位 | 是 |
-| 1 | OKX | :5004 | :15201 | 下单、关键位 | **否**（`HUB_DISABLED_IDS=1`） |
-| 2 | Gate 训练 | :5000 | :15202 | 下单、关键位 | 是 |
-| 3 | Gate 趋势 | :5002 | :15203 | **下单、趋势回调**（无关键位 Tab） | 是 |
+| id | 名称 | Flask | Agent | 监控能力（设置页勾选） | 默认启用 |
+|----|------|-------|-------|------------------------|----------|
+| 0 | 币安 | :5001 | :15200 | 关键位 | 是 |
+| 1 | OKX | :5004 | :15201 | 关键位 | **否**（`HUB_DISABLED_IDS=1`） |
+| 2 | Gate 训练 | :5000 | :15202 | 关键位 | 是 |
+| 3 | Gate 趋势 | :5002 | :15203 | 趋势计划 | 是 |
 
-- **Gate 趋势户**：保留 **人工下单** 与 **趋势回调**；监控区可看到运行中的趋势计划，但 **不展示关键位**（capabilities 无 `key`）。
+- **Gate 趋势户**：监控区展示**趋势计划**；**不展示关键位**（capabilities 无 `key`）。人工下单、趋势回调、关键位均在各实例网页操作。
 - **OKX**：默认关闭；需要时在「系统设置」勾选启用，并去掉环境变量 `HUB_DISABLED_IDS` 中的 `1`。
 
 ### 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`（在网页 **系统设置 → 保存设置** 后写入）。
 - 未保存前使用 `settings_store.py` 内置默认四所地址。
@@ -139,7 +157,15 @@ python hub.py
 
 - 监控区：http://127.0.0.1:5100/monitor  
 - 系统设置：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） |
 | **关键位** | 仅 `capabilities` 含 `key` 的户；展示门控摘要（`/api/price_snapshot`） |
 | **趋势计划** | 仅 Gate 趋势户；`trend_pullback_plans` active |
-| **实例 / 复盘** | 「实例」打开该户 Flask 首页；「复盘」打开 `/records`。**中控不做下单与复盘编辑**。若配置 **`HUB_PUBLIC_ORIGIN`**，外链会把 `127.0.0.1` 换成内网 IP |
-| **关键位** | 来自实例 `/api/hub/monitor` + `/api/price_snapshot`（须 Flask 已启动）；无记录或 Flask 未连通时卡片会提示原因；**Gate 趋势户**无关键位 |
+| **实例 / 复盘** | 「实例」→ 该户 Flask（**下单、关键位、趋势**均在此操作）；「复盘」→ `/records`。若配置 **`HUB_PUBLIC_ORIGIN`**，外链替换 `127.0.0.1` |
+| **关键位列表** | 来自 `/api/hub/monitor` + `/api/price_snapshot`；Flask 未连通时卡片提示原因；**Gate 趋势户**无关键位块 |
 | **该户全平** | `POST` 子代理 `/emergency/close-all`，仅平该 API Key 仓位 |
 | **全局紧急全平** | 对所有已启用户依次全平（不含 `HUB_DISABLED_IDS` 强制关闭的 id） |
 | **自动刷新** | 默认每 5 秒请求 `/api/monitor/board` |
@@ -211,8 +237,11 @@ python hub.py
 | GET | `/api/auth/status` | 是否需登录、是否已登录 |
 | POST | `/api/auth/login` | body `{"username":"...","password":"..."}` |
 | POST | `/api/auth/logout` | 退出 |
+| GET | `/api/ping` | 版本与健康检查（**免登录**） |
 
-实例侧（中控只读调用 `/api/hub/monitor` 等；下单请在实例网页）：
+已移除的 `/api/trade/*` 若被旧缓存页面请求，返回 **410** 并提示前往各实例网页。
+
+实例侧（中控只读；下单/关键位/趋势在实例网页）：
 
 | 路径 | 说明 |
 |------|------|
@@ -235,7 +264,7 @@ python hub.py
 | `HUB_USERNAME` | `admin` | 登录用户名（仅当已设密码时生效） |
 | `HUB_PASSWORD` | （空） | 非空即启用 Web 登录 |
 | `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` | 登录保持天数 |
 
 ### 子代理 agent.py
@@ -266,19 +295,28 @@ python hub.py
 
 ---
 
-## 9. 故障排查
+## 9. 故障排查（速查）
+
+完整实录（含 `api_trade_key`、`multipart`、git 版本、PM2 等）见 **[常见问题.md](./常见问题.md)**。
 
 | 现象 | 可能原因 | 处理 |
 |------|----------|------|
-| 监控卡片「子代理不可用」 | agent 未启动或端口错 | 检查 Agent URL、启动 agent |
-| 无关键位/趋势信息 | Flask 未启动或令牌错误 | 启动 app.py；核对 `HUB_BRIDGE_TOKEN` |
-| 全平 401 | 子代理 `CONTROL_TOKEN` 与中控不一致 | 中控用 `X-Control-Token` 转发，需与 agent 一致 |
-| OKX 始终灰色 | `HUB_DISABLED_IDS=1` | 清空该环境变量并在设置页启用 |
-| 无关键位块 | 该户 capabilities 无 `key` | 正常；Gate 趋势户无关键位 |
-| 局域网无法打开中控 | 防火墙 / `HUB_TRUST_LAN=0` | 放行端口或恢复默认信任私网 |
-| 打开即跳转登录 | 已设 `HUB_PASSWORD` | 正常；输入密码后 7 天内免登（可改 `HUB_SESSION_DAYS`） |
-| 域名能登录、IP:5100 不能 | `HUB_COOKIE_SECURE=true` 且用 http 访问 IP | 已改为仅 HTTPS 才发 Secure Cookie；或 IP 用 http、域名用 https 各登一次 |
-| 登录后仍 401 | Cookie 未带上 | 反代需传 `X-Forwarded-Proto: https`；勿混用不同主机名的 Cookie |
+| 监控卡片「子代理不可用」 | agent 未启动或端口错 | 检查 Agent URL；`pm2 restart` agent |
+| 无关键位/趋势信息 | Flask 未起或 hub_bridge 未加载 | 启动 `crypto_*`；`curl .../api/hub/ping` |
+| 全平 401 | `CONTROL_TOKEN` 与中控不一致 | 与 `HUB_BRIDGE_TOKEN` 对齐 |
+| OKX 始终灰色 | `HUB_DISABLED_IDS=1` | 改掉环境变量并在设置页启用 |
+| 打开即跳转登录 | 已设 `HUB_PASSWORD` | 正常；访问 `/login` |
+| 域名能登、IP:5100 不能 | Secure Cookie + HTTP | 见常见问题 §2.1；或分别登录 |
+| 添加关键位报错 / SyntaxError | 旧前端或旧 hub 代码 | 强刷浏览器；`git pull` + `verify_hub_deploy.sh` |
+| `curl /api/ping` 非 JSON | hub 未启动 | `pm2 restart manual-trading-hub` |
+
+**运维脚本**（在 `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. 异常行情 → 单户全平或全局紧急全平。
 
 如有新交易所，在 **系统设置** 添加一行并勾选能力，无需修改 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

@@ -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

@@ -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 换行 |