MomentumLab/app/backend/DOCKER_README.md

# A股智投分析平台 - Docker 部署指南

## 📋 概述

本项目提供完整的 Docker 化部署方案，包含：
- **MySQL 8.0** - 带分区表的数据库
- **Redis 7** - 缓存服务
- **后端应用** - Node.js + Express + TypeScript
- **AKShare** - 可选的数据源服务

## 🚀 快速开始

### 方式一：一键启动（推荐）

**Linux/Mac:**
```bash
./docker-start.sh
```

**Windows:**
```bash
docker-start.bat
```

### 方式二：手动启动

```bash
# 1. 进入后端目录
cd app/backend

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

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

## 📁 文件结构

```
app/backend/
├── docker-compose.yml          # Docker 编排配置
├── Dockerfile                  # 后端应用镜像
├── .env.docker                 # Docker 环境变量
├── .dockerignore               # Docker 忽略文件
├── docker-start.sh             # Linux/Mac 启动脚本
├── docker-start.bat            # Windows 启动脚本
├── init-scripts/               # 数据库初始化脚本
│   ├── 01-init-database.sql   # 创建表结构（含分区）
│   └── 02-seed-data.sql       # 种子数据
└── DOCKER_README.md           # 本文档
```

## 🔧 配置说明

### 环境变量 (`.env.docker`)

| 变量名 | 默认值 | 说明 |
|-------|-------|------|
| `DATABASE_URL` | mysql://root:1qazse42W3@mysql:3306/aguzhitou | MySQL 连接 |
| `REDIS_URL` | redis://redis:6379 | Redis 连接 |
| `JWT_SECRET` | aguzhitou-docker... | JWT 密钥 |
| `PORT` | 3000 | 服务端口 |

### 数据库分区设计

| 表名 | 分区字段 | 分区范围 | 分区数 |
|------|---------|---------|-------|
| `stock_quotes_history` | quote_time | 2024-01 ~ 2026-12 | 37 |
| `sector_quotes` | quote_time | 2024-01 ~ 2026-12 | 37 |
| `high_low_stocks` | date | 2024-01 ~ 2026-12 | 37 |
| `momentum_stocks` | date | 2024-01 ~ 2026-12 | 37 |

## 📊 服务访问

启动后可通过以下地址访问：

| 服务 | 地址 | 说明 |
|------|------|------|
| API 接口 | http://localhost:3000/api/v1 | 后端 API |
| 健康检查 | http://localhost:3000/api/v1/health | 服务状态 |
| MySQL | localhost:3306 | 数据库 |
| Redis | localhost:6379 | 缓存 |

### 默认账号

- **MySQL**: root / 1qazse42W3

## 🔍 常用命令

### 查看状态
```bash
# 查看所有容器状态
docker-compose ps

# 查看资源使用
docker-compose top
```

### 查看日志
```bash
# 查看所有服务日志
docker-compose logs

# 查看后端应用日志（实时）
docker-compose logs -f app

# 查看 MySQL 日志
docker-compose logs -f mysql

# 查看 Redis 日志
docker-compose logs -f redis
```

### 服务管理
```bash
# 停止服务
docker-compose stop

# 启动服务
docker-compose start

# 重启服务
docker-compose restart

# 停止并删除容器（保留数据）
docker-compose down

# 完全重置（删除容器和数据卷）
docker-compose down -v
```

### 数据库操作
```bash
# 进入 MySQL 容器
mysql -h localhost -P 3306 -u root -p1qazse42W3

# 备份数据库
docker-compose exec mysql mysqldump -u root -p1qazse42W3 aguzhitou > backup.sql

# 恢复数据库
docker-compose exec -T mysql mysql -u root -p1qazse42W3 aguzhitou < backup.sql
```

## 🗄️ 数据持久化

数据通过 Docker Volumes 持久化：

| 卷名 | 用途 | 位置 |
|------|------|------|
| `mysql_data` | MySQL 数据 | /var/lib/mysql |
| `redis_data` | Redis 数据 | /data |
| `./logs` | 应用日志 | /app/logs |

## 🛠️ 自定义配置

### 修改数据库密码

1. 编辑 `docker-compose.yml`：
```yaml
mysql:
  environment:
    MYSQL_ROOT_PASSWORD: your-new-password
```

2. 编辑 `.env.docker`：
```env
DATABASE_URL=mysql://root:your-new-password@mysql:3306/aguzhitou
```

3. 重启服务：
```bash
docker-compose down -v
docker-compose up --build -d
```

### 修改服务端口

编辑 `docker-compose.yml`：
```yaml
app:
  ports:
    - "8080:3000"  # 改为 8080 端口
```

### 添加 AKShare 数据源

```bash
docker-compose --profile with-akshare up -d
```

## 📈 性能优化

### MySQL 配置

已针对生产环境优化：
- `innodb_buffer_pool_size=512M`
- `max_connections=200`
- 字符集：utf8mb4

### Redis 配置

使用 Alpine 版本，轻量级：
- 数据持久化
- 自动清理策略

## 🔒 安全配置

### 生产环境建议

1. **修改默认密码**
   - MySQL root 密码
   - JWT Secret

2. **使用 HTTPS**
   - 配置 Nginx 反向代理
   - 使用 Let's Encrypt 证书

3. **限制端口访问**
   - 仅开放必要端口
   - 使用防火墙规则

## 🐛 故障排查

### 问题1：数据库连接失败

**现象**：
```
Error: Can't reach database server
```

**解决方案**：
```bash
# 检查 MySQL 容器状态
docker-compose ps mysql

# 查看 MySQL 日志
docker-compose logs mysql

# 手动测试连接
docker-compose exec mysql mysql -u root -p1qazse42W3 -e "SHOW DATABASES;"
```

### 问题2：端口被占用

**现象**：
```
Bind for 0.0.0.0:3306 failed: port is already allocated
```

**解决方案**：
```bash
# 查找占用进程
sudo lsof -i :3306

# 停止占用进程或修改端口
# 编辑 docker-compose.yml 修改端口映射
```

### 问题3：内存不足

**现象**：
```
Error: Out of memory
```

**解决方案**：
```bash
# 查看内存使用
docker stats

# 减少 MySQL 内存占用
# 编辑 docker-compose.yml 调整 innodb_buffer_pool_size
```

## 📝 更新记录

### v1.0.0
- ✨ 初始版本
- ✨ MySQL 8.0 带分区表
- ✨ Redis 7 缓存
- ✨ 自动初始化脚本
- ✨ 健康检查

## 📞 技术支持

如有问题，请检查：
1. Docker 和 Docker Compose 版本
2. 端口占用情况
3. 日志文件中的错误信息
4. 系统资源（内存、磁盘）

## 📄 许可证

MIT License