Rekey
6c0a3f2ab3
- 数据层职责：K线合成 → K线聚合（实际使用 TimescaleDB 连续聚合） - 技术选型表：更新为实际使用的 Binance SDK + TypeORM - 子模块划分：反映实际模块结构，标注各模块完成状态 - 实施路线图：更新各阶段 ✅/⏳/❌ 状态 - 项目结构树：替换为实际目录结构 - 删除未实现的 K线合成器详解，引用 data/ARCHITECTURE.md
771 lines
41 KiB
Markdown
771 lines
41 KiB
Markdown
# 数字货币量化交易系统开发计划
|
||
|
||
> 基于 Python + TypeScript 混合架构的数字货币量化交易系统 —— 核心模块划分与开发步骤
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [项目概述](#项目概述)
|
||
2. [技术栈选型](#技术栈选型)
|
||
3. [架构方案对比](#架构方案对比)
|
||
4. [核心模块划分](#核心模块划分)
|
||
5. [TypeScript 数据模块详解](#typescript-数据模块详解)
|
||
6. [开发步骤](#开发步骤)
|
||
7. [项目目录结构](#项目目录结构)
|
||
8. [部署与运维](#部署与运维)
|
||
9. [注意事项与风险提示](#注意事项与风险提示)
|
||
|
||
---
|
||
|
||
## 项目概述
|
||
|
||
本项目的目标是构建一套**可扩展、低延迟、稳定可靠**的数字货币量化交易系统，支持：
|
||
|
||
- 多交易所接入（Binance、OKX、Bybit 等）
|
||
- 多策略并行运行
|
||
- 实时行情数据采集与存储
|
||
- 策略回测与参数优化
|
||
- 实盘交易执行与风控管理
|
||
- 可视化监控与告警
|
||
|
||
### 架构策略
|
||
|
||
采用 **Python + TypeScript 混合架构**：
|
||
|
||
| 层 | 语言 | 职责 |
|
||
|---|------|------|
|
||
| **数据层** | TypeScript (Bun) | 行情采集、WebSocket 连接管理、K 线聚合、数据写入 |
|
||
| **业务层** | Python 3.10+ | 策略引擎、回测、风控、交易执行 |
|
||
| **接口层** | TypeScript / Python | FastAPI (Python) 或 NestJS (TS) 提供 REST/WS API |
|
||
|
||
---
|
||
|
||
## 技术栈选型
|
||
|
||
| 分类 | 技术 / 库 | 说明 |
|
||
| ------------ | ---------------------------------- | -------------------------------------- |
|
||
| **数据层语言** | **TypeScript 5.x (Bun)** | 行情采集、WebSocket 管理、数据管道 |
|
||
| **业务层语言** | **Python 3.10+** | 策略引擎、回测、风控逻辑 |
|
||
| **时序数据库** | **TimescaleDB** | K 线数据存储，连续聚合，基于 PostgreSQL 扩展 |
|
||
| 关系型数据库 | PostgreSQL 16+ | 订单、策略配置等（与 TimescaleDB 共用实例）|
|
||
| 消息队列 | Redis | 跨语言数据流解耦，事件驱动（远期） |
|
||
| 异步框架(TS) | Binance 官方 SDK + TypeORM | REST/WS 客户端、ORM 映射 |
|
||
| 异步框架(Py) | `asyncio` + `aiohttp` / `httpx` | 异步 I/O，高性能网络请求 |
|
||
| 数据分析 | `pandas` + `numpy` + `ta` / `talib` | 技术指标计算与数据分析 |
|
||
| 策略回测 | `backtrader` / `vectorbt` / 自研 | 高性能回测引擎 |
|
||
| Web 框架 | FastAPI + Uvicorn | REST API 与 WebSocket 服务 |
|
||
| 可视化 | Grafana + Streamlit | 监控仪表盘与交互式分析 |
|
||
| 任务调度 | Celery / APScheduler / Bull | 定时任务与异步任务队列 |
|
||
| 配置管理 | pydantic-settings + `.env` | 类型安全的配置管理 |
|
||
| 日志监控 | loguru + winston + sentry | 结构化日志与异常追踪 |
|
||
| **类型校验** | **Zod (TS) / Pydantic (Py)** | 运行时数据校验，双端类型一致性保证 |
|
||
|
||
---
|
||
|
||
## 架构方案对比
|
||
|
||
### 方案 A：纯 Python（原方案）
|
||
|
||
```
|
||
[Python] 数据采集 → 策略引擎 → 交易执行 → 风控
|
||
```
|
||
|
||
| 优势 | 劣势 |
|
||
|------|------|
|
||
| 单一语言，维护简单 | WebSocket 大规模连接管理不如 Node.js |
|
||
| 数据分析生态无敌 | Python GIL 在 CPU 密集型场景受限 |
|
||
| 量化金融社区成熟 | 异步生态相对 Node.js 较新 |
|
||
|
||
### 方案 B：TypeScript 数据模块 + Python 业务引擎 ✅ **（推荐）**
|
||
|
||
```
|
||
[TypeScript] 数据采集 → Redis/消息队列 → [Python] 策略引擎 → 交易执行
|
||
```
|
||
|
||
| 优势 | 劣势 |
|
||
|------|------|
|
||
| Node.js WebSocket 性能优异，天然适合高并发连接 | 需要维护两套技术栈 |
|
||
| TypeScript 类型系统在数据管道中减少运行时错误 | 跨语言调试稍复杂 |
|
||
| **共享类型**：前后端可用同一套 TypeScript 类型定义 | 部署需要 Bun + Python 双运行时 |
|
||
| 事件驱动模型与行情数据流天然匹配 | 团队需要双语言能力 |
|
||
| npm 生态有成熟的交易 SDK（ccxt 等） | |
|
||
|
||
### 方案 C：全 TypeScript
|
||
|
||
```
|
||
[TypeScript] 数据采集 → 策略引擎 → 交易执行 → 风控
|
||
```
|
||
|
||
| 优势 | 劣势 |
|
||
|------|------|
|
||
| 单一语言 | 回测/量化分析生态远不如 Python |
|
||
| 类型安全 | 缺乏 pandas/numpy 级别的数据处理库 |
|
||
| 全栈一致性（前后端 + 数据层共用 TS） | 量化社区资源少，需要自研大量基础设施 |
|
||
|
||
---
|
||
|
||
## 核心模块划分
|
||
|
||
系统划分为 **7 大核心模块**，模块间通过消息队列或 API 解耦，整体架构如下：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Web UI / Dashboard │
|
||
│ (FastAPI / Streamlit / Grafana) │
|
||
└──────────────┬──────────────────┬───────────────────────────┘
|
||
│ │
|
||
┌──────────▼──────────┐ ┌───▼────────────────────┐
|
||
│ API Gateway │ │ 监控告警模块 │
|
||
│ (REST + WebSocket) │ │ (Prometheus + Alert) │
|
||
└──────────┬──────────┘ └────────────────────────┘
|
||
│
|
||
┌──────────▼──────────────────────────────────────────┐
|
||
│ 策略引擎 🐍 Python │
|
||
│ (策略加载 / 生命周期管理 / 信号分发) │
|
||
└────┬──────────────┬──────────────┬─────────────────┘
|
||
│ │ │
|
||
┌────▼────┐ ┌─────▼─────┐ ┌───▼──────────┐
|
||
│ 策略 A │ │ 策略 B │ │ 策略 C ... │
|
||
│(趋势) │ │ (网格) │ │ │
|
||
└────┬────┘ └─────┬─────┘ └───┬──────────┘
|
||
│ │ │
|
||
┌────▼──────────────▼──────────────▼─────────────────┐
|
||
│ 交易执行模块 🐍 Python │
|
||
│ (订单管理 / 仓位管理 / 交易所适配器 / 重试机制) │
|
||
└────────────────────┬───────────────────────────────┘
|
||
│
|
||
┌────────────────────▼───────────────────────────────┐
|
||
│ 消息队列 (Redis / NATS) │
|
||
│ ┌───────────── 数据管道 ─────────────┐ │
|
||
└────────────────────┬───────────────────────────────┘
|
||
│
|
||
┌────────────────────▼───────────────────────────────┐
|
||
│ 数据模块 🟦 TypeScript │
|
||
│ (行情采集 / K线合成 / 数据存储 / 数据清洗 / 因子计算) │
|
||
└────────────────────┬───────────────────────────────┘
|
||
│
|
||
┌────────────────────▼───────────────────────────────┐
|
||
│ 风控模块 🐍 Python │
|
||
│ (资金管理 / 仓位限制 / 最大回撤 / 异常交易熔断 / 白名单)│
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
### 1. 数据模块 (`data/`) — 🟦 TypeScript
|
||
|
||
负责从交易所获取和处理市场数据，是一切策略和决策的基础。
|
||
|
||
#### 为什么数据模块用 TypeScript？
|
||
|
||
| 原因 | 说明 |
|
||
|------|------|
|
||
| **WebSocket 性能** | Node.js 事件循环天然适合处理大量 WebSocket 连接（单进程万级连接） |
|
||
| **内存管理** | V8 引擎的垃圾回收机制在短生命周期对象场景表现优异 |
|
||
| **类型安全** | TypeScript 编译期检查确保数据管道中的类型正确性 |
|
||
| **流式处理** | Node.js Stream / Observable 模式与行情数据流完美匹配 |
|
||
| **生态优势** | 各交易所官方/社区 SDK 对 Node.js 支持最好 |
|
||
|
||
#### 子模块划分
|
||
|
||
| 子模块 | 职责 | 关键技术点 | 状态 |
|
||
| ---------------- | -------------------------------------------------------------------- | ----------------------------------------------- | :--: |
|
||
| **交易所适配器** | 封装不同交易所的 REST / WebSocket API，提供统一的 K 线拉取和订阅接口 | 适配器模式、`rest-registry` 自动路由、`ws-manager` 实例池 | ✅ |
|
||
| **数据回补** | 启动时自动检测数据缺口，通过 REST API 逐交易对拉取历史 K 线补齐 | 增量回补、断点续传、并发控制、`lastBackfillTime` 追踪 | ✅ |
|
||
| **实时行情** | WebSocket 订阅 1m K 线流，通过 EventBus 桥接到入库和聚合刷新 | Binance 官方 SDK、断线重连、超时检测、`kline:tick` 微回补 | ✅ |
|
||
| **数据存储** | K 线数据持久化到 TimescaleDB，5 列复合主键 UPSERT | TypeORM + `@timescaledb/typeorm`、`synchronize: false`、DDL 由 SQL 脚本管理 | ✅ |
|
||
| **连续聚合** | TimescaleDB 连续聚合视图自动从 1m K 线生成高周期（3m→1mon，共 12 层） | `FIRST(open, time)` / `LAST(close, time)` 保证 OHLC 语义 | ✅ |
|
||
| **事件总线** | `node:events` 类型安全封装，解耦 WS 接收、入库、聚合刷新、策略消费 | `TypedEventBus`、`kline:update` → `kline:saved` → `aggregate:refreshed` | ✅ |
|
||
| **数据发布** | 将处理后的数据通过 Redis Pub/Sub 推送给 Python 策略引擎 | `ioredis`、频道设计（设计阶段，尚未实现） | ⏳ |
|
||
| **数据清洗** | 去除异常数据、填充缺失值、处理停盘数据 | 统计异常检测、插值法（远期） | ❌ |
|
||
|
||
#### 关键接口
|
||
|
||
```typescript
|
||
// exchanges/rest-registry.ts — REST 客户端注册 + 自动路由
|
||
export function createRestClient(exchange: string, type: PairType): BaseRestClient;
|
||
export async function fetchKlines(params: FetchKlinesParams): Promise<Kline[]>;
|
||
|
||
// exchanges/ws-manager.ts — WS 订阅管理
|
||
export function watchKline(target: { exchange: string; type: PairType; symbol: string }): void;
|
||
export function watchKlines(targets: Array<{ exchange: string; type: PairType; symbol: string }>): void;
|
||
export function unWatchKline(symbol: string, type: PairType): void;
|
||
|
||
// service/backfill.ts — 历史数据回补
|
||
export async function backfillKline(pair: TradingPair): Promise<void>;
|
||
export async function backfillKlines(): Promise<void>; // 遍历所有交易对
|
||
|
||
// service/kline.ts — K 线写入
|
||
export async function upsertOrUpdateKlines(klines: Kline[]): Promise<void>;
|
||
|
||
// service/aggregate.ts — 聚合刷新
|
||
export async function checkAndRefresh(openTime: number): Promise<void>; // 从 openTime 所在的分钟桶开始刷新
|
||
```
|
||
|
||
> 详细 API 参考见 [`data/ARCHITECTURE.md`](data/ARCHITECTURE.md)。
|
||
|
||
---
|
||
|
||
#### 数据采集与聚合策略
|
||
|
||
本模块**不自行合成 K 线**，而是采用"交易所原始 K 线 + TimescaleDB 连续聚合"方案：
|
||
|
||
1. **1m K 线**：通过交易所 REST API 回补历史数据 + WebSocket 订阅实时 1m K 线，直接 UPSERT 到 `klines` hypertable。K 线的 `time` 字段存储交易所原始 `openTime`（UTC），不做本地转换。
|
||
2. **高周期 K 线**：由 TimescaleDB 连续聚合视图（Continuous Aggregate）自动从 1m 表生成，`FIRST(open, time)` / `LAST(close, time)` 保证 OHLC 语义与交易所原生高周期 K 线一致。
|
||
3. **聚合刷新**：TS 侧 `checkAndRefresh()` 在每根 1m K 线入库后触发 TimescaleDB 刷新策略，确保连续聚合视图实时更新。
|
||
|
||
**K 线复合主键**：`[exchange, symbol, type, interval, time]`（5 列），其中 `type` 区分现货（spot）/ USDT-M 合约（um）/ Coin-M（cm）。
|
||
|
||
> 详细设计见 [`data/ARCHITECTURE.md`](data/ARCHITECTURE.md) §4.3、§5 和 [`data/db/init-db/03-continuous-aggregates.sql`](data/db/init-db/03-continuous-aggregates.sql)。
|
||
|
||
---
|
||
|
||
#### TimescaleDB 数据存储方案
|
||
|
||
K 线数据具有典型的时序特征：**持续写入、按时间范围查询、少有更新、数据量大**。TimescaleDB 作为 PostgreSQL 的时序扩展，相比 InfluxDB 有以下核心优势：
|
||
|
||
| 对比维度 | TimescaleDB | InfluxDB |
|
||
|---------|------------|----------|
|
||
| **基础数据库** | PostgreSQL 扩展 | 独立时序数据库 |
|
||
| **SQL 兼容** | 完整 SQL 支持（JOIN、子查询、窗口函数） | 类 SQL 但不完全兼容 |
|
||
| **与业务数据关联** | K 线表和订单表可以在同一个 PG 实例中 JOIN | 需要跨数据库查询 |
|
||
| **数据压缩** | 列式压缩，压缩比 90%+ | 压缩比约 85% |
|
||
| **连续聚合** | 内置自动刷新物化视图 | 需要外部工具 |
|
||
| **保留策略** | 内置自动删除（数据保留策略） | 内置 |
|
||
| **生态集成** | 可与 PostGIS、pgvector 等 PG 扩展共存 | 独立生态 |
|
||
| **运维成本** | 复用 PG 运维经验 | 需独立运维 |
|
||
|
||
**实际表结构**（5 列复合主键）：
|
||
|
||
```sql
|
||
CREATE TABLE klines (
|
||
exchange TEXT NOT NULL,
|
||
symbol TEXT NOT NULL,
|
||
type TEXT NOT NULL, -- spot / um / cm
|
||
interval TEXT NOT NULL, -- 1m / 5m / 15m / 1h / 4h / 1d …
|
||
time BIGINT NOT NULL, -- 交易所原始 openTime (ms)
|
||
open NUMERIC(20,8) NOT NULL,
|
||
high NUMERIC(20,8) NOT NULL,
|
||
low NUMERIC(20,8) NOT NULL,
|
||
close NUMERIC(20,8) NOT NULL,
|
||
volume NUMERIC(20,8) NOT NULL,
|
||
-- ... 扩展字段
|
||
PRIMARY KEY (exchange, symbol, type, interval, time)
|
||
);
|
||
SELECT create_hypertable('klines', 'time', chunk_time_interval => INTERVAL '1 day');
|
||
```
|
||
|
||
> **DDL 全部由 SQL 脚本管理**（`synchronize: false`），TypeORM 实体仅用于运行时映射。连续聚合视图共 **12 层**（3m → 5m → 15m → 30m → 1h → 2h → 4h → 6h → 8h → 12h → 1d → 1mon），使用 `FIRST(open, time)` / `LAST(close, time)` 保证 OHLC 语义。
|
||
>
|
||
> 详见 [`data/db/init-db/`](data/db/init-db/) 和 [`data/ARCHITECTURE.md`](data/ARCHITECTURE.md) §4.3。
|
||
|
||
**磁盘空间估算**：
|
||
|
||
| 数据量 | 未压缩 | 压缩后 (~92%) |
|
||
|--------|--------|-------------|
|
||
| 10 币种 / 1 年 | ~945 MB | ~75 MB |
|
||
| 50 币种 / 1 年 | ~4.7 GB | ~375 MB |
|
||
| 200 币种 / 1 年 | ~18.9 GB | ~1.5 GB |
|
||
|
||
|
||
---
|
||
|
||
#### 推荐的 npm 包（实际依赖）
|
||
|
||
| 包名 | 用途 | 状态 |
|
||
|------|------|:--:|
|
||
| `binance` | Binance 官方 SDK（MainClient + USDMClient + WebSocket） | ✅ |
|
||
| `typeorm` + `@timescaledb/typeorm` | ORM 框架 + TimescaleDB 装饰器映射 | ✅ |
|
||
| `pg` | PostgreSQL 原生驱动（TypeORM 底层） | ✅ |
|
||
| `pino` + `pino-pretty` + `pino-roll` | 高性能结构化日志 | ✅ |
|
||
| `yaml` | 解析 env.yaml 配置文件 | ✅ |
|
||
| `ioredis` | Redis 客户端（Pub/Sub 远期集成） | ⏳ |
|
||
| `ccxt` | 统一交易所 API（多交易所远期） | ⏳ |
|
||
|
||
---
|
||
|
||
### 2. 策略引擎 (`engine/`) — 🐍 Python
|
||
|
||
核心调度中心，负责策略的生命周期管理和信号分发。
|
||
|
||
#### 子模块划分
|
||
|
||
| 子模块 | 职责 | 关键技术点 |
|
||
| -------------- | ---------------------------------------------- | -------------------------------------- |
|
||
| **通用模块** | 策略基类、数据模型、日志、配置 | `engine/common/` 目录，基础类型定义 |
|
||
| **策略管理器** | 策略注册、启动、停止、热加载 | 插件化架构、动态导入、`importlib` |
|
||
| **信号分发器** | 将策略产生的交易信号分发到交易执行模块 | 事件总线、消息队列 |
|
||
| **回测引擎** | 使用历史数据模拟策略执行，评估收益、回撤等指标 | `vectorbt` / `backtrader`、事件驱动 |
|
||
| **参数优化器** | 网格搜索 / 贝叶斯优化策略参数 | `scipy.optimize`、`optuna`、并行计算 |
|
||
|
||
#### 策略基类设计
|
||
|
||
```python
|
||
from common import BaseStrategy, StrategyConfig, Signal
|
||
from common.models import Kline, Ticker, OrderBook
|
||
|
||
class MyStrategy(BaseStrategy):
|
||
"""策略示例 — 所有策略继承 BaseStrategy"""
|
||
strategy_type = "my_strategy"
|
||
|
||
async def on_kline(self, kline: Kline) -> Signal | None:
|
||
...
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 交易执行模块 (`executor/`) — 🐍 Python
|
||
|
||
负责将策略信号转化为实际订单，管理交易所连接和仓位。虽然数据采集在 TypeScript 层完成，但下单操作仍需在 Python 侧执行，因为策略引擎和风控逻辑同在 Python 侧，减少跨语言通信延迟。
|
||
|
||
#### 子模块划分
|
||
|
||
| 子模块 | 职责 | 关键技术点 |
|
||
| ---------------- | ------------------------------------------------------ | ---------------------------------------- |
|
||
| **交易所适配器** | 封装不同交易所的 REST / WebSocket API，提供统一接口 | 适配器模式、限频控制、签名算法 |
|
||
| **订单管理器** | 下单、撤单、查询订单状态；支持限价单、市价单、条件单 | 订单状态机、幂等性、超时处理 |
|
||
| **仓位管理器** | 跟踪当前持仓、可用余额、未实现盈亏 | 实时同步、增量更新 |
|
||
| **执行算法** | TWAP、VWAP、冰山订单等高级执行算法（降低滑点） | 切片算法、时间加权 |
|
||
|
||
#### 交易所适配器接口
|
||
|
||
```python
|
||
class ExchangeAdapter(ABC):
|
||
"""交易所统一适配器接口"""
|
||
|
||
@abstractmethod
|
||
async def create_order(self, order: Order) -> OrderResult:
|
||
...
|
||
|
||
@abstractmethod
|
||
async def cancel_order(self, order_id: str) -> bool:
|
||
...
|
||
|
||
@abstractmethod
|
||
async def get_balance(self) -> dict[str, float]:
|
||
...
|
||
|
||
@abstractmethod
|
||
async def get_position(self, symbol: str) -> Position:
|
||
...
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 风控模块 (`risk/`) — 🐍 Python
|
||
|
||
系统的安全防线，在交易前、交易中、交易后全链路控制风险。
|
||
|
||
| 功能 | 说明 |
|
||
| ------------------ | ------------------------------------------------------------------ |
|
||
| **资金管理** | 单笔下单量限制、总仓位比例限制、逐仓/全仓模式支持 |
|
||
| **最大回撤控制** | 当日/累计回撤超过阈值时自动暂停策略 |
|
||
| **异常检测** | 检测价格异常波动、交易所 API 异常、网络延迟过高 |
|
||
| **熔断机制** | 极端行情下自动停止所有交易，进入只平不开模式 |
|
||
| **订单频率限制** | 控制单位时间内的下单次数，防止过度交易 |
|
||
| **白名单/黑名单** | 限制可交易的币种和交易对 |
|
||
|
||
```python
|
||
class RiskManager:
|
||
async def check_order(self, order: Order, context: TradingContext) -> RiskResult:
|
||
"""下单前风控检查"""
|
||
checks = [
|
||
self._check_max_position,
|
||
self._check_order_value,
|
||
self._check_order_frequency,
|
||
self._check_drawdown_limit,
|
||
self._check_price_deviation,
|
||
]
|
||
for check in checks:
|
||
result = await check(order, context)
|
||
if not result.passed:
|
||
return result
|
||
return RiskResult(passed=True)
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 监控告警模块 (`monitor/`)
|
||
|
||
保障系统运行的可观测性。
|
||
|
||
| 功能 | 说明 |
|
||
| ---------------- | -------------------------------------------------- |
|
||
| **指标收集** | 收集策略收益、胜率、夏普比率、最大回撤等绩效指标 |
|
||
| **系统监控** | CPU / 内存 / 网络延迟 / API 调用量 |
|
||
| **告警通知** | 通过钉钉、Telegram、飞书等发送告警 |
|
||
| **日志管理** | 结构化日志存储，支持按级别、模块检索 |
|
||
| **Web 仪表盘** | 实时展示资金曲线、持仓、交易记录、策略状态等 |
|
||
|
||
---
|
||
|
||
### 6. API 网关 (`api/`)
|
||
|
||
对外提供统一接口，支持浏览器端和移动端访问。
|
||
|
||
| 功能 | 说明 |
|
||
| ------------------ | ----------------------------------- |
|
||
| **REST API** | 策略管理、查询持仓、查看交易记录 |
|
||
| **WebSocket** | 实时推送行情、交易信号和通知 |
|
||
| **用户认证** | JWT 认证、API Key 管理 |
|
||
| **权限管理** | 多用户角色（管理员 / 只读用户） |
|
||
|
||
---
|
||
|
||
### 7. 配置与工具模块 (`common/`)
|
||
|
||
提供跨模块共享的基础设施。
|
||
|
||
| 模块 | 功能 |
|
||
| -------- | ---------------------------------------- |
|
||
| **配置** | 基于 `pydantic-settings` 的环境配置管理 |
|
||
| **日志** | 基于 `loguru` 的统一日志配置 |
|
||
| **工具** | 时间工具、重试装饰器、限流器、加解密工具 |
|
||
| **模型** | 共享的 Pydantic 数据模型（订单、K 线等） |
|
||
| **常量** | 交易所枚举、订单类型、时间周期等定义 |
|
||
|
||
---
|
||
|
||
## TypeScript 数据模块详解
|
||
|
||
### 核心架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ TypeScript 数据模块 (Bun) │
|
||
│ │
|
||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||
│ │ Binance REST │── backfill ──────→│ TimescaleDB │ │
|
||
│ │ · MainClient │ │ Klines (1m) │ │
|
||
│ │ · USDMClient │ └────────┬─────────┘ │
|
||
│ └──────────────────┘ │ │
|
||
│ │ │
|
||
│ ┌──────────────────┐ EventBus (node:events) │ │
|
||
│ │ Binance WS │── kline:update ────→ upsert─┘ │
|
||
│ │ (官方 SDK) │ ↓ │
|
||
│ └────────┬─────────┘ kline:saved ────→ 连续聚合刷新 │
|
||
│ │ │
|
||
│ │ pair:ready ← backfill 完成后触发 │
|
||
│ │ ws:disconnected / ws:connected / ws:stale │
|
||
│ │ │
|
||
│ ┌────────┴──────────────────────────┐ │
|
||
│ │ run/start.ts（编排层） │ │
|
||
│ │ 注册 bus 监听 → backfillKlines() │ │
|
||
│ │ → WS 订阅 → 入库 → 聚合刷新 │ │
|
||
│ └───────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌───────────────────────────────────┐ │
|
||
│ │ TypeORM 实体（关系数据） │ │
|
||
│ │ Exchange / TradingPair │ │
|
||
│ └───────────────────────────────────┘ │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 数据流生命周期
|
||
|
||
```
|
||
回补阶段 实时阶段
|
||
──────── ────────
|
||
REST API WebSocket
|
||
│ │
|
||
▼ ▼
|
||
fetchKlines() kline:update (bus event)
|
||
│ │
|
||
▼ ▼
|
||
upsertOrUpdateKlines() upsertOrUpdateKlines()
|
||
│ │
|
||
▼ ▼
|
||
pair:ready (bus event) kline:saved (bus event)
|
||
│ │
|
||
▼ ▼
|
||
watchKline() checkAndRefresh()
|
||
│ (连续聚合刷新)
|
||
▼
|
||
WS 实时订阅启动 aggregate:refreshed
|
||
│
|
||
▼
|
||
Redis Pub/Sub (远期)
|
||
│
|
||
▼
|
||
Python 策略引擎消费
|
||
```
|
||
|
||
### TypeScript 数据模块目录结构
|
||
|
||
```
|
||
data/
|
||
├── package.json
|
||
├── tsconfig.json
|
||
├── bun.lock
|
||
│
|
||
├── run/ # 启动入口
|
||
│ ├── start.ts # 编排层：回补 → WS 订阅 → 入库 → 聚合刷新
|
||
│ ├── exchange.ts # 独立回补入口
|
||
│ └── build_aggregates_sql.ts # 聚合刷新（dry-run / --execute）
|
||
│
|
||
├── config/ # 配置模块
|
||
│ ├── index.ts # 加载 env.yaml → 校验 → 分组导出
|
||
│ └── validators.ts # 零依赖运行时校验
|
||
│
|
||
├── db/ # 数据库层
|
||
│ ├── data-source.ts # TypeORM DataSource（synchronize: false）
|
||
│ ├── entities/ # ORM 实体
|
||
│ │ ├── kline.entity.ts # TimescaleDB K 线 hypertable（5 列复合 PK）
|
||
│ │ ├── exchange.entity.ts # 交易所
|
||
│ │ ├── trading-pair.entity.ts # 交易对（含 type 列）
|
||
│ │ └── common.entity.ts # 公共基类
|
||
│ ├── init-db/ # DDL SQL（容器首次启动自动执行）
|
||
│ │ ├── 01-timescaledb.sql
|
||
│ │ ├── 02-init-tables.sql
|
||
│ │ └── 03-continuous-aggregates.sql
|
||
│ └── migrations/ # TypeORM 迁移文件
|
||
│
|
||
├── exchanges/ # 交易所适配器
|
||
│ ├── base.ts # BaseRestClient / BaseWsClient 抽象基类
|
||
│ ├── constants.ts # KLINE_INTERVAL_MS 等常量
|
||
│ ├── rest-registry.ts # REST 客户端注册 + fetchKlines() 自动路由
|
||
│ ├── ws-manager.ts # WS 实例池 + watchKline/watchKlines
|
||
│ └── binance/
|
||
│ ├── rest.ts # BinanceRestClient（现货）+ Futures（合约）
|
||
│ └── ws.ts # BinanceWsClient
|
||
│
|
||
├── service/ # 业务服务层
|
||
│ ├── backfill.ts # 回补编排
|
||
│ ├── kline.ts # upsertOrUpdateKlines（批量 UPSERT）
|
||
│ ├── pair.ts # 交易对查询/更新
|
||
│ └── aggregate.ts # checkAndRefresh（聚合刷新触发）
|
||
│
|
||
├── types/ # 共享类型
|
||
│ ├── base.ts # Kline / Ticker / Trade 等接口
|
||
│ └── kline.ts # PairType / KlineInterval 枚举
|
||
│
|
||
├── utils/ # 工具
|
||
│ ├── bus.ts # TypedEventBus（node:events 类型安全封装）
|
||
│ ├── logger.ts # Pino 日志
|
||
│ └── index.ts # getNowMinuteMS / wait 等
|
||
│
|
||
└── tests/ # 测试（4 个文件，覆盖率建设中）
|
||
```
|
||
|
||
> 详细架构说明见 [`data/ARCHITECTURE.md`](data/ARCHITECTURE.md)。
|
||
|
||
### Python ↔ TypeScript 跨语言通信
|
||
|
||
> ⚠️ **当前状态**：Redis Pub/Sub 尚未集成，TS 侧已安装 `ioredis` 依赖。当前 Python engine 通过直接读取 TimescaleDB 获取 K 线数据进行回测。
|
||
|
||
```
|
||
┌──────────────────┐ Redis/NATS ┌──────────────────┐
|
||
│ 🟦 TypeScript │ ──────────────────────────► │ 🐍 Python │
|
||
│ 数据模块 │ Pub: "market:kline:1m" │ 策略引擎 │
|
||
│ │ Pub: "market:trade" │ │
|
||
│ │ │ Sub: 消费行情 │
|
||
└──────────────────┘ └──────────────────┘
|
||
|
||
---
|
||
|
||
## 开发步骤
|
||
|
||
### 第一阶段：基础建设 ✅ 数据模块已完成
|
||
|
||
**目标**：搭建项目骨架，完成 TypeScript 数据模块的基础能力和 Python 项目基础。
|
||
|
||
| 步骤 | 状态 | 任务 | 产出物 |
|
||
| ---- | :--: | ---- | ------ |
|
||
| 1.1 | ✅ | 初始化 TypeScript 数据项目（`data/`），配置 `package.json` | 项目结构，ESLint + Prettier 配置 |
|
||
| 1.2 | ✅ | 初始化 Python 项目，配置 `uv` 依赖管理 | `pyproject.toml`，项目目录结构 |
|
||
| 1.3 | ✅ | 定义共享类型：TypeScript `types/` + Python `engine/common/models.py` | 双端对齐的数据模型 |
|
||
| 1.4 | ✅ | 实现 TS 交易所适配器基类 + Binance 适配器（`data/exchanges/`） | 统一接口 + REST/WS 连接 |
|
||
| 1.5 | ✅ | 实现 TS 行情采集器，WebSocket 订阅实时 1m K 线 | 实时行情流入 |
|
||
| 1.6 | ✅ | 实现 TS 数据存储模块，TypeORM + TimescaleDB UPSERT | 数据持久化 |
|
||
| 1.7 | ✅ | TimescaleDB 连续聚合视图（12 层，3m→1mon） | 高周期 K 线自动生成 |
|
||
| 1.8 | ⏳ | 实现 TS → Redis 数据发布 | 实时行情推送到消息队列（远期） |
|
||
| 1.9 | ⏳ | Python 侧实现 Redis 订阅消费者 | 消费端就绪（远期） |
|
||
| 1.10 | ✅ | Docker Compose 编排基础服务（TimescaleDB） | `docker-compose.yml` |
|
||
|
||
> 实际 TS 路径为 `data/exchanges/`（非 `data/src/exchanges/`），未实现本地 K 线合成器，改为交易所原始 K 线 + TimescaleDB 连续聚合。详见 [`data/ARCHITECTURE.md`](data/ARCHITECTURE.md)。
|
||
|
||
### 第二阶段：策略与回测 🔄 进行中
|
||
|
||
**目标**：实现策略框架和回测引擎，能编写策略并进行回测验证。
|
||
|
||
| 步骤 | 状态 | 任务 | 产出物 |
|
||
| ---- | :--: | ---- | ------ |
|
||
| 2.1 | ✅ | 实现策略基类（`engine/common/base.py`） | `BaseStrategy` 抽象基类 |
|
||
| 2.2 | ❌ | 实现策略管理器，支持策略注册和生命周期 | 策略热加载、启动/停止控制 |
|
||
| 2.3 | ❌ | 实现信号分发器 | 事件总线，策略到执行器的信号传递 |
|
||
| 2.4 | ✅ | 实现回测引擎（`engine/backtest/`） | 历史数据回测，收益曲线、回撤等指标 |
|
||
| 2.5 | ✅ | 实现技术指标（`engine/indicators/`） | MA、ATR、RSI 等常用指标 |
|
||
| 2.6 | ✅ | 编写示例策略（`engine/example/`） | 多个可运行的策略示例 |
|
||
| 2.7 | ❌ | 实现参数优化器 | 基于 Optuna 的参数搜索 |
|
||
|
||
### 第三阶段：交易执行与风控（远期）
|
||
|
||
**目标**：连接实盘交易通道，实现完整的交易执行流程和风控体系。
|
||
|
||
| 步骤 | 状态 | 任务 | 产出物 |
|
||
| ---- | :--: | ---- | ------ |
|
||
| 3.1 | ❌ | 实现订单管理器 | 下单、撤单、订单状态更新 |
|
||
| 3.2 | ❌ | 实现仓位管理器 | 实时仓位跟踪 |
|
||
| 3.3 | ❌ | 实现交易状态机 | 订单生命周期管理 |
|
||
| 3.4 | ❌ | 实现重试与容错机制 | 网络异常自动重试 |
|
||
| 3.5 | ❌ | 实现风控管理器 | 资金管理、仓位限制、熔断 |
|
||
| 3.6 | ❌ | 实现风控规则引擎 | 可扩展的风控规则链 |
|
||
| 3.7 | ❌ | 整合 TS → Redis → Python 端到端流程 | 跨语言运行流水线 |
|
||
|
||
### 第四阶段：API 与监控（远期）
|
||
|
||
| 步骤 | 状态 | 任务 | 产出物 |
|
||
| ---- | :--: | ---- | ------ |
|
||
| 4.1 | ❌ | 搭建 FastAPI 项目 | REST API 服务 |
|
||
| 4.2 | ❌ | 实现 WebSocket 实时推送 | 行情和交易数据推送 |
|
||
| 4.3 | ❌ | 实现策略管理 API | 策略启停、参数修改 |
|
||
| 4.4 | ❌ | 实现交易记录查询 API | 交易历史查询 |
|
||
| 4.5 | ❌ | 集成 Prometheus 指标 | 关键业务指标暴露 |
|
||
| 4.6 | ❌ | 配置 Grafana 仪表盘 | 可视化仪表盘 |
|
||
| 4.7 | ❌ | 实现告警通知集成 | Telegram / 钉钉通知 |
|
||
|
||
### 第五阶段：优化与生产化（远期）
|
||
|
||
| 步骤 | 状态 | 任务 |
|
||
| ---- | :--: | ---- |
|
||
| 5.1 | ❌ | 性能优化与压测 |
|
||
| 5.2 | ❌ | 测试覆盖率 > 80% |
|
||
| 5.3 | ❌ | CI/CD 流水线 |
|
||
|
||
---
|
||
|
||
## 项目目录结构
|
||
|
||
```
|
||
trade/
|
||
├── env.yaml # 统一环境配置源（TS/Python 共享）
|
||
├── docker-compose.yml # 基础服务编排（TimescaleDB + Adminer）
|
||
├── .gitignore
|
||
├── README.md
|
||
│
|
||
├── data/ # 🟦 TypeScript 数据模块 ✅ MVP 就绪
|
||
│ ├── ARCHITECTURE.md # 模块技术架构说明
|
||
│ ├── package.json
|
||
│ ├── tsconfig.json
|
||
│ ├── run/ # 启动入口（start.ts / exchange.ts / build_aggregates_sql.ts）
|
||
│ ├── config/ # 配置（加载 env.yaml）
|
||
│ ├── db/ # TypeORM DataSource + 实体 + init-db SQL
|
||
│ ├── exchanges/ # 交易所适配器（base / binance / rest-registry / ws-manager）
|
||
│ ├── service/ # 业务层（backfill / kline / pair / aggregate）
|
||
│ ├── types/ # 共享类型（Kline / PairType / KlineInterval）
|
||
│ ├── utils/ # EventBus / Logger / 工具函数
|
||
│ └── tests/ # 测试（覆盖率建设中）
|
||
│
|
||
├── engine/ # 🐍 Python 策略引擎 🔄 进行中
|
||
│ ├── common/ # 策略基类 + 数据模型 + 日志
|
||
│ ├── backtest/ # 回测引擎
|
||
│ ├── indicators/ # 技术指标（ATR / MA / RSI …）
|
||
│ └── example/ # 示例策略（ma_cross / atr_band …）
|
||
│
|
||
├── executor/ # 🐍 Python 交易执行 ❌ 远期
|
||
├── risk/ # 🐍 Python 风控 ❌ 远期
|
||
├── monitor/ # 监控告警 ❌ 远期
|
||
├── api/ # API 网关 ❌ 远期
|
||
├── strategies/ # 策略目录 ❌ 远期
|
||
└── docs/ # 文档
|
||
```
|
||
|
||
---
|
||
|
||
## 部署与运维
|
||
|
||
### 服务组件依赖
|
||
|
||
```
|
||
┌──────────────────┐ ┌──────────────┐ ┌─────────────┐
|
||
│ TS 数据模块 │ │ PostgreSQL │ │ Grafana │
|
||
│ (Bun 进程) │ │ (业务数据) │ │ (可视化) │
|
||
└──────┬───────────┘ └──────────────┘ └──────┬──────┘
|
||
│ │
|
||
│ ┌──────────────┐ │
|
||
├────────────▶ TimescaleDB │◀────────────┤
|
||
│ │ (时序存储) │ │
|
||
│ └──────────────┘ │
|
||
│ │
|
||
│ ┌──────────────┐ │
|
||
├────────────▶ Redis ├─────────────┤
|
||
│ │ (队列/缓存) │ │
|
||
│ └──────┬───────┘ │
|
||
│ │ │
|
||
│ ┌──────▼───────┐ │
|
||
└────────────▶ Python 引擎 │ │
|
||
│ (策略+执行) │ │
|
||
└──────────────┘ │
|
||
```
|
||
|
||
### 容器化方案
|
||
|
||
```dockerfile
|
||
# Dockerfile.data — TypeScript 数据模块
|
||
FROM node:20-alpine AS builder
|
||
WORKDIR /app
|
||
COPY data/package*.json ./
|
||
RUN npm ci
|
||
COPY data/ .
|
||
RUN npm run build
|
||
|
||
FROM node:20-alpine AS runner
|
||
WORKDIR /app
|
||
COPY --from=builder /app/dist ./dist
|
||
COPY --from=builder /app/node_modules ./node_modules
|
||
CMD ["node", "dist/index.js"]
|
||
```
|
||
|
||
```dockerfile
|
||
# Dockerfile.engine — Python 业务引擎
|
||
FROM python:3.11-slim
|
||
WORKDIR /app
|
||
COPY pyproject.toml poetry.lock ./
|
||
RUN pip install poetry && poetry install --no-dev
|
||
COPY . .
|
||
CMD ["poetry", "run", "python", "-m", "engine.main"]
|
||
```
|
||
|
||
### 关键运维指标
|
||
|
||
- **API 延迟**：单次下单 < 500ms（网络延迟不计）
|
||
- **数据延迟**：行情从交易所到 Redis < 500ms（TypeScript 采集）
|
||
- **系统可用性**：核心交易链路 > 99.9%
|
||
- **策略执行周期**：秒级 tick 策略 < 100ms / 次
|
||
- **跨语言通信延迟**：Redis Pub/Sub < 1ms（同机部署）
|
||
|
||
---
|
||
|
||
## 注意事项与风险提示
|
||
|
||
> ⚠️ **风险声明**：数字货币交易具有高风险，本系统仅为技术实现，不构成任何投资建议。使用前请充分了解风险。
|
||
|
||
### 技术注意事项
|
||
|
||
1. **API 限频**：各交易所均有严格 API 限频，需实现本地限流器
|
||
2. **WebSocket 重连**：网络波动导致断线，需实现心跳检测和自动重连（指数退避策略）
|
||
3. **数据一致性**：订单状态需轮询确认，避免因异步回调丢失状态
|
||
4. **时间同步**：服务器需 NTP 同步，防止时间偏差导致下单失败
|
||
5. **日志安全**：避免记录 API Secret 等敏感信息到日志
|
||
6. **灰度发布**：新策略先在模拟盘运行，验证通过后方可接入实盘
|
||
7. **资金隔离**：不同策略的资金账户严格隔离，防止交叉影响
|
||
8. **跨语言类型一致性**：TypeScript 的 `zod` schema 和 Python 的 `Pydantic` model 需保持同步，建议用自动化脚本生成或共享 schema 文件
|
||
|
||
### 开发建议
|
||
|
||
1. **模块化开发**：各模块独立开发、独立测试，通过接口契约协作
|
||
2. **代码质量**：TS 用 `ESLint` + `Prettier`，Python 用 `ruff` + `mypy`
|
||
3. **版本控制**：配置文件和策略参数不应硬编码，使用 `.env` 或配置文件
|
||
4. **日志先行**：先写好日志，再写业务逻辑，便于调试
|
||
5. **单元测试**：核心逻辑（风控、订单状态机、K 线合成器）必须有单元测试覆盖
|
||
6. **模拟盘先行**：实盘前至少 2 周模拟盘验证策略稳定性
|
||
7. **本地开发**：Python 和 TS 模块分别 `npm run dev` / `poetry run dev` 独立开发调试
|
||
8. **schema 驱动**：考虑使用 Protocol Buffers 的 `.proto` 文件同时生成 TS 和 Python 代码，保证类型完全一致
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
MIT License
|