diff --git a/logs/auto-sync.log b/logs/auto-sync.log index 26a48700..c43465f7 100644 --- a/logs/auto-sync.log +++ b/logs/auto-sync.log @@ -173,5 +173,6 @@ + diff --git a/scripts/backtest-service/README.md b/scripts/backtest-service/README.md new file mode 100644 index 00000000..d7b3646c --- /dev/null +++ b/scripts/backtest-service/README.md @@ -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.json # 任务信息 +│ ├── result.json # 回测结果 +│ ├── equity.csv # 每日净值 +│ ├── equity_curve.png # 收益曲线图 +│ └── trades.csv # 成交记录 +└── failed/ # 执行失败 + └── / + ├── task.json + └── result.json # 包含错误信息 +``` + +## 设计原则 + +1. **不改动 vnpy 核心**:完全复用原生 `BacktestingEngine` +2. **轻量级**:只用 Python 标准库,不引入额外第三方任务队列 +3. **隔离性**:每个回测在独立进程,一个失败不影响其他 +4. **可配置并发**:根据 CPU 性能调整 `MAX_WORKERS`,避免资源耗尽 + +## 作者 + +三国量化团队 姜维 伯约 +2026-04-12