QuantOL - 基于事件驱动的量化交易系统

一个基于事件驱动架构的专业量化交易系统，提供完整的策略开发、回测分析和交易执行功能。采用前后端分离架构，支持实时进度追踪和异步任务执行。

✨ 特性

🚀 核心功能

事件驱动架构 - 基于消息总线的松耦合设计
前后端分离 - React/Next.js 前端 + FastAPI 后端
异步任务执行 - 支持后台回测和实时进度追踪
WebSocket 通信 - 实时推送回测进度和状态更新
Redis 状态存储 - 持久化回测状态和结果
Nginx 反向代理 - 统一入口，支持 WebSocket 代理
双数据库模式 - 支持SQLite(快速体验)和PostgreSQL(生产环境)
多数据源支持 - Tushare、Baostock、AkShare等数据源集成
策略回测引擎 - 支持多股票组合回测和规则组管理
风险控制系统 - 完整的资金管理和风险控制机制

📊 策略支持

规则策略 - 支持技术指标组合和自定义规则
仓位管理 - 固定比例、凯利公式、马丁格尔等多种仓位策略
多股票组合 - 支持多股票策略映射和资金分配
技术指标 - MA、MACD、RSI、布林带等常用指标

🎯 专业工具

图表服务 - K线图、成交量、资金流向等专业图表
性能分析 - 夏普比率、最大回撤、年化收益等指标
交易记录 - 完整的交易历史和持仓管理
数据管理 - 异步数据加载和缓存机制

🚀 快速开始

环境要求

Python 3.12+
Node.js 20+ (用于 React 前端)
uv (包管理器)
Redis: 7.0+ (用于状态存储)
Nginx: 1.24+ (反向代理)
数据库: SQLite 3.0+ (默认) 或 PostgreSQL 13+ (可选)

🗄️ 数据库模式选择

本项目支持两种数据库模式：

模式	适用场景	优点	缺点
SQLite (默认)	快速体验、开发测试	零配置、开箱即用	性能有限、不适合大数据量
PostgreSQL	生产环境、大数据处理	高性能、高并发	需要额外安装配置

📦 安装步骤

安装依赖软件

# 安装 Redis
# Ubuntu/Debian
sudo apt-get install redis-server

# macOS
brew install redis

# 或使用 Docker
docker run -d -p 6379:6379 redis:7

# 安装 Nginx
# Ubuntu/Debian
sudo apt-get install nginx

# macOS
brew install nginx

安装 uv

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用包管理器
pip install uv

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

克隆项目

git clone https://github.com/FAKE0704/QuantOL.git
cd QuantOL

安装依赖

# Python 依赖
uv sync

# 前端依赖
cd landing-page && npm install && cd ..

配置环境

# 复制配置文件
cp .env.example .env

启动应用

use pm2 to start 启动后访问：- 新版界面: http://localhost:8087
Streamlit: http://localhost:8087/app

🔄 数据库模式切换

方式一：命令行切换

# 切换到SQLite模式（默认）
uv run python -m src.cli.database_switch switch --type sqlite

# 切换到PostgreSQL模式
uv run python -m src.cli.database_switch switch --type postgresql

方式二：Web界面切换

启动应用后，在左侧导航栏选择"系统设置-数据库设置"
点击相应按钮切换数据库类型
系统会自动处理配置和初始化

方式三：手动配置

编辑 .env 文件：

# 选择数据库类型 (sqlite/postgresql)
DATABASE_TYPE=sqlite

# SQLite配置
SQLITE_DB_PATH=./data/quantdb.sqlite

# PostgreSQL配置 (当使用PostgreSQL时)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=quantdb
DB_USER=quant
DB_PASSWORD=your_password_here

🐘 PostgreSQL模式配置（可选）

如果需要使用PostgreSQL模式，请按以下步骤配置：

使用Docker（推荐）

# 启动PostgreSQL容器
docker-compose up -d

# 验证数据库运行状态
docker-compose ps

使用本地PostgreSQL

# macOS (使用Homebrew)
brew install postgresql
brew services start postgresql

# 创建数据库和用户
createdb quantdb
createuser quant
psql -d postgres -c "ALTER USER quant PASSWORD 'your_password';"
psql -d quantdb -c "GRANT ALL PRIVILEGES ON DATABASE quantdb TO quant;"

# 参见详细文档: LOCAL_POSTGRES_SETUP.md

🛠️ 常用命令

包管理

# 同步依赖（安装/更新虚拟环境）
uv sync

