# Docker 部署指南

本目录包含 RAG 系统的 Docker 配置文件。

## 文件说明

- `Dockerfile`: 多阶段构建的 Docker 镜像定义
  - `base`: 基础镜像，包含系统依赖和 Python 包
  - `development`: 开发环境镜像，包含开发工具和热重载
  - `production`: 生产环境镜像，优化的多 worker 配置
- `docker-compose.yml`: 生产环境的 Docker Compose 配置
- `docker-compose.dev.yml`: 开发环境的 Docker Compose 配置
- `start.sh`: Linux/macOS 启动脚本
- `start.bat`: Windows 启动脚本

## 快速开始

### 开发环境

```bash
# Linux/macOS
./docker/start.sh dev

# Windows
docker\start.bat dev

# 或直接使用 docker-compose
docker-compose -f docker/docker-compose.dev.yml up -d
```

开发环境包含：
- RAG 应用（带热重载）
- PostgreSQL 数据库
- Infinity 向量数据库
- Redis 缓存
- pgAdmin 数据库管理工具

访问地址：
- API 文档: http://localhost:8000/docs
- pgAdmin: http://localhost:5050 (admin@example.com / admin)

### 生产环境

```bash
# Linux/macOS
./docker/start.sh prod

# Windows
docker\start.bat prod

# 或直接使用 docker-compose
docker-compose -f docker/docker-compose.yml up -d
```

生产环境包含：
- RAG 应用（多 worker）
- PostgreSQL 数据库
- Infinity 向量数据库
- Redis 缓存

## 详细使用

### 构建镜像

```bash
# 构建开发环境镜像
docker build -f docker/Dockerfile --target development -t rag-system:dev .

# 构建生产环境镜像
docker build -f docker/Dockerfile --target production -t rag-system:prod .
```

### 启动服务

```bash
# 启动所有服务
docker-compose -f docker/docker-compose.yml up -d

# 启动特定服务
docker-compose -f docker/docker-compose.yml up -d app postgres

# 查看日志
docker-compose -f docker/docker-compose.yml logs -f

# 查看特定服务日志
docker-compose -f docker/docker-compose.yml logs -f app
```

### 停止服务

```bash
# 停止所有服务
docker-compose -f docker/docker-compose.yml down

# 停止并删除数据卷
docker-compose -f docker/docker-compose.yml down -v
```

### 数据库迁移

```bash
# 进入应用容器
docker exec -it rag-system-app bash

# 运行迁移
alembic upgrade head

# 或者从宿主机运行
docker-compose -f docker/docker-compose.yml exec app alembic upgrade head
```

### 运行测试

```bash
# 进入开发环境容器
docker exec -it rag-system-app-dev bash

# 运行测试
pytest

# 运行带覆盖率的测试
pytest --cov=src --cov-report=html
```

## 环境变量配置

在项目根目录创建 `.env` 文件：

```bash
# 应用配置
APP_NAME=RAG System
DEBUG=false
LOG_LEVEL=INFO

# 数据库配置（Docker 环境）
DB_HOST=postgres
DB_PORT=5432
DB_DATABASE=rag_system
DB_USERNAME=rag_user
DB_PASSWORD=rag_password

# 向量数据库配置
VECTOR_DB_TYPE=infinity
INFINITY_HOST=infinity
INFINITY_PORT=23817

# Redis 配置
REDIS_HOST=redis
REDIS_PORT=6379
```

## 服务端口

| 服务 | 端口 | 说明 |
|-----|------|------|
| RAG 应用 | 8000 | API 服务 |
| PostgreSQL | 5432 | 关系数据库 |
| Infinity | 23817 | 向量数据库 |
| Redis | 6379 | 缓存服务 |
| pgAdmin | 5050 | 数据库管理（仅开发环境） |

## 数据持久化

Docker Compose 使用命名卷来持久化数据：

- `postgres-data`: PostgreSQL 数据
- `infinity-data`: Infinity 向量数据
- `redis-data`: Redis 数据

查看数据卷：
```bash
docker volume ls
```

备份数据卷：
```bash
# 备份 PostgreSQL
docker exec rag-system-postgres pg_dump -U rag_user rag_system > backup.sql

# 恢复 PostgreSQL
docker exec -i rag-system-postgres psql -U rag_user rag_system < backup.sql
```

## 健康检查

所有服务都配置了健康检查：

```bash
# 查看服务健康状态
docker-compose -f docker/docker-compose.yml ps

# 检查应用健康
curl http://localhost:8000/health

# 检查数据库健康
docker exec rag-system-postgres pg_isready -U rag_user

# 检查 Redis 健康
docker exec rag-system-redis redis-cli ping
```

## 故障排查

### 应用无法启动

1. 检查日志：
   ```bash
   docker-compose -f docker/docker-compose.yml logs app
   ```

2. 检查环境变量：
   ```bash
   docker-compose -f docker/docker-compose.yml exec app env
   ```

3. 检查数据库连接：
   ```bash
   docker-compose -f docker/docker-compose.yml exec app python -c "from src.config.settings import get_settings; print(get_settings().database.url)"
   ```

### 数据库连接失败

1. 确保数据库服务已启动：
   ```bash
   docker-compose -f docker/docker-compose.yml ps postgres
   ```

2. 测试数据库连接：
   ```bash
   docker exec rag-system-postgres psql -U rag_user -d rag_system -c "SELECT 1"
   ```

### 向量数据库连接失败

1. 检查 Infinity 服务状态：
   ```bash
   docker-compose -f docker/docker-compose.yml ps infinity
   ```

2. 查看 Infinity 日志：
   ```bash
   docker-compose -f docker/docker-compose.yml logs infinity
   ```

## 性能优化

### 生产环境优化

1. **调整 worker 数量**：
   编辑 `Dockerfile`，修改 CMD 中的 `--workers` 参数：
   ```dockerfile
   CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "8"]
   ```

2. **配置资源限制**：
   在 `docker-compose.yml` 中添加：
   ```yaml
   services:
     app:
       deploy:
         resources:
           limits:
             cpus: '2'
             memory: 4G
           reservations:
             cpus: '1'
             memory: 2G
   ```

3. **使用生产级数据库**：
   - 使用外部 PostgreSQL 服务（如 AWS RDS）
   - 配置数据库连接池
   - 启用数据库复制

### 开发环境优化

1. **减少构建时间**：
   - 使用 `.dockerignore` 排除不必要的文件
   - 利用 Docker 层缓存

2. **加快热重载**：
   - 只挂载必要的目录
   - 使用 `watchfiles` 替代默认的文件监控

## 安全建议

1. **不要在生产环境使用默认密码**
2. **使用 secrets 管理敏感信息**
3. **限制容器权限**
4. **定期更新基础镜像**
5. **扫描镜像漏洞**：
   ```bash
   docker scan rag-system:prod
   ```

## 更多信息

- [Docker 官方文档](https://docs.docker.com/)
- [Docker Compose 文档](https://docs.docker.com/compose/)
- [部署指南](../docs/deployment.md)
- [架构文档](../docs/architecture.md)