初稿：中控第一期设计与说明/部署文档（关联 crypto_okx）。

2026-10-01 10:49:25 +08:00
commit 55e77d6b2b
6 changed files with 487 additions and 0 deletions
@@ -0,0 +1,255 @@
+# crypto_okx_hub 设计文档（第一期）
+
+> 状态：**设计定稿，待实现**  
+> 仓库：[https://git.bz121.com/dekun/crypto_okx_hub.git](https://git.bz121.com/dekun/crypto_okx_hub.git)
+
+---
+
+## 1. 目标与边界
+
+### 1.1 第一期要做
+
+| 能力 | 说明 |
+|------|------|
+| 中控登录 | 独立账号（与客户端账号分离） |
+| 客户端注册表 | 名称、公网 URL、Bridge Token、标签、启用状态 |
+| 多机持仓总览 | 定时拉取各客户端只读快照，卡片/表格展示持仓与浮盈 |
+| 一键打开 | **默认内嵌**中控（iframe / embed 壳）；同时提供 **新标签打开** |
+| 在线探测 | 心跳/拉快照失败则标离线 |
+
+### 1.2 第一期明确不做
+
+- 中控代下单 / 代改 env / 统一密钥
+- 跨机资金划转、策略编排引擎
+- 把中控塞进每台 `crypto_okx` 同进程部署
+
+### 1.3 原则
+
+- **中控 = 编排 + 只读聚合**；**客户端 = 唯一执行面**（密钥、下单、模拟盘均在客户端）。
+- 浏览器「打开客户端」依赖用户能访问客户端 **公网域名**；中控拉快照依赖中控机器能访问同一公网 URL。
+
+---
+
+## 2. 关联仓库
+
+| 仓库 | 角色 | 地址 |
+|------|------|------|
+| **crypto_okx_hub** | 中控（本仓库） | https://git.bz121.com/dekun/crypto_okx_hub.git |
+| **crypto_okx** | 期权客户端 / 执行机 | https://git.bz121.com/dekun/crypto_okx.git |
+
+客户端对外：**公网域名**（如 `https://okx-eth.example.com`）。  
+中控可部署在：**局域网机器** 或云服务器（第一期可用局域网）。
+
+协议靠约定对齐，不强制 monorepo。客户端侧需提供（实现阶段在 `crypto_okx` 补）：
+
+1. 只读 Bridge API（Token 鉴权）— 持仓/资金/模式快照  
+2. Embed 入口 — 供中控 iframe 打开（可带短期 SSO / token）
+
+---
+
+## 3. 总体架构
+
+```
+┌─────────────────────┐         HTTPS 公网          ┌──────────────────────┐
+│  浏览器（操作员）    │────────────────────────────▶│ crypto_okx Worker A  │
+│                     │  iframe / 新标签打开          │ 公网域名 + 密钥/DB   │
+│  ┌───────────────┐  │                             └──────────────────────┘
+│  │ crypto_okx_hub│  │  中控服务端拉快照
+│  │ (局域网或云)  │──┼────────────────────────────▶┌──────────────────────┐
+│  └───────────────┘  │  GET /api/hub/options/...    │ crypto_okx Worker B  │
+└─────────────────────┘  Header: X-Hub-Token         └──────────────────────┘
+```
+
+- **中控 → 客户端**：服务端用 `base_url + bridge_token` 拉快照（不经过浏览器 CORS）。  
+- **浏览器 → 客户端**：内嵌 iframe 或新标签，走客户端公网域名（用户网络可达即可）。
+
+---
+
+## 4. 中控信息架构（页面）
+
+| 页面 | 用途 |
+|------|------|
+| `/login` | 中控登录 |
+| `/` 或 `/dashboard` | **多机总览**：每台一卡片（在线、模式 sim/live、总浮盈、持仓笔数、简表） |
+| `/instances` | 客户端 CRUD（名称、URL、Token、标签、启用） |
+| `/desk?id=…` | **工作台**：左侧实例列表，右侧 **iframe 内嵌** 该客户端；工具条含「新标签打开」 |
+| （可选）`/desk` 无 id | 提示先选实例 |
+
+总览卡片操作：
+
+- **打开（内嵌）** → `/desk?id=`  
+- **新标签** → `window.open(public_url + embed路径)`  
+- 显示最近拉取时间 / 错误信息
+
+---
+
+## 5. 数据模型（中控本地 SQLite）
+
+### 5.1 `hub_users`（可选极简：仅 env 账号也行）
+
+第一期可用 `.env` 的 `HUB_USERNAME` / `HUB_PASSWORD`，表可后补。
+
+### 5.2 `hub_instances`（核心）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | INTEGER PK | |
+| name | TEXT | 展示名，如 `ETH-保守` |
+| base_url | TEXT | 公网根，`https://okx-eth.example.com`（无尾斜杠） |
+| bridge_token | TEXT | 与客户端 `HUB_BRIDGE_TOKEN` 一致 |
+| embed_path | TEXT | 默认 `/embed` 或 `/options`（以实现为准） |
+| tags | TEXT | JSON 或逗号标签 |
+| enabled | INTEGER | 1=参与拉取 |
+| sort_order | INTEGER | |
+| created_at / updated_at | TEXT | |
+
+拉取结果可 **内存缓存**（第一期），不必落库；需要历史再加 `hub_snapshot_cache`。
+
+---
+
+## 6. 客户端 Bridge 约定（crypto_okx 侧，实现期补齐）
+
+### 6.1 鉴权
+
+```
+GET {base_url}/api/hub/options/snapshot
+Header: X-Hub-Token: <与 HUB_BRIDGE_TOKEN 相同>
+```
+
+或 `Authorization: Bearer <token>`（二选一，实现时定一种）。
+
+### 6.2 响应草案（version 字段便于演进）
+
+```json
+{
+  "ok": true,
+  "version": 1,
+  "instance": {
+    "label": "okx_sim",
+    "mode": "sim",
+    "options_enabled": true
+  },
+  "funds": {
+    "total_usdt": 0,
+    "trading_usdt": 0
+  },
+  "pnl": {
+    "unrealized_usdt": 0
+  },
+  "positions": [
+    {
+      "inst_id": "ETH-USD-...",
+      "opt_type": "C",
+      "sheets": 1,
+      "pnl_usdt": 12.3,
+      "mark": 0.01
+    }
+  ],
+  "ts": "2026-10-01 10:00:00"
+}
+```
+
+字段与现有 `lib/options/options_hub_lib.py` 的 `build_options_hub_snapshot` 对齐即可，减少客户端改动。
+
+### 6.3 Embed / 打开
+
+- 内嵌 URL：`{base_url}{embed_path}`，建议客户端提供可嵌套的 `/embed`（已有壳可复用）。  
+- 新标签：同一 URL。  
+- SSO（实现期）：中控签发短时 `hub_sso` query，客户端校验后建 session；第一期也可先要求用户在 iframe 内再登一次（体验较差，优先做短期 token）。
+
+---
+
+## 7. 中控内部模块（建议目录）
+
+```
+crypto_okx_hub/
+  app.py                 # Flask 入口
+  requirements.txt
+  .env.example
+  ecosystem.config.cjs   # 可选 PM2
+  lib/
+    auth_lib.py          # 登录 session
+    instances_lib.py     # 注册表 CRUD
+    bridge_client_lib.py # 拉取各机 snapshot（超时、并发）
+    dashboard_lib.py     # 聚合总览
+  templates/             # 登录、总览、实例管理、desk(iframe)
+  static/
+  deploy/                # 安装脚本（第二期可细化）
+  使用说明.md
+  部署文档.md
+  设计文档.md
+```
+
+技术选型（第一期）：
+
+- Python + Flask（与客户端同栈，好维护）  
+- SQLite 存注册表  
+- 服务端 `concurrent.futures` / 线程池并发拉多机  
+- 前端：总览轮询 5–15s；desk 页 iframe + 顶栏按钮
+
+---
+
+## 8. 打开方式详细设计
+
+| 方式 | 行为 | 默认 |
+|------|------|------|
+| 内嵌 | 进入 `/desk?id=`，右侧 iframe `src=客户端embed URL` | **是** |
+| 新标签 | `target=_blank` 打开同一 URL | 提供按钮 |
+
+注意：
+
+- iframe 需客户端不设过于严格的 `X-Frame-Options: DENY`（或对中控 Origin 放行）。实现期在 `crypto_okx` 配置。  
+- 混合内容：中控若 HTTPS，客户端必须 HTTPS。局域网中控用 HTTP 时，客户端 HTTPS iframe 一般仍可用。  
+- Cookie：跨站 iframe 第三方 Cookie 受限 → **强烈建议短期 SSO token**，不要依赖第三方 Cookie。
+
+---
+
+## 9. 安全
+
+| 项 | 做法 |
+|----|------|
+| Bridge Token | 每客户端独立；中控库中加密或至少权限收紧；只服务端使用 |
+| 中控登录 | 强密码；仅局域网可再加 IP 限制 |
+| 客户端防火墙 | 可选：仅允许中控出口 IP 访问 `/api/hub/*` |
+| 密钥 | 永不到中控 |
+| SSO | 短时、一次性、绑定 instance_id |
+
+---
+
+## 10. 实现分期
+
+| 阶段 | 内容 | 仓库 |
+|------|------|------|
+| **H1** | 中控骨架：登录、实例 CRUD、总览拉快照、desk 内嵌 + 新标签 | hub |
+| **C1** | 客户端：稳定 `/api/hub/options/snapshot` + Token；embed 允许被中控嵌；SSO | crypto_okx |
+| **H2** | 总览体验：离线红标、错误条、标签筛选 | hub |
+| 以后 | 告警汇总、代操作（慎重） | 双仓 |
+
+建议顺序：**先 C1 最小快照可用 → 再 H1 总览能绿**；或 H1 用 mock 快照并行，联调时接真 API。
+
+---
+
+## 11. 验收标准（第一期）
+
+1. 中控能登记 ≥2 个公网客户端（URL + Token）。  
+2. 总览能显示各机在线状态、浮盈、持仓列表（或空仓）。  
+3. 「打开」进入内嵌工作台，iframe 内可见客户端期权页。  
+4. 「新标签打开」可独立打开同一客户端。  
+5. 关掉某客户端进程后，总览在一轮拉取后显示离线/错误，不拖垮整页。  
+6. 文档写明关联仓库与部署步骤（本仓库已具备设计/说明/部署文档）。
+
+---
+
+## 12. 待实现时拍板的小项
+
+- Bridge 路径最终用 `/api/hub/options/snapshot` 还是复用现有 hub 扩展点名。  
+- Embed 默认进 `/embed` 还是 `/options`。  
+- SSO 第一期是否必须（建议必须，否则 iframe 二次登录体验差）。
+
+设计以上述默认为准；写代码时若有变，改本文件「变更记录」。
+
+### 变更记录
+
+| 日期 | 说明 |
+|------|------|
+| 2026-10-01 | 初稿：双仓、公网客户端、内嵌+新标签、总览第一期 |