free-stockdb -开源数据源-数据提供商-01057

评论
12 views

free-stockdb 项目完整架构与设计详解

一、项目总览定位

free-stockdb 是面向A股/ETF量化研究的本地私有化时序数据引擎，核心解决量化从业者远程API数据拉取慢、清洗复权工程繁重、多端调用割裂的痛点，整体采用底层C++高性能存储计算 + 上层多语言多协议接入的分层解耦架构，实现「数据同步-存储-计算-多终端调用」一站式量化数据底座。 核心设计理念：时序优先、本地优先、全链路内置数据治理、多协议统一封装、AI原生兼容，完全抛弃通用关系型数据库SQL范式，为股票行情场景做垂直深度定制。

源码目录分层（仓库文件结构）

free-stockdb/
├── cpp/                # 底层C++核心引擎（时序存储、同步器、计算内核、服务端）
├── pybao/              # Python SDK客户端封装，策略回测专用
├── docs/               # 文档、接口说明、部署指南
├── 调用方式/           # HTTP/Excel/HTML/MCP多端调用示例代码
├── 数据网页版.html     # 无代码可视化前端
├── stockdb.conf        # 服务全局配置
├── sync_url.txt        # 多数据源同步配置文件
├── .gitignore LICENSE README.md
├── 使用说明.txt        # 快速部署、版本迭代记录
└── 资源文件（运行截图、示范图）

语言占比：HTML35.5%、Python33.6%、C++17.4%、JS12.8%、CMake0.7%，兼顾底层性能与上层易用性。

二、五层整体分层架构（自上而下）

整体依赖单向流转：接入层 → 服务协议层 → 计算业务层 → 时序存储引擎层 → 数据同步采集层，层与层之间通过统一内部协议隔离，任意层可独立替换，数据更新与策略查询完全解耦。

┌─────────────────────────────────────────────┐
│ 第一层：多终端统一接入层（5种调用入口）       │ 面向用户/AI/办公工具
├─────────────────────────────────────────────┤
│ 第二层：服务网关协议层（HTTP/MCP/本地IPC）   │ 统一请求路由、参数解析
├─────────────────────────────────────────────┤
│ 第三层：量化业务计算层（指标/板块/私有存储）  │ 行情加工、技术指标、指数、自定义因子
├─────────────────────────────────────────────┤
│ 第四层：C++时序存储引擎核心层                │ 底层读写、压缩、索引、并发、持久化
├─────────────────────────────────────────────┤
│ 第五层：多源数据同步采集层                  │ 远程拉取、清洗、复权、增量落盘
└─────────────────────────────────────────────┘

第一层：多终端统一接入层（五大调用通道）

面向不同使用人群设计5套原生接入方案，底层复用同一套数据计算内核，接口语义完全对齐，无需重复适配数据逻辑。 | 接入方式 | 实现载体 | 核心场景 | |--------|---------|---------| | Python SDK | pybao目录封装rd/zb/bk三类API | 量化回测、批量策略、全市场遍历，支持同步/异步 get_data_async | | HTTP API | 内置web服务 127.0.0.1:7899 | 跨语言集成（Java/Go/JS）、第三方系统对接 | | Excel/WPS宏 | 配套宏脚本 | 无代码选股、表格量化、办公自动化分析 | | HTML网页 | 数据网页版.html | 可视化K线浏览、行情筛选、数据导出CSV | | AI MCP协议 | 内置MCP Server | Claude/Cursor/Windsurf等AI工具自然语言查行情、算指标 |

MCP架构特殊设计：自研兼容Model Context Protocol服务端，对外暴露三类工具：行情查询get_data、指标计算zb.get、板块映射bk.get，AI无需理解底层数据格式，直接通过自然语言完成全市场量化分析。

第二层：服务网关协议层

内置统一网关，统一处理所有接入层请求，核心职责： 1. 协议转换：将Python对象、HTTP Query、MCP JSON-RPC、Excel请求统一转为引擎内部标准指令； 2. 参数校验与分发：区分行情查询、指标计算、板块查询、私有数据读写四大指令路由； 3. 并发控制：支持128进程高并发并行查询、读写分离，回测与数据更新互不阻塞； 4. 结果格式化：统一输出List/Dict/Pandas DataFrame/JSON多格式； 5. 安全隔离：默认仅监听本地127.0.0.1，无公网暴露风险。

