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

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

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

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 |