arbitrage-engine/docs/PROJECT.md

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异常时无友好提示