MomentumLab/docs/PYTHON_DATA_SERVICE_DOCKER.md

# Python 数据服务 Docker 化部署指南

## 概述

本指南介绍如何将 Python AKShare 数据服务 Docker 化部署，并连接 Docker 中的 MySQL 数据库。

## 架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                        Docker Network                            │
│                                                                  │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐          │
│  │   MySQL     │◄───┤  AKShare    │    │   Node.js   │          │
│  │  :3306      │    │  :8000      │◄───┤   :3000     │          │
│  │             │    │             │    │             │          │
│  │ aguzhitou   │    │ 数据获取    │    │  API服务    │          │
│  │             │    │ 数据存储    │    │             │          │
│  └─────────────┘    └─────────────┘    └─────────────┘          │
│         ▲                  │                   │                 │
│         │                  │                   │                 │
│  ┌─────────────┐           │                   │                 │
│  │   Redis     │◄──────────┴───────────────────┘                 │
│  │  :6379      │                                                  │
│  └─────────────┘                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## 数据表说明

Python 数据服务需要以下数据表：

### 1. 市场指数表 (market_indices)
```sql
- id: 主键
- name: 指数名称（如上证指数）
- code: 指数代码（如000001）
- current: 当前点位
- change: 涨跌额
- change_percent: 涨跌幅
- volume: 成交量
- turnover: 成交额
```

### 2. 板块信息表 (sectors)
```sql
- id: UUID主键
- name: 板块名称
- code: 板块代码
```

### 3. 板块行情表 (sector_quotes)
```sql
- id: 主键
- sector_code: 板块代码
- current/change/change_percent: 行情数据
- momentum_score: 动量分数
- rank/previous_rank: 排名信息
- quote_time: 行情时间
```

### 4. 板块K线数据表 (sector_klines)
```sql
- id: 主键
- sector_code: 板块代码
- period: 周期(day/week/month)
- date: 日期
- open/high/low/close/volume: K线数据
```

### 5. 股票信息表 (stocks) ⭐核心表
```sql
- id: UUID主键
- code: 股票代码（如000001）
- name: 股票名称
- sector_code: 所属板块
- market_cap: 市值
- pe/pb: 市盈率/市净率
```

### 6. 股票行情表 (stock_quotes) ⭐高频写入
```sql
- id: 主键
- stock_code: 股票代码
- price/open/high/low/pre_close: 价格数据
- volume/turnover: 成交数据
- change_percent: 涨跌幅
- turnover_rate/amplitude: 换手率/振幅
- quote_time: 行情时间
```

### 7. 股票K线数据表 (stock_klines) ⭐核心表
```sql
- id: 主键
- stock_code: 股票代码
- period: 周期
- date: 日期
- open/high/low/close/volume: K线数据
- ma5/ma10/ma20/ma30/ma60: 移动平均线
```

### 8. 新高新低记录表 (high_low_stocks)
```sql
- id: 主键
- stock_code: 股票代码
- type: high(新高) / low(新低)
- price: 触发价格
- date: 日期
- days_to_highlow: 距离前高/低天数
```

### 9. 动量股票推荐表 (momentum_stocks)
```sql
- id: 主键
- stock_code: 股票代码
- momentum_score: 动量分数(0-100)
- tags: 标签JSON（如["强势突破","量价齐升"]）
- volume_ratio: 量比
- break_through: 是否突破
- date: 日期
```

## 快速启动

### 方式一：完整 Docker 部署（推荐）

```bash
cd app/backend

# 启动所有服务（MySQL + Redis + AKShare + Node.js后端）
docker-compose up -d

# 查看日志
docker-compose logs -f akshare
```

### 方式二：仅数据库 + Python 服务

```bash
cd app/backend

# 使用简化配置
docker-compose up -d mysql redis akshare

# 后端在宿主机运行（开发模式）
cd ../backend
npm install
npx prisma db push
npm run dev
```

## 服务地址

启动后各服务地址：

