d8ad87958a
- Full architecture overview - All 36 files documented with purpose and line counts - 5-layer scoring system explained - Database schema, PM2 processes, signal sources - Deployment info, version roadmap - Known issues and improvements
426 lines
16 KiB
Markdown
426 lines
16 KiB
Markdown
# Arbitrage Engine V5.1 — 项目文档
|
||
|
||
> 最后更新：2026-03-01
|
||
> 版本：V5.1
|
||
> 作者：琪智科技
|
||
|
||
## 一、项目概述
|
||
|
||
**Arbitrage Engine** 是一套加密货币合约交易信号系统，基于多因子评分模型，实时分析市场微观结构数据（Order Flow），生成做多/做空信号并执行模拟盘交易。
|
||
|
||
### 核心能力
|
||
- **5层100分评分体系**：方向层(45) + 拥挤层(20) + 环境层(15) + 确认层(15) + 辅助层(5)
|
||
- **4个交易币种**：BTCUSDT、ETHUSDT、XRPUSDT、SOLUSDT
|
||
- **8个信号源**（6个已接入评分，2个在采集中）
|
||
- **模拟盘自动交易**：信号触发 → 开仓 → TP/SL → 平仓，全自动
|
||
- **实时数据采集**：aggTrades、市场指标、清算数据
|
||
- **Web仪表盘**：信号展示、模拟盘监控、收益统计
|
||
|
||
### 技术栈
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 后端 | Python 3 + FastAPI + uvicorn |
|
||
| 前端 | Next.js 15 + React + TypeScript + Tailwind CSS |
|
||
| 数据库 | PostgreSQL 18（GCP Cloud SQL） |
|
||
| 进程管理 | PM2 |
|
||
| 数据源 | Binance Futures API + WebSocket |
|
||
| 反向代理 | Caddy |
|
||
|
||
### 代码统计
|
||
| 模块 | 文件数 | 代码行数 |
|
||
|------|--------|---------|
|
||
| Backend (Python) | 15个 | 4,598行 |
|
||
| Frontend (TSX/TS) | 21个 | 3,518行 |
|
||
| **总计** | **36个** | **8,116行** |
|
||
|
||
---
|
||
|
||
## 二、项目结构
|
||
|
||
```
|
||
arbitrage-engine/
|
||
├── backend/ # Python后端
|
||
│ ├── main.py # FastAPI主入口 + 全部API路由
|
||
│ ├── db.py # 数据库连接层（PG同步+异步池+Cloud SQL双写）
|
||
│ ├── auth.py # 用户认证系统（JWT + 邀请码注册）
|
||
│ ├── signal_engine.py # 🔥 核心：信号评估引擎（5层评分）
|
||
│ ├── paper_monitor.py # 模拟盘监控（WebSocket实时TP/SL）
|
||
│ ├── agg_trades_collector.py # aggTrades实时采集（Binance WS）
|
||
│ ├── market_data_collector.py# 市场指标采集（多空比/OI/FR等）
|
||
│ ├── liquidation_collector.py# 清算数据采集（Binance forceOrder）
|
||
│ ├── backtest.py # 回测框架
|
||
│ ├── backfill_agg_trades.py # aggTrades历史回补工具
|
||
│ ├── admin_cli.py # 管理命令行工具
|
||
│ ├── signal_pusher.py # [已废弃] 旧版信号推送
|
||
│ ├── subscriptions.py # [预留] 订阅系统
|
||
│ ├── migrate_sqlite_to_pg.py # [一次性] SQLite→PG数据迁移
|
||
│ └── migrate_auth_sqlite_to_pg.py # [一次性] Auth SQLite→PG迁移
|
||
├── frontend/ # Next.js前端
|
||
│ ├── app/
|
||
│ │ ├── page.tsx # 首页（仪表盘概览）
|
||
│ │ ├── layout.tsx # 全局布局
|
||
│ │ ├── signals/page.tsx # 信号引擎页面（5层评分展示）
|
||
│ │ ├── paper/page.tsx # 模拟盘页面（持仓+历史+统计）
|
||
│ │ ├── trades/page.tsx # 历史交易页面
|
||
│ │ ├── server/page.tsx # 服务器监控页面
|
||
│ │ ├── kline/page.tsx # K线图页面
|
||
│ │ ├── live/page.tsx # 实时数据页面
|
||
│ │ ├── dashboard/page.tsx # 仪表盘页面
|
||
│ │ ├── login/page.tsx # 登录页面
|
||
│ │ ├── register/page.tsx # 注册页面（需邀请码）
|
||
│ │ ├── about/page.tsx # 关于页面
|
||
│ │ └── history/page.tsx # [占位] 历史页面
|
||
│ ├── components/
|
||
│ │ ├── Sidebar.tsx # 侧边导航栏
|
||
│ │ ├── Navbar.tsx # 顶部导航栏
|
||
│ │ ├── AuthHeader.tsx # 认证头部
|
||
│ │ ├── LiveTradesCard.tsx # 实时交易卡片
|
||
│ │ ├── FundingChart.tsx # 资金费率图表
|
||
│ │ ├── RateCard.tsx # 费率卡片
|
||
│ │ └── StatsCard.tsx # 统计卡片
|
||
│ ├── lib/
|
||
│ │ ├── auth.tsx # 前端认证逻辑（JWT管理）
|
||
│ │ └── api.ts # API请求封装
|
||
│ ├── next.config.ts # Next.js配置（API代理）
|
||
│ ├── package.json # 依赖配置
|
||
│ └── tsconfig.json # TypeScript配置
|
||
├── docs/ # 项目文档
|
||
│ └── PROJECT.md # 本文件
|
||
├── .gitignore
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 三、后端文件详解
|
||
|
||
### 3.1 `main.py`（949行）— API主入口
|
||
|
||
FastAPI应用，包含全部HTTP API路由：
|
||
|
||
**API路由：**
|
||
| 路径 | 方法 | 功能 |
|
||
|------|------|------|
|
||
| `/api/health` | GET | 健康检查 |
|
||
| `/api/signals/latest` | GET | 最新信号数据 |
|
||
| `/api/signals/history` | GET | 历史信号 |
|
||
| `/api/paper/summary` | GET | 模拟盘概览 |
|
||
| `/api/paper/positions` | GET | 当前持仓 |
|
||
| `/api/paper/trades` | GET | 历史交易 |
|
||
| `/api/paper/equity-curve` | GET | 权益曲线 |
|
||
| `/api/paper/stats` | GET | 详细统计（支持按币种） |
|
||
| `/api/paper/config` | GET/POST | 模拟盘配置 |
|
||
| `/api/server/status` | GET | 服务器监控 |
|
||
|
||
**依赖：** FastAPI, uvicorn, asyncpg, psutil
|
||
|
||
**运行方式：** `uvicorn main:app --host 0.0.0.0 --port 4332`
|
||
|
||
---
|
||
|
||
### 3.2 `signal_engine.py`（739行）— 🔥 核心信号引擎
|
||
|
||
**最重要的文件**。每15秒评估一次4个币种的交易信号。
|
||
|
||
**5层评分体系（100分满分）：**
|
||
|
||
| 层级 | 权重 | 信号源 | 逻辑 |
|
||
|------|------|--------|------|
|
||
| 方向层 | 45分 | CVD三轨(fast/mid) + P99大单 + CVD加速度 | 资金流向判断多空 |
|
||
| 拥挤层 | 20分 | 多空比 + 大户持仓比 | 市场拥挤度，反向指标 |
|
||
| 环境层 | 15分 | OI变化率 | 合约持仓量变化 |
|
||
| 确认层 | 15分 | CVD-Price背离 + 大单方向确认 | 信号交叉验证 |
|
||
| 辅助层 | 5分 | Coinbase Premium | 机构资金流向 |
|
||
|
||
**核心类：**
|
||
- `TradeWindow`：滑动窗口，维护buy_vol/sell_vol/CVD，自动trim过期数据
|
||
- `ATRCalculator`：ATR计算器，用于仓位管理和TP/SL计算
|
||
- `SymbolState`：每个币种的完整状态（4个窗口 + ATR + 大单 + 市场指标）
|
||
|
||
**数据流：**
|
||
```
|
||
aggTrades(PG) → process_trade() → 4个TradeWindow更新
|
||
↓
|
||
evaluate_signal() → 5层打分
|
||
↓
|
||
score >= 60 → 开仓信号
|
||
↓
|
||
paper_trading_open() → 写入paper_trades
|
||
```
|
||
|
||
**关键参数：**
|
||
- `WINDOW_FAST = 30min`：CVD快线窗口
|
||
- `WINDOW_MID = 4h`：CVD慢线窗口
|
||
- `WINDOW_DAY = 24h`：P99大单计算窗口
|
||
- `EVAL_INTERVAL = 15s`：评估间隔
|
||
- `SIGNAL_THRESHOLD = 60`：开仓阈值分数
|
||
- `COOLDOWN = 300s`：同币种同方向冷却时间
|
||
|
||
**冷启动机制：**
|
||
1. 启动时`load_historical()`从PG读取最近4小时aggTrades灌入窗口
|
||
2. 前3轮(45秒)不出信号（冷启动保护）
|
||
|
||
---
|
||
|
||
### 3.3 `paper_monitor.py`（179行）— 模拟盘监控
|
||
|
||
独立PM2进程，通过WebSocket连接Binance实时监控持仓的TP/SL。
|
||
|
||
**核心逻辑：**
|
||
1. 启动时加载所有active/tp1_hit持仓
|
||
2. 连接Binance aggTrade WS获取实时价格
|
||
3. 每笔成交检查是否触发TP1/TP2/SL
|
||
4. 触发后更新paper_trades状态
|
||
|
||
**TP/SL规则：**
|
||
- TP1 = entry ± 1.5×ATR（平半仓）
|
||
- TP2 = entry ± 3.0×ATR（平剩余）
|
||
- SL = entry ∓ 1.0×ATR
|
||
- TP1触发后SL移动到成本价（保本）
|
||
|
||
**为什么独立进程：** TP/SL必须毫秒级响应，不能和15秒评估循环共享进程。
|
||
|
||
---
|
||
|
||
### 3.4 `db.py`（357行）— 数据库连接层
|
||
|
||
统一的PostgreSQL连接管理，支持同步和异步两种模式。
|
||
|
||
**连接池：**
|
||
- `get_sync_pool()` / `get_sync_conn()`：psycopg2同步池（供collector/signal_engine用）
|
||
- `get_async_pool()` / `async_fetch()`：asyncpg异步池（供FastAPI用）
|
||
- `get_cloud_sync_pool()` / `get_cloud_sync_conn()`：Cloud SQL双写池
|
||
|
||
**配置（环境变量）：**
|
||
- `PG_HOST`：数据库地址（默认127.0.0.1，现在应指向Cloud SQL）
|
||
- `CLOUD_PG_HOST`：Cloud SQL地址（10.106.0.3）
|
||
- `CLOUD_PG_ENABLED`：双写开关
|
||
|
||
**Schema管理：** `init_schema()` + `ensure_partitions()`（按月自动建分区表）
|
||
|
||
---
|
||
|
||
### 3.5 `agg_trades_collector.py`（307行）— aggTrades采集器
|
||
|
||
实时采集Binance合约aggTrades数据，是数据的源头。
|
||
|
||
**架构：**
|
||
- **WebSocket主链路**：4个币种各一条WS连接，实时推送
|
||
- **REST补洞**：断线重连后用REST API从last_agg_id追平
|
||
- **连续性巡检**：每60秒检查agg_id连续性，发现断档自动补洞
|
||
- **批量写入**：攒200条或1秒flush一次
|
||
|
||
**双写机制：** flush_buffer同时写本地PG和Cloud SQL，Cloud SQL写失败不影响主流程。
|
||
|
||
**数据量：** 目前约7000万条（BTC 23天 + ETH 3天 + XRP/SOL 3天）
|
||
|
||
---
|
||
|
||
### 3.6 `market_data_collector.py`（192行）— 市场指标采集
|
||
|
||
每5分钟从Binance REST API采集市场指标，存入`market_indicators`表。
|
||
|
||
**采集指标（5种）：**
|
||
| 指标 | API | 用途 |
|
||
|------|-----|------|
|
||
| long_short_ratio | /futures/data/globalLongShortAccountRatio | 多空比 |
|
||
| top_trader_position | /futures/data/topLongShortPositionRatio | 大户持仓比 |
|
||
| open_interest_hist | /futures/data/openInterestHist | 持仓量变化 |
|
||
| coinbase_premium | Coinbase vs Binance价差 | 机构资金流 |
|
||
| funding_rate | /fapi/v1/fundingRate | 资金费率 |
|
||
|
||
---
|
||
|
||
### 3.7 `liquidation_collector.py`（140行）— 清算数据采集
|
||
|
||
连接Binance WebSocket `forceOrder`流，实时采集强制平仓事件。
|
||
|
||
**双层存储：**
|
||
1. `liquidations`表：每笔清算原始记录
|
||
2. `market_indicators`表：每5分钟聚合（long_liq_usd/short_liq_usd/total/count）
|
||
|
||
**Side映射：** BUY order = SHORT被清算，SELL order = LONG被清算
|
||
|
||
---
|
||
|
||
### 3.8 `auth.py`（384行）— 认证系统
|
||
|
||
基于JWT的用户认证，邀请码注册制。
|
||
|
||
**功能：**
|
||
- 注册（需邀请码）/ 登录 / Token刷新
|
||
- Admin管理（邀请码生成/用户封禁）
|
||
- JWT签发（access_token 24h + refresh_token 7d）
|
||
|
||
**安全：** scrypt密码哈希 + HMAC-SHA256 JWT签名
|
||
|
||
---
|
||
|
||
### 3.9 `backtest.py`（503行）— 回测框架
|
||
|
||
对历史aggTrades数据运行信号引擎，验证策略表现。
|
||
|
||
**输出指标：** 胜率、PF、夏普比率、最大回撤、按方向/币种统计
|
||
|
||
---
|
||
|
||
### 3.10 其他文件
|
||
|
||
| 文件 | 行数 | 说明 |
|
||
|------|------|------|
|
||
| `backfill_agg_trades.py` | 209 | aggTrades历史数据回补（REST API批量拉取） |
|
||
| `admin_cli.py` | 123 | 命令行管理工具（生成邀请码、管理用户） |
|
||
| `signal_pusher.py` | 108 | **[已废弃]** 旧版信号推送（仍用SQLite，可删除） |
|
||
| `subscriptions.py` | 23 | **[预留]** 订阅系统占位 |
|
||
| `migrate_sqlite_to_pg.py` | 215 | **[一次性]** SQLite→PG数据迁移脚本 |
|
||
| `migrate_auth_sqlite_to_pg.py` | 170 | **[一次性]** Auth SQLite→PG迁移脚本 |
|
||
|
||
---
|
||
|
||
## 四、前端文件详解
|
||
|
||
### 4.1 页面
|
||
|
||
| 文件 | 行数 | 功能 |
|
||
|------|------|------|
|
||
| `app/page.tsx` | 320 | 首页仪表盘（资金费率卡片 + 概览） |
|
||
| `app/signals/page.tsx` | 523 | 信号引擎（4币种实时评分 + 5层分数展示） |
|
||
| `app/paper/page.tsx` | 459 | 模拟盘（当前持仓 + 历史交易 + 权益曲线 + 按币种统计） |
|
||
| `app/trades/page.tsx` | 384 | 历史交易（筛选、排序、详情） |
|
||
| `app/server/page.tsx` | 279 | 服务器监控（PM2进程 + CPU/内存 + PG状态） |
|
||
| `app/kline/page.tsx` | 170 | K线图 |
|
||
| `app/live/page.tsx` | 130 | 实时数据流 |
|
||
| `app/dashboard/page.tsx` | 112 | 仪表盘 |
|
||
| `app/login/page.tsx` | 75 | 登录 |
|
||
| `app/register/page.tsx` | 88 | 注册（邀请码） |
|
||
| `app/about/page.tsx` | 81 | 关于 |
|
||
| `app/layout.tsx` | 34 | 全局布局 |
|
||
|
||
### 4.2 组件
|
||
|
||
| 文件 | 行数 | 功能 |
|
||
|------|------|------|
|
||
| `components/Sidebar.tsx` | 139 | 侧边导航栏 |
|
||
| `components/LiveTradesCard.tsx` | 124 | 实时交易卡片组件 |
|
||
| `components/FundingChart.tsx` | 95 | 资金费率图表（Recharts） |
|
||
| `components/RateCard.tsx` | 82 | 费率展示卡片 |
|
||
| `components/Navbar.tsx` | 71 | 顶部导航 |
|
||
| `components/StatsCard.tsx` | 57 | 统计卡片 |
|
||
| `components/AuthHeader.tsx` | 37 | 认证状态头部 |
|
||
|
||
### 4.3 工具库
|
||
|
||
| 文件 | 行数 | 功能 |
|
||
|------|------|------|
|
||
| `lib/auth.tsx` | 137 | JWT管理（存储/刷新/authFetch封装） |
|
||
| `lib/api.ts` | 116 | API请求基础封装 |
|
||
|
||
---
|
||
|
||
## 五、数据库Schema
|
||
|
||
### PostgreSQL（Cloud SQL）
|
||
|
||
**核心表：**
|
||
|
||
| 表名 | 说明 | 数据量 |
|
||
|------|------|--------|
|
||
| `agg_trades` | aggTrades分区父表 | 7039万+ |
|
||
| `agg_trades_202602` | 2月分区 | 6854万 |
|
||
| `agg_trades_202603` | 3月分区 | 185万+ |
|
||
| `agg_trades_meta` | 每币种最新agg_id | 4条 |
|
||
| `signal_indicators` | 信号评分记录（每15秒×4币种） | 2.7万+ |
|
||
| `market_indicators` | 市场指标（每5分钟×4币种×5指标） | 5400+ |
|
||
| `paper_trades` | 模拟盘交易记录 | 163+ |
|
||
| `liquidations` | 清算事件原始记录 | 3600+ |
|
||
| `rate_snapshots` | 资金费率快照（旧，K线图用） | 12万+ |
|
||
| `users` | 用户表 | 1 |
|
||
| `invite_codes` | 邀请码 | 1 |
|
||
| `subscriptions` | 订阅信息 | 1 |
|
||
| `refresh_tokens` | JWT刷新令牌 | — |
|
||
| `signal_indicators_1m` | 1分钟粒度信号（备用） | — |
|
||
| `signal_trades` | 信号交易记录（旧） | — |
|
||
| `signal_logs` | 信号日志（旧） | — |
|
||
|
||
---
|
||
|
||
## 六、PM2进程列表
|
||
|
||
| 进程名 | 文件 | 端口 | 说明 |
|
||
|--------|------|------|------|
|
||
| `arb-api` | backend/main.py | 4332 | FastAPI后端 |
|
||
| `arb-web` | frontend/ | 4333 | Next.js前端 |
|
||
| `signal-engine` | backend/signal_engine.py | — | 信号评估引擎 |
|
||
| `paper-monitor` | backend/paper_monitor.py | — | 模拟盘TP/SL监控 |
|
||
| `agg-collector` | backend/agg_trades_collector.py | — | aggTrades采集 |
|
||
| `market-collector` | backend/market_data_collector.py | — | 市场指标采集 |
|
||
| `liq-collector` | backend/liquidation_collector.py | — | 清算数据采集 |
|
||
|
||
---
|
||
|
||
## 七、信号源清单
|
||
|
||
| # | 信号源 | 采集方式 | 存储 | 评分使用 |
|
||
|---|--------|---------|------|---------|
|
||
| 1 | CVD三轨（fast 30m / mid 4h） | aggTrades WS实时计算 | 内存 | ✅ 方向层 |
|
||
| 2 | P99大单流 | aggTrades实时统计 | 内存 | ✅ 方向层 |
|
||
| 3 | CVD加速度 | CVD差分计算 | 内存 | ✅ 方向层+5 bonus |
|
||
| 4 | 多空比 + 大户持仓比 | Binance REST 5min | market_indicators | ✅ 拥挤层 |
|
||
| 5 | OI变化率 | Binance REST 5min | market_indicators | ✅ 环境层 |
|
||
| 6 | Coinbase Premium | Coinbase+Binance价差 | market_indicators | ✅ 辅助层 |
|
||
| 7 | Funding Rate | Binance REST 5min | market_indicators | ⬜ 采集中 |
|
||
| 8 | 清算数据 | Binance WS forceOrder | liquidations + market_indicators | ⬜ 采集中 |
|
||
|
||
---
|
||
|
||
## 八、模拟盘配置
|
||
|
||
| 参数 | 值 |
|
||
|------|-----|
|
||
| 初始资金 | $10,000 |
|
||
| 单笔风险 | 2%（$200 = 1R） |
|
||
| 最大同时持仓 | 4个 |
|
||
| TP1 | 1.5× ATR（平半仓） |
|
||
| TP2 | 3.0× ATR（平剩余） |
|
||
| SL | 1.0× ATR |
|
||
| 手续费 | Taker 0.05% × 2（开仓+平仓） |
|
||
| 反向信号 | 先平仓再开新仓 |
|
||
| 冷却时间 | 同币种同方向300秒 |
|
||
|
||
---
|
||
|
||
## 九、部署信息
|
||
|
||
| 项目 | 详情 |
|
||
|------|------|
|
||
| 运行服务器 | GCP asia-northeast1-b (n2-standard-2, 2核8G) |
|
||
| 数据库 | GCP Cloud SQL PG18 (8核64G 100G) |
|
||
| Cloud SQL 内网IP | 10.106.0.3 |
|
||
| Cloud SQL 公网IP | 34.85.117.248 |
|
||
| Web访问 | https://arb.zhouyangclaw.com |
|
||
| Git仓库 | https://git.darkerilclaw.com/lulu/arbitrage-engine.git |
|
||
| 反向代理 | Caddy（SSL自动） |
|
||
|
||
---
|
||
|
||
## 十、版本路线图
|
||
|
||
| 版本 | 状态 | 内容 |
|
||
|------|------|------|
|
||
| V5.0 | ✅ 完成 | 基础信号系统 + PG迁移 |
|
||
| V5.1 | ✅ 当前 | 5层评分 + 模拟盘 + 6信号源评分 + 2信号源采集 |
|
||
| V5.2 | 📋 计划 | FR+清算加入评分 + 策略配置化 + AB测试 + 24h warmup |
|
||
| V5.3 | 📋 远期 | 推特新闻情绪信号（多模型投票制） |
|
||
|
||
---
|
||
|
||
## 十一、已知问题与待改进
|
||
|
||
1. **signal_pusher.py 已废弃**：仍用SQLite，应删除或重写
|
||
2. **subscriptions.py 空文件**：预留的订阅系统未实现
|
||
3. **history/page.tsx 空页面**：只有5行占位代码
|
||
4. **冷启动warmup只有4小时**：P99大单需要24小时数据（V5.2改进）
|
||
5. **开仓价用信号评估价**：实盘需改为真实成交价
|
||
6. **双写机制**：切主库后agg_collector的本地双写可关闭
|
||
7. **前端缺少错误边界**：API异常时无友好提示
|