第三层：量化业务计算层（业务逻辑中台）

引擎核心业务能力封装，全部下沉至服务端计算，避免上层客户端反复搬运海量行情数据，分为三大独立子模块：

1. RD行情数据模块（rd.get_data）

负责原始时序行情读写，支持： - 多周期数据：日/周/月/1/5/15/30分钟K线、Tick逐笔数据； - 复权统一处理：查询时动态计算前复权/后复权/不复权，内置完整分红送转因子； - 高级查询语法：代码正则匹配（600*）、时间区间筛选、切片截取、列式字段提取、排序； - 私有批量存储引擎（v0.2.1新增）：mydb自定义库，支持千万级数据Pipe批量写入、嵌套字典/DF持久化、WAL事务防丢失，用于存储自定义因子、策略缓存、私有数据源； - 多点数据源挂载：sync_url.txt配置多路径数据分片（data/data1/data2），查询自动聚合全部分片数据。

2. ZB指标计算模块（zb.get）

Rust加速计算内核，性能较原生Pandas快3倍，内置39类技术指标 + 5种加权指数： - 趋势类：MA/EMA/DMA/TRIX/DMI等10种； - 震荡类：MACD/KDJ/RSI/CCI/WR等10种； - 通道/量价/综合类：BOLL/OBV/MFI/ATR/STD等19种； - 指数算法：等权、总市值加权、流通市值加权、成交额加权、成交量加权； - 批量能力：一次性传入全市场7000+标的，秒级批量输出指标与金叉/死叉信号。

3. BK板块映射模块（bk.get）

内置完整A股板块元数据，毫秒级双向映射： - 申万一/二/三级行业分类； - 1200+市场概念板块； - 双向查询：根据股票查所属板块、根据板块批量获取成分股； - 支持批量代码、板块名称模糊检索。

第四层：C++时序存储引擎核心层（底层底座）

完全自研垂直定制时序数据库，放弃通用SQL、无固定Schema，针对股票代码+时间双主键查询深度优化，解决SQLite/Mongo/Redis在全市场分钟线场景下的性能、存储膨胀痛点。

1. 存储模型设计

主键结构：[市场代码, 时间戳]，一维时序有序存储，天然适配K线按时间范围批量扫描； 数据类型无约束：支持int/float/str/list/dict/bytes/Pandas DF任意嵌套，新增自定义因子无需改表结构。

2. 存储压缩与IO优化

  • Zstd高压缩存储：磁盘占用仅为CSV/MySQL的1/3；
  • 分片目录存储：./data区分日线、分钟线、tick、私有因子库；
  • 内存映射+读写分离：查询只读内存缓存，写入走磁盘WAL日志，断电数据不丢失；
  • 轻量单进程服务：程序本体仅2.2MB，Windows/Mac/Linux跨平台预编译包。

3. 底层读写API（原子操作）

# 批量管道写入（千万级高性能）
pipeline = rd.pipe()
pipeline.mset(table, k1, k2, value)
# 单条/嵌套修改
await rd.set(table, key, subkey, new_val)
# 高级查询：正则、区间、切片、子字段
rd.get("day", "600*", start="20250101", end="20260801")["close"][-100:]
# 配套辅助：keys/vals/len/delete 元操作

4. 并发架构

支持多进程并行读取，128进程压力测试通过；读无锁、写加轻量管道锁，回测批量计算与每日数据增量更新可同时运行无冲突。

第五层：多源数据同步采集层（数据流入层）

解耦数据源与本地查询引擎，实现数据源可插拔、增量同步、全链路数据治理，无需人工清洗处理脏数据。 1. 多数据源配置：sync_url.txt支持远程HTTPS节点、本地文件目录file://、内网私有同步服务，可配置多路径分别存储日线/分钟线/Tick； 2. 增量同步机制：仅拉取新增变更数据，断点续传、SHA256文件校验防损坏，无需全量重下； 3. 内置全自动数据治理流水线（传统方案需人工开发1~3周）： - 基础清洗：剔除停牌、退市、重复数据、修复代码更名、时间排序对齐； - 复权计算：自动同步分红、送转、配股除权信息，生成复权因子持久化； - 元数据同步：新股、行业概念板块每日自动更新； 4. 离线兼容：同步完成后断开外网，本地完整保留历史行情，无远程接口依赖。