# 添加新依赖
uv add <package>

# 更新所有依赖
uv lock --upgrade

数据库管理

# 查看当前数据库状态
uv run python -m src.cli.database_switch status

# 重新初始化数据库
uv run python -m src.cli.database_switch init

# 切换数据库类型
uv run python -m src.cli.database_switch switch --type sqlite
uv run python -m src.cli.database_switch switch --type postgresql

应用管理

# 启动应用
uv run streamlit run main.py

# 指定端口启动
uv run streamlit run main.py --server.port 8501

# 允许外部访问
uv run streamlit run main.py --server.address 0.0.0.0

⚠️ 注意事项

SQLite模式: 数据存储在本地文件中，适合开发测试和个人使用
PostgreSQL模式: 需要数据库服务运行，适合生产环境和团队使用
数据迁移: 两种模式间的数据需要手动迁移
性能差异: PostgreSQL在处理大量数据时性能更优

🔧 故障排除

常见问题

数据库连接失败: 检查数据库服务状态和配置信息
SQLite权限错误: 确保数据目录有写入权限
PostgreSQL连接超时: 检查防火墙和网络配置

获取帮助

查看应用日志获取详细错误信息
使用"数据库设置"页面进行连接测试
检查配置文件格式和参数

数据源配置

系统支持多种数据源，可通过系统设置页面灵活切换：

数据源	特点	配置要求	适用场景
Tushare	专业级金融数据接口	需要注册获取Token	生产环境、专业分析
Baostock	免费开源证券数据平台	无需配置	学习测试、快速体验
AkShare	多市场数据源	可选API密钥	多市场数据获取

Tushare配置 (推荐)

访问 Tushare官网注册账户
在个人中心获取API Token
在系统设置 → 数据源配置中输入Token

或在 .env 文件中配置：

TUSHARE_TOKEN=your_32_character_token_here
SELECTED_DATA_SOURCE=Tushare

Baostock配置 (默认)

无需任何配置，开箱即用
适合快速体验和学习测试
在系统设置中直接选择即可使用

🏗️ 项目架构

核心模块

QuantOL/
├── src/                     # 后端核心
│   ├── api/                 # FastAPI 路由
│   │   ├── models/          # Pydantic 请求/响应模型
│   │   │   ├── common.py           # 通用模型
│   │   │   ├── backtest_requests.py
│   │   │   └── backtest_responses.py
│   │   ├── routers/         # API 端点
│   │   │   ├── backtest/    # 回测路由子包 (模块化)
│   │   │   │   ├── execution.py      # 执行端点
│   │   │   │   ├── results.py        # 结果端点
│   │   │   │   ├── configs.py        # 配置端点
│   │   │   │   ├── custom_strategies.py # 策略端点
│   │   │   │   └── logs.py           # 日志端点
│   │   │   ├── auth.py      # 认证 API
│   │   │   ├── stocks.py    # 股票 API
│   │   │   └── websocket.py # WebSocket API
│   │   ├── deps.py          # 通用依赖注入
│   │   ├── utils.py         # 共享工具函数
│   │   └── server.py        # FastAPI 应用
│   ├── core/                # 核心业务逻辑
│   │   ├── data/            # 数据管理
│   │   │   ├── database.py  # 数据库管理
│   │   │   └── data_source.py
│   │   ├── strategy/        # 策略管理
│   │   │   ├── backtesting.py      # 回测引擎
│   │   │   ├── rule_parser/        # 规则解析器包 (模块化)
│   │   │   │   ├── expression_context.py    # 评估上下文
│   │   │   │   ├── ast_node_handler.py      # AST操作工具
│   │   │   │   ├── cache_manager.py          # LRU缓存管理
│   │   │   │   ├── result_storage.py         # 结果存储管理
│   │   │   │   ├── cross_sectional_ranker.py # 横截面排名
│   │   │   │   ├── rule_evaluator.py         # 表达式评估
│   │   │   │   └── rule_parser.py            # 门面类 (向后兼容)
│   │   │   ├── rule_based_strategy.py # 规则策略
│   │   │   └── position_strategy.py   # 仓位策略 (固定比例、马丁格尔、凯利公式)
│   │   ├── backtest/        # 回测引擎 (模块化)
│   │   │   ├── protocols/    # 协议接口
│   │   │   ├── services/     # 服务层
│   │   │   ├── coordinators/ # 协调器
│   │   │   └── engine.py     # 重构引擎
│   │   ├── execution/       # 交易执行
│   │   ├── risk/            # 风险控制
│   │   └── portfolio/       # 投资组合
│   ├── frontend/            # Streamlit 界面
│   │   ├── backtesting.py
│   │   └── backtest_config_ui.py
│   ├── services/            # 服务层
│   │   ├── interfaces/      # 服务接口定义
│   │   ├── backtest_state_service.py    # Redis 状态存储
│   │   ├── backtest_task_manager.py     # 异步任务管理
│   │   ├── backtest_task_service.py     # 任务服务
│   │   ├── websocket_manager.py         # WebSocket 连接管理
│   │   └── chart_service.py             # 图表服务
│   ├── event_bus/          # 事件总线
│   │   ├── service_events.py            # 服务事件定义
│   │   └── local_service_bus.py         # 本地服务总线
│   └── utils/              # 工具模块
│       ├── encoders.py      # JSON 编码器
│       ├── async_helpers.py # 异步辅助工具
│       └── strategy_registry.py # 策略注册表
├── landing-page/            # React/Next.js 前端
│   ├── app/                 # Next.js App Router
│   │   └── (app)/
│   │       └── backtest/    # 回测页面
│   ├── components/          # React 组件
│   │   └── backtest/        # 回测相关组件
│   ├── lib/                 # 工具库
│   │   ├── api.ts           # API 客户端
│   │   └── hooks/           # React Hooks
│   │       └── useBacktestWebSocket.ts
│   └── package.json
├── nginx.conf               # Nginx 配置
├── start.sh                 # 启动脚本
└── stop.sh                  # 停止脚本

