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