From 82edacd7241d15eb457be0e9f067daf1aefcd516 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Wed, 29 Apr 2026 20:19:02 +0800 Subject: [PATCH] auto-sync: 2026-04-29 20:19:02 --- docs/03-detailed-design.md | 175 +++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 docs/03-detailed-design.md diff --git a/docs/03-detailed-design.md b/docs/03-detailed-design.md new file mode 100644 index 00000000..840f51bd --- /dev/null +++ b/docs/03-detailed-design.md @@ -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)*