sanguo_vnpy/docs/03-detailed-design.md

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 任务模型

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 镜像分层构建

# 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 启动流程

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挂载设计

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端口：

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