diff --git a/logs/auto-sync.log b/logs/auto-sync.log index ff1a1259..5fc49d1a 100644 --- a/logs/auto-sync.log +++ b/logs/auto-sync.log @@ -67,5 +67,6 @@ + diff --git a/research/docker/automated-backtest-service-design.md b/research/docker/automated-backtest-service-design.md new file mode 100644 index 00000000..f1b535a0 --- /dev/null +++ b/research/docker/automated-backtest-service-design.md @@ -0,0 +1,244 @@ +# 自动化回测服务设计方案 + +## 需求背景 + +三国量化团队需要支持**自动化批量回测**场景: +- 将军们提交回测脚本和参数 +- 系统自动运行回测 +- 完成后返回结果给将军 +- 不需要手动干预 + +## 现有环境基础 + +当前 Docker 容器环境已经提供: +- ✅ Python 3.10 +- ✅ 完整 vnpy 框架 +- ✅ `vnpy.trader.backtesting.BacktestingEngine` 原生回测引擎 +- ✅ FastAPI(已被 vnpy_webtrader 依赖) +- ✅ SSH 远程访问 +- ✅ Jupyter Lab 结果分析 + +## 设计原则 + +1. **尽量基于vnpy原生**:核心回测使用原生 `BacktestingEngine`,不重复造轮子 +2. **轻量级实现**:不引入过重的第三方任务队列(如 Redis/RabbitMQ) +3. **保持简单**:够用就好,便于维护 +4. **不强制自动启动**:作为可选服务,需要时手动启动 + +## 架构设计 + +``` +┌─────────────┐ +│ 将军 │ +└──────┬──────┘ + │ POST /api/backtest/submit + ↓ +┌──────────────────────────┐ +│ FastAPI 回测服务 │ ← 监听 8088 端口 +│ - 接收任务 │ +│ - 任务排队 │ +│ - 进程池执行 │ +│ - 保存结果 │ +└──────┬───────────────────┘ + │ 调用 + ↓ +┌──────────────────────────┐ +│ vnpy 原生 BacktestingEngine ← 核心回测计算 +│ - 加载历史数据 │ +│ - 运行策略回测 │ +│ - 计算统计结果 │ +│ - 输出图表 │ +└──────┬───────────────────┘ + │ 保存结果 + ↓ +┌──────────────────────────┐ +│ 文件系统存储 │ +│ - 任务元数据 JSON │ +│ - 回测结果 CSV/JSON │ +│ - 收益曲线图片 │ +└──────┬───────────────────┘ + │ GET /api/backtest/result/{task_id} + ↓ +┌─────────────┐ +│ 将军 │ ← 获取结果分析 +└─────────────┘ +``` + +## 端口分配 + +| 服务 | 端口 | 用途 | 状态 | +|------|------|------|------| +| SSH | 22 → 2222 | 远程登录 | ✅ 已映射 | +| Jupyter Lab | 8888 | Notebook开发 | ✅ 已映射 | +| code-server | 8080 | Web VS Code | ✅ 已映射 | +| VNPY Web Trader | 8000 | 交易Web API | ✅ 已映射 | +| VNPY RPC 交易核心 | 2018 | RPC 请求 | ✅ 已映射 | +| VNPY RPC 交易核心 | 4102 | RPC 订阅 | ✅ 已映射 | +| **自动化回测服务** | **8088** | **回测API** | ✅ 已映射 | + +## API 接口设计 + +### 1. 提交回测任务 + +**接口:** `POST /api/backtest/submit` + +**请求体:** +```json +{ + "strategy_name": "double_ma", + "strategy_code": "from vnpy.trader.strategy import ...", + "parameters": { + "fast_window": 5, + "slow_window": 20 + }, + "start_date": "2020-01-01", + "end_date": "2024-01-01", + "symbol": "IF888", + "interval": "1h" +} +``` + +**响应:** +```json +{ + "code": 0, + "msg": "success", + "data": { + "task_id": "a1b2c3d4-1234-5678-90ef-ghijklmnopqr", + "status": "pending" + } +} +``` + +### 2. 查询任务状态 + +**接口:** `GET /api/backtest/status/{task_id}` + +**响应:** +```json +{ + "code": 0, + "msg": "success", + "data": { + "task_id": "a1b2c3d4-1234-5678-90ef-ghijklmnopqr", + "status": "running|completed|failed", + "progress": 75, + "message": "正在计算统计结果" + } +} +``` + +### 3. 获取回测结果 + +**接口:** `GET /api/backtest/result/{task_id}` + +**响应:** +```json +{ + "code": 0, + "msg": "success", + "data": { + "task_id": "...", + "status": "completed", + "statistics": { + "total_trades": 100, + "win_rate": 0.6, + "sharpe_ratio": 1.8, + "max_drawdown": 0.15, + "total_return": 0.35, + "annual_return": 0.08 + }, + "result_file": "/app/backtest_results/.../result.csv", + "chart_file": "/app/backtest_results/.../equity_curve.png", + "completed_at": "2026-04-11T22:00:00Z" + } +} +``` + +### 4. 列出所有任务 + +**接口:** `GET /api/backtest/list` + +**响应:** +```json +{ + "code": 0, + "msg": "success", + "data": { + "tasks": [ + { + "task_id": "...", + "strategy_name": "...", + "status": "...", + "created_at": "..." + } + ] + } +} +``` + +## 目录结构 + +``` +/app/ +├── scripts/ +│ └── backtest-service/ +│ ├── main.py # FastAPI 入口 +│ ├── task_queue.py # 任务队列实现 +│ ├── executor.py # 任务执行器 +│ ├── models.py # 数据模型 +│ └── README.md # 使用说明 +└── backtest_jobs/ + ├── pending/ # 等待执行 + ├── running/ # 执行中 + ├── completed/ # 已完成 + └── failed/ # 执行失败 +``` + +## 任务队列实现 + +使用 Python 内置 `multiprocessing.Pool` 做进程池,限制并发回测数量,避免资源耗尽: + +```python +# 配置示例 +MAX_WORKERS = 2 # 最大并发回测数,根据CPU核数调整 +``` + +每个回测任务在独立进程中运行,互不干扰,一个失败不影响其他任务。 + +## 启动方式 + +### 手动启动(开发环境) + +```bash +ssh -p 2222 vnpy@192.168.2.153 +cd /app/scripts/backtest-service +python main.py +``` + +### 后台运行 + +```bash +nohup python main.py > backtest-service.log 2>&1 & +``` + +## 后续实现步骤 + +1. [ ] 创建目录结构 +2. [ ] 编写 Pydantic 数据模型 +3. [ ] 编写任务队列 +4. [ ] 编写任务执行器 +5. [ ] 编写 FastAPI 路由 +6. [ ] 编写 README 使用说明 +7. [ ] 测试验证 + +## 参考文档 + +- [vnpy-webtrader-research-report.md](./../task-20260331-vnpy-webtrader-research/final/vnpy-webtrader-research-report.md) +- [docker-dependency-cache-scheme.md](./docker-dependency-cache-scheme.md) + +--- + +**文档记录时间:** 2026-04-11 22:21 GMT+8 +**记录人:** 姜维 伯约 +**状态:** 设计完成,待实现