中控增加下单，关键位，系统设置

2026-05-22 10:04:28 +08:00
parent ed6b56ff87
commit 46f73fce43
19 changed files with 1844 additions and 568 deletions
@@ -0,0 +1,337 @@
+# 多账户交易中控 — 使用说明
+
+本文档说明 **manual_trading_hub**（方案 A）的架构、启动方式、三页界面操作与故障排查。中控聚合四所 **监控 + 下单 + 关键位 + 趋势回调（仅 Gate 趋势户）**；**交易复盘**仍进入各实例网页，中控只提供跳转链接。
+
+---
+
+## 1. 架构总览
+
+```
+浏览器
+  ├─ /monitor   监控区（持仓、关键位、趋势计划、全平）
+  ├─ /trade     下单区（人工下单 / 关键位 / 趋势回调）
+  └─ /settings  系统设置（hub_settings.json）
+
+中控 hub.py（默认 :5100）
+  ├─ HTTP → 子代理 agent.py × N（/status、/emergency/close-all）
+  └─ HTTP → 各实例 Flask app.py（/api/hub/*、/api/price_snapshot）
+```
+
+| 组件 | 职责 | 默认端口（可在设置页改） |
+|------|------|-------------------------|
+| **hub.py** | 聚合 UI、转发下单/监控 API、全平 | `5100` |
+| **agent.py** | 交易所只读状态 + 紧急市价全平 | 币安 `15200`、OKX `15201`、Gate `15202`、Gate趋势 `15203` |
+| **crypto_monitor_*.app** | 策略库、关键位、人工单、趋势预览/执行 | 币安 `5001`、Gate `5000`、Gate趋势 `5002`、OKX `5004` |
+
+### 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） | 是 |
+
+- **Gate 趋势户**：保留 **人工下单** 与 **趋势回调**；监控区可看到运行中的趋势计划，但 **不展示关键位**（capabilities 无 `key`）。
+- **OKX**：默认关闭；需要时在「系统设置」勾选启用，并去掉环境变量 `HUB_DISABLED_IDS` 中的 `1`。
+
+### 1.2 实例侧改动（最小）
+
+各 `crypto_monitor_*` 仅增加：
+
+1. `login_required` 走 `hub_auth.request_allowed`（支持请求头 `X-Hub-Token`）。
+2. 文件末尾 `hub_bridge.install_on_app(...)` 注册 `/api/hub/*`。
+
+业务逻辑、数据库、复盘页面 **未改**；复盘请打开各实例 `/records`（设置里的「复盘链接」）。
+
+---
+
+## 2. 环境准备
+
+### 2.1 依赖安装
+
+```powershell
+cd c:\Users\dekun\Desktop\crypto_monitor\manual_trading_hub
+pip install -r requirements.txt
+```
+
+### 2.2 鉴权令牌（推荐生产启用）
+
+四实例 Flask 与中控、子代理需 **同一密钥**：
+
+| 变量 | 作用 |
+|------|------|
+| `HUB_BRIDGE_TOKEN` | 中控 → Flask 使用头 `X-Hub-Token`；各实例 `hub_auth` 校验 |
+| `CONTROL_TOKEN` | 可与上相同；中控 → 子代理使用头 `X-Control-Token` |
+
+中控 `hub.py` 会读取 `HUB_BRIDGE_TOKEN`，若无则回退 `CONTROL_TOKEN`。
+
+**开发本机**可临时在各实例 `.env` 设 `APP_AUTH_DISABLED=true`，则 Flask 不校验令牌（仍建议子代理设 `CONTROL_TOKEN` 防误暴露）。
+
+### 2.3 强制关闭某账户
+
+```powershell
+$env:HUB_DISABLED_IDS="1"    # 默认即关闭 OKX（id=1）
+```
+
+与设置页「启用」取 **与** 关系：环境变量强制关闭时，网页勾选框会灰掉且无法启用。
+
+### 2.4 配置文件
+
+- 路径：`manual_trading_hub/hub_settings.json`（在网页 **系统设置 → 保存设置** 后写入）。
+- 未保存前使用 `settings_store.py` 内置默认四所地址。
+- 建议 **不要** 把含内网 IP 的 `hub_settings.json` 提交到公开仓库。
+- 环境变量模板：`manual_trading_hub/.env.example`；四实例模板中已补充 `HUB_BRIDGE_TOKEN` 说明。
+
+---
+
+## 3. 启动顺序（Windows 示例）
+
+**原则**：先子代理与四实例 Flask，再中控。
+
+### 3.1 子代理（每所一个终端）
+
+在对应策略目录加载 `.env` 后：
+
+```powershell
+# 币安
+cd c:\Users\dekun\Desktop\crypto_monitor\crypto_monitor_binance
+$env:EXCHANGE="binance"; $env:PORT="15200"; $env:HOST="127.0.0.1"
+# 可选：$env:CONTROL_TOKEN="你的随机串"
+python ..\manual_trading_hub\agent.py
+```
+
+```powershell
+# OKX（若启用）
+cd ..\crypto_monitor_okx
+$env:EXCHANGE="okx"; $env:PORT="15201"
+python ..\manual_trading_hub\agent.py
+```
+
+```powershell
+# Gate 训练
+cd ..\crypto_monitor_gate
+$env:EXCHANGE="gate"; $env:PORT="15202"
+python ..\manual_trading_hub\agent.py
+```
+
+```powershell
+# Gate 趋势
+cd ..\crypto_monitor_gate_bot
+$env:EXCHANGE="gate"; $env:PORT="15203"
+python ..\manual_trading_hub\agent.py
+```
+
+### 3.2 四实例 Flask
+
+在各目录按原有方式启动 `app.py`（确保 `APP_PORT` 与设置页 Flask URL 一致）。
+
+### 3.3 中控
+
+```powershell
+cd c:\Users\dekun\Desktop\crypto_monitor\manual_trading_hub
+$env:HUB_HOST="0.0.0.0"          # 仅本机可改为 127.0.0.1
+$env:HUB_PORT="5100"
+$env:HUB_BRIDGE_TOKEN="你的随机串"  # 与各实例、子代理一致
+python hub.py
+```
+
+浏览器打开：
+
+- 监控区：http://127.0.0.1:5100/monitor  
+- 下单区：http://127.0.0.1:5100/trade  
+- 系统设置：http://127.0.0.1:5100/settings  
+
+---
+
+## 4. 页面操作说明
+
+### 4.1 监控区 `/monitor`
+
+| 功能 | 说明 |
+|------|------|
+| **2×2 卡片** | 仅显示「已启用」账户；每卡含子代理持仓、浮盈、余额 |
+| **机器人持仓** | 来自实例 `/api/hub/monitor` 的 `order_monitors`（active） |
+| **关键位** | 仅 `capabilities` 含 `key` 的户；展示门控摘要（`/api/price_snapshot`） |
+| **趋势计划** | 仅 Gate 趋势户；`trend_pullback_plans` active |
+| **复盘** | 新标签打开该户 `review_url`（各实例交易记录页） |
+| **该户全平** | `POST` 子代理 `/emergency/close-all`，仅平该 API Key 仓位 |
+| **全局紧急全平** | 对所有已启用户依次全平（不含 `HUB_DISABLED_IDS` 强制关闭的 id） |
+| **自动刷新** | 默认每 5 秒请求 `/api/monitor/board` |
+
+持仓数据以 **子代理 ccxt** 为准；关键位/趋势/机器人单以 **Flask 数据库** 为准。若 Flask 未启动，卡片仍会显示 agent 持仓，但下方策略信息可能为空或报错。
+
+### 4.2 下单区 `/trade`
+
+顶部 **账户下拉** 切换目标所；下方 Tab 根据该户 **能力** 自动启用/禁用：
+
+#### Tab：人工下单
+
+- 字段与各实例「手工开仓」一致：合约、方向、止盈止损模式（价格/百分比）、趋势单/波段单、杠杆、移动保本、止损/止盈。
+- 提交后中控转发 `POST /api/hub/add_order`，逻辑与在实例网页下单相同（含以损定仓、门控等）。
+- **Gate 趋势户** 同样可使用本 Tab（保留人工下单）。
+
+#### Tab：关键位
+
+- 仅 **币安、Gate 训练、OKX**（capabilities 含 `key`）显示。
+- 类型：箱体突破、收敛突破、斐波回调、关键阻力/支撑等；模式含标准突破、箱体 1R、趋势单自填止盈。
+- 提交转发 `POST /api/hub/add_key`。
+- 页面上方会显示该实例 **关键位门控规则** 文案（来自 `/api/hub/meta`）。
+
+#### Tab：趋势回调
+
+- 仅 **Gate 趋势户**（capabilities 含 `trend`）。
+- 流程：**填写参数 → 生成预览 → 确认执行（实盘）**。
+- 预览转发 `POST /api/hub/trend/preview`；执行须带 `preview_id`，转发 `POST /api/hub/trend/execute`。
+- 预览有效期内展示补仓档位表；过期需重新生成。
+- 做空时「补仓上沿」在 UI 上提示为补仓下沿价（字段名仍为 `add_upper`，与实例一致）。
+
+操作结果在页面底部 **Toast** 显示实例返回的 flash 汇总信息。
+
+### 4.3 系统设置 `/settings`
+
+**可用**：打开 http://127.0.0.1:5100/settings ，修改表格后点 **保存设置** 即写入 `hub_settings.json`；**重新加载** 从磁盘/默认再读（会重新套用 `HUB_DISABLED_IDS`）。保存后监控区、下单区立即使用新 URL/启用状态，**无需重启 hub**。
+
+| 列 | 含义 |
+|----|------|
+| 启用 | 是否参与监控与全局全平；被 `HUB_DISABLED_IDS` 锁定的无法勾选 |
+| 显示名 | 监控卡片标题 |
+| Flask URL | 实例根地址，如 `http://127.0.0.1:5001` |
+| Agent URL | 子代理根地址，如 `http://127.0.0.1:15200` |
+| 复盘链接 | 一般为 `{Flask}/records` |
+| 能力 | 勾选 order / key / trend，控制下单区 Tab |
+| id | 与 `HUB_DISABLED_IDS`、全平 API 路径中的 id 对应 |
+
+- **保存设置**：写入 `hub_settings.json`，重启 hub 后仍生效。
+- **添加交易所**：可增第五所等，需自行启动对应 Flask + agent 并填写 URL。
+- **删**：从列表移除（保存后生效）。
+
+---
+
+## 5. 能力矩阵（下单区 Tab）
+
+| 账户 | 人工下单 | 关键位 | 趋势回调 |
+|------|:--------:|:------:|:--------:|
+| 币安 | ✓ | ✓ | — |
+| OKX | ✓ | ✓ | — |
+| Gate 训练 | ✓ | ✓ | — |
+| Gate 趋势 | ✓ | — | ✓ |
+
+---
+
+## 6. HTTP API 摘要（中控）
+
+访问控制：默认允许 **本机** 与 **RFC1918 私网**（`HUB_TRUST_LAN=true`）；公网 IP 访问返回 403。
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/settings` | 读取配置 |
+| POST | `/api/settings` | 保存配置 |
+| GET | `/api/monitor/board` | 监控聚合 |
+| POST | `/api/close/{id}` | 单户全平 |
+| POST | `/api/close-all` | 全局全平，body 可选 `exclude_ids` |
+| GET | `/api/trade/meta/{id}` | 实例 meta（门控文案等） |
+| POST | `/api/trade/order/{id}` | 人工下单 |
+| POST | `/api/trade/key/{id}` | 添加关键位 |
+| POST | `/api/trade/trend/preview/{id}` | 趋势预览 |
+| POST | `/api/trade/trend/execute/{id}` | 趋势执行 |
+
+实例侧（需 `X-Hub-Token` 或已登录）：
+
+| 路径 | 说明 |
+|------|------|
+| `/api/hub/ping` | 连通与能力 |
+| `/api/hub/meta` | 表单规则、预览 TTL 等 |
+| `/api/hub/monitor` | 关键位、机器人单、趋势计划 |
+| `/api/hub/add_order` | 人工开仓 |
+| `/api/hub/add_key` | 添加关键位 |
+| `/api/hub/trend/preview` | 趋势预览 |
+| `/api/hub/trend/execute` | 趋势执行 |
+
+---
+
+## 7. 环境变量速查
+
+### 中控 hub.py
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `HUB_HOST` | `0.0.0.0` | 监听地址 |
+| `HUB_PORT` | `5100` | 监听端口 |
+| `HUB_BRIDGE_TOKEN` | 空 | Flask 桥接令牌；可同 `CONTROL_TOKEN` |
+| `HUB_DISABLED_IDS` | `1` | 逗号分隔，强制关闭的账户 id |
+| `HUB_TRUST_LAN` | `true` | `false` 时仅本机可访问中控页面 |
+
+### 子代理 agent.py
+
+| 变量 | 说明 |
+|------|------|
+| `EXCHANGE` | `binance` / `okx` / `gate` |
+| `PORT` / `HOST` | 监听 |
+| `CONTROL_TOKEN` | 与中控一致时必填头 `X-Control-Token` |
+
+### 各实例 Flask
+
+| 变量 | 说明 |
+|------|------|
+| `HUB_BRIDGE_TOKEN` | 与中控一致 |
+| `APP_AUTH_DISABLED` | `true` 时跳过登录与令牌（仅建议本机调试） |
+
+---
+
+## 8. 安全与边界
+
+1. **中控可下单**：下单区操作会真实调用交易所逻辑，与在实例网页操作等价，请确认账户与参数。
+2. **全平为市价减仓**：监控区全平不可撤销，操作前二次确认。
+3. **子代理建议只监听 127.0.0.1**，不要对局域网暴露 API Key 通道。
+4. **公网暴露 hub**：请防火墙限制 `5100`，或 `HUB_HOST=127.0.0.1` + `HUB_TRUST_LAN=0`。
+5. **复盘不在中控**：时间筛选、导出 CSV、编辑笔记仍在各实例 `/records`。
+6. **OKX 默认关**：避免未部署 OKX 时监控卡片持续报错。
+
+---
+
+## 9. 故障排查
+
+| 现象 | 可能原因 | 处理 |
+|------|----------|------|
+| 监控卡片「子代理不可用」 | agent 未启动或端口错 | 检查 Agent URL、启动 agent |
+| 无关键位/趋势信息 | Flask 未启动或令牌错误 | 启动 app.py；核对 `HUB_BRIDGE_TOKEN` |
+| 下单返回 401 | 令牌不一致 | 四实例与中控设相同 `HUB_BRIDGE_TOKEN` |
+| 全平 401 | 子代理 `CONTROL_TOKEN` 与中控不一致 | 中控用 `X-Control-Token` 转发，需与 agent 一致 |
+| OKX 始终灰色 | `HUB_DISABLED_IDS=1` | 清空该环境变量并在设置页启用 |
+| 趋势预览成功但执行失败 | 预览过期 | 重新「生成预览」再执行 |
+| 关键位 Tab 灰色 | 该户 capabilities 无 `key` | 正常；Gate 趋势户无关键位 |
+| 局域网无法打开中控 | 防火墙 / `HUB_TRUST_LAN=0` | 放行端口或恢复默认信任私网 |
+
+手动探测实例桥接：
+
+```powershell
+$tok = "你的令牌"
+Invoke-WebRequest -Uri "http://127.0.0.1:5001/api/hub/ping" -Headers @{"X-Hub-Token"=$tok}
+```
+
+---
+
+## 10. 与旧版 README 的差异
+
+早期中控 **仅监控 + 全平**，使用环境变量 `HUB_AGENTS` 列表。当前版本改为：
+
+- **hub_settings.json**（或内置默认）管理四所 URL 与能力；
+- **三页 UI**：监控 / 下单 / 设置；
+- 通过 **hub_bridge** 调用实例下单 API。
+
+子代理 `agent.py` 仍负责持仓与全平；`HUB_AGENTS` 环境变量在新版 hub 中 **不再使用**（以设置文件为准）。
+
+更细的 Ubuntu screen / systemd 示例见同目录 **《部署文档.md》** 与 **scripts/**。
+
+---
+
+## 11. 日常推荐流程
+
+1. 启动四所 **agent** + **Flask**（OKX 按需）。
+2. 启动 **hub.py**，打开监控区确认持仓与关键位门控正常。
+3. 在下单区选账户 → 人工单 / 关键位 / 趋势（按能力）。
+4. 复盘、导出记录 → 点击监控卡片「复盘」进入对应实例。
+5. 异常行情 → 单户全平或全局紧急全平。
+
+如有新交易所，在 **系统设置** 添加一行并勾选能力，无需修改 hub.py 源码（需该所有 Flask 注册 `hub_bridge` 且 agent 已部署）。