dekun/eth_hedge_sim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial eth_hedge_sim: P0 market, auth UI, one-click deploy.

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
dekun
2026-07-24 16:33:25 +08:00
commit e51f357b48
49 changed files with 4783 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/代码结构.md
+283
View File
@@ -0,0 +1,283 @@
# eth_hedge_sim — 代码结构
> 本文描述目标仓库目录与模块职责。当前阶段以文档为准；业务代码按阶段逐步添加。
> 可从 `crypto_monitor` **复制** 有用片段到本仓库后改造；**禁止修改** 现网仓库内文件。
---
## 1. 根目录总览
```text
eth_hedge_sim/
├── README.md
├── .gitignore
├── .env.example # 无密钥的示例；真 .env 不上库
├── package.json # 若前端/Node；或改用 Python 则 requirements.txt
├── requirements.txt # 后端若用 Python
├── docs/
│ ├── 开发方案.md # 业务与部署方案（本文档姐妹篇）
│ └── 代码结构.md # 本文件
├── deploy/
│ ├── ecosystem.config.cjs # PM2：仅本项目进程
│ └── pull_and_restart.sh # git pull + 构建 + pm2 reload（不碰现网）
├── backend/ # API + 行情 + 策略 + 本地撮合
│ ├── app/
│ │ ├── main.py # 或 index.ts：进程入口
│ │ ├── config.py
│ │ ├── api/ # HTTP 路由
│ │ ├── ws/ # 向前端推送
│ │ ├── market/ # OKX 只读行情
│ │ ├── strategy/ # 自动对冲状态机
│ │ ├── sim/ # 本地撮合与账本
│ │ ├── live/ # 实盘适配器（后期，默认关闭）
│ │ ├── models/ # DB 模型 / schema
│ │ └── services/ # 组、统计、设置等应用服务
│ ├── data/ # 本地 SQLite 等（gitignore 数据文件）
│ └── tests/
├── frontend/ # OKX 风格 Web
│ ├── index.html
│ ├── package.json
│ ├── src/
│ │ ├── main.tsx
│ │ ├── App.tsx
│ │ ├── layouts/ # 导航壳
│ │ ├── pages/
│ │ │ ├── Plan.tsx # 自动对冲计划
│ │ │ ├── Trades.tsx # 交易记录
│ │ │ ├── Stats.tsx # 统计
│ │ │ └── Settings.tsx # 系统设置
│ │ ├── components/ # 盘口、组标识、持仓条等
│ │ ├── api/ # 调后端
│ │ └── styles/ # OKX 深色交易台风
│ └── dist/ # 构建产物（可部署由 API 托管或 nginx）
└── scripts/ # 运维/一次性工具（可选）
└── smoke_market.py # 只读行情连通性检查
```
技术栈可在开工时二选一（建议尽快定一种，避免双栈）：
- **推荐 A**：后端 Python（FastAPI）+ 前端 React/Vite（与现网 Python 生态接近，便于复制行情代码）。
- **推荐 B**：全 Node（Nest/Express + React）。
下文按 **推荐 A** 描述模块；若选 B，目录名对应平移即可。
---
## 2. 后端模块职责
### 2.1 `backend/app/market/` — 行情（OKX 实盘只读）
```text
market/
├── okx_rest.py # 合约列表、到期、启动对齐
├── okx_ws.py # 永续 + 期权盘口订阅
├── instruments.py # 解析「次日 16:00」到期、ATM 行权价
├── book_cache.py # 买一/卖一/深度内存缓存
└── types.py # Quote / Depth 结构
```
职责：
- 只拉行情，**不调用交易接口**。
- 对外提供：永续买卖一、Call/Put 买卖一与深度、标记价。
- 可选：行情快照落盘，供 P4 回放。
可参考现网 OKX WS/REST 实现，复制后改成本模块 API。
### 2.2 `backend/app/sim/` — 本地模拟
```text
sim/
├── matcher.py # 撮合：永续市价；期权吃买卖一；滑点=1×f；双边手续费
├── ledger.py # 虚拟资金、占用、流水
├── liquidity.py # 买一深度是否覆盖 2 ETH
└── pricing.py # 成交价公式（含 f）
```
成交价口径（与开发方案一致）：
| 腿 | 动作 | 基准 | 成交价 |
|----|------|------|--------|
| 永续 | 开多 / 平空 | 卖一 | 基准 × (1+f) |
| 永续 | 开空 / 平多 | 买一 | 基准 × (1-f) |
| 期权 | 买入 | 卖一 | 基准 × (1+f) |
| 期权 | 卖出 | 买一 | 基准 × (1-f) |
另扣：`手续费 = 名义 × f`。
### 2.3 `backend/app/strategy/` — 自动对冲
```text
strategy/
├── clock.py # 业务窗：D 16:00～D+1 08:00；次数≤3
├── signal.py # Call 卖一 vs Put 卖一 → 方向
├── exits.py # 权利金覆盖 / 30 点
├── sizing.py # 永续 1 ETH、期权 2 ETH（写死）
├── group.py # 组 ID：G-YYYYMMDD-NN
└── engine.py # 状态机：空仓→开仓→盯盘→全平→下一组
```
状态机要点：
- 同时最多 1 组。
- 平完才允许下一组；达 3 次或过 08:00 则停开。
- 每组锁定 `initial_premium`。
### 2.4 `backend/app/live/` — 实盘（P5）
```text
live/
├── okx_trade.py # 永续市价单；期权吃一对应下单
└── adapter.py # 与 sim.matcher 相同接口，便于切换
```
默认关闭；仅 `MODE=LIVE` 且设置页确认后启用。
### 2.5 `backend/app/api/` + `ws/`
```text
api/
├── plan.py # 当前组、策略启停、紧急全平
├── trades.py # 组列表、组成交明细
├── stats.py # 汇总统计
└── settings.py # 读写配置（脱敏）
ws/
└── push.py # market.snapshot / group.updated / fill.created / strategy.state
```
### 2.6 `backend/app/models/` — 数据
建议表：
| 表 | 用途 |
|----|------|
| `groups` | 组头：方向、开平时间、初始权利金、平仓原因、盈亏 |
| `fills` | 成交：腿、价、量、滑点、手续费 |
| `positions` | 当前仓（最多一组两腿） |
| `ledger_entries` | 资金流水 |
| `settings` | 配置 KV |
| `market_ticks` | 可选行情快照 |
---
## 3. 前端结构
```text
frontend/src/pages/
├── Plan.tsx # 自动对冲计划（主盘）
├── Trades.tsx # 交易记录（按组）
├── Stats.tsx # 统计
└── Settings.tsx # 系统设置
frontend/src/components/
├── Nav.tsx # 四项导航
├── GroupBadge.tsx # 组 ID + 状态色
├── PerpOrderBook.tsx # 永续盘口
├── OptionOrderBook.tsx # Call/Put；卖一选向高亮、买一平仓
├── PositionBar.tsx # 1 ETH + 2 ETH、浮盈、触发进度
└── EquityChart.tsx # 统计页曲线
```
导航文案固定：
1. 自动对冲计划
2. 交易记录
3. 统计
4. 系统设置
---
## 4. 部署相关文件
### 4.1 `deploy/ecosystem.config.cjs`（示意）
```js
module.exports = {
apps: [
{
name: 'eth-hedge-api',
cwd: '/opt/eth_hedge_sim/backend',
script: 'uvicorn',
args: 'app.main:app --host 0.0.0.0 --port 8100',
interpreter: 'python3',
env: { MODE: 'SIM' },
},
// 若前端独立静态服务可再加 eth-hedge-web；也可由 nginx 指到 frontend/dist
],
};
```
### 4.2 `deploy/pull_and_restart.sh`（原则）
- 仅 `cd /opt/eth_hedge_sim && git pull`
- 安装依赖 / `frontend` build
- `pm2 startOrReload deploy/ecosystem.config.cjs --update-env`
- **禁止** `pm2 restart all`，**禁止** 调用现网 `crypto_monitor` 的部署脚本
---
## 5. 进程与端口（建议，可改）
| 服务 | 端口 | PM2 名 |
|------|------|--------|
| API + WS | `8100` | `eth-hedge-api` |
| 前端（若独立） | `8101` 或 nginx 反代 | `eth-hedge-web` |
与现网端口、进程名全部错开。
---
## 6. 配置与密钥
```text
.env.example # 提交到 git
.env # 仅服务器 / 本机，gitignore
```
关键项：
- `MODE=SIM|LIVE`
- `OKX_API_KEY / SECRET / PASSPHRASE`（SIM 阶段只读权限即可）
- `FEE_RATE`（滑点自动 = 1 × FEE_RATE）
- `INITIAL_EQUITY`
- `MAX_ROUNDS=3`
- `OPEN_HHMM=16:00` / `STOP_OPEN_HHMM=08:00`
- `TZ=Asia/Shanghai`
---
## 7. 从现网复制代码时的规则
| 允许 | 禁止 |
|------|------|
| 复制 OKX 行情订阅、签名、深度解析到本仓库 | 修改 `C:\Users\dekun\Desktop\crypto_monitor` 下任何文件 |
| 复制「买一流动性检查」思路后重写 | 把本项目塞进现网 monorepo 一起 PM2 |
| 新建本仓库的 `.env` | 默认使用现网交易 Key 做模拟（模拟不需要交易权限） |
复制后在本仓库内自由修改；现网保持原样。
---
## 8. 建议落地顺序（与开发方案分期对应）
1. 建 git 远程 → clone 到本机该目录与服务器 `/opt/eth_hedge_sim`
2. P0：`market/` 通行情
3. P1：`sim/` 手动开平
4. P2：`strategy/` 自动化
5. P3：`frontend/` 四页
6. `deploy/` PM2 上独立机
7. P5：`live/` 实盘开关
---
## 9. 当前仓库已有文件
```text
eth_hedge_sim/
└── docs/
├── 开发方案.md
└── 代码结构.md
```
负责人创建远程仓库后，将本目录作为首批提交即可；业务代码按上表目录逐步添加。
docs/开发方案.md
+221
View File
@@ -0,0 +1,221 @@
# eth_hedge_sim — 自动对冲模拟盘开发方案
> 独立项目，与现网 `crypto_monitor` / `zk.hyf2.cc` **无部署、无进程、无密钥共用关系**。
> 可参考现有仓库的实现思路或复制片段到本仓库，但 **禁止修改** `crypto_monitor` 内任何文件。
> Git 仓库由负责人自行创建；本目录为本地工程骨架与文档。
---
## 1. 项目定位
| 项 | 约定 |
|----|------|
| 项目名 / 目录名 | `eth_hedge_sim` |
| 本机路径 | `C:\Users\dekun\Desktop\新建文件夹\eth_hedge_sim` |
| 云服务器 | **单独一台 Ubuntu**（或同机不同目录/不同 PM2 进程名，且与现网隔离） |
| 部署 | PM2 |
| 行情 | OKX **实盘只读** API（REST + WebSocket） |
| 成交（默认） | **本地模拟撮合 + 本地虚拟资金**（非 OKX 模拟盘） |
| 后期 | 支持切换 **实盘下单**（显式开关 + 二次确认） |
### 1.1 硬边界
- 模拟阶段：**零交易类 API**（不下单、不撤单、不改单）。
- 永续：全部 **市价**（不做限价）。
- 期权：只吃 **买一 / 卖一**。
- 仓位固定：永续 **1 ETH**，期权 **2 ETH** 名义（始终 2 倍，与权利金金额无关）。
- 卖一比对 **仅用于选方向**；平仓用买一，并检查买一流动性。
---
## 2. 业务规则
### 2.1 时间与次数
- 期权合约：选 **次日 16:00** 到期。
- 可开仓窗：业务日 **D 日 16:00** 起 → **D+1 日 08:00** 前。
- **D+1 08:00 起禁止新开仓**（已有持仓仍按平仓规则处理，不强制到点清仓——若改规则在设置中可配）。
- 每个业务窗最多 **3 轮**；同时最多 **1 组**仓；平完才能开下一组。
### 2.2 方向（Call 卖一 vs Put 卖一）
| 条件 | 永续 | 期权 |
|------|------|------|
| Call 卖一 > Put 卖一 | 市价做多 1 ETH | 做空 2 ETH 名义 |
| Call 卖一 < Put 卖一 | 市价做空 1 ETH | 做多 2 ETH 名义 |
| 相等 | 不开仓，等待 | — |
> **实现前待定稿**：期权「做多/做空」具体买卖 Call 还是 Put（或组合）；行权价选择（建议默认 ATM / 最接近标记价的同一行权价）。
### 2.3 平仓（任一触发 → 该组全平）
1. **权利金覆盖**：永续浮盈 ≥ 该组开仓锁定的 **期权初始权利金总额**（建议触发口径 **不含手续费**；费用单独记账）。此时期权侧通常仍有盈余/剩余价值，属预期内。
2. **方向 30 点**：期权方向运行满 30 点 → 全平（**待定**：标的 ETH 点数 vs 权利金点数）。
平仓执行：
- 永续：本地市价平仓。
- 期权：吃买一；买一深度需覆盖 2 ETH 名义；不足则不成交并记「流动性不足」，默认继续等待。
### 2.4 组（Group）标识
每一轮开→平为一组，稳定 ID 例如：`G-YYYYMMDD-序号`（`G-20260724-01`）。
前端、交易记录、统计全部按组聚合。
---
## 3. 本地撮合与费用
### 3.1 手续费与滑点
- 永续、期权 **均收取手续费**，费率可配置，默认按 OKX taker 档位。
- **滑点 = 1 倍手续费**（费率 `f` 时，滑点幅度按 `f` 计入成交价；手续费另扣）。
### 3.2 永续（仅市价）
本地市价定义（无真实交易所市价单时）：
- 开多 / 平空：基准 **卖一**，成交价 = 基准 × `(1 + f)`，再扣手续费。
- 开空 / 平多：基准 **买一**，成交价 = 基准 × `(1 - f)`，再扣手续费。
- UI 与引擎均不提供限价单。
### 3.3 期权（只吃买卖一）
- 买入：吃 **卖一**，成交价 = 卖一 × `(1 + f)`，再扣费。
- 卖出：吃 **买一**，成交价 = 买一 × `(1 - f)`，再扣费。
- 开仓成交后锁定该组 **初始权利金总额**（按成交价 × 2 ETH 名义）。
### 3.4 本地账本
虚拟权益、可用、占用、持仓、成交、滑点、手续费、按组盈亏；持久化 SQLite（或等价本地 DB）。
**不是** OKX 模拟盘余额。
---
## 4. 系统架构
```
OKX 实盘只读行情 (WS/REST)
↓
market 行情网关（本地缓存/可选落盘）
↓
strategy 策略状态机（时间窗 / 选向 / 开平 / 3 次 / 组 ID）
↓
executor
├─ SIM（默认）→ LocalMatcher + Ledger
└─ LIVE（后期）→ OkxTradeAdapter
↓
API + WebSocket 推送
↓
Frontend（OKX 风格四页）
```
### 4.1 与现网隔离
| | crypto_monitor（现网） | eth_hedge_sim（本项目） |
|--|----------------------|------------------------|
| 代码仓 | 独立 | 独立（负责人自建 remote） |
| 服务器目录 | 如 `/opt/crypto_monitor` | 如 `/opt/eth_hedge_sim`（另定） |
| PM2 进程名 | 现有一套 | **新名字**，如 `eth-hedge-api` / `eth-hedge-web` |
| 域名/端口 | 现网 | 独立端口或独立域名 |
| 密钥 | 现网 `.env` | 本项目独立 `.env`（先只读行情 Key） |
允许：从现网 **复制** 盘口解析、OKX WS 订阅、流动性检查等代码到本仓库后改。
禁止：在现网仓库里改文件、共用 PM2 restart 脚本、共用生产 Key（除非只读 Key 故意共用且你知情）。
---
## 5. 前端
视觉：复刻 OKX 交易台观感（深色、盘口、持仓、紧凑数字）。
### 导航（4 项）
1. **自动对冲计划**
模式 SIM/LIVE、时间窗状态、当前组 ID、方向、1+2 仓位、初始权利金、永续浮盈、距触发差值、30 点进度、永续/期权盘口、启动暂停、紧急全平（模拟）。
2. **交易记录**
按组列表与组内成交明细；筛选日期、平仓原因、盈亏。
3. **统计**
组数、胜率、总盈亏、总手续费、总滑点、平仓原因分布、按组权益曲线。
4. **系统设置**
虚拟资金、费率 `f`（滑点自动 1×f）、轮次与时间、30 点定义、选约规则、OKX Key、SIM/LIVE 开关（LIVE 二次确认）。
每组必须有明确标识（组 ID + 状态标签：持仓中 / 已平 / 流动性等待等）。
---
## 6. 部署（Ubuntu + PM2）
### 6.1 建议目录
```text
/opt/eth_hedge_sim # git clone 目标
.env # 仅本机/本项目，不进 git
deploy/
ecosystem.config.cjs # PM2 配置
pull_and_restart.sh # 仅重启本项目进程
```
### 6.2 PM2 进程（示例名，可改）
| 进程名 | 作用 |
|--------|------|
| `eth-hedge-api` | 行情网关 + 策略 + 本地撮合 + HTTP/WS API |
| `eth-hedge-web` | 前端静态或 Node 服务（若前后端合一可合并为一个进程） |
原则：**不要** `pm2 restart all` 误伤现网；脚本里写死本项目进程名。
### 6.3 发布流程（负责人自建仓库后）
```bash
cd /opt/eth_hedge_sim
git pull
# 安装依赖 / 构建前端（按实际栈）
pm2 startOrReload deploy/ecosystem.config.cjs --update-env
pm2 save
```
### 6.4 环境变量（示例）
```bash
MODE=SIM
OKX_API_KEY=... # 模拟阶段只需能拉行情的权限
OKX_API_SECRET=...
OKX_API_PASSPHRASE=...
FEE_RATE=0.0005 # 示例；滑点 = 1 × FEE_RATE
INITIAL_EQUITY=100000
TZ=Asia/Shanghai
```
---
## 7. 分期实施
| 阶段 | 内容 | 完成标准 |
|------|------|----------|
| P0 | 仓库骨架、依赖、OKX 只读行情（永续 + 次日期权盘口） | 能稳定收到真盘口 |
| P1 | 本地账本 + 撮合（永续市价、期权吃一、费+1×费滑点） | 手动开平一组账目正确 |
| P2 | 策略状态机（选向、两套平仓、3 次、08:00 停开、组 ID） | 无 UI 也能跑完业务窗 |
| P3 | 四页前端 | 可完整操作与复盘 |
| P4 | 行情落盘与回放 | 重放结果与当时一致 |
| P5 | 实盘适配器 | 显式开关下最小仓验证 |
---
## 8. 实现前待拍板
1. 期权多空的具体合约腿（Call / Put）。
2. 「30 点」定义（标的 vs 权利金）。
3. 行权价选择规则。
4. 初始权利金触发是否不含手续费（建议不含）。
5. Call 卖一 = Put 卖一时：跳过等待（建议）。
6. 云服务器路径、域名/端口、PM2 进程最终命名。
---
## 9. 一句话
**独立仓 `eth_hedge_sim`：OKX 真行情只读 + 本地虚拟资金撮合（永续市价、期权只吃买卖一、滑点=1×手续费）+ OKX 风四页前端 + Ubuntu/PM2 单独部署；可抄现网思路，但不改现网代码、不共用现网进程。**