From 55e77d6b2bd5519012ef3ee3f1aa3c34ff160698 Mon Sep 17 00:00:00 2001 From: dekun Date: Thu, 1 Oct 2026 10:49:25 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=9D=E7=A8=BF=EF=BC=9A=E4=B8=AD=E6=8E=A7?= =?UTF-8?q?=E7=AC=AC=E4=B8=80=E6=9C=9F=E8=AE=BE=E8=AE=A1=E4=B8=8E=E8=AF=B4?= =?UTF-8?q?=E6=98=8E/=E9=83=A8=E7=BD=B2=E6=96=87=E6=A1=A3=EF=BC=88?= =?UTF-8?q?=E5=85=B3=E8=81=94=20crypto=5Fokx=EF=BC=89=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 9 ++ .gitignore | 22 +++++ README.md | 19 ++++ 使用说明.md | 80 ++++++++++++++++ 设计文档.md | 255 +++++++++++++++++++++++++++++++++++++++++++++++++++ 部署文档.md | 102 +++++++++++++++++++++ 6 files changed, 487 insertions(+) create mode 100644 .env.example create mode 100644 .gitignore create mode 100644 README.md create mode 100644 使用说明.md create mode 100644 设计文档.md create mode 100644 部署文档.md diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..27939c6 --- /dev/null +++ b/.env.example @@ -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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..cba1b70 --- /dev/null +++ b/.gitignore @@ -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/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..dddce0f --- /dev/null +++ b/README.md @@ -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 +``` diff --git a/使用说明.md b/使用说明.md new file mode 100644 index 0000000..c78f854 --- /dev/null +++ b/使用说明.md @@ -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) | 仓库入口摘要 | diff --git a/设计文档.md b/设计文档.md new file mode 100644 index 0000000..7708ee5 --- /dev/null +++ b/设计文档.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 `（二选一，实现时定一种）。 + +### 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 | 初稿：双仓、公网客户端、内嵌+新标签、总览第一期 | diff --git a/部署文档.md b/部署文档.md new file mode 100644 index 0000000..44717f6 --- /dev/null +++ b/部署文档.md @@ -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>:` + +生产可用 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 草案、联调清单（代码待实现） |