auto-sync: 2026-04-29 20:19:02
This commit is contained in:
cfdaily
@@ -0,0 +1,175 @@
|
||||
# 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)*
|
||||
Reference in New Issue
Block a user