# 数字货币量化交易系统开发计划 > 基于 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 基于 PG，可共用）| | 消息队列 | Redis / NATS | 跨语言数据流解耦，事件驱动 | | 异步框架(TS) | `ws` + `axios` + `bull` | WebSocket 客户端、HTTP 请求、任务队列 | | 异步框架(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 支持最好 | #### 子模块划分 | 子模块 | 职责 | 关键技术点 | | ---------------- | -------------------------------------------------------------------- | ----------------------------------------------- | | **行情采集器** | 通过 WebSocket 订阅实时行情（ticker、orderbook、trade），定时拉取K线 | `ws`、断线重连、心跳检测、连接池管理 | | **K 线合成器** | 将实时 tick/trade 流合成为 OHLCV K 线，支持多周期并行、补齐、异常处理 | 时间桶算法、增量更新、多级合成(1m→5m→15m→1h) | | **数据存储** | K 线数据持久化到 TimescaleDB，订单数据存入 PostgreSQL | TimescaleDB hypertable、批量 UPSERT、列式压缩 | | **数据清洗** | 去除异常 tick、填充缺失值、处理停盘数据 | 统计异常检测、插值法 | | **数据发布** | 将处理后的数据通过消息队列推送给 Python 策略引擎 | Redis Pub/Sub、NATS、协议缓冲（Protocol Buffers） | #### 关键接口 ```typescript // src/data/collector.ts export interface DataFeed { subscribeTicker(symbols: string[]): Promise; subscribeOrderbook(symbol: string, depth: number): Promise; fetchKlines(symbol: string, interval: KlineInterval, limit?: number): Promise; } // src/data/types.ts export interface Ticker { exchange: string; symbol: string; price: number; volume: number; timestamp: number; } export interface Kline { exchange: string; symbol: string; interval: KlineInterval; open: number; high: number; low: number; close: number; volume: number; timestamp: number; } // src/data/pipeline.ts export class DataPipeline { constructor( private collector: DataFeed, private klineSynthesizer: KlineSynthesizer, private storage: DataStorage, private publisher: DataPublisher, ) {} async start(): Promise { // 启动数据流管道 const tickerStream = await this.collector.subscribeTicker(['BTCUSDT', 'ETHUSDT']); tickerStream .pipe(this.klineSynthesizer.transform()) .pipe(this.storage.writeStream()) .pipe(this.publisher.publishStream()); } } ``` --- #### K 线合成器详解 K 线合成器是数据模块中最核心的组件之一，负责将交易所推送的 **实时离散数据** 合成为标准的 **OHLCV K 线**。以下是其完整的工作机制。 ##### 1. 输入数据源 合成器接收三种类型的原始数据： | 数据源 | 交易所推送频率 | 数据量 | 用途 | |--------|---------------|--------|------| | **Ticker**（最新成交价） | 100ms~1s/次 | 中等 | 实时价格监控，快速 K 线更新 | | **Trade**（逐笔成交） | 毫秒级 | 极大 | 精确 K 线合成（推荐） | | **K 线（原始）** | 1s~1min（交易所合成好的） | 小 | 直接使用，无需合成（最快方案） | > **推荐方案**：使用 `Trade`（逐笔成交）作为主数据源合成 K 线，精度最高；`Ticker` 作为辅助用于快速预览。 ##### 2. 核心算法：时间桶（Time Bucket） ``` 时间轴（1分钟 K 线为例）: 时间桶 [t0, t0+1min) ┌─────────────────────────────────────────┐ │ Trade A Trade B Trade C │ │ p: 50000 p: 50020 p: 50010 │ │ v: 0.5 v: 1.2 v: 0.8 │ │ t: 00:10 t: 00:25 t: 00:45 │ │ │ │ OHLCV = { O: 50000, H: 50020, │ │ L: 50000, C: 50010, │ │ V: 2.5 } │ └─────────────────────────────────────────┘ ``` **算法步骤**： ``` 每收到一条 Trade/Ticker： 1. 计算时间桶索引：bucketIndex = floor(timestamp / interval_ms) 2. 如果 bucketIndex != currentBucketIndex: a. 关闭当前桶，emit K 线 b. 创建新桶，初始化 O=H=L=C=当前价格, V=当前成交量 3. 否则（仍在当前桶内）: a. O = 不变（桶内第一条的价格） b. H = max(H, 当前价格) c. L = min(L, 当前价格) d. C = 当前价格 e. V += 当前成交量 ``` ##### 3. 多周期并行合成 系统需要同时维护多个周期的 K 线（1m、5m、15m、1h...），有两种实现策略： **策略 A：独立合成（每个周期独立计算）** ✅ 推荐 ``` Trade 流 ──► 1m 合成器 ──► 1m K 线 ├──► 5m 合成器 ──► 5m K 线 ├──► 15m 合成器 ─► 15m K 线 └──► 1h 合成器 ──► 1h K 线 ``` - 每个周期维护独立的时间桶 - 优点：实现简单，各周期互不影响 - 缺点：内存占用随周期数量线性增长 **策略 B：多级合成（从低周期聚合为高周期）** ``` Trade 流 ──► 1m 合成器 ──► 5m 合成器 ──► 15m 合成器 ──► 1h 合成器 ↑ 由 5 根 1m 合成 ↑ 由 3 根 5m 合成 ``` - 高周期 K 线由低周期 K 线聚合而成 - 优点：内存效率高，无需为每个周期维护独立的 Trade 缓存 - 缺点：低周期 K 线未完成时，高周期无法产生完整 K 线 **混合策略（推荐）**： ``` Trade 流 ──► 1m 合成器（实时，数据源为 Trade） │ ▼ 1m K 线 ──► 5m 聚合器（由 5 根 1m 聚合） │ ▼ 5m K 线 ──► 15m 聚合器 │ ▼ 15m K 线 ──► 1h 聚合器 ``` 1m 用 Trade 实时合成（精度最高），5m 及以上从 1m 聚合（计算量最小）。 ##### 4. K 线补齐与边界处理 这是合成器最容易被忽视但极其重要的部分： | 场景 | 问题 | 处理方案 | |------|------|----------| | **无成交周期** | 某个 1m 区间内没有任何 Trade | 使用前一根 K 线的 Close 作为当前 K 线的 OHLC（平盘），Volume=0 | | **交易所暂停** | 交易所临时停盘或维护 | 停止 emit 新 K 线，标记为 `gap: true`，策略端跳过 | | **周期边界错位** | 交易所 1h K 线从整点开始，本地合成可能有时区偏移 | 使用 UTC 时间统一对齐，`bucketIndex = floor(utcTimestamp / intervalMs) * intervalMs` | | **首根 K 线不完整** | 系统启动时间不在周期起点，第一根 K 线数据不足 | emit 时标记 `isPartial: true`，策略端可选择忽略或使用 | | **数据延迟/乱序** | Trade 到达顺序与发生顺序不一致 | 缓冲区保留 100ms 的排序窗口，按 timestamp 排序后处理 | ##### 5. 增量更新 vs 完整替换 ```typescript // 增量更新模式（推荐）—— 只推送变化部分，大幅减少数据量 interface KlineDelta { exchange: string; symbol: string; interval: KlineInterval; bucketTime: number; // 时间桶起始时间戳（毫秒） o: number; // Open（只在开桶时更新） h: number; // High l: number; // Low c: number; // Close v: number; // Volume isClosed: boolean; // 当前桶是否已关闭（不再变化） tradeCount: number; // 桶内的成交笔数 } // 完整 K 线（用于回测和历史数据） interface Kline { exchange: string; symbol: string; interval: KlineInterval; openTime: number; closeTime: number; open: number; high: number; low: number; close: number; volume: number; quoteVolume: number; // 成交额 takerBuyBaseVolume: number; // 主动买入量 takerBuyQuoteVolume: number; // 主动买入额 tradeCount: number; // 成交笔数 } ``` ##### 6. 完整实现示例 ```typescript // src/data/pipeline/kline-synthesizer.ts import { Subject, interval } from 'rxjs'; import { bufferTime, filter, map } from 'rxjs/operators'; type KlineInterval = '1m' | '5m' | '15m' | '30m' | '1h' | '4h' | '1d'; const INTERVAL_MS: Record = { '1m': 60_000, '5m': 300_000, '15m': 900_000, '30m': 1_800_000, '1h': 3_600_000, '4h': 14_400_000, '1d': 86_400_000, }; interface Trade { price: number; amount: number; timestamp: number; } interface KlineBucket { openTime: number; open: number; high: number; low: number; close: number; volume: number; tradeCount: number; isClosed: boolean; } export class KlineSynthesizer { private buckets = new Map(); /** * 核心合成方法：输入一条 Trade，输出（可能）闭合的 K 线 */ synthesize( symbol: string, interval: KlineInterval, trade: Trade, ): KlineBucket | null { const intervalMs = INTERVAL_MS[interval]; const bucketTime = Math.floor(trade.timestamp / intervalMs) * intervalMs; const key = `${symbol}:${interval}:${bucketTime}`; let bucket = this.buckets.get(key); if (!bucket) { // 新时间桶：初始化 bucket = { openTime: bucketTime, open: trade.price, high: trade.price, low: trade.price, close: trade.price, volume: trade.amount, tradeCount: 1, isClosed: false, }; this.buckets.set(key, bucket); return null; // 新桶第一条，暂不 emit } // 更新当前桶 bucket.high = Math.max(bucket.high, trade.price); bucket.low = Math.min(bucket.low, trade.price); bucket.close = trade.price; bucket.volume += trade.amount; bucket.tradeCount += 1; return null; // 桶未关闭 } /** * 关闭过期桶（由定时器调用），返回所有已关闭的 K 线 */ closeExpiredBuckets(now: number): KlineBucket[] { const closed: KlineBucket[] = []; for (const [key, bucket] of this.buckets.entries()) { if (!bucket.isClosed && now >= bucket.openTime + INTERVAL_MS['1m']) { bucket.isClosed = true; closed.push(bucket); this.buckets.delete(key); } } return closed; } /** * RxJS 操作符：将 Trade 流转换为 K 线流 */ transform(interval: KlineInterval) { return (source: Subject) => { const output = new Subject(); // 每笔 Trade 更新桶 source.subscribe((trade) => { this.synthesize('BTCUSDT', interval, trade); }); // 定时检查过期桶（每秒一次） interval(1000).subscribe(() => { const closed = this.closeExpiredBuckets(Date.now()); closed.forEach((k) => output.next(k)); }); return output; }; } } ``` ##### 7. 性能考量 | 指标 | 数据量 | 说明 | |------|--------|------| | **单币种 Trade/秒** | ~50~200 tps | BTCUSDT 高峰期 | | **单币种 Ticker/秒** | ~10 tps | Binance WebSocket 推送频率 | | **内存开销/币种** | ~1~5 MB | 100 个并行时间桶 | | **单笔合成耗时** | < 1 μs | Node.js V8 优化后 | | **10 币种 5 周期并行** | ~500 μs/轮 | 全部更新一次 | > **优化建议**：对于高频币种（BTC/ETH），可以采用 Trade 合成 + 1m K 线直接复用交易所推送的原始 K 线（无需自行合成）。 ##### 8. 与交易所 K 线的差异处理 | 差异项 | 交易所推送 K 线 | 本地合成 K 线 | |--------|---------------|-------------| | **延迟** | 通常延迟 1~5 秒 | 实时（Trade 到达即更新） | | **精度** | 包含所有成交数据 | 取决于 WebSocket 推送的 Trade 覆盖率 | | **完整性** | 最终数据，不可变 | 可能因断线导致缺失（需补齐） | | **自定义周期** | 仅支持标准周期 | 支持任意周期（如 3m、7m、自定义） | | **多交易所对齐** | 各交易所时间不同 | 使用 UTC 统一对齐 | > **最佳实践**：本地合成 K 线用于 **实时策略决策**，交易所 K 线用于 **回测和历史分析**。两者结合使用。 --- #### TimescaleDB 数据存储方案 K 线数据具有典型的时序特征：**持续写入、按时间范围查询、少有更新、数据量大**。TimescaleDB 作为 PostgreSQL 的时序扩展，相比 InfluxDB 有以下核心优势： | 对比维度 | TimescaleDB | InfluxDB | |---------|------------|----------| | **基础数据库** | PostgreSQL 扩展 | 独立时序数据库 | | **SQL 兼容** | 完整 SQL 支持（JOIN、子查询、窗口函数） | 类 SQL 但不完全兼容 | | **与业务数据关联** | K 线表和订单表可以在同一个 PG 实例中 JOIN | 需要跨数据库查询 | | **数据压缩** | 列式压缩，压缩比 90%+ | 压缩比约 85% | | **连续聚合** | 内置自动刷新物化视图 | 需要外部工具 | | **保留策略** | 内置自动删除（数据保留策略） | 内置 | | **生态集成** | 可与 PostGIS、pgvector 等 PG 扩展共存 | 独立生态 | | **运维成本** | 复用 PG 运维经验 | 需独立运维 | ##### 1. 表结构设计 ```sql -- 创建 TimescaleDB 扩展 CREATE EXTENSION IF NOT EXISTS timescaledb; CREATE EXTENSION IF NOT EXISTS timescaledb_toolkit; -- ============================================ -- 1. K 线主表（hypertable） -- ============================================ CREATE TABLE klines ( time TIMESTAMPTZ NOT NULL, -- K 线开盘时间 exchange TEXT NOT NULL, -- 交易所 (binance/okx/bybit) symbol TEXT NOT NULL, -- 交易对 (BTCUSDT/ETHUSDT) interval TEXT NOT NULL, -- 周期 (1m/5m/15m/1h/4h/1d) -- OHLCV 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, -- 扩展字段 quote_volume NUMERIC(20,8), -- 成交额（计价币种） taker_buy_base_vol NUMERIC(20,8), -- 主动买入成交量 taker_buy_quote_vol NUMERIC(20,8), -- 主动买入成交额 trade_count INTEGER, -- 成交笔数 is_closed BOOLEAN DEFAULT TRUE, -- K 线是否已关闭 -- 元数据 created_at TIMESTAMPTZ DEFAULT NOW(), -- 记录创建时间 updated_at TIMESTAMPTZ DEFAULT NOW(), -- 最后更新时间 -- 分区键 -- time 是分区列，symbol + interval 是分布列 UNIQUE (time, exchange, symbol, interval) ); -- 转换为 hypertable（按时间和空间分区） SELECT create_hypertable( 'klines', 'time', -- 时间分区列 chunk_time_interval => INTERVAL '1 day', -- 每分区 1 天数据 partitioning_column => 'exchange', -- 空间分区列 number_partitions => 4, -- 4 个空间分区 if_not_exists => TRUE ); -- ============================================ -- 2. 索引设计 -- ============================================ -- 查询最频繁：按交易对+周期+时间范围查 CREATE INDEX idx_klines_lookup ON klines (exchange, symbol, interval, time DESC); -- 回测查询：按交易对+周期+时间范围 CREATE INDEX idx_klines_backtest ON klines (symbol, interval, time ASC); -- 最新 K 线查询 CREATE INDEX idx_klines_latest ON klines (exchange, symbol, interval, time DESC) WHERE is_closed = TRUE; -- ============================================ -- 3. 数据压缩策略 -- ============================================ -- 启用压缩（已关闭的 K 线自动压缩） ALTER TABLE klines SET ( timescaledb.compress, timescaledb.compress_segmentby = 'exchange, symbol, interval', timescaledb.compress_orderby = 'time DESC' ); -- 自动压缩策略：K 线关闭 7 天后压缩 SELECT add_compression_policy('klines', INTERVAL '7 days', if_not_exists => TRUE); -- ============================================ -- 4. 数据保留策略 -- ============================================ -- 1m K 线保留 30 天 SELECT add_retention_policy('klines', INTERVAL '30 days', if_not_exists => TRUE); ``` ##### 2. 连续聚合（Continuous Aggregates） 连续聚合是 TimescaleDB 最强大的功能之一 —— 自动从低周期 K 线聚合为高周期 K 线，无需手动维护。 ```sql -- ============================================ -- 5m K 线（从 1m 自动聚合） -- ============================================ CREATE MATERIALIZED VIEW klines_5m WITH (timescaledb.continuous) AS SELECT time_bucket('5 minutes', time) AS time, exchange, symbol, '5m'::TEXT AS interval, FIRST(open, time) AS open, MAX(high) AS high, MIN(low) AS low, LAST(close, time) AS close, SUM(volume) AS volume, SUM(quote_volume) AS quote_volume, SUM(taker_buy_base_vol) AS taker_buy_base_vol, SUM(taker_buy_quote_vol) AS taker_buy_quote_vol, SUM(trade_count) AS trade_count FROM klines WHERE interval = '1m' GROUP BY time_bucket('5 minutes', time), exchange, symbol; -- 自动刷新策略（每 1 分钟刷新最近 10 分钟数据） SELECT add_continuous_aggregate_policy('klines_5m', start_offset => INTERVAL '1 day', end_offset => INTERVAL '10 minutes', -- 留 10 分钟给延迟数据 schedule_interval => INTERVAL '1 minute', if_not_exists => TRUE ); -- ============================================ -- 15m K 线 -- ============================================ CREATE MATERIALIZED VIEW klines_15m WITH (timescaledb.continuous) AS SELECT time_bucket('15 minutes', time) AS time, exchange, symbol, '15m'::TEXT AS interval, FIRST(open, time), MAX(high), MIN(low), LAST(close, time), SUM(volume), SUM(quote_volume), SUM(taker_buy_base_vol), SUM(taker_buy_quote_vol), SUM(trade_count) FROM klines WHERE interval = '1m' GROUP BY time_bucket('15 minutes', time), exchange, symbol; SELECT add_continuous_aggregate_policy('klines_15m', start_offset => INTERVAL '2 days', end_offset => INTERVAL '30 minutes', schedule_interval => INTERVAL '5 minutes', if_not_exists => TRUE ); -- ============================================ -- 1h K 线 -- ============================================ CREATE MATERIALIZED VIEW klines_1h WITH (timescaledb.continuous) AS SELECT time_bucket('1 hour', time) AS time, exchange, symbol, '1h'::TEXT AS interval, FIRST(open, time), MAX(high), MIN(low), LAST(close, time), SUM(volume), SUM(quote_volume), SUM(taker_buy_base_vol), SUM(taker_buy_quote_vol), SUM(trade_count) FROM klines WHERE interval = '1m' GROUP BY time_bucket('1 hour', time), exchange, symbol; SELECT add_continuous_aggregate_policy('klines_1h', start_offset => INTERVAL '3 days', end_offset => INTERVAL '1 hour', schedule_interval => INTERVAL '5 minutes', if_not_exists => TRUE ); -- ============================================ -- 1d K 线（含周线、月线可在查询时用 time_bucket） -- ============================================ CREATE MATERIALIZED VIEW klines_1d WITH (timescaledb.continuous) AS SELECT time_bucket('1 day', time) AS time, exchange, symbol, '1d'::TEXT AS interval, FIRST(open, time), MAX(high), MIN(low), LAST(close, time), SUM(volume), SUM(quote_volume), SUM(taker_buy_base_vol), SUM(taker_buy_quote_vol), SUM(trade_count) FROM klines WHERE interval = '1m' GROUP BY time_bucket('1 day', time), exchange, symbol; SELECT add_continuous_aggregate_policy('klines_1d', start_offset => INTERVAL '7 days', end_offset => INTERVAL '2 hours', schedule_interval => INTERVAL '1 hour', if_not_exists => TRUE ); ``` **查询示例**： ```sql -- 查询 BTC 最近 100 根 1h K 线（自动走连续聚合） SELECT * FROM klines_1h WHERE symbol = 'BTCUSDT' AND exchange = 'binance' ORDER BY time DESC LIMIT 100; -- 查询 BTC 1h K 线的周线 SELECT time_bucket('1 week', time) AS week, FIRST(open, time), MAX(high), MIN(low), LAST(close, time), SUM(volume) FROM klines_1h WHERE symbol = 'BTCUSDT' GROUP BY week ORDER BY week DESC; -- 统计最近 7 天各币种波动率 SELECT symbol, MAX(high) / MIN(low) - 1 AS volatility FROM klines_1h WHERE time > NOW() - INTERVAL '7 days' GROUP BY symbol ORDER BY volatility DESC; ``` ##### 3. 空间与时间分区原理 ``` hypertable: klines ┌─────────────────────────────────────────────────────┐ │ 时间线 │ │ │ │ chunk_1 (2024-01-01) chunk_2 (2024-01-02) ... │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ exchange=A │ │ exchange=A │ │ │ │ exchange=B │ │ exchange=B │ │ │ │ exchange=C │ │ exchange=C │ │ │ │ exchange=D │ │ exchange=D │ │ │ └──────────────────┘ └──────────────────┘ │ │ │ │ 每个 chunk 内部按 exchange 做空间分区 │ │ chunk 大小 ≈ 1 天数据（自动调整） │ └─────────────────────────────────────────────────────┘ ``` | 参数 | 值 | 说明 | |------|----|------| | `chunk_time_interval` | `1 day` | 每个 chunk 存储 1 天数据，约 100~500MB | | `number_partitions` | 4 | 按交易所分区，4 个空间分区 | | 空间分区列 | `exchange` | Binance/OKX/Bybit 等分布在不同分区 | ##### 4. TypeScript 写入实现 ```typescript // data/src/storage/timescaledb.ts import { Pool } from 'pg'; interface KlineRecord { time: Date; exchange: string; symbol: string; interval: string; open: number; high: number; low: number; close: number; volume: number; quoteVolume: number; takerBuyBaseVol: number; takerBuyQuoteVol: number; tradeCount: number; isClosed: boolean; } export class TimescaleDBStorage { private pool: Pool; private batchBuffer: KlineRecord[] = []; private batchSize: number; private flushInterval: number; constructor(config: { connectionString: string; batchSize?: number; // 批量写入条数，默认 500 flushIntervalMs?: number; // 最大等待时间，默认 1000ms }) { this.pool = new Pool({ connectionString: config.connectionString }); this.batchSize = config.batchSize ?? 500; this.flushInterval = config.flushIntervalMs ?? 1000; // 定时刷新缓冲区 setInterval(() => this.flush(), this.flushInterval); } /** * 写入单条 K 线（加入缓冲区，批量写入） */ async write(kline: KlineRecord): Promise { this.batchBuffer.push(kline); if (this.batchBuffer.length >= this.batchSize) { await this.flush(); } } /** * 批量刷新缓冲区 */ async flush(): Promise { if (this.batchBuffer.length === 0) return; const batch = this.batchBuffer.splice(0, this.batchSize); const client = await this.pool.connect(); try { // 使用 UNLOGGED 表写入时跳过 WAL 日志（提升写入性能） await client.query('SET LOCAL timescaledb.enable_skip_scan = ON'); // 批量 UPSERT：已存在的 K 线只更新 close/high/low（增量更新） const values = batch.map((k, i) => { const offset = i * 14; return `($${offset + 1}, $${offset + 2}, $${offset + 3}, $${offset + 4}, $${offset + 5}, $${offset + 6}, $${offset + 7}, $${offset + 8}, $${offset + 9}, $${offset + 10}, $${offset + 11}, $${offset + 12}, $${offset + 13}, $${offset + 14})`; }).join(','); const params = batch.flatMap(k => [ k.time, k.exchange, k.symbol, k.interval, k.open, k.high, k.low, k.close, k.volume, k.quoteVolume, k.takerBuyBaseVol, k.takerBuyQuoteVol, k.tradeCount, k.isClosed, ]); await client.query(` INSERT INTO klines ( time, exchange, symbol, interval, open, high, low, close, volume, quote_volume, taker_buy_base_vol, taker_buy_quote_vol, trade_count, is_closed ) VALUES ${values} ON CONFLICT (time, exchange, symbol, interval) DO UPDATE SET high = GREATEST(klines.high, EXCLUDED.high), low = LEAST(klines.low, EXCLUDED.low), close = EXCLUDED.close, volume = klines.volume + EXCLUDED.volume, trade_count = klines.trade_count + EXCLUDED.trade_count, is_closed = EXCLUDED.is_closed, updated_at = NOW() `, params); } finally { client.release(); } } /** * 查询 K 线 */ async query(options: { exchange: string; symbol: string; interval: string; startTime: Date; endTime: Date; limit?: number; }): Promise { const result = await this.pool.query(` SELECT * FROM klines WHERE exchange = $1 AND symbol = $2 AND interval = $3 AND time >= $4 AND time <= $5 ORDER BY time ASC LIMIT $6 `, [ options.exchange, options.symbol, options.interval, options.startTime, options.endTime, options.limit ?? 1000, ]); return result.rows; } async close(): Promise { await this.flush(); await this.pool.end(); } } ``` ##### 5. 写入性能优化策略 | 策略 | 说明 | 效果 | |------|------|------| | **批量写入** | 每 500 条或 1 秒批量写入一次 | 减少 99% 的数据库连接开销 | | **UPSERT** | 用 `ON CONFLICT DO UPDATE` 处理同一 K 线的增量更新 | 避免重复写入 | | **连接池** | `pg.Pool` 管理 10~20 个连接 | 控制并发，避免 PG 连接暴涨 | | **压缩** | 关闭 7 天后自动压缩 | 存储空间减少 90%+ | | **chunk 对齐** | chunk 按天分区，避免跨分区查询 | 查询性能提升 10x | | **索引** | 精确的复合索引覆盖所有查询模式 | 避免全表扫描 | ##### 6. Python 读取实现（策略引擎侧） ```python # engine/common/storage.py import asyncpg from datetime import datetime from typing import Optional class TimescaleDBReader: """Python 策略引擎侧的 K 线读取器""" def __init__(self, dsn: str): self.dsn = dsn self.pool: Optional[asyncpg.Pool] = None async def connect(self): self.pool = await asyncpg.create_pool( self.dsn, min_size=5, max_size=20, command_timeout=10, ) async def get_klines( self, symbol: str, interval: str, start_time: datetime, end_time: datetime, exchange: str = "binance", limit: int = 1000, ) -> list[dict]: """ 获取 K 线数据（自动路由到连续聚合视图） 当 interval >= '1h' 时，自动使用连续聚合视图查询， 性能远优于扫描原始 1m 表。 """ # 自动路由到对应的物化视图 view_map = { "5m": "klines_5m", "15m": "klines_15m", "30m": "klines_30m", "1h": "klines_1h", "4h": "klines_4h", "1d": "klines_1d", } table = view_map.get(interval, "klines") async with self.pool.acquire() as conn: rows = await conn.fetch( f""" SELECT time, open, high, low, close, volume, quote_volume, trade_count FROM {table} WHERE exchange = $1 AND symbol = $2 AND interval = $3 AND time >= $4 AND time <= $5 ORDER BY time ASC LIMIT $6 """, exchange, symbol, interval, start_time, end_time, limit, ) return [dict(row) for row in rows] async def get_latest_kline( self, symbol: str, interval: str, exchange: str = "binance", ) -> Optional[dict]: """获取最新一根 K 线""" async with self.pool.acquire() as conn: row = await conn.fetchrow( """ SELECT * FROM klines WHERE exchange = $1 AND symbol = $2 AND interval = $3 AND is_closed = TRUE ORDER BY time DESC LIMIT 1 """, exchange, symbol, interval, ) return dict(row) if row else None async def get_ohlcv_batch( self, symbol: str, interval: str, limit: int = 200, exchange: str = "binance", ) -> list[tuple]: """ 获取 OHLCV 数组（直接用于 pandas DataFrame 或 TA-Lib 计算） 返回格式: [(timestamp, open, high, low, close, volume), ...] """ view_map = { "5m": "klines_5m", "15m": "klines_15m", "1h": "klines_1h", "4h": "klines_4h", "1d": "klines_1d", } table = view_map.get(interval, "klines") async with self.pool.acquire() as conn: rows = await conn.fetch( f""" SELECT time, open, high, low, close, volume FROM {table} WHERE exchange = $1 AND symbol = $2 AND interval = $3 ORDER BY time DESC LIMIT $4 """, exchange, symbol, interval, limit, ) # 正序返回 return [ (row['time'], row['open'], row['high'], row['low'], row['close'], row['volume']) for row in reversed(rows) ] async def close(self): if self.pool: await self.pool.close() ``` ##### 7. 磁盘空间估算 ```sql -- 单币种单交易所 1m K 线行数 -- 1天 = 1440 行，1月 ≈ 43200 行，1年 ≈ 525600 行 -- 无压缩时： -- 1 行 ≈ 180 bytes -- 10 币种 × 1 年 × 180 B = 945 MB -- 启用压缩后（压缩比约 92%）： -- 10 币种 × 1 年 × 180 B × 8% ≈ 75 MB -- 50 币种 × 1 年 ≈ 375 MB ``` | 数据量 | 未压缩 | 压缩后 (92%) | 连续聚合额外 | |--------|--------|-------------|------------| | 10 币种 / 1 年 | ~945 MB | ~75 MB | ~30 MB | | 50 币种 / 1 年 | ~4.7 GB | ~375 MB | ~150 MB | | 200 币种 / 1 年 | ~18.9 GB | ~1.5 GB | ~600 MB | ##### 8. Docker Compose 配置 ```yaml # docker-compose.yml version: '3.8' services: timescaledb: image: timescale/timescaledb:2-pg16 container_name: trade-timescaledb restart: unless-stopped ports: - "5432:5432" environment: POSTGRES_DB: trade POSTGRES_USER: trader POSTGRES_PASSWORD: ${DB_PASSWORD:-changeme} volumes: - timescaledb-data:/var/lib/postgresql/data - ./data/init-db:/docker-entrypoint-initdb.d # 自动执行建表 SQL command: > -c shared_buffers=1GB -c effective_cache_size=3GB -c maintenance_work_mem=256MB -c work_mem=64MB -c wal_buffers=64MB -c random_page_cost=1.1 -c effective_io_concurrency=200 -c max_connections=50 healthcheck: test: ["CMD-SHELL", "pg_isready -U trader -d trade"] interval: 10s timeout: 5s retries: 5 volumes: timescaledb-data: ``` > **初始化脚本**：将上述建表 SQL 保存为 `data/init-db/001_init.sql`，容器首次启动时自动执行。 --- #### 推荐的 npm 包 | 包名 | 用途 | |------|------| | `ws` | WebSocket 客户端（轻量、高性能） | | `ccxt` | 统一交易所 API（支持 100+ 交易所） | | `pg` | PostgreSQL 客户端（TimescaleDB 兼容） | | `ioredis` | Redis 客户端（支持集群、哨兵） | | `zod` | 运行时数据校验，与 Python Pydantic 对应 | | `pino` | 高性能结构化日志 | | `rxjs` | 响应式编程，优雅处理数据流 | | `bull` / `bullmq` | Redis 任务队列，用于定时采集任务 | | `technicalindicators` | 技术指标计算（备选） | --- ### 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 数据模块 │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Binance │ │ OKX │ │ Bybit │ │ │ │ WS Adapter │ │ WS Adapter │ │ WS Adapter │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ └───────────────────┼───────────────────┘ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ 统一行情流 (RxJS Observable) │ │ │ │ ┌───────────┐ ┌──────────┐ ┌─────────────────┐ │ │ │ │ │ ticker$ │ │ trade$ │ │ orderbook$ │ │ │ │ │ └─────┬─────┘ └────┬─────┘ └───────┬─────────┘ │ │ │ └────────┼──────────────┼────────────────┼─────────────┘ │ │ ▼ ▼ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ K 线合成器 (时间桶算法) │ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ │ │ 1m │ │ 5m │ │ 15m │ │ 1h │ ... │ │ │ │ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ │ │ │ └────────┼────────┼────────┼────────┼─────────────────┘ │ │ ▼ ▼ ▼ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ 数据清洗 & 异常检测 │ │ │ └───────────────┬──────────────────┬───────────────────┘ │ │ ▼ ▼ │ │ ┌─────────────────────┐ ┌─────────────────────────┐ │ │ │ TimescaleDB 写入器 │ │ Redis Pub/Sub 发布者 │ │ │ └─────────────────────┘ └───────────┬─────────────┘ │ └────────────────────────────────────────┼───────────────────┘ │ ▼ ┌────────────────────┐ │ Python 策略引擎 │ │ (消费实时行情) │ └────────────────────┘ ``` ### 数据流生命周期 ``` 交易所 WS ──► TypeScript 采集器 ──► RxJS 管道 │ ┌───────────┴───────────┐ │ │ ▼ ▼ TimescaleDB 持久化 Redis Pub/Sub │ │ ▼ ▼ Grafana 查询 Python 策略消费 (历史分析) (实时交易) ``` ### TypeScript 数据模块目录结构 ``` data/ ├── package.json ├── tsconfig.json ├── vitest.config.ts ├── src/ │ ├── index.ts # 模块入口 │ ├── config.ts # 配置（基于 zod 校验） │ ├── logger.ts # 日志（pino） │ │ │ ├── exchanges/ # 交易所适配器 │ │ ├── types.ts # 交易所统一接口 │ │ ├── base.ts # 抽象基类 │ │ ├── binance.ts # Binance 实现 │ │ ├── okx.ts # OKX 实现 │ │ └── bybit.ts # Bybit 实现 │ │ │ ├── pipeline/ # 数据管道 │ │ ├── kline-synthesizer.ts # K 线合成器 │ │ ├── cleaner.ts # 数据清洗 │ │ └── transformer.ts # 数据转换 │ │ │ ├── storage/ # 数据存储 │ │ ├── timescaledb.ts # TimescaleDB 写入器 │ │ └── postgres.ts # PostgreSQL 客户端（业务数据） │ │ │ ├── publisher/ # 数据发布 │ │ ├── redis.ts # Redis Pub/Sub │ │ └── nats.ts # NATS（可选） │ │ │ ├── types/ # 类型定义 │ │ ├── market.ts # Ticker, Kline, Trade… │ │ ├── exchange.ts # 交易所枚举 │ │ └── enums.ts # 常量枚举 │ │ │ └── utils/ # 工具函数 │ ├── retry.ts # 重试逻辑 │ ├── rate-limiter.ts # 限频器 │ └── time.ts # 时间工具 │ └── tests/ ├── exchanges/ ├── pipeline/ └── storage/ ``` ### Python ↔ TypeScript 跨语言通信 ``` ┌──────────────────┐ Redis/NATS ┌──────────────────┐ │ 🟦 TypeScript │ ──────────────────────────► │ 🐍 Python │ │ 数据模块 │ Pub: "market:ticker" │ 策略引擎 │ │ │ Pub: "market:kline:1m" │ │ │ │ Pub: "market:trade" │ Sub: 消费行情 │ └──────────────────┘ └──────────────────┘ │ │ │ Redis Pub/Sub 频道设计 │ │ ───────────────────── │ │ market:ticker:{exchange}:{symbol} │ │ market:kline:{exchange}:{symbol}:{interval} │ │ market:trade:{exchange}:{symbol} │ │ system:heartbeat:{module} │ │ system:error:{module} │ │ │ └─────────────────────────────────────────────────┘ ``` **数据序列化格式**：推荐使用 **Protocol Buffers** 或 **MessagePack**，比 JSON 更小、更快： ```typescript // TypeScript 侧 - 发布 const data = { symbol: 'BTCUSDT', price: 50000, timestamp: Date.now() }; const encoded = msgpack.encode(data); // 比 JSON 小 30-50% await redis.publish('market:ticker:binance:BTCUSDT', encoded); ``` ```python # Python 侧 - 消费 import msgpack async with redis.pubsub() as pubsub: await pubsub.subscribe('market:ticker:binance:BTCUSDT') async for msg in pubsub.listen(): if msg['type'] == 'message': data = msgpack.unpackb(msg['data']) await strategy.on_ticker(Ticker(**data)) ``` --- ## 开发步骤 ### 第一阶段：基础建设（第 1-2 周） **目标**：搭建项目骨架，完成 TypeScript 数据模块的基础能力和 Python 项目基础。 | 步骤 | 任务 | 产出物 | | ---- | ------------------------------------------------------------ | ----------------------------------- | | 1.1 | 初始化 TypeScript 数据项目（`data/`），配置 `package.json` | 项目结构，ESLint + Prettier 配置 | | 1.2 | 初始化 Python 项目，配置 `poetry` / `uv` 依赖管理 | `pyproject.toml`，项目目录结构 | | 1.3 | 定义共享类型：TypeScript `types/` + Python `engine/common/models.py` | 双端对齐的数据模型 | | 1.4 | 实现 TS 交易所适配器基类 + Binance 适配器（`data/src/exchanges/`） | 统一接口 + WebSocket 连接 | | 1.5 | 实现 TS 行情采集器，WebSocket 订阅实时 ticker 和 K 线 | 实时行情流入 | | 1.6 | 实现 TS K 线合成器（`data/src/pipeline/kline-synthesizer.ts`） | 多周期 K 线实时合成 | | 1.7 | 实现 TS 数据存储模块，写入 TimescaleDB | 数据持久化 | | 1.8 | 实现 TS → Redis 数据发布 | 实时行情推送到消息队列 | | 1.9 | Python 侧实现配置管理 + 日志 + Redis 订阅消费者 | 消费端就绪 | | 1.10 | Docker Compose 编排基础服务（TimescaleDB / Redis） | `docker-compose.yml` | ### 第二阶段：策略与回测（第 3-4 周） **目标**：实现策略框架和回测引擎，能编写策略并进行回测验证。 | 步骤 | 任务 | 产出物 | | ---- | ------------------------------------------------------------ | -------------------------------- | | 2.1 | 实现策略基类（`engine/common/base.py`） | `BaseStrategy` 抽象基类 | | 2.2 | 实现策略管理器（`engine/manager.py`），支持策略注册和生命周期 | 策略热加载、启动/停止控制 | | 2.3 | 实现信号分发器（`engine/signals.py`） | 事件总线，策略到执行器的信号传递 | | 2.4 | 实现回测引擎（`engine/backtest.py`） | 历史数据回测，收益曲线、回撤等指标 | | 2.5 | 实现技术指标计算（`data/indicators.py`） | MA、MACD、RSI 等常用指标 | | 2.6 | 编写示例策略 1：双均线交叉策略 | 可运行的策略示例 | | 2.7 | 编写示例策略 2：网格交易策略 | 可运行的策略示例 | | 2.8 | 实现参数优化器（`engine/optimizer.py`） | 基于 Optuna 的参数搜索 | ### 第三阶段：交易执行与风控（第 5-6 周） **目标**：连接实盘交易通道，实现完整的交易执行流程和风控体系。 | 步骤 | 任务 | 产出物 | | ---- | ------------------------------------------------------------ | --------------------------------- | | 3.1 | 实现订单管理器（`executor/order_manager.py`） | 下单、撤单、订单状态更新 | | 3.2 | 实现仓位管理器（`executor/position_manager.py`） | 实时仓位跟踪 | | 3.3 | 实现交易状态机（`executor/state_machine.py`） | 订单生命周期管理（Created→Filled） | | 3.4 | 实现重试与容错机制（`executor/retry.py`） | 网络异常自动重试、幂等性保证 | | 3.5 | 实现风控管理器（`risk/manager.py`） | 资金管理、仓位限制、熔断逻辑 | | 3.6 | 实现风控规则引擎（`risk/rules.py`） | 可扩展的风控规则链 | | 3.7 | 整合 TS 数据模块 → Redis → Python 策略引擎 → 交易执行的端到端流程 | 完整的跨语言运行流水线 | | 3.8 | 编写集成测试，模拟实盘环境验证 | 测试覆盖率报告 | ### 第四阶段：API 与监控（第 7-8 周） **目标**：完善系统的可观测性和对外接口。 | 步骤 | 任务 | 产出物 | | ---- | ------------------------------------------------------------ | ----------------------------------- | | 4.1 | 搭建 FastAPI 项目（`api/main.py`） | REST API 服务启动 | | 4.2 | 实现 WebSocket 实时推送（`api/ws.py`） | 行情和交易数据实时推送 | | 4.3 | 实现策略管理 API（`api/routes/strategies.py`） | 策略启停、参数修改接口 | | 4.4 | 实现交易记录查询 API（`api/routes/trades.py`） | 交易历史查询 | | 4.5 | 集成 Prometheus 指标（`monitor/metrics.py`） | 关键业务指标暴露 | | 4.6 | 配置 Grafana 仪表盘 | 可视化资金曲线、交易频率、策略绩效 | | 4.7 | 实现告警通知集成（`monitor/alerts.py`） | Telegram / 钉钉通知 | | 4.8 | JWT 用户认证与 API Key 管理 | 安全访问控制 | ### 第五阶段：优化与生产化（第 9-10 周） **目标**：性能优化，系统加固，上线准备。 | 步骤 | 任务 | 产出物 | | ---- | ------------------------------------------------------------ | -------------------------------- | | 5.1 | 性能优化：数据库批量写入、连接池调优、TS/Python 异步性能分析 | 性能测试报告 | | 5.2 | 增加单元测试与集成测试，目标覆盖率 > 80% | 测试报告 | | 5.3 | 编写部署文档（`docs/deployment.md`） | 部署手册 | | 5.4 | 编写使用文档（`docs/usage.md`） | 用户手册 | | 5.5 | CI/CD 流水线配置（GitHub Actions） — TS 和 Python 双管道 | 自动化测试、构建、部署 | | 5.6 | 压力测试与稳定性测试 | 压测报告 | | 5.7 | 生产环境部署与监控上線 | 线上系统 | --- ## 项目目录结构 ``` trade/ ├── pyproject.toml # Python 项目依赖与配置（Poetry / uv） ├── package.json # TS 项目根依赖（可选 monorepo 管理） ├── docker-compose.yml # 基础服务编排 ├── Dockerfile # 应用容器化 ├── .env.example # 环境变量模板 ├── .gitignore ├── README.md │ ├── config/ # Python 配置文件 │ ├── __init__.py │ ├── settings.py # pydantic-settings 全局配置 │ └── strategies/ # 策略配置文件 │ ├── ma_cross.yaml │ └── grid_trading.yaml │ ├── data/ # 🟦 TypeScript 数据模块 │ ├── package.json │ ├── tsconfig.json │ ├── vitest.config.ts │ ├── src/ │ │ ├── index.ts # 模块入口 │ │ ├── config.ts # 配置 │ │ ├── exchanges/ # 交易所适配器 │ │ │ ├── types.ts │ │ │ ├── base.ts │ │ │ ├── binance.ts │ │ │ ├── okx.ts │ │ │ └── bybit.ts │ │ ├── pipeline/ # 数据管道 │ │ │ ├── kline-synthesizer.ts │ │ │ ├── cleaner.ts │ │ │ └── transformer.ts │ │ ├── storage/ # 数据存储 │ │ │ ├── timescaledb.ts # TimescaleDB K 线写入 │ │ │ └── postgres.ts # PostgreSQL 其他数据 │ │ ├── publisher/ # 数据发布 │ │ │ ├── redis.ts │ │ │ └── nats.ts │ │ ├── types/ # 类型定义 │ │ │ ├── market.ts │ │ │ ├── exchange.ts │ │ │ └── enums.ts │ │ └── utils/ │ │ ├── retry.ts │ │ ├── rate-limiter.ts │ │ └── time.ts │ └── tests/ │ ├── engine/ # 🐍 Python 策略引擎 │ ├── __init__.py │ ├── env.yaml # 引擎环境配置 │ ├── common/ # 引擎通用模块 │ │ ├── __init__.py │ │ ├── base.py # BaseStrategy 基类 │ │ ├── models.py # 数据模型（Kline/Ticker/Trade/OrderBook） │ │ └── logger.py # 结构化日志 │ ├── manager.py # 策略管理器 │ ├── signals.py # 信号分发器 │ ├── backtest.py # 回测引擎 │ └── optimizer.py # 参数优化器 │ ├── executor/ # 🐍 Python 交易执行模块 │ ├── __init__.py │ ├── exchange.py # 交易所适配器（基类+实现） │ ├── order_manager.py # 订单管理器 │ ├── position_manager.py # 仓位管理器 │ ├── state_machine.py # 订单状态机 │ └── retry.py # 重试与容错 │ ├── risk/ # 🐍 Python 风控模块 │ ├── __init__.py │ ├── manager.py # 风控管理器 │ └── rules.py # 风控规则 │ ├── monitor/ # 监控告警模块 │ ├── __init__.py │ ├── metrics.py # Prometheus 指标 │ ├── alerts.py # 告警通知 │ └── dashboard.py # 仪表盘数据聚合 │ ├── api/ # API 网关 │ ├── __init__.py │ ├── main.py # FastAPI 入口 │ ├── ws.py # WebSocket 处理 │ ├── auth.py # 用户认证 │ └── routes/ # 路由 │ ├── __init__.py │ ├── strategies.py │ ├── trades.py │ └── account.py │ ├── strategies/ # 🐍 Python 策略实现 │ ├── __init__.py │ ├── ma_cross.py # 双均线交叉策略 │ ├── grid_trading.py # 网格交易策略 │ └── arbitrage.py # 套利策略（可选） │ ├── common/ # 🐍 Python 公共基础设施（跨模块共享配置、工具等） │ ├── __init__.py │ ├── config.py # 全局配置 │ ├── constants.py # 常量定义 │ └── utils.py # 工具函数 │ ├── tests/ # 🐍 Python 测试 │ ├── __init__.py │ ├── data/ │ ├── engine/ │ ├── executor/ │ ├── risk/ │ └── conftest.py # pytest fixtures │ └── docs/ # 文档 ├── deployment.md ├── usage.md └── api_reference.md ``` --- ## 部署与运维 ### 服务组件依赖 ``` ┌──────────────────┐ ┌──────────────┐ ┌─────────────┐ │ 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