A_Share_DP/README.md

A-Share Data Platform

A股全量数据服务 — Parquet + DuckDB 存储，REST + WebSocket 双协议。

支持的 K 线周期

周期	代码	数据范围	来源
1 分钟	1m	近 1-3 月（需每日盘后积累）	AKShare
5 分钟	5m	同上	AKShare
15 分钟	15m	同上	AKShare
30 分钟	30m	同上	AKShare
1 小时	1h	同上	AKShare
2 小时	2h	从 1h 实时推导	DuckDB
日线	1d	全部历史（1990 年起）	AKShare
周线	1w	从日线推导	DuckDB
月线	1M	从日线推导	DuckDB

分钟线数据受限于上游 API 只保留近 1-3 个月，必须通过每日盘后自动拉取持续积累。日线/周线/月线可随时回填全部历史。

架构

AKShare (East Money / Sina)
  → AKShareClient (dual backend, auto-fallback)
    → BackfillPipeline / EODPipeline
      → Parquet (Hive-partitioned, Zstd compressed)
        → DuckDB (metadata + read_parquet queries)
          → FastAPI (REST + WebSocket)

• 存储: Parquet 列存（Zstd 压缩 ~80%），Hive 分区 year=YYYY/month=MM/day=DD/data.parquet
• 查询: DuckDB 内嵌 OLAP，read_parquet() 直接读取，支持分区裁剪和谓词下推
• 数据源: AKShare 封装，双后端自动切换（East Money 国内优先，Sina 全球可访问）

快速开始

安装

pip install -e .

配置

cp .env.example .env
# 编辑 .env 按需调整参数

初始化数据库 + 导入股票列表

ashare-dp backfill init

回填历史数据

# 回填全部日线/周线/月线
ashare-dp backfill daily --workers 10

# 回填指定股票指定日期范围
ashare-dp backfill daily --start 2025-01-01 --end 2026-05-16 --symbols 000001,600000

# 回填近 30 天分钟数据
ashare-dp backfill minute --days 30 --workers 5

启动 API 服务

ashare-dp serve start --port 8000

启动后访问 http://localhost:8000/ 查看文档，http://localhost:8000/docs 查看 Swagger。

命令行查询

ashare-dp query kline 1d 000001.SZ --start 2026-01-01
ashare-dp query latest --freq 1d --ts-code 000001.SZ
ashare-dp query stats
ashare-dp query stocks --exchange SH

API 端点

所有 REST 端点前缀 /api/v1。

股票查询

方法	路径	说明
GET	/stocks	分页列表，可按交易所/板块筛选
GET	/stocks/search?q=平安	名称/代码模糊搜索
GET	/stocks/{ts_code}	单只股票详情

K 线查询

方法	路径	说明
GET	/klines/{freq}?ts_code=&start_date=&end_date=	单只 K 线查询
POST	/klines/{freq}/batch	批量 K 线查询
GET	/klines/{freq}/latest?ts_code=	最新交易日数据
GET	/klines/available-freqs	支持的频率列表

实时行情

方法	路径	说明
GET	/realtime/spot?codes=000001.SZ,600000.SH	实时快照
GET	/realtime/market-state	市场状态

交易日历

方法	路径	说明
GET	/calendar/trading-days?start=&end=	区间内交易日
GET	/calendar/is-trading-day?date=	判断交易日
GET	/calendar/next-trading-day?date=	下一个交易日

WebSocket

ws://localhost:8000/ws/realtime

交易时段每 5 秒推送订阅股票的实时行情。连接后发送 JSON 控制消息：

{"action": "subscribe", "codes": ["000001.SZ", "600519.SH"]}
{"action": "unsubscribe", "codes": ["000001.SZ"]}
{"action": "unsubscribe_all"}

其他

方法	路径	说明
GET	/health	健康检查
GET	/stats	数据库统计（各周期记录数、日期范围）

CLI 命令

ashare-dp version                  # 显示版本
ashare-dp backfill init            # 初始化数据库
ashare-dp backfill daily [...]     # 回填日线/周线/月线
ashare-dp backfill minute [...]    # 回填分钟线
ashare-dp serve start [...]        # 启动 API 服务
ashare-dp query kline ...          # 查询 K 线
ashare-dp query latest ...         # 最新数据
ashare-dp query stocks ...         # 股票列表
ashare-dp query stats              # 数据统计

配置参数

变量	默认值	说明
DATA_DIR	data	数据目录
DUCKDB_PATH	data/duckdb/ashare.db	DuckDB 文件路径
API_HOST	0.0.0.0	API 绑定地址
API_PORT	8000	API 绑定端口
BACKFILL_WORKERS	10	回填并发线程数
AKSHARE_MAX_RETRIES	3	API 调用重试次数
AKSHARE_RETRY_DELAY	1.0	重试基础延迟（指数退避）
AKSHARE_BACKEND	auto	数据后端: auto, em (East Money), sina
REALTIME_POLL_INTERVAL	5	实时行情轮询间隔（秒）
LOG_LEVEL	INFO	日志级别

部署说明

• 国内服务器: 配置 AKSHARE_BACKEND=em 使用 East Money 后端（数据质量更好）
• 海外服务器: 保持 auto，客户端会自动检测并降级到 Sina 后端
• 分钟线积累: 盘后拉取任务（15:05 北京时间）必须稳定运行，否则分钟线历史会出现缺口
• 存储估算: 约 12 GB / ~3,300 文件（全部历史 + 所有频率），建议 SSD

开发

pip install -e ".[dev]"
pytest
ruff check src/