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

2026-10-01 10:49:25 +08:00
commit 55e77d6b2b
6 changed files with 487 additions and 0 deletions
@@ -0,0 +1,9 @@
+# crypto_okx_hub — 设计阶段占位；实现时补全
+APP_HOST=0.0.0.0
+APP_PORT=5100
+HUB_USERNAME=admin
+HUB_PASSWORD=change-me
+FLASK_SECRET_KEY=change-me-to-long-random
+DB_PATH=hub.db
+HUB_PULL_INTERVAL_SEC=10
+HUB_PULL_TIMEOUT_SEC=5
@@ -0,0 +1,22 @@
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+
+# Env & data
+.env
+*.db
+*.db-journal
+hub.db
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
@@ -0,0 +1,19 @@
+# crypto_okx_hub
+
+OKX **期权多机中控**：登录后查看各期权客户端持仓总览，并在中控内嵌（或新标签）打开客户端。
+
+| 项 | 说明 |
+|----|------|
+| 云仓库 | [https://git.bz121.com/dekun/crypto_okx_hub.git](https://git.bz121.com/dekun/crypto_okx_hub.git) |
+| 关联客户端 | [crypto_okx](https://git.bz121.com/dekun/crypto_okx.git)（期权执行机，公网域名部署） |
+| 文档 | [使用说明.md](./使用说明.md) · [部署文档.md](./部署文档.md) · [设计文档.md](./设计文档.md) |
+
+**第一期范围：** 多机持仓总览 + 内嵌打开客户端（可新标签）。中控不下单、不存交易所密钥。
+
+```bash
+# 本地开发（实现后）
+# python -m venv .venv && .venv\Scripts\activate
+# pip install -r requirements.txt
+# copy .env.example .env
+# python app.py
+```
@@ -0,0 +1,80 @@
+# crypto_okx_hub 使用说明
+
+**仓库:** [https://git.bz121.com/dekun/crypto_okx_hub.git](https://git.bz121.com/dekun/crypto_okx_hub.git)
+
+OKX **期权多机中控**：在一个入口查看多台期权客户端的持仓总览，并在中控内打开客户端操作。
+
+部署见 **[部署文档.md](./部署文档.md)**；架构见 **[设计文档.md](./设计文档.md)**。
+
+---
+
+## 1. 关联仓库（必读）
+
+| 仓库 | 角色 | 地址 |
+|------|------|------|
+| **本仓库 crypto_okx_hub** | 中控：登录、实例登记、多机总览、内嵌/新标签打开 | [https://git.bz121.com/dekun/crypto_okx_hub.git](https://git.bz121.com/dekun/crypto_okx_hub.git) |
+| **crypto_okx** | 期权客户端（执行机）：密钥、开平仓、模拟盘、持仓与提醒 | [https://git.bz121.com/dekun/crypto_okx.git](https://git.bz121.com/dekun/crypto_okx.git) |
+
+关系简述：
+
+- 每个策略 / 账户部署一台（或多进程）**crypto_okx**，挂 **公网域名**。  
+- **中控只部署一次**（可局域网电脑或云机），在后台登记各客户端的公网 URL 与 Bridge Token。  
+- **交易所 API 密钥只在客户端**；中控不存、不代下单（第一期）。
+
+---
+
+## 2. 第一期能做什么
+
+| 功能 | 说明 |
+|------|------|
+| 多机持仓总览 | 按客户端卡片展示在线状态、sim/live、浮盈、持仓摘要 |
+| 内嵌打开 | 在中控工作台 iframe 中打开该客户端（默认） |
+| 新标签打开 | 浏览器新标签直达同一客户端公网地址 |
+| 实例管理 | 增删改：名称、公网 URL、Token、标签、是否启用 |
+
+**不做：** 中控里直接下单、改客户端 env、保管 OKX 密钥。
+
+---
+
+## 3. 使用流程（实现后）
+
+1. 部署并登录中控（账号见中控 `.env`）。  
+2. **实例管理** 中添加客户端：  
+   - 名称（如 `ETH-主策略`）  
+   - 公网根地址（如 `https://okx-eth.example.com`）  
+   - Bridge Token（与该客户端 `.env` 的 `HUB_BRIDGE_TOKEN` 一致）  
+3. 打开 **总览**：确认各机在线且有持仓/空仓数据。  
+4. 点 **打开** → 进入内嵌工作台操作期权；需要独立窗口时点 **新标签打开**。
+
+---
+
+## 4. 对客户端的要求
+
+每台 crypto_okx 需（实现阶段在客户端仓库完成）：
+
+1. 公网 HTTPS（或至少浏览器与中控都能访问的 URL）。  
+2. 配置 `HUB_BRIDGE_TOKEN`，并开放中控约定的只读快照 API。  
+3. 允许被中控页面 iframe 嵌入（或提供 embed 入口 + 短期登录链）。
+
+客户端日常操作仍以该机页面为准；中控是「总台 + 快捷入口」。
+
+---
+
+## 5. 网络说明
+
+| 链路 | 谁连谁 | 要求 |
+|------|--------|------|
+| 总览拉数 | 中控服务器 → 客户端公网 URL | 中控出口能访问客户端 |
+| 内嵌/新标签 | 操作员浏览器 → 客户端公网 URL | 操作员网络能打开客户端 |
+
+中控放在 **局域网** 时：只要上面两条仍成立即可（常见：客户端公网域名，人在家访问局域网中控）。
+
+---
+
+## 6. 文档索引
+
+| 文档 | 内容 |
+|------|------|
+| [设计文档.md](./设计文档.md) | 架构、数据表、API 约定、验收标准 |
+| [部署文档.md](./部署文档.md) | 安装、环境变量、与客户端联调 |
+| [README.md](./README.md) | 仓库入口摘要 |
@@ -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 | 初稿：双仓、公网客户端、内嵌+新标签、总览第一期 |
@@ -0,0 +1,102 @@
+# crypto_okx_hub 部署文档
+
+**仓库:** [https://git.bz121.com/dekun/crypto_okx_hub.git](https://git.bz121.com/dekun/crypto_okx_hub.git)
+
+配套说明：**[使用说明.md](./使用说明.md)** · **[设计文档.md](./设计文档.md)**  
+关联客户端仓库：[crypto_okx](https://git.bz121.com/dekun/crypto_okx.git)
+
+> 当前仓库处于 **设计定稿 / 代码待实现**。下文为第一期部署约定；可执行安装脚本随实现一并补齐。
+
+---
+
+## 1. 部署拓扑（推荐）
+
+```
+[局域网 PC 或一台云机]          [云服务器 A]              [云服务器 B]
+   crypto_okx_hub      ──拉快照──▶  crypto_okx            crypto_okx
+   (中控只一份)                    公网域名 A              公网域名 B
+                                   HUB_BRIDGE_TOKEN=xxx    HUB_BRIDGE_TOKEN=yyy
+```
+
+- 客户端：**必须**能被浏览器与中控以 **公网域名（建议 HTTPS）** 访问。  
+- 中控：可局域网；需能访问各客户端公网 URL。
+
+---
+
+## 2. 中控环境变量（草案）
+
+实现后提供 `.env.example`，核心项预计包括：
+
+| 变量 | 说明 |
+|------|------|
+| `APP_HOST` / `APP_PORT` | 例如 `0.0.0.0` / `5100` |
+| `HUB_USERNAME` / `HUB_PASSWORD` | 中控登录 |
+| `FLASK_SECRET_KEY` | Session |
+| `DB_PATH` | 注册表 SQLite，默认 `./hub.db` |
+| `HUB_PULL_INTERVAL_SEC` | 总览拉取间隔，默认 `10` |
+| `HUB_PULL_TIMEOUT_SEC` | 单机超时，默认 `5` |
+
+**不要**在中控配置任何 `OKX_API_*`。
+
+---
+
+## 3. 客户端侧（crypto_okx）联调清单
+
+在每台客户端 `.env`（名称以实现为准）：
+
+| 变量 | 说明 |
+|------|------|
+| `HUB_BRIDGE_TOKEN` | 与中控登记的 Token 一致，足够长随机串 |
+| （可选）`HUB_EMBED_FRAME_ANCESTORS` | 允许嵌入的中控 Origin |
+
+并确认：
+
+1. 公网 DNS → 该机；反向代理 HTTPS。  
+2. 快照 API 返回 `ok: true`（见设计文档 §6）。  
+3. Embed 路径可打开（默认倾向 `/embed`）。
+
+防火墙可选：仅放行中控出口 IP 访问 `/api/hub/*`。
+
+---
+
+## 4. 安装步骤（实现后）
+
+本地 / 局域网示意：
+
+```bash
+git clone https://git.bz121.com/dekun/crypto_okx_hub.git
+cd crypto_okx_hub
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+cp .env.example .env        # 编辑账号端口
+python app.py
+```
+
+访问：`http://<中控局域网IP>:<APP_PORT>`
+
+生产可用 PM2（实现后提供 `ecosystem.config.cjs`），安装路径建议 `/opt/crypto_okx_hub`。
+
+---
+
+## 5. 联调验收
+
+1. 中控添加 2 个客户端（不同公网域名 + Token）。  
+2. 总览两卡均在线，持仓/浮盈与客户端页面大致一致。  
+3. 「打开」内嵌可见期权页；「新标签」独立打开。  
+4. `pm2 stop` 一台客户端后，总览该卡变离线，另一台正常。
+
+---
+
+## 6. 与客户端部署文档的关系
+
+- 客户端安装、PM2、实盘密钥：见 **crypto_okx** 仓库内 [部署文档.md](https://git.bz121.com/dekun/crypto_okx/src/branch/main/部署文档.md) 等。  
+- 本仓库只描述 **中控自身** 及如何指向已部署的客户端。
+
+---
+
+## 变更记录
+
+| 日期 | 说明 |
+|------|------|
+| 2026-10-01 | 初稿：双仓拓扑、env 草案、联调清单（代码待实现） |