cfdaily
150 lines
3.7 KiB
Markdown
150 lines
3.7 KiB
Markdown
# 自动化回测服务 - 使用说明
|
||
|
||
## 概述
|
||
|
||
基于 vnpy 原生 `BacktestingEngine` 封装的 RESTful API 自动化回测服务。
|
||
|
||
支持：
|
||
- 通过 API 提交回测任务
|
||
- 自动排队控制并发
|
||
- 使用 vnpy 原生回测引擎执行
|
||
- 保存回测结果（CSV + 图表 + JSON）
|
||
- 查询任务状态和结果
|
||
|
||
## 架构设计
|
||
|
||
严格遵循 vnpy 原生设计，不修改核心，只做外层封装：
|
||
|
||
```
|
||
[API 服务] ← 接收任务
|
||
↓
|
||
[任务队列 + 进程池] ← 控制并发
|
||
↓
|
||
[BacktestingEngine (vnpy 原生)] ← 执行回测
|
||
↓
|
||
[文件存储] ← 保存结果
|
||
↓
|
||
[API 查询] ← 返回结果
|
||
```
|
||
|
||
## 启动方式
|
||
|
||
```bash
|
||
# 手动启动
|
||
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. 提交回测
|
||
|
||
```bash
|
||
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
|
||
}'
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "任务提交成功",
|
||
"data": {
|
||
"task_id": "a1b2c3d4...",
|
||
"status": "pending",
|
||
"created_at": "2026-04-12T10:00:00+08:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 查询任务状态
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8088/api/backtest/status/a1b2c3d4
|
||
```
|
||
|
||
### 3. 获取回测结果
|
||
|
||
```bash
|
||
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
|