Hyperliquid 配对交易系统 — 项目说明文档

版本: 0.2.0 · Python: ≥ 3.12 · 最后更新: 2026-02-17

目录

• 项目概述
• 系统架构
• 目录结构
• 核心模块详解
  • 交易引擎 (src/trading)
  • 实时服务 (src/services)
  • 事件系统 (src/events)
  • 工具库 (src/utils)
  • 回测脚本 (src/scripts)
• 数据库设计
• 配置说明
• 部署方式
• 快速开始
• 安全机制
• 依赖清单

项目概述

本系统是一个基于 Hyperliquid 去中心化永续合约交易所的实时配对交易（Pair Trading）信号分析与自动执行系统。核心交易标的为 HYPE/USDC 与 PURR/USDC 永续合约，通过统计套利策略在两者价差偏离时自动开仓/平仓。

核心能力

系统架构

┌─────────────────────────────────────────────────────────┐
│                    Hyperliquid API                        │
│          (WebSocket + REST, wss://api.hyperliquid.xyz)   │
└──────────┬──────────────────────────────┬────────────────┘
           │ K线/L2/订单更新               │ 下单/查询
           ▼                              ▼
┌────────────────────┐        ┌────────────────────────┐
│ EnhancedWebSocket  │        │  HyperliquidExecutor   │
│    Manager         │        │  (SDK 封装 + 429 重试) │
│ ·双重心跳检测      │        │  ·限价/市价下单        │
│ ·指数退避重连      │        │  ·杠杆/账户管理        │
│ ·L2 订单簿缓存     │        │  ·L2 快照零延迟定价    │
└────────┬───────────┘        └────────┬───────────────┘
         │                             │
         ▼                             ▼
┌────────────────────────────────────────────────────────┐
│           RealtimeKlineServiceBase (抽象基类)            │
│  ·K线入库  ·分析调度  ·数据自愈  ·策略信号触发           │
└───────────────────────┬────────────────────────────────┘
                        │ 信号
                        ▼
┌────────────────────────────────────────────────────────┐
│               TradingOrchestrator (编排器)               │
│  ┌──────────────┐ ┌──────────────┐ ┌────────────────┐  │
│  │  Strategy    │ │ PositionMgr  │ │  RiskManager   │  │
│  │ (Adaptive    │ │ ·开/平仓     │ │ ·9项风控审查   │  │
│  │  Bollinger)  │ │ ·DB持久化    │ │ ·仓位缩放     │  │
│  │ ·EMA+Welford │ │ ·孤儿仓位    │ │ ·止损/回撤    │  │
│  └──────────────┘ └──────────────┘ └────────────────┘  │
└───────────────────────┬────────────────────────────────┘
                        │
                        ▼
        ┌───────────────────────────────┐
        │   TimescaleDB + EventBus      │
        │   ·7张表/4个Hypertable        │
        │   ·事件驱动通知               │
        └───────────────────────────────┘

目录结构

Trading-in-websocket/
├── src/                          # 源代码主目录
│   ├── config.py                 # 全局配置（环境变量 + 常量）
│   ├── trading/                  # 交易引擎核心
│   │   ├── config.py             # TradingConfig 数据类 + .env 加载
│   │   ├── models.py             # 数据模型（信号、订单、仓位）
│   │   ├── executor.py           # Hyperliquid SDK 封装（下单/查询）
│   │   ├── orchestrator.py       # 交易编排器（信号路由 + 线程协调）
│   │   ├── strategy.py           # Adaptive Bollinger Z-Score 策略
│   │   ├── position_manager.py   # 配对仓位生命周期管理
│   │   ├── risk_manager.py       # 风控审查 + 仓位计算
│   │   ├── safety.py             # KillSwitch / RateLimiter / CircuitBreaker
│   │   ├── trade_repository.py   # 交易数据持久化（CRUD）
│   │   ├── websocket_order_manager.py  # WS 订单追踪 + HTTP 兜底
│   │   └── protocols.py          # 协议接口定义
│   ├── services/                 # 实时数据服务
│   │   ├── realtime_kline_service_base.py  # 抽象基类（90%共同逻辑）
│   │   ├── realtime_kline_service.py       # 通用实例（全币种监控）
│   │   ├── realtime_kline_service_hype.py  # HYPE/PURR 专用实例
│   │   └── eth_btc.py            # ETH/BTC 配对服务
│   ├── events/                   # 事件驱动架构
│   │   ├── base.py               # Event 基类 + 优先级
│   │   ├── event_bus.py          # 线程安全单例 EventBus
│   │   ├── trading_events.py     # 交易事件定义
│   │   └── system_events.py      # 系统事件定义
│   ├── utils/                    # 工具库
│   │   ├── analysis/             # 分析算法
│   │   │   ├── analysis_core.py  # 相关性/协整/Z-Score 核心
│   │   │   ├── coingetation_more_check.py  # 高级协整检验
│   │   │   ├── kline_data_filler.py        # K线数据补充器
│   │   │   ├── kline_data_filler_lazy.py   # 惰性加载补充器
│   │   │   └── risk_evaluator.py # 风险评估
│   │   ├── data_healing/         # 数据自愈框架
│   │   │   ├── orchestrator.py   # 自愈编排器（4阶段流程）
│   │   │   ├── continuity_checker.py  # 连续性检查
│   │   │   ├── repair_executor.py     # 修复执行器
│   │   │   ├── quality_assessor.py    # 质量评估
│   │   │   └── config.py         # 自愈配置参数
│   │   ├── database/
│   │   │   └── timescaledb.py    # TimescaleDB 连接池客户端
│   │   ├── websocket/
│   │   │   └── enhanced_ws_manager.py  # 增强型 WS 管理器
│   │   ├── monitoring/
│   │   │   ├── lark_bot.py       # 飞书 Lark Bot 告警
│   │   │   ├── alert_sender.py   # 告警发送封装
│   │   │   ├── alert_level.py    # 告警级别定义
│   │   │   └── signal_alert_formatter.py  # 信号告警格式化
│   │   ├── core/
│   │   │   └── logging_config.py # 日志配置
│   │   ├── hyperliquid_candles.py  # K线 REST API 封装
│   │   ├── message_deduplicator.py # 消息去重器
│   │   └── retry_utils.py         # 重试工具
│   └── scripts/                  # 脚本工具
│       ├── backtest_*.py         # 多种策略回测脚本
│       ├── backfill_*.py         # 历史数据回填
│       ├── optimize_*.py         # 参数优化
│       └── validate_data_consistency.py  # 数据一致性验证
├── database/
│   └── init_timescaledb.sql      # 数据库初始化（7张表 + 索引 + 策略）
├── docker/
│   ├── docker-compose.yml        # TimescaleDB 容器编排
│   ├── Dockerfile.akash          # Akash 部署镜像
│   ├── deploy-akash.yaml         # Akash SDL 部署清单
│   └── AKASH_QUICKSTART.md       # Akash 快速部署指南
├── docs/                         # 文档目录
├── pyproject.toml                # 项目依赖定义
├── .env.example                  # 环境变量模板
└── .gitignore

核心模块详解

交易引擎 (src/trading)

交易引擎由 6 个核心组件 + 3 个辅助模块构成，采用分层架构设计。

1. 数据模型 (models.py)

定义所有交易数据结构：

2. 交易配置 (config.py)

TradingConfig 数据类从 .env 环境变量加载所有交易参数：

• 基础设置: 交易开关、网络（测试/主网）、配对模式（single/pair）、账户类型（auto/unified/standard）
• 仓位参数: 基础/最大/最小仓位 USD、杠杆倍数、杠杆模式、Portfolio Margin 上限
• 风控参数: 最大持仓数、总敞口限制、止损比例、最大回撤、每日亏损上限、移动止损激活/回调比例、最大持仓时间
• 安全机制: 频率限制、熔断器阈值/冷却、KillSwitch 路径、黑名单、禁止平仓代币（close_disabled_symbols）
• 策略参数: EMA 窗口、STD 窗口、Adaptive Z 阈值、最小 Z-Score 绝对值、均值回归因子、冷却期；支持按币种覆盖（StrategyParams）
• 订单参数: 开仓/平仓订单类型（market/limit）、限价偏移、超时、滑点；WebSocket 订单追踪超时与重连
• 信号缩放: 强/中/弱信号的仓位缩放倍数（TRADING_STRENGTH_SCALE_*）、最低余额系数、是否允许同币种重复持仓
• 内置业务逻辑验证（__post_init__）和安全审计（validate_secrets）

3. 执行器 (executor.py) — 1854行

HyperliquidExecutor 封装 Hyperliquid SDK 的 Exchange + Info 类：

• 初始化: 钱包创建、SDK 连接（带重试）、币种元数据缓存（szDecimals/maxLeverage）
• 杠杆管理: 动态设置杠杆倍数 + 模式（全仓/逐仓），支持 Portfolio Margin 自动检测
• 下单系统:
  • open_pair_position() — 配对开仓（Leg A → Leg B 顺序执行，含 Leg B 预检查）
  • close_pair_position() — 配对平仓（反向下单 + 残留处理）
  • 支持限价单和市价单两种模式
  • 限价单使用 L2 快照零延迟定价，API 仅作降级
  • 内置 @retry 429 限流自动重试（指数退避 + 抖动）
• 订单追踪: 集成 WebSocketOrderManager，实时追踪限价单成交状态
• 价格精度: 按 szDecimals 自动截断下单数量和价格

4. 策略引擎 (strategy.py) — Adaptive Bollinger Z-Score

AdaptiveBollingerStrategy 实现完整的入场/退场信号生成：

核心算法:

adaptive_z = (z4h - EMA(z4h, span)) / StdDev(z4h, window)

• EMA: 指数移动平均（默认 ema_span=36，由 TRADING_STRATEGY_EMA_SPAN 配置）
• StdDev: Welford 在线增量法计算标准差，滚动窗口大小由 TRADING_STRATEGY_STD_WINDOW（默认 72）配置
• 入场: adaptive_z 从低于阈值突破到高于阈值时触发（突破检测），阈值 TRADING_STRATEGY_ADAPTIVE_THRESHOLD（默认 3.0），并受 TRADING_STRATEGY_MIN_ZSCORE_ABS 过滤
• 退场: adaptive_z 回归到入场值的指定比例时触发（均值回归），比例由 TRADING_STRATEGY_REVERSION_FACTOR（默认 0.30）配置

架构特性:

• Per-Symbol 隔离: 每个交易对独立的 SymbolState（缓冲区、EMA、统计量、持仓追踪）
• 按币种策略覆盖: 通过 TRADING_STRATEGY_OVERRIDE_SYMBOLS 与 TRADING_STRATEGY_{SYMBOL}_{PARAM} 为指定币种覆盖 EMA_SPAN、STD_WINDOW、ADAPTIVE_THRESHOLD、MIN_ZSCORE_ABS、REVERSION_FACTOR、COOLDOWN_MINUTES、STOP_LOSS_PCT、MAX_HOLD_HOURS
• 去重 K 线: 通过 kline_time 过滤重复 tick
• 冷却期: 平仓后强制等待（TRADING_STRATEGY_COOLDOWN_MINUTES），避免连续反复交易
• 历史预热: prime_buffer() 从数据库加载历史数据初始化缓冲区

5. 仓位管理器 (position_manager.py) — 1172行

PositionManager 管理配对仓位的完整生命周期：

• 开仓流程: 防重复 → 获取价格 → 风控审查 → 计算仓位 → 下单 → 持久化
• 平仓流程: 查找仓位 → 状态锁定 → 执行 → 计算盈亏 → 持久化
• 重启恢复: 从 DB 恢复未关闭仓位 → 与交易所对比验证 → 清理幽灵仓位
• 仓位同步: 定期与交易所实际持仓对比
  • 检测并收纳孤儿仓位（交易所有但内存没有）
  • 自动配对检测（alt/base 孤儿方向相反时合并为 pair）
  • 清理幽灵仓位（内存有但交易所没有）
• 价格更新: 批量原子性更新所有仓位的当前价格

6. 风控管理器 (risk_manager.py)

RiskManager 提供 9 项开仓前检查：

1. KillSwitch 是否激活
2. 熔断器是否触发
3. 频率限制检查
4. 币种黑名单检查
5. 同币种重复持仓检查
6. 最大持仓数量检查
7. 每日亏损上限检查
8. 最大回撤检查
9. 余额充足性检查

额外能力：

• 仓位大小计算: 基础仓位 × 信号强度缩放 × 余额动态限制
• 止损检查: 固定止损 + 移动止损（激活阈值 + 回调阈值）
• 持仓超时检查: 最大持仓时间控制
• 每日统计: PnL 跟踪 + 峰值权益 + UTC 每日重置

7. 编排器 (orchestrator.py)

TradingOrchestrator 是交易模块的统一入口：

• 启动流程: 初始化 Executor → 恢复仓位 → 加载历史数据（含数据自愈降级） → 启动监控线程
• 信号处理: 接收 process_analysis() 调用 → Strategy 生成信号 → 执行开/平仓
• 后台线程:
  • 止损监控线程（固定止损 + 移动止损 + 持仓超时 + 失败重试）
  • 仓位同步线程（定期与交易所对账）
• 通知: 开仓/平仓结果通过飞书 Lark Bot 推送

8. 安全机制 (safety.py)

三层安全保护：

9. WebSocket 订单管理器 (websocket_order_manager.py)

WebSocketOrderManager 基于 WebSocket orderUpdates 实时追踪限价单：

• 注册订单追踪 → 等待 WS 成交通知 → 超时 HTTP 兜底验证
• 与 K 线服务共享 WebSocket 连接，无需独立连接
• 支持 userFills 消息补充成交均价信息

实时服务 (src/services)

RealtimeKlineServiceBase — 抽象基类（1770行）

包含 90% 的共同逻辑，子类仅需实现 4 个抽象方法：

1. _get_active_symbols() — 获取活跃币种列表
2. _get_config_params() — 获取服务配置
3. _should_enable_symbol_monitoring() — 是否启用新币种监控
4. _get_corr_threshold_for_analysis() — 分析用相关系数阈值

核心功能:

• WebSocket 订阅: K 线 + L2 订单簿 + 订单状态更新
• 消息处理: 解析 K 线数据 → 去重 → 入分析队列
• 批量写入: K 线数据批量 upsert 到 TimescaleDB（带死锁重试）
• 分析调度: 多工作线程并行分析，生成交易信号
• 数据自愈: 集成 DataHealingOrchestrator，启动时自动修复历史数据
• 交易集成: 信号触发时调用 TradingOrchestrator.process_analysis()

子类实例

事件系统 (src/events)

采用发布-订阅模式解耦组件：

EventBus — 线程安全单例：

• 同步分发，订阅者异常隔离
• 性能监控（发布延迟、订阅者耗时告警 >100ms）

事件类型:

工具库 (src/utils)

分析核心 (analysis/analysis_core.py)

提供共享的时序分析算法：

• prepare_price_series() — K 线数据转价格序列
• calculate_correlation() — 收益率相关系数（Pearson/Spearman/Kendall）
• calculate_cointegration_params_ols() — Engle-Granger 两步法全量协整分析
• calculate_cointegration_params_dual_window() — 双窗口策略（beta=100期 + zscore=30期）
• calculate_zscore_ols() — 基于 OLS 残差的 Z-Score
• analyze_pair_advanced() — 高级配对分析（完整流程）
• analyze_multi_period() — 多周期 Z-Score 验证（3 周期协整一致性）

协整模型智能选择:

• α 显著且较大 → 无 α 模型（跨资产类）
• α 不显著或较小 → 含 α 模型（同类资产）

数据自愈框架 (data_healing/)

DataHealingOrchestrator 四阶段自愈流程：

1. Phase 1 - 加载: 从 DB 加载历史 Z-Score 数据
2. Phase 2 - 诊断: 三类问题检测
   • 连续性缺口 → gap_targets
   • 数据过期 → stale_targets
   • 数量不足 → shortfall_targets
3. Phase 3 - 修复: 循环执行（诊断 → 合并目标 → 修复 → 重新加载）
4. Phase 4 - 评估: 最终质量评估，返回 HealingResult

辅助组件：ContinuityChecker（连续性检查）、RepairExecutor（修复执行）、QualityAssessor（质量评估）

增强型 WebSocket 管理器 (websocket/enhanced_ws_manager.py)

EnhancedWebSocketManager（1416行）提供生产级 WebSocket 连接管理：

• 双重健康检测: 底层 TCP 连接 + 应用层心跳（数据流中断检测）
• 指数退避重连: 1s → 2s → 4s → ... → 60s（含 ±25% 随机抖动）
• 状态机: DISCONNECTED → CONNECTING → CONNECTED → RECONNECTING → FAILED
• L2 缓存: 最新订单簿快照缓存，供 Executor 零延迟定价
• 事件集成: 连接/断开/重连事件发布到 EventBus

数据库客户端 (database/timescaledb.py)

TimescaleDBClient 基于 psycopg[pool] 的连接池客户端：

• 异步连接池管理（可配置 min/max/超时/最大存活/最大空闲）
• K 线批量 upsert（ON CONFLICT DO UPDATE）
• 分析结果批量写入
• 通用查询接口

监控告警 (monitoring/lark_bot.py)

飞书 Lark Bot Webhook 告警：

• 彩色卡片消息（sender_colourful）
• 带重试的 HTTP 请求（指数退避）
• 支持自定义标题/内容/颜色

回测脚本 (src/scripts)

多币种回测 v2（4H 相关系数过滤 + Gate1+Gate2）的详细分析报告见 BACKTEST_MULTICOIN_V2_ANALYSIS_REPORT.md。

数据库设计

使用 TimescaleDB（PostgreSQL + 时序扩展），7 张表 + 4 个 Hypertable：

表结构

自动化策略

• 数据保留: klines 保留 90 天，analysis_results 永久保留
• 自动压缩: klines 7 天后压缩，其余 30 天后压缩
• 连续聚合: daily_analysis_stats 物化视图，每小时自动刷新
• 索引优化: 14+ 个索引（含覆盖索引、局部索引、组合索引）

配置说明

所有配置通过 .env 文件管理，参考 .env.example 模板。

核心配置分类

部署方式

方式一：本地运行

# 1. 克隆项目
git clone https://github.com/zhajingwen/Trading-in-websocket.git
cd Trading-in-websocket

# 2. 创建环境
cp .env.example .env
# 编辑 .env 填入实际配置

# 3. 启动 TimescaleDB
cd docker && docker compose up -d && cd ..

# 4. 安装依赖
uv sync

# 5. 启动服务（二选一）
# HYPE/PURR 配对专用（推荐）
uv run python -m src.services.realtime_kline_service_hype
# 或：全币种通用监控
# uv run python -m src.services.realtime_kline_service

方式二：Docker Compose

cd docker
docker compose up -d

方式三：Akash 去中心化云

参考 docker/AKASH_QUICKSTART.md 和 docs/AKASH_DEPLOYMENT.md。

使用 docker/Dockerfile.akash 构建镜像，通过 docker/deploy-akash.yaml SDL 清单部署。

安全机制

多层保护体系

Layer 1: KillSwitch        → touch 文件立即停止
Layer 2: CircuitBreaker     → 连续失败自动熔断
Layer 3: RateLimiter        → 滑动窗口频率限制
Layer 4: RiskManager        → 9项开仓前审查
Layer 5: .env 权限检查      → 启动时验证文件权限 + 弱密码检测
Layer 6: 私钥安全           → repr 遮蔽 + 格式校验 + 主网额外约束

紧急操作

# 紧急停止所有交易
touch /tmp/trading_kill_switch

# 恢复交易
rm /tmp/trading_kill_switch

依赖清单

核心依赖

可选依赖