架构改进 (2025年2月重构)

RuleParser 模块化 (1061行 → 7个组件)

ExpressionContext - 不可变的评估上下文数据类
ASTNodeHandler - 无状态AST节点操作工具
RuleCacheManager - LRU缓存管理器 (时间相关/无关分离)
ResultStorageManager - DataFrame列存储管理
CrossSectionalRanker - 横截面排名逻辑
RuleEvaluator - 表达式评估核心逻辑
RuleParser (门面) - 向后兼容的统一入口

API Router 模块化 (1408行 → 5个子模块)

execution.py - 回测执行端点
results.py - 结果查询端点 (6个)
configs.py - 配置管理端点 (6个)
custom_strategies.py - 自定义策略端点 (6个)
logs.py - 日志查询端点
models/ - 统一的Pydantic模型组织

事件驱动架构

系统采用事件驱动设计，主要事件类型：

MarketDataEvent - 市场数据事件
SignalEvent - 策略信号事件
OrderEvent - 订单事件
FillEvent - 成交回报事件

数据流

数据获取 → 数据管理器 → 指标计算
策略引擎 → 信号生成 → 风险验证 → 订单执行
交易执行 → 持仓更新 → 组合管理 → 业绩评估

异步回测流程

前端发起 → POST /api/backtest/run
创建任务 → BacktestTaskManager 提交后台任务
状态存储 → Redis 保存回测状态
执行回测 → BacktestEngine 异步执行
进度推送 → WebSocket 实时推送进度
前端展示 → 进度条显示 + 结果展示

技术栈

层级	技术栈	用途
前端	React 18, Next.js 14, Tailwind CSS	用户界面
后端	FastAPI, Python 3.12+	API 服务
通信	WebSocket, HTTP/REST	实时通信
缓存	Redis 7.0+	状态存储
代理	Nginx 1.24+	反向代理
数据库	SQLite, PostgreSQL	数据持久化
任务	FastAPI BackgroundTasks	异步执行

📈 使用示例

策略回测

from src.core.strategy.backtesting import BacktestConfig, BacktestEngine

# 创建回测配置
config = BacktestConfig(
    start_date="2023-01-01",
    end_date="2024-01-01",
    target_symbol="000001.SZ",
    initial_capital=100000,
    position_strategy_type="fixed_percent",
    position_strategy_params={"percent": 0.1}
)

# 执行回测
engine = BacktestEngine(config)
results = engine.run()

规则策略

# 定义交易规则
rules = {
    "buy_rule": "CLOSE > MA(CLOSE, 20) AND MA(CLOSE, 5) > MA(CLOSE, 20)",
    "sell_rule": "CLOSE < MA(CLOSE, 10)"
}

🛠️ 开发指南

添加新策略

继承 BaseStrategy 类
实现 generate_signals 方法
注册到策略工厂

from src.core.strategy.strategy import BaseStrategy

