sanguo_vnpy/scripts/backtest-service/README.md

自动化回测服务 - 使用说明

概述

基于 vnpy 原生 BacktestingEngine 封装的 RESTful API 自动化回测服务。

支持：

• 通过 API 提交回测任务
• 自动排队控制并发
• 使用 vnpy 原生回测引擎执行
• 保存回测结果（CSV + 图表 + JSON）
• 查询任务状态和结果

架构设计

严格遵循 vnpy 原生设计，不修改核心，只做外层封装：

[API 服务] ← 接收任务
    ↓
[任务队列 + 进程池] ← 控制并发
    ↓
[BacktestingEngine (vnpy 原生)] ← 执行回测
    ↓
[文件存储] ← 保存结果
    ↓
[API 查询] ← 返回结果

启动方式

# 手动启动
cd /app/scripts/backtest-service
python main.py

# 后台运行
nohup python main.py > backtest-service.log 2>&1 &

# 查看日志
tail -f backtest-service.log

访问地址

启动后访问：

• 服务地址：http://container-ip:8088
• API 文档：http://container-ip:8088/docs → 可以直接在网页上测试API

API 接口说明

接口	方法	路径	说明
提交回测	POST	/api/backtest/submit	提交新的回测任务
任务列表	GET	/api/backtest/list	列出任务，支持分页和状态过滤
任务状态	GET	/api/backtest/status/{task_id}	查询任务状态
回测结果	GET	/api/backtest/result/{task_id}	获取完整回测结果
删除任务	DELETE	/api/backtest/delete/{task_id}	删除任务
健康检查	GET	/api/backtest/health	查看服务状态，返回任务统计

配置

可以通过环境变量覆盖默认配置：

环境变量	说明	默认值
MAX_WORKERS	最大并发回测数	2
HOST	监听地址	0.0.0.0
PORT	监听端口	8088
BASE_DIR	任务存储根目录	/app/backtest_jobs
DEBUG	调试模式	True

使用示例

1. 提交回测

curl -X POST http://127.0.0.1:8088/api/backtest/submit \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "双均线策略",
    "strategy_code": "完整的策略Python代码...",
    "symbol": "IF888.CFFEX",
    "interval": "1h",
    "start_date": "2020-01-01",
    "end_date": "2025-01-01",
    "parameters": {
      "fast_window": 5,
      "slow_window": 20
    },
    "capital": 1000000
  }'

响应：

{
  "code": 0,
  "msg": "任务提交成功",
  "data": {
    "task_id": "a1b2c3d4...",
    "status": "pending",
    "created_at": "2026-04-12T10:00:00+08:00"
  }
}

2. 查询任务状态

curl http://127.0.0.1:8088/api/backtest/status/a1b2c3d4

3. 获取回测结果

curl http://127.0.0.1:8088/api/backtest/result/a1b2c3d4

结果存储结构

/app/backtest_jobs/
├── pending/           # 等待执行
├── running/           # 执行中
├── completed/         # 已完成
│   └── <task_id>/
│       ├── task.json       # 任务信息
│       ├── result.json     # 回测结果
│       ├── equity.csv      # 每日净值
│       ├── equity_curve.png  # 收益曲线图
│       └── trades.csv      # 成交记录
└── failed/            # 执行失败
    └── <task_id>/
        ├── task.json
        └── result.json     # 包含错误信息

设计原则

1. 不改动 vnpy 核心：完全复用原生 BacktestingEngine
2. 轻量级：只用 Python 标准库，不引入额外第三方任务队列
3. 隔离性：每个回测在独立进程，一个失败不影响其他
4. 可配置并发：根据 CPU 性能调整 MAX_WORKERS，避免资源耗尽

作者

三国量化团队 姜维 伯约
2026-04-12