sanguo_vnpy/docs/02-architecture.md

02 - 系统架构设计

版本: v1.0 日期: 2026-04-29

---

1. 架构总览

┌─────────────────────────────────────────────────────────────┐
│                     三国量化团队（7个Agent）                    │
│  诸葛亮 · 庞统 · 张飞 · 关羽 · 赵云 · 司马懿 · 姜维            │
└───────────┬─────────────────────────────────┬───────────────┘
            │ 提交策略                         │ 查看结果
            ▼                                 ▼
┌───────────────────────┐         ┌───────────────────┐
│   回测API服务          │         │  OpenClaw Gateway  │
│   FastAPI :8088       │         │  任务调度/通信      │
│   /api/backtest/*     │         └───────────────────┘
└───────────┬───────────┘
            │ 调用
            ▼
┌───────────────────────┐
│   vnpy BacktestingEngine │  ← vnpy 4.x原生回测引擎
│   CTA策略回测            │
└───────────┬───────────┘
            │ 读取数据
            ▼
┌───────────────────────┐
│   数据层               │
│   SQLite / akshare     │  ← 本地数据 + 实时数据
└───────────────────────┘

            所有服务运行在：
┌─────────────────────────────────────┐
│        群晖 NAS Docker 容器           │
│  192.168.2.154                       │
│  sanguo_vnpy:with-scripts 镜像       │
│  restart: unless-stopped             │
└─────────────────────────────────────┘

2. 分层架构

┌────────────────────────────────────┐
│  适配层 (src/)                      │  ← 我们的代码
│  ├── backtest-service/  回测API服务  │
│  ├── adapters/          数据适配器   │
│  └── scripts/           启动脚本     │
├────────────────────────────────────┤
│  vnpy框架层 (pip install vnpy)      │  ← 开源框架，不修改
│  ├── BacktestingEngine  回测引擎     │
│  ├── CtaTemplate       策略基类      │
│  ├── BaseDatafeed      数据接口      │
│  └── BaseGateway       交易网关      │
├────────────────────────────────────┤
│  基础设施层 (docker/)               │
│  ├── Dockerfile         镜像构建     │
│  ├── entrypoint.sh      容器启动     │
│  └── requirements/      依赖管理     │
└────────────────────────────────────┘

3. 核心设计决策

3.1 适配层 vs Fork

方案	适用场景	当前选择
适配层（继承/封装）	新策略、新数据源、新网关	✅ 当前采用
Fork vnpy	修改回测引擎核心、修改事件机制	🔜 预留

原则：优先通过继承和封装实现需求，vnpy接口不满足时再考虑fork。

3.2 数据架构

数据获取层（赵云负责）
    │
    ├── akshare（实时行情）
    ├── tushare（历史数据）
    └── 本地CSV/Parquet
    │
    ▼
数据适配层（src/adapters/）
    │
    ├── vnpy_local_data_adapter.py  ← 实现BaseDatafeed接口
    │
    ▼
数据存储层
    │
    └── SQLite（vnpy标准数据库）

3.3 多用户隔离

每个用户独立进程对，通过Nginx反向代理统一入口：

用户        RPC端口   Web端口   Nginx路径
诸葛亮       2010      8001     /zhugeliang/
庞统         2020      8002     /pangtong/
司马懿       2030      8003     /simayi/
张飞         2040      8004     /zhangfei/
关羽         2050      8005     /guanyu/
赵云         2060      8006     /zhaoyun/
姜维         2070      8007     /jiangwei/

3.4 容器化部署

sanguo_vnpy 容器
├── 8888  Jupyter Lab（开发环境）
├── 8088  回测API服务（FastAPI）
├── 8000  WebTrader（预留）
├── 2222  SSH（运维通道）
└── /app/scripts/backtest_service  ← volume挂载代码

4. 技术选型

组件	选型	理由
量化框架	vn.py 4.x	开源、社区活跃、架构成熟
API服务	FastAPI + uvicorn	异步高性能、自动文档
数据库	SQLite	轻量、vnpy原生支持
数据源	akshare + tushare	免费A股数据
容器	Docker	环境隔离、可移植
部署	群晖NAS	团队已有硬件、7×24运行

---

下一步：03-detailed-design.md