Files

T

dekun d20acaf852 第一期骨架：登录、实例登记、多机总览、内嵌/新标签打开。

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

2026-10-01 10:54:07 +08:00

9.3 KiB

Raw Blame History

crypto_okx_hub 设计文档（第一期）

状态：第一期骨架已落地（登录 / 实例 CRUD / 总览拉取 / 内嵌+新标签 SSO）
仓库：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 补）：

只读 Bridge API（Token 鉴权）— 持仓/资金/模式快照
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 字段便于演进）

{
  "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. 验收标准（第一期）

中控能登记 ≥2 个公网客户端（URL + Token）。
总览能显示各机在线状态、浮盈、持仓列表（或空仓）。
「打开」进入内嵌工作台，iframe 内可见客户端期权页。
「新标签打开」可独立打开同一客户端。
关掉某客户端进程后，总览在一轮拉取后显示离线/错误，不拖垮整页。
文档写明关联仓库与部署步骤（本仓库已具备设计/说明/部署文档）。

12. 待实现时拍板的小项

Bridge 路径最终用 /api/hub/options/snapshot 还是复用现有 hub 扩展点名。
Embed 默认进 /embed 还是 /options。
SSO 第一期是否必须（建议必须，否则 iframe 二次登录体验差）。

设计以上述默认为准；写代码时若有变，改本文件「变更记录」。

变更记录

日期	说明
2026-10-01	初稿：双仓、公网客户端、内嵌+新标签、总览第一期
2026-10-01	骨架实现：Flask 中控 + 客户端 Bridge/SSO

9.3 KiB Raw Blame History Unescape Escape