crypto_okx_hub/使用说明.md

# 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) | 仓库入口摘要 |