三、核心数据流完整链路

链路1：每日数据更新链路（离线同步）

远程数据源 → Zstd增量分片拉取 → 自动清洗/复权/校验 → C++时序引擎压缩落盘（./data） → 私有存储写入自定义因子（可选）

链路2：量化查询/回测链路（本地离线）

用户（Python/网页/AI） → HTTP/MCP/IPC网关 → RD行情读取 → ZB批量指标计算（服务端完成） → BK板块成分过滤 → 返回结构化数据给上层做策略回测

链路3：自定义私有数据写入链路

Python/HTTP批量管道写入 → mydb私有时序库持久化 → 后续查询自动聚合原生行情+私有因子数据

四、关键架构设计亮点

1. 分层完全解耦，模块可独立替换

  • 数据源层可自由切换，不改动上层查询代码；
  • 计算内核与存储分离，可单独升级指标算法；
  • 接入层多协议统一抽象，新增调用端无需重构底层。

2. 计算下沉服务端，极致降低上层开销

传统量化方案：全市场行情下载到客户端Pandas再计算，内存爆炸、耗时数小时； free-stockdb：7000+标的指标、指数全在C++/Rust服务端批量运算，仅返回结果给客户端，全市场计算秒级完成。

3. 无Schema时序存储，适配量化多变因子

关系库需要提前建表，新增自定义因子、另类数据必须DDL改库；本项目动态存储任意结构化/嵌套数据，私有因子直接写入无需调整存储结构。

4. AI原生MCP协议架构，适配AI量化新场景

行业少见内置原生MCP服务的本地行情库，AI工具可通过自然语言直接执行选股、回测、指标分析，打通AI与本地金融数据壁垒。

5. 跨平台轻量化部署，零数据库依赖

无需安装MySQL/Redis/DuckDB等第三方数据库，Windows/Mac/Linux一键双击启动，最低仅需5GB磁盘、2GB内存即可运行完整日线数据集。

五、部署与运行架构

  1. 单机本地架构（主流） 单机器启动stockdb服务（127.0.0.1:7899），本地Python/Excel/网页/AI全部直连本机服务，数据存储本机磁盘，完全离线可用。
  2. 局域网分布式架构 服务监听内网IP，多台电脑共享同一套本地行情数据，分布式并行回测、多人团队共用数据源。
  3. 离线无网架构 提前完成全量数据同步，断网后所有查询、指标计算、回测功能不受任何影响，无Token、接口限额约束。

六、扩展性设计

  1. 数据源扩展：新增行情源仅需在sync_url.txt添加地址，同步层自动适配增量拉取；
  2. 数据类型扩展：财报、宏观、资金流等低频数据可通过rd.pipe写入私有mydb库，复用同一套查询API；
  3. 指标扩展：底层C++计算内核可新增自定义技术指标，上层zb.get无需改动调用代码；
  4. 接入端扩展：新增客户端协议只需在网关层增加解析逻辑，复用底层存储计算能力。

七、架构对比传统量化数据方案

环节 传统远程API+自建数据库方案 free-stockdb一体化分层架构
数据同步 逐股请求、限频封号、全量下载3~5天 增量分片同步、断点续传，几十分钟完成全量
数据治理 人工开发清洗/复权逻辑，耗时1~3周 同步层内置全自动治理流水线
存储引擎 通用数据库，表结构复杂、查询慢、占用磁盘大 垂直时序C++引擎，压缩存储、代码+时间索引优化
指标计算 Pandas客户端遍历，全市场小时级耗时 服务端Rust加速，全市场秒级批量计算
多端调用 分别开发Python/网页/Excel三套接口 统一底层，5种调用通道原生内置
AI对接 需自行封装API适配MCP 原生MCP Server，开箱即用对接AI工具
工程落地周期 10~15个工作日跑通全市场回测 30分钟从零部署至可回测

八、版本迭代架构演进

  • v0.2.0基础版：完成C++时序引擎、Python/HTTP/HTML三端接入、基础指标；
  • v0.2.1（08-05最新版）：新增私有批量存储mydb、多点数据源分片、MCP协议、Linux/Mac完整适配、128进程并发优化，完善全链路分布式、自定义因子扩展能力，当前完整五层架构定型。

Github