| 服务 | 容器内地址 | 宿主机访问地址 |
|------|-----------|--------------|
| MySQL | mysql:3306 | localhost:3306 |
| Redis | redis:6379 | localhost:6379 |
| AKShare | akshare:8000 | localhost:8000 |
| Node.js后端 | app:3000 | localhost:3000 |

## Python 服务接口

### 原始数据接口（从AKShare实时获取）

```
GET /stock_zh_a_spot          # A股实时行情
GET /stock_zh_a_hist          # A股历史K线
GET /stock_zh_index_spot      # 指数行情
GET /stock_sector_spot        # 板块行情
```

### 数据库查询接口（从MySQL查询）

```
GET /db/stocks                # 获取股票列表
GET /db/klines/{symbol}       # 获取K线数据
```

### 数据同步接口

```
POST /sync/stocks             # 同步股票列表
POST /sync/quotes             # 同步实时行情
POST /sync/klines             # 同步K线数据
POST /sync/all                # 执行全量同步
POST /sync/daily              # 执行每日增量同步
GET  /sync/status             # 获取同步状态
```

## 数据同步流程

### 首次部署 - 全量同步

```bash
# 1. 初始化数据库表
docker exec aguzhitou-akshare python -c "from database import init_db; init_db()"

# 2. 执行全量同步（快速模式，只同步少量数据测试）
curl -X POST http://localhost:8000/sync/all?quick=true

# 3. 查看同步状态
curl http://localhost:8000/sync/status
```

### 定时同步 - 增量更新

设置定时任务（crontab）：

```bash
# 编辑 crontab
crontab -e

# 添加定时任务（每5分钟同步一次实时行情）
*/5 * * * 1-5 curl -X POST http://localhost:8000/sync/quotes > /dev/null 2>&1

# 每晚8点执行每日同步
0 20 * * 1-5 curl -X POST http://localhost:8000/sync/daily > /dev/null 2>&1
```

## 环境变量配置

Python 服务支持以下环境变量：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| DB_HOST | MySQL主机 | mysql |
| DB_PORT | MySQL端口 | 3306 |
| DB_NAME | 数据库名 | aguzhitou |
| DB_USER | 用户名 | root |
| DB_PASSWORD | 密码 | 1qazse42W3 |

## 数据量预估

| 表名 | 预估数据量 | 存储空间 |
|------|-----------|---------|
| stocks | ~5000条 | ~1MB |
| stock_quotes | ~5000条/天 | ~500MB/年 |
| stock_klines | ~120万条/年 | ~2GB/年 |
| sector_klines | ~3万条/年 | ~50MB/年 |
| high_low_stocks | ~1万条/年 | ~10MB/年 |
| momentum_stocks | ~5000条/年 | ~5MB/年 |

## 常见问题

### 1. 数据库连接失败

```bash
# 检查MySQL是否运行
docker-compose ps mysql

# 查看MySQL日志
docker-compose logs mysql

# 测试连接
docker exec aguzhitou-akshare python -c "from database import check_connection; print(check_connection())"
```

### 2. 表不存在

如果使用 Prisma，执行：
```bash
cd app/backend
npx prisma db push
```

如果使用 SQL 脚本，执行：
```bash
docker exec -i aguzhitou-mysql mysql -uroot -p1qazse42W3 aguzhitou < app/backend/init-scripts/01-init-database.sql
```

### 3. 数据同步太慢

```bash
# 只同步部分股票（max_stocks参数）
curl -X POST "http://localhost:8000/sync/klines?max_stocks=100"

# 减少同步天数
curl -X POST "http://localhost:8000/sync/klines?days=30"
```

### 4. 清理旧数据

```sql
-- 清理3个月前的行情数据
DELETE FROM stock_quotes WHERE quote_time < DATE_SUB(NOW(), INTERVAL 3 MONTH);

-- 优化表空间
OPTIMIZE TABLE stock_quotes;
```

## 开发调试

### 进入 Python 容器

```bash
docker exec -it aguzhitou-akshare bash

# 测试数据同步
python -c "from data_sync import sync_all_stocks; sync_all_stocks()"
```

### 查看实时日志

```bash
docker-compose logs -f akshare --tail 100
```

### 重启服务

```bash
docker-compose restart akshare
```