free-stockdb 部署教程：本地A股量化数据引擎

free-stockdb 是一个面向 A 股（包括股票、ETF）的本地量化数据引擎，集成了日K、分钟K数据同步、清洗、复权、批量查询、技术指标计算和回测功能。它将数据工程与策略研究解耦，让用户能在本地快速开展全市场回测和研究。

本教程将指导你在 Windows、macOS 或 Linux 上完成从零到运行的部署。

📦 第一步：下载与安装

free-stockdb 提供预编译的发行包，推荐直接下载使用。

下载发行包：
- 访问项目的 GitHub Releases 页面。
- 根据你的操作系统下载对应的压缩包：
  - Windows：下载 free-stockdb-windows-*.zip
  - macOS：下载 free-stockdb-macos-*.dmg 或 .zip
  - Linux：下载 free-stockdb-linux-*.tar.gz (Alpine 或 Manylinux 版本)
解压到本地目录：
将下载的压缩包解压到一个你容易找到的文件夹，例如 D:\stockdb (Windows) 或 ~/stockdb (Linux/macOS)。解压后的目录结构应包含：
- stockdb.exe (Windows) 或 stockdb (macOS/Linux) — 主程序
- sync_url.txt — 数据源配置文件
- 调用方式/ 目录 — 包含 Python、Excel、HTML 等示例

⚙️ 第二步：首次启动与数据同步

关键步骤：首次使用前必须同步数据，以在本地建立完整的行情数据库。

运行数据同步工具：
- Windows：双击运行 update_stockdb.bat 或直接在命令行执行 stockdb.exe sync。
- macOS/Linux：在终端中，cd 到解压目录，执行 ./stockdb sync。
- 同步过程会从 sync_url.txt 中配置的数据源下载 Zstd 压缩的历史数据，并进行校验和解压。数据会存储在 ./data 目录下。
注意：
- 首次同步可能需要较长时间（取决于网络和全量数据大小，但远快于逐股请求 API）。
- sync_url.txt 允许你配置多个数据源，甚至本地路径 (file://) 以实现完全离线部署。
- 后续更新只同步增量变化，速度很快。
启动本地数据服务：
同步完成后，启动服务引擎：
- Windows：双击 start_stockdb.bat。
- macOS/Linux：执行 ./stockdb server。
- 服务默认会在本地的 127.0.0.1:7899 端口启动。请保持此终端窗口运行（或设置后台运行）。

🐍 第三步：通过 Python SDK 调用

这是最推荐的研究与回测交互方式。

安装 Python 客户端（可选但推荐）：
在解压目录下的 调用方式/Python/ 文件夹中，有封装好的 Python 调用示例。你可以直接复制 rd.py 或 pybao 模块到你的项目中使用，无需安装额外大型依赖。

基础查询示例 (rd.get_data())：

from rd import rd # 假设 rd.py 在当前路径

# 查询单只股票
data = rd.get_data(
    code='000001',          # 股票代码
    start='2024-01-01',
    end='2024-12-31',
    frequency='day',        # 日线
    fq='qfq',               # 前复权
    fields='open,high,low,close,volume'
)
print(data)

批量计算技术指标 (zb.get())：

from rd import zb

# 计算全市场股票的 MA 和 MACD
indicators = zb.get(
    name='ma,macd',
    codes='all',            # 全市场
    start='2024-06-01',
    end='2024-07-01',
    frequency='30min',      # 30分钟K线
    fq='qfq',
    n=['5,10,20', '12,26,9'] # 各自参数
)

板块与概念查询 (bk.get())：

from rd import bk

# 查询 "新能源" 概念板块包含的股票
stocks = bk.get(x='新能源', category=0) # category: 0-概念, 1-申万一级...
print(stocks)

🌐 第四步：其他调用方式

HTTP API：在浏览器或任何支持 HTTP 的语言中访问 http://127.0.0.1:7899/?cmd=get&t=000001&freq=day。
Excel / WPS：使用 调用方式/Excel/ 目录下的宏文件，在表格中直接调用数据。
HTML 网页：在浏览器中打开 调用方式/HTML/数据网页版.html，即可进行无代码的可视化查询。
AI MCP 协议：支持 Claude、Cursor 等 AI 工具，通过 MCP 协议直接连接本地服务进行数据查询和分析。

🛠️ 第五步：高级配置与数据管理

5.1 写入私有数据 (`./mydb`)

free-stockdb 允许你将自定义的因子、策略信号或私有数据写入本地存储，与核心行情数据隔离。

from rd import rd

# 批量写入示例
pipeline = rd.pipe()
for i in range(10000):
    pipeline.set('my_table', f'key_{i}', {'value': i}) # 可存储 dict/list 等
pipeline.execute() # 执行

5.2 配置多数据源

编辑 sync_url.txt 文件，每行一个数据源地址，支持 http://、https:// 或 file:/// 本地路径。服务启动时会自动合并读取这些来源的数据。

🩺 常见问题与排障

服务无法启动或端口被占用：
默认端口 7899。如果被占用，可以在 stockdb.conf 中修改 port 参数。
同步失败或数据不完整：
1. 检查网络是否能访问 sync_url.txt 中的地址。
2. 查看 sync_url.txt 是否配置正确，可尝试切换为备用的数据源地址。
3. 检查磁盘空间是否充足。
查询结果为空或报错：
1. 确认 stockdb server 正在运行。
2. 检查查询的 code、start/end 日期格式是否正确，是否超出数据范围。
3. 在 Python 调用中，将 rd.debug = True 开启调试模式查看详细日志。
如何更新数据：
重复执行第二步中的 stockdb sync 命令即可进行增量更新。可以将其设置为定时任务。