graph_rag_server/docker

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 启动脚本

快速开始

开发环境

# 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)

生产环境

# 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 缓存

详细使用

构建镜像

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

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

启动服务

# 启动所有服务
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

停止服务

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

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

数据库迁移

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

# 运行迁移
alembic upgrade head

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

运行测试

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

# 运行测试
pytest

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

环境变量配置

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

# 应用配置
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 数据

查看数据卷：

docker volume ls

备份数据卷：

# 备份 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

健康检查

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

# 查看服务健康状态
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. 检查日志：

   docker-compose -f docker/docker-compose.yml logs app
   

2. 检查环境变量：

   docker-compose -f docker/docker-compose.yml exec app env
   

3. 检查数据库连接：

   docker-compose -f docker/docker-compose.yml exec app python -c "from src.config.settings import get_settings; print(get_settings().database.url)"
   

数据库连接失败

1. 确保数据库服务已启动：

   docker-compose -f docker/docker-compose.yml ps postgres
   

2. 测试数据库连接：

   docker exec rag-system-postgres psql -U rag_user -d rag_system -c "SELECT 1"
   

向量数据库连接失败

1. 检查 Infinity 服务状态：

   docker-compose -f docker/docker-compose.yml ps infinity
   

2. 查看 Infinity 日志：

   docker-compose -f docker/docker-compose.yml logs infinity
   

性能优化

生产环境优化

1. 调整 worker 数量： 编辑 Dockerfile，修改 CMD 中的 --workers 参数：

   CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "8"]
   

2. 配置资源限制： 在 docker-compose.yml 中添加：

   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. 扫描镜像漏洞：

   docker scan rag-system:prod
   

更多信息

• Docker 官方文档
• Docker Compose 文档
• 部署指南
• 架构文档