fin_data_unify_plat/README.md

期货股票数据统一平台

基于 FastAPI + Vue 3 + TimescaleDB 的专业 K 线数据与实时行情服务平台

项目简介

本项目是一个统一的期货、股票数据服务平台，提供：

• 📊 K 线数据查询 - 支持多周期历史 K 线数据
• 📈 实时行情推送 - WebSocket 实时数据推送
• 🔔 价格告警 - 灵活的价格条件告警
• 📱 数据订阅 - 个性化数据订阅管理
• 🔐 用户认证 - JWT 令牌认证 + API Key

技术栈

后端

• 框架: FastAPI 0.109+
• 数据库: TimescaleDB (时序数据) + SQLite (配置数据)
• 缓存: Redis 7.2+
• 认证: JWT (PyJWT)
• 异步: asyncio + uvicorn

前端

• 框架: Vue 3 + Vite
• UI 组件: Element Plus
• 图表: ECharts 5.4+
• 状态管理: Pinia
• 路由: Vue Router 4

部署

• 容器化: Docker + Docker Compose
• 反向代理: Nginx

快速开始

1. 克隆项目

cd 20260330_kline_system

2. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，修改必要配置

3. 一键部署

# 初始化数据库并启动所有服务
chmod +x deploy/init_db.sh
./deploy/init_db.sh

4. 访问系统

• 前端页面: http://localhost
• API 文档: http://localhost:8000/docs
• 健康检查: http://localhost:8000/health

默认管理员账号:

• 用户名：admin
• 密码：admin123 (首次登录请修改)

项目结构

20260330_kline_system/
├── backend/                 # 后端服务
│   ├── app/
│   │   ├── api/v1/         # API 路由
│   │   ├── db/             # 数据库配置
│   │   ├── middleware/     # 中间件
│   │   ├── models/         # 数据模型
│   │   ├── schemas/        # 数据验证
│   │   ├── services/       # 业务服务
│   │   ├── config.py       # 配置文件
│   │   └── main.py         # 应用入口
│   ├── tests/              # 测试代码
│   ├── requirements.txt    # Python 依赖
│   └── Dockerfile
├── frontend/               # 前端服务
│   ├── src/
│   │   ├── api/           # API 封装
│   │   ├── layouts/       # 布局组件
│   │   ├── router/        # 路由配置
│   │   ├── stores/        # 状态管理
│   │   ├── views/         # 页面组件
│   │   ├── App.vue
│   │   └── main.js
│   ├── package.json
│   └── Dockerfile
├── deploy/                 # 部署脚本
│   ├── init_db.sh         # 数据库初始化
│   └── nginx.conf         # Nginx 配置
├── docker-compose.yml      # Docker 编排
└── .env.example           # 环境变量示例

API 接口

认证接口

• POST /api/v1/auth/login - 用户登录
• POST /api/v1/auth/refresh - 刷新令牌
• GET /api/v1/auth/me - 获取当前用户
• POST /api/v1/auth/api-key - 创建 API Key

K 线数据

• GET /api/v1/kline/data - 获取 K 线数据
• GET /api/v1/kline/latest - 获取最新 K 线
• GET /api/v1/kline/symbols - 获取品种列表
• GET /api/v1/kline/periods - 获取周期列表

实时行情

• WS /api/v1/realtime/ws - WebSocket 实时推送
• GET /api/v1/realtime/quote - 获取最新行情

告警管理

• POST /api/v1/alert - 创建告警
• GET /api/v1/alert - 获取告警列表
• DELETE /api/v1/alert/{id} - 删除告警

数据订阅

• POST /api/v1/subscription - 创建订阅
• GET /api/v1/subscription - 获取订阅列表
• DELETE /api/v1/subscription/{id} - 取消订阅

开发指南

后端开发

cd backend

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

# 本地运行
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 运行测试
pytest tests/ -v

前端开发

cd frontend

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建生产版本
npm run build

运维命令

# 查看所有服务状态
docker-compose ps

# 查看服务日志
docker-compose logs -f backend
docker-compose logs -f frontend

# 重启服务
docker-compose restart backend

# 停止所有服务
docker-compose down

# 停止并删除数据卷
docker-compose down -v

系统要求

• Docker 24+
• Docker Compose 2.0+
• 内存：至少 4GB
• 磁盘：至少 10GB

安全建议

1. 修改默认密钥: 生产环境务必修改 SECRET_KEY
2. 修改默认密码: 首次登录后立即修改管理员密码
3. 启用 HTTPS: 生产环境使用 HTTPS 加密传输
4. 限制 API 访问: 配置防火墙规则，限制外部访问
5. 定期备份: 定期备份数据库数据

性能优化

1. 数据库索引: 已为常用查询字段创建索引
2. 数据压缩: TimescaleDB 自动压缩历史数据
3. 缓存策略: Redis 缓存热点数据
4. 限流保护: API 限流防止恶意请求

故障排查

后端无法启动

# 查看后端日志
docker-compose logs backend

# 检查数据库连接
docker exec kline_timescaledb psql -U postgres -d kline_data -c "SELECT 1"

前端无法访问

# 查看前端日志
docker-compose logs frontend

# 检查 Nginx 配置
docker exec kline_nginx nginx -t

数据库连接失败

# 重启数据库
docker-compose restart timescaledb

# 等待数据库就绪
sleep 10

许可证

MIT License

联系方式

如有问题或建议，请提交 Issue 或联系开发团队。

---

版本: v1.0.0
更新日期: 2026-04-02