class MyCustomStrategy(BaseStrategy):
    def generate_signals(self, data):
        # 实现策略逻辑
        return signals

添加新指标

继承 Indicator 类
实现计算逻辑
注册到指标工厂

from src.services.chart_service import Indicator

class CustomIndicator(Indicator):
    def calculate(self, data):
        # 实现指标计算
        return result

📊 性能指标

系统提供完整的性能分析：

年化收益率 - 策略年化收益表现
夏普比率 - 风险调整后收益
最大回撤 - 最大亏损幅度
胜率 - 交易成功比例
盈亏比 - 平均盈利/平均亏损

🤝 贡献指南

我们欢迎各种形式的贡献！请查看 CONTRIBUTING.md 了解详情。

开发流程

Fork 项目
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📄 许可证

本项目采用 Apache 2.0 许可证。详细信息请参见 LICENSE 文件。

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

🙏 致谢

核心技术

FastAPI - 现代化 Python Web 框架
React - 用户界面库
Next.js - React 应用框架
WebSocket - 实时双向通信
Redis - 内存数据库和缓存
Nginx - 高性能反向代理
Streamlit - 优秀的Web应用框架

数据源

Baostock - 免费A股数据源
AkShare - 多市场数据接口
Tushare - 专业金融数据接口

🌐 Web 前端

本项目包含一个基于 Next.js 的前端界面，位于 web/ 目录。

前端功能

✅ 回测配置和执行
✅ 回测结果查看
✅ 策略管理和配置
✅ K线图表展示
✅ 数据源配置
✅ 参数优化功能

前端快速启动

# 进入前端目录
cd web

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 访问 http://localhost:3000

前端环境变量

创建 web/.env 文件：

# 后端 API 地址（默认通过 Nginx 代理，留空即可）
PYTHON_API_URL=

# 或直接连接后端（开发环境）
# PYTHON_API_URL=http://localhost:8000

📞 联系方式

如有问题或建议，请通过以下方式联系：

项目 Issues: GitHub Issues
邮箱: pengfeigaofake@gmail.com
微信: ThomasGao0704

⭐ 如果这个项目对您有帮助，请给我一个 Star！

Name		Name	Last commit message	Last commit date
Latest commit History 239 Commits
.github/workflows		.github/workflows
.spec-workflow/designs/draft		.spec-workflow/designs/draft
Scripts		Scripts
config		config
docs		docs
examples		examples
scripts		scripts
src		src
tests		tests
web		web
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile.streamlit		Dockerfile.streamlit
LICENSE		LICENSE
LOCAL_POSTGRES_SETUP.md		LOCAL_POSTGRES_SETUP.md
README.md		README.md
SECURITY.md		SECURITY.md
dev.sh		dev.sh
docker-compose.yml		docker-compose.yml
ecosystem.config.js		ecosystem.config.js
ecosystem.dev.config.js		ecosystem.dev.config.js
main.py		main.py
nginx-site.conf		nginx-site.conf
nginx.conf		nginx.conf
pyproject.toml		pyproject.toml
run_automation_tests.py		run_automation_tests.py
stop.sh		stop.sh
test_real_data_quick.py		test_real_data_quick.py
test_rule_with_real_data.py		test_rule_with_real_data.py
test_tushare_integration.py		test_tushare_integration.py
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

QuantOL - 基于事件驱动的量化交易系统

✨ 特性

🚀 核心功能

📊 策略支持

🎯 专业工具

🚀 快速开始

环境要求

🗄️ 数据库模式选择

📦 安装步骤

🔄 数据库模式切换

方式一：命令行切换

方式二：Web界面切换

方式三：手动配置

🐘 PostgreSQL模式配置（可选）

使用Docker（推荐）

使用本地PostgreSQL

🛠️ 常用命令

包管理

数据库管理

应用管理

⚠️ 注意事项

🔧 故障排除

常见问题

获取帮助

数据源配置

Tushare配置 (推荐)

Baostock配置 (默认)

🏗️ 项目架构

核心模块

架构改进 (2025年2月重构)

RuleParser 模块化 (1061行 → 7个组件)

API Router 模块化 (1408行 → 5个子模块)

事件驱动架构

数据流

异步回测流程

技术栈

📈 使用示例

策略回测

规则策略

🛠️ 开发指南

添加新策略

添加新指标

📊 性能指标

🤝 贡献指南

开发流程

📄 许可证

🙏 致谢

核心技术

数据源

🌐 Web 前端

前端功能

前端快速启动

前端环境变量

📞 联系方式

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages