fin_data_unify_plat/DEPLOYMENT.md

# 期货股票数据统一平台 - 部署指南

## 系统要求

- Docker 20.10+
- Docker Compose 2.0+
- 内存：至少 4GB
- 磁盘：至少 10GB

## 快速部署

### 1. 克隆项目

```bash
cd 20260330_kline_system
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 文件，修改必要配置
# 生产环境务必修改 SECRET_KEY
```

### 3. 初始化数据库并启动服务

```bash
# 赋予执行权限
chmod +x deploy/init_db.sh

# 执行初始化脚本
./deploy/init_db.sh
```

该脚本会：
1. 启动 TimescaleDB 和 Redis 容器
2. 初始化数据库表结构
3. 创建默认管理员账号
4. 启动后端和前端服务

### 4. 验证部署

```bash
# 检查容器状态
docker-compose ps

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

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

### 5. 访问系统

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

**默认管理员账号**:
- 用户名：`admin`
- 密码：`admin123`

⚠️ **首次登录后请立即修改密码！**

## 服务说明

### 容器列表

| 服务名 | 端口 | 说明 |
|--------|------|------|
| timescaledb | 5432 | TimescaleDB 时序数据库 |
| redis | 6379 | Redis 缓存 |
| backend | 8000 | FastAPI 后端服务 |
| frontend | 80 | Nginx 前端服务 |

### 数据持久化

数据通过 Docker volumes 持久化：

- `timescaledb_data`: TimescaleDB 数据
- `redis_data`: Redis 数据
- `backend_data`: 后端 SQLite 配置数据

## 开发环境部署

### 后端开发

```bash
cd backend

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

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

# 运行开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 前端开发

```bash
cd frontend

# 安装依赖
npm install

# 运行开发服务器
npm run dev
```

## 生产环境部署

### 1. 修改配置

编辑 `.env` 文件：

```bash
# 生产环境配置
DEBUG=false
SECRET_KEY=<生成一个强随机密钥>
LOG_LEVEL=WARNING

# 数据库配置（如使用外部数据库）
TIMESCALE_DB_URL=postgresql://user:password@db-host:5432/kline_data
```

### 2. 生成安全密钥

```bash
# 使用 Python 生成
python -c "import secrets; print(secrets.token_urlsafe(32))"

# 或使用 OpenSSL
openssl rand -hex 32
```

### 3. 启动服务

```bash
# 生产环境启动（后台运行）
docker-compose up -d

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

### 4. 配置 Nginx（可选）

如果使用外部 Nginx 反向代理：

```nginx
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location /api/ {
        proxy_pass http://localhost:8000/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

## 常用命令

### 查看服务状态

```bash
docker-compose ps
```

### 重启服务

```bash
docker-compose restart
```

### 停止服务

```bash
docker-compose down
```

### 停止并删除数据

```bash
# ⚠️ 警告：这将删除所有数据！
docker-compose down -v
```

### 查看日志

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

# 查看特定服务日志
docker-compose logs backend

# 实时查看日志
docker-compose logs -f backend
```

### 进入容器

```bash
# 进入后端容器
docker-compose exec backend bash

# 进入数据库容器
docker-compose exec timescaledb psql -U postgres -d kline_data
```

### 备份数据

```bash
# 备份 TimescaleDB
docker-compose exec timescaledb pg_dump -U postgres kline_data > backup.sql

# 备份 SQLite
docker cp kline_backend:/app/data/config.db ./config.db.backup
```

### 恢复数据

```bash
# 恢复 TimescaleDB
cat backup.sql | docker-compose exec -T timescaledb psql -U postgres -d kline_data
```

## 监控与维护

### 健康检查

```bash
# 检查后端健康
curl http://localhost:8000/health

# 检查数据库连接
docker-compose exec timescaledb pg_isready -U postgres
```

### 数据库维护

```bash
# 查看数据库大小
docker-compose exec timescaledb psql -U postgres -d kline_data -c "SELECT pg_size_pretty(pg_database_size('kline_data'));"

# 清理旧数据（示例：删除 30 天前的数据）
docker-compose exec timescaledb psql -U postgres -d kline_data -c "DELETE FROM kline_data WHERE time < NOW() - INTERVAL '30 days';"
```

### 日志轮转

配置 Docker 日志轮转（在 docker-compose.yml 中添加）：

```yaml
services:
  backend:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
```

## 故障排查

### 后端无法启动

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

# 检查数据库连接
docker-compose exec backend python -c "from app.db.init_db import timescale_engine; print(timescale_engine.connect())"
```

### 前端无法访问

```bash
# 检查前端容器状态
docker-compose ps frontend

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

# 检查 Nginx 配置
docker-compose exec frontend nginx -t
```

### 数据库连接失败

```bash
# 检查数据库容器
docker-compose ps timescaledb

# 测试数据库连接
docker-compose exec timescaledb pg_isready -U postgres
```

### WebSocket 连接失败

1. 检查 Nginx 配置中的 WebSocket 支持
2. 确保防火墙允许 WebSocket 连接
3. 查看浏览器控制台错误信息

## 安全建议

1. **修改默认密码**：首次登录后立即修改 admin 密码
2. **使用 HTTPS**：生产环境配置 SSL 证书
3. **限制访问**：配置防火墙只允许必要端口
4. **定期更新**：及时更新 Docker 镜像和依赖
5. **备份数据**：定期备份数据库
6. **监控日志**：设置日志监控和告警

## 技术支持

如有问题，请查看：
- 项目 README.md
- 后端 API 文档：http://localhost:8000/docs
- 开发日志：DEVELOPMENT_LOG.md