dekun
309 lines
10 KiB
Markdown
309 lines
10 KiB
Markdown
# 比特骆驼自动化对冲系统 — 代码结构
|
||
|
||
> **产品名**：比特骆驼自动化对冲系统 · **工程目录**：`eth_hedge_sim`
|
||
> 本文描述目标仓库目录与模块职责。当前阶段以文档为准；业务代码按阶段逐步添加。
|
||
> 可从 `crypto_monitor` **复制** 有用片段到本仓库后改造；**禁止修改** 现网仓库内文件。
|
||
|
||
---
|
||
|
||
## 1. 根目录总览
|
||
|
||
```text
|
||
eth_hedge_sim/ # 产品：比特骆驼自动化对冲系统
|
||
├── README.md
|
||
├── .gitignore
|
||
├── .env.example # 策略机示例；真 .env 不上库
|
||
├── .env.control.example # 中控示例；真 .env.control 不上库
|
||
├── requirements.txt
|
||
├── docs/
|
||
│ ├── 开发方案.md
|
||
│ ├── 代码结构.md # 本文件
|
||
│ ├── 中控Fleet说明.md # 本地中控安装 / 配对 / 监控
|
||
│ └── 更新说明.md
|
||
├── deploy/ # 策略机部署 + manage.sh 菜单
|
||
│ ├── manage.sh # 1策略机 / 2中控 / 4更新策略 / 5更新中控
|
||
│ ├── ecosystem.config.cjs
|
||
│ └── pull_and_restart.sh
|
||
├── backend/ # 策略机 API
|
||
│ └── app/api/fleet.py # 中控专用：status/start/pause/update/issue-login
|
||
├── frontend/ # 策略机 Web
|
||
├── control/ # 本地中控（独立进程 :5160）
|
||
│ ├── backend/app/ # FastAPI：机器清单、Token、代理启停/更新
|
||
│ ├── frontend/ # 监控区 + 系统设置（Tab）
|
||
│ └── deploy/
|
||
│ ├── ecosystem.config.cjs # PM2 eth-hedge-control
|
||
│ └── update.sh
|
||
└── scripts/
|
||
├── deploy_remote.py # SSH 更新策略机
|
||
└── deploy_control.py # SSH/本机更新中控
|
||
```
|
||
|
||
中控详细用法见 **[中控 Fleet 说明](./中控Fleet说明.md)**。
|
||
|
||
---
|
||
|
||
## 1b. 中控模块职责（`control/`）
|
||
|
||
| 路径 | 职责 |
|
||
|------|------|
|
||
| `control/backend/app/main.py` | 中控入口，托管前端 dist |
|
||
| `control/backend/app/api/nodes.py` | 机器 CRUD、探活、启停/更新/免密登录 URL |
|
||
| `control/backend/app/api/auth_routes.py` | 登录、改密、局域网免登、login-meta |
|
||
| `control/backend/app/envfile.py` | `.env.control` 补缺（不覆盖已有值） |
|
||
| `control/backend/app/lan.py` | 私网 IP 判断 |
|
||
| `control/frontend/src/pages/Monitor.tsx` | 监控卡片 / 详情弹层 |
|
||
| `control/frontend/src/pages/Settings.tsx` | 账户 / 添加机 / 列表 Tab |
|
||
|
||
策略机侧配对接口：`backend/app/api/fleet.py` + 设置页「中控 API Token」。
|
||
|
||
---
|
||
|
||
## 1. 根目录总览（策略机为主，续）
|
||
|
||
```text
|
||
eth_hedge_sim/
|
||
├── backend/ # API + 行情 + 策略 + 本地撮合
|
||
│ ├── app/
|
||
│ │ ├── main.py
|
||
│ │ ├── config.py
|
||
│ │ ├── api/ # HTTP 路由（含 fleet）
|
||
│ │ ├── strategy/
|
||
│ │ ├── sim/
|
||
│ │ ├── live/
|
||
│ │ └── models/
|
||
│ ├── data/
|
||
│ └── tests/
|
||
├── frontend/ # 策略机 Web
|
||
│ └── src/pages/
|
||
│ ├── Plan.tsx
|
||
│ ├── Trades.tsx
|
||
│ ├── Stats.tsx
|
||
│ └── Settings.tsx # 含中控 Token
|
||
└── ...
|
||
```
|
||
|
||
> 下文原「根目录总览」中较旧的骨架示意仍保留模块职责描述；以本节 + [中控说明](./中控Fleet说明.md) 为准补充 `control/`。
|
||
|
||
---
|
||
|
||
## 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. 部署相关文件
|
||
|
||
目标环境：**Ubuntu 22.04** + PM2。目录默认 `/opt/eth_hedge_sim`。
|
||
|
||
### 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 行情订阅、签名、深度解析到本仓库 | 修改现网 `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
|
||
```
|
||
|
||
负责人创建远程仓库后，将本目录作为首批提交即可；业务代码按上表目录逐步添加。
|