auto-sync: 2026-04-12 10:19:49

2026-04-12 10:19:50 +08:00
parent 075be0df1c
commit 925d262164
2 changed files with 150 additions and 0 deletions
@@ -173,5 +173,6 @@



+


@@ -0,0 +1,149 @@
+# 自动化回测服务 - 使用说明
+
+## 概述
+
+基于 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