cfdaily
176 lines
5.6 KiB
Markdown
176 lines
5.6 KiB
Markdown
# 03 - 详细设计
|
||
|
||
**版本**: v1.0
|
||
**日期**: 2026-04-29
|
||
|
||
---
|
||
|
||
## 1. 回测服务模块（src/backtest-service/）
|
||
|
||
### 1.1 模块职责
|
||
|
||
将vnpy的BacktestingEngine封装为HTTP API服务，支持策略提交、任务调度、结果查询。
|
||
|
||
### 1.2 模块结构
|
||
|
||
```
|
||
src/backtest-service/
|
||
├── main.py # FastAPI应用入口 + 生命周期管理
|
||
├── api.py # API路由定义
|
||
├── executor.py # vnpy回测执行器（核心）
|
||
├── models.py # Pydantic数据模型
|
||
├── config.py # 配置管理
|
||
├── task_queue.py # 任务队列（线程池调度）
|
||
└── result_storage.py # 结果持久化（磁盘存储）
|
||
```
|
||
|
||
### 1.3 核心流程
|
||
|
||
```
|
||
用户提交策略 → API接收 → 生成task_id → 入队pending
|
||
│
|
||
worker线程取出
|
||
│
|
||
executor.execute_backtest()
|
||
│
|
||
┌───────────┴───────────┐
|
||
│ 加载策略代码 │
|
||
│ 创建BacktestingEngine │
|
||
│ 设置参数（合约/周期/资金） │
|
||
│ engine.run_backtesting() │
|
||
│ 收集结果统计 │
|
||
│ 生成图表（资金曲线） │
|
||
└───────────┬───────────┘
|
||
│
|
||
结果写入磁盘 → 用户查询
|
||
```
|
||
|
||
### 1.4 API接口
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/backtest/submit` | POST | 提交回测任务 |
|
||
| `/api/backtest/status/{task_id}` | GET | 查询任务状态 |
|
||
| `/api/backtest/result/{task_id}` | GET | 获取回测结果 |
|
||
| `/api/backtest/list` | GET | 任务列表（分页） |
|
||
| `/api/backtest/health` | GET | 健康检查 |
|
||
| `/api/backtest/delete/{task_id}` | DELETE | 删除任务 |
|
||
|
||
### 1.5 任务模型
|
||
|
||
```python
|
||
class BacktestTask:
|
||
strategy_name: str # 策略名称
|
||
strategy_code: str # 策略代码（必须含CtaTemplate子类）
|
||
symbol: str # 合约代码（如 IF888.CFFEX）
|
||
interval: str # K线周期（1m/5m/1h/1d）
|
||
start_date: date # 开始日期
|
||
end_date: date # 结束日期
|
||
capital: float # 初始资金
|
||
engine_type: str # 引擎类型（cta）
|
||
tick_size: Optional[float] # 最小变动价位
|
||
```
|
||
|
||
### 1.6 vnpy 4.x适配要点
|
||
|
||
- Interval枚举精简：`1m → Interval.MINUTE`（4.x移除了FIVE_MINUTE等）
|
||
- BacktestingEngine初始化：需要先add_strategy再load_data
|
||
- 数据加载：通过engine.load_bar()或自定义数据适配器
|
||
- 结果获取：engine.calculate_result() + engine.calculate_statistics()
|
||
|
||
---
|
||
|
||
## 2. 数据适配层（src/adapters/）
|
||
|
||
### 2.1 职责
|
||
|
||
实现vnpy的BaseDatafeed接口，将本地/第三方数据源适配为vnpy可识别格式。
|
||
|
||
### 2.2 vnpy_local_data_adapter.py
|
||
|
||
已实现的本地数据适配器，支持：
|
||
- 从SQLite数据库读取K线数据
|
||
- 从CSV文件批量导入
|
||
- 时间范围过滤
|
||
- 转换为vnpy BarData对象
|
||
|
||
### 2.3 扩展计划
|
||
|
||
| 适配器 | 数据源 | 状态 |
|
||
|--------|--------|------|
|
||
| vnpy_local_data_adapter | 本地SQLite/CSV | ✅ 已完成 |
|
||
| akshare_data_adapter | akshare实时API | 🔜 规划中 |
|
||
| jqdata_adapter | 聚宽数据接口 | 🔜 规划中 |
|
||
| qmt_adapter | QMT交易终端 | 🔜 规划中 |
|
||
|
||
---
|
||
|
||
## 3. 容器镜像（docker/）
|
||
|
||
### 3.1 镜像分层构建
|
||
|
||
```dockerfile
|
||
# Layer 1: 基础镜像 + 系统依赖（低频变更）
|
||
FROM python:3.10-slim
|
||
RUN apt-get update && apt-get install -y ...
|
||
|
||
# Layer 2: Python基础依赖（低频变更）— vnpy/numpy/pandas等
|
||
COPY requirements/requirements-base.txt .
|
||
RUN pip install -r requirements-base.txt
|
||
|
||
# Layer 3: 额外依赖（高频变更）— akshare/tushare等
|
||
COPY requirements/requirements-extra.txt .
|
||
RUN pip install -r requirements-extra.txt
|
||
```
|
||
|
||
### 3.2 entrypoint.sh 启动流程
|
||
|
||
```bash
|
||
1. pip3 install vnpy_ctastrategy vnpy_sqlite # 自动安装运行时依赖
|
||
2. sshd -D & # SSH服务
|
||
3. jupyter lab & # Jupyter开发环境
|
||
4. uvicorn backtest_service.main:app & # 回测API服务
|
||
5. 健康检查 # 确认服务就绪
|
||
6. tail -f /dev/null # 保持容器运行
|
||
```
|
||
|
||
### 3.3 Volume挂载设计
|
||
|
||
```bash
|
||
docker run \
|
||
-v /volume1/stock/sanguo_vnpy/bt-service:/app/scripts/backtest_service:ro \
|
||
-v /volume1/stock/sanguo_vnpy/entrypoint.sh:/app/entrypoint.sh:ro \
|
||
sanguo_vnpy:with-scripts
|
||
```
|
||
|
||
**设计理由**：代码通过volume挂载而非docker commit，便于更新和回滚。
|
||
|
||
---
|
||
|
||
## 4. 部署配置（config/）
|
||
|
||
### 4.1 Nginx反向代理
|
||
|
||
每个用户一个location配置，按路径分发到对应的Web端口：
|
||
|
||
```nginx
|
||
location /zhangfei/ {
|
||
proxy_pass http://127.0.0.1:8004/;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "upgrade";
|
||
}
|
||
```
|
||
|
||
### 4.2 Systemd服务管理
|
||
|
||
每个用户两个systemd服务：
|
||
- `sanguo-trade-{user}.service` — 交易进程（RPC服务端）
|
||
- `sanguo-web-{user}.service` — Web进程（FastAPI）
|
||
|
||
支持独立启停，不影响其他用户。
|
||
|
||
---
|
||
|
||
*下一步：[04-deployment.md](04-deployment.md)*
|