7.2 KiB

Raw Blame History Unescape Escape

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

期货统一数据平台 - 项目文档

版本: 0.1.0
状态: 开发中 (Dev)
维护者: 小马哥

1. 项目概述

本项目是一个期货统一数据平台，旨在解决多数据源接入、数据格式不统一、历史行情查询困难等问题。平台提供标准化的 RESTful API 供外部系统或 AI 调用，并配备管理后台进行数据源配置、合约管理及行情可视化。

核心目标

统一出口：无论底层是 Tushare、CTP 还是其他数据源，对外提供统一的数据格式。
灵活配置：支持多数据源切换、优先级管理。
高效缓存：针对历史 K 线数据（日 K/周 K/分钟级）进行分级存储。
易于扩展：基于适配器模式，新增数据源只需实现标准接口。

2. 技术架构

2.1 技术栈

层次	技术选型	说明
前端	Vue3 + Vite + Element Plus	现代化 SPA，响应式布局
图表	Apache ECharts 5	专业金融 K 线图表渲染
后端	Python 3.11 + FastAPI	高性能异步 Web 框架
数据库	PostgreSQL + TimescaleDB	专为时序数据优化，支持高效压缩与查询
本地开发	SQLite	无需外部依赖，快速验证
缓存/消息	Redis	实时行情缓存与发布订阅
数据源	Tushare / AKShare / CTP (规划)	外部数据接入
部署	Docker Compose	一键环境搭建

2.2 数据源架构

[外部系统/AI] <--> [统一 API 网关] <--> [业务逻辑层] <--> [数据源适配器]
                                             |
                                        [缓存层 (Redis)]
                                             |
                                        [持久层 (PostgreSQL)]

适配器模式：DataSourceBase 定义了 get_kline_daily、get_contract_list 等标准方法。
管理器模式：DataSourceManager 负责加载配置、优先级排序和实例管理。

3. 部署与启动指南

3.1 环境准备

Docker & Docker Compose（生产/测试环境）
Python 3.11+（本地开发环境）
Node.js 20+（前端开发）

3.2 Docker Compose 部署（推荐）

适用于拥有完整基础设施（PostgreSQL, Redis）的环境。

cd share_data/project/futures-data-platform

# 1. 配置环境变量
cp .env.example .env
# 编辑 .env，填入你的 Tushare Token: TUSHARE_TOKEN=xxxxxx

# 2. 启动服务
docker compose up -d --build

# 3. 查看日志
docker compose logs -f backend

服务地址：

管理后台：http://localhost:3000
后端 API：http://localhost:8000
Swagger 文档：http://localhost:8000/docs

3.3 本地开发模式（SQLite）

适用于快速调试，无需启动数据库容器。

cd backend

# 1. 安装依赖
pip install -r requirements.txt

# 2. 使用 SQLite 启动后端
export DATABASE_URL="sqlite:///./futures.db"
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 3. 启动前端 (新终端)
cd frontend
npm install
npm run dev

4. 操作指南

4.1 配置数据源

进入**"数据源监控"**页面。
点击 tushare 或 akshare 行的**"配置"**按钮。
在弹出的配置对话框中：
- 启用状态：使用开关快速启用/禁用该数据源
- 显示名称：自定义数据源在界面上的显示名称
- Token (Tushare)：填入你的 Tushare API Token
- 最大重试次数 (AKShare)：设置反爬重试策略
- 优先级：数字越小优先级越高，系统将优先使用高优先级数据源
点击**"测试连接"**，确认状态为 ok。
点击**"保存"**完成配置。

提示：也可在表格的"启用"列直接点击开关快速切换启用/禁用状态，无需打开配置对话框。

4.2 同步合约信息

进入**"合约管理"**页面。
点击右上角**"同步合约"**按钮。
系统将遍历所有交易所（CFFEX, SHFE, DCE 等）拉取合约信息并入库。
同步完成后，列表将显示所有活跃合约。

4.3 查询与展示 K 线

进入**"K 线查询"**页面。
选择合约（如 rb2401）和周期（如 日 K）。
点击**"同步数据"**（首次查询建议同步，后续直接查询数据库）。
点击**"查询"**，下方将渲染 ECharts K 线图和详细数据表格。

5. 注意事项

5.1 Tushare 积分限制

不同积分等级对数据调用的频率和数据范围有限制。
高频调用分钟级数据或全量历史数据可能需要较高级别的积分（如 2000 分以上）。
建议：在"接口测试"中先测试单个合约的同步，确认返回数据正常后再批量同步。

5.2 AKShare 反爬策略

AKShare 数据源内置了 SmartRequester 反爬管理器，包含以下策略：

随机 User-Agent：每次请求轮换浏览器指纹。
拟人化延时：首次请求随机延迟 0.5~1.5s，重试时指数级增加。
智能重试：遇到 403 或网络错误自动重试（默认 3 次）。
Referer 伪装：自动匹配目标网站的 Referer。

注：IP 代理功能预留接口，当前版本主要依赖频率控制和头部伪装。

5.3 数据一致性

平台默认**"优先读库"**策略。如果数据库中已有缓存数据，直接返回；若无，则调用数据源。
sync_kline 接口采用 upsert 逻辑（插入或更新），支持增量同步，不会破坏已有数据。

5.4 生产环境配置

数据库：务必使用 Docker Compose 中的 PostgreSQL + TimescaleDB，SQLite 仅用于本地开发。
安全性：生产环境应移除 cors.allow_origins=["*"] 的宽泛策略，改为白名单；数据库密码应通过 Secret 管理。

6. 后续规划与改进

Phase 1: 基础完善 (当前阶段)

历史 K 线数据同步与查询（日 K/周 K/分钟）
合约信息管理
Tushare 数据源接入
AKShare 数据源接入 (含反爬策略)
管理后台基础功能

Phase 2: 实时行情与推送

实时行情引擎：开发 CTP 适配器，接入实时 Tick 和 K 线。
WebSocket 订阅：实现实时数据推送服务，支持客户端按合约订阅。
行情快照缓存：利用 Redis 实现最新行情快照的快速读取。

Phase 3: 性能与高可用

TimescaleDB 优化：配置超表（Hypertables）和自动压缩策略。
定时任务调度：使用 APScheduler 实现每日收盘后的自动数据同步。
多数据源回退：主数据源异常时，自动切换到备用数据源。

Phase 4: 高级功能

数据清洗与校验：增加数据质量监控，自动识别异常跳空或缺失数据。
AI 辅助接口：提供专为大模型优化的自然语言转 SQL 接口。

7. 开发规范

代码风格：后端遵循 PEP 8，使用 black 格式化；前端遵循 ESLint + Prettier。
提交规范：
- feat: 新功能
- fix: 修复
- docs: 文档更新
- refactor: 重构

API 响应格式

{
  "code": 0,
  "message": "ok",
  "data": { ... }
}

文档最后更新：2026-05-07

7.2 KiB Raw Blame History Unescape Escape