Deployment Guide

本文档说明如何在不同环境中部署 RAG 系统。

环境要求

最低要求

Python: 3.11 或 3.12
内存: 4GB RAM（推荐 8GB+）
磁盘: 10GB 可用空间
CPU: 2 核心（推荐 4 核心+）

依赖服务

PostgreSQL: 12+ （关系数据库）
Infinity 或 Elasticsearch: 向量数据库
Redis: 可选，用于缓存
MinIO 或 S3: 可选，用于文件存储

配置管理

环境变量

系统通过环境变量进行配置。创建 .env 文件：

# 复制示例配置
cp .env.example .env

# 编辑配置
nano .env

必需配置

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

# 数据库配置
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=rag_system
DB_USERNAME=rag_user
DB_PASSWORD=your_secure_password

# 向量数据库配置
VECTOR_DB_TYPE=infinity  # 或 elasticsearch

# Infinity 配置（如果使用）
INFINITY_HOST=localhost
INFINITY_PORT=23817

# Elasticsearch 配置（如果使用）
ES_HOST=localhost
ES_PORT=9200
ES_USERNAME=elastic
ES_PASSWORD=your_es_password

详细配置选项请参考配置指南。

本地部署

1. 安装依赖

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

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

2. 启动依赖服务

使用 Docker Compose（推荐）

cd docker
docker-compose up -d postgres infinity

手动启动

PostgreSQL:

# Ubuntu/Debian
sudo apt-get install postgresql
sudo systemctl start postgresql

# macOS
brew install postgresql
brew services start postgresql

Infinity:

# 参考 Infinity 官方文档
# https://github.com/infiniflow/infinity

3. 初始化数据库

# 创建数据库
createdb rag_system

# 运行迁移
alembic upgrade head

4. 启动应用

# 开发模式
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

# 生产模式
uvicorn src.main:app --host 0.0.0.0 --port 8000 --workers 4

5. 验证部署

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

# 查看 API 文档
open http://localhost:8000/docs

Docker 部署

使用 Docker Compose（推荐）

1. 构建镜像

cd docker
docker-compose build

2. 启动所有服务

docker-compose up -d

这将启动：

RAG 应用（端口 8000）
PostgreSQL（端口 5432）
Infinity（端口 23817）
Redis（端口 6379）

3. 查看日志

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

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

4. 停止服务

docker-compose down

# 同时删除数据卷
docker-compose down -v

使用 Docker（单容器）

1. 构建镜像

docker build -f docker/Dockerfile -t rag-system:latest .

2. 运行容器

docker run -d \
  --name rag-system \
  -p 8000:8000 \
  -e DB_HOST=host.docker.internal \
  -e DB_PORT=5432 \
  -e DB_DATABASE=rag_system \
  -e DB_USERNAME=rag_user \
  -e DB_PASSWORD=your_password \
  -e INFINITY_HOST=host.docker.internal \
  -e INFINITY_PORT=23817 \
  rag-system:latest

3. 查看日志

docker logs -f rag-system

生产环境部署

使用 Kubernetes

1. 创建配置文件

deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: rag-system
spec:
  replicas: 3
  selector:
    matchLabels:
      app: rag-system
  template:
    metadata:
      labels:
        app: rag-system
    spec:
      containers:
      - name: rag-system
        image: your-registry/rag-system:latest
        ports:
        - containerPort: 8000
        env:
        - name: DB_HOST
          valueFrom:
            secretKeyRef:
              name: rag-secrets
              key: db-host
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: rag-secrets
              key: db-password
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "2Gi"
            cpu: "2000m"
        livenessProbe:
          httpGet:
            path: /health/live
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 5

service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: rag-system
spec:
  selector:
    app: rag-system
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8000
  type: LoadBalancer

2. 部署到 Kubernetes

# 创建 secrets
kubectl create secret generic rag-secrets \
  --from-literal=db-host=postgres.default.svc.cluster.local \
  --from-literal=db-password=your_password

# 部署应用
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

# 查看状态
kubectl get pods
kubectl get services

使用云服务

AWS 部署

使用 ECS/Fargate:
- 推送镜像到 ECR
- 创建 ECS 任务定义
- 配置 ALB 负载均衡器
- 设置 Auto Scaling
数据库:
- 使用 RDS for PostgreSQL
- 使用 OpenSearch（Elasticsearch）
文件存储:
- 使用 S3

Azure 部署

使用 Azure Container Instances:
- 推送镜像到 ACR
- 创建容器实例
- 配置 Application Gateway
数据库:
- 使用 Azure Database for PostgreSQL
- 使用 Azure Cognitive Search

Google Cloud 部署

使用 Cloud Run:
- 推送镜像到 GCR
- 部署到 Cloud Run
- 配置 Cloud Load Balancing
数据库:
- 使用 Cloud SQL for PostgreSQL
- 使用 Vertex AI Vector Search

数据库迁移

使用 Alembic

1. 初始化 Alembic（已完成）

alembic init alembic

2. 创建迁移

# 自动生成迁移
alembic revision --autogenerate -m "描述变更"

# 手动创建迁移
alembic revision -m "描述变更"

3. 应用迁移

# 升级到最新版本
alembic upgrade head

# 升级到特定版本
alembic upgrade <revision>

# 回滚一个版本
alembic downgrade -1

# 查看当前版本
alembic current

# 查看迁移历史
alembic history

生产环境迁移流程

备份数据库:

pg_dump rag_system > backup_$(date +%Y%m%d).sql

测试迁移:

# 在测试环境先运行
alembic upgrade head

应用迁移:

# 在生产环境运行
alembic upgrade head

验证:

# 检查应用是否正常
curl http://localhost:8000/health

监控和日志

日志配置

系统使用结构化日志（JSON 格式）：

# 配置日志级别
export LOG_LEVEL=INFO

# 配置日志输出
export LOG_FILE=/var/log/rag-system/app.log

日志聚合

使用 ELK Stack

配置 Filebeat:

filebeat.inputs:
- type: log
 enabled: true
 paths:
   - /var/log/rag-system/*.log
 json.keys_under_root: true
   
output.elasticsearch:
 hosts: ["elasticsearch:9200"]

启动 Filebeat:
```
filebeat -e -c filebeat.yml
```

使用云服务

AWS: CloudWatch Logs
Azure: Azure Monitor
GCP: Cloud Logging

性能监控

使用 Prometheus

配置指标端点:
```
# 已在 /metrics 端点实现
```

配置 Prometheus:

scrape_configs:
 - job_name: 'rag-system'
   static_configs:
     - targets: ['localhost:8000']

配置 Grafana:
- 导入 FastAPI 仪表板
- 创建自定义仪表板

告警配置

Prometheus Alertmanager

groups:
- name: rag-system
  rules:
  - alert: HighErrorRate
    expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.05
    for: 5m
    annotations:
      summary: "High error rate detected"
  
  - alert: HighResponseTime
    expr: http_request_duration_seconds > 1
    for: 5m
    annotations:
      summary: "High response time detected"

故障排查

常见问题

1. 应用无法启动

检查日志:

# Docker
docker logs rag-system

# Kubernetes
kubectl logs <pod-name>

# 本地
tail -f logs/app.log

常见原因:

数据库连接失败
配置错误
端口被占用

2. 数据库连接失败

检查连接:

# 测试 PostgreSQL 连接
psql -h $DB_HOST -p $DB_PORT -U $DB_USERNAME -d $DB_DATABASE

# 检查网络
ping $DB_HOST
telnet $DB_HOST $DB_PORT

解决方案:

检查数据库是否运行
验证连接参数
检查防火墙规则

3. 向量数据库连接失败

检查 Infinity:

curl http://$INFINITY_HOST:$INFINITY_PORT/health

检查 Elasticsearch:

curl http://$ES_HOST:$ES_PORT/_cluster/health

4. 性能问题

检查资源使用:

# CPU 和内存
docker stats

# 数据库连接
SELECT count(*) FROM pg_stat_activity;

优化建议:

增加 worker 数量
调整数据库连接池大小
启用缓存
优化查询

调试模式

启用调试模式获取更多信息：

# 设置环境变量
export DEBUG=true
export LOG_LEVEL=DEBUG

# 重启应用

健康检查

# 基本健康检查
curl http://localhost:8000/health

# 就绪检查
curl http://localhost:8000/health/ready

# 存活检查
curl http://localhost:8000/health/live

# 性能指标
curl http://localhost:8000/metrics

安全最佳实践

1. 环境变量

不要在代码中硬编码密码
使用密钥管理服务（AWS Secrets Manager、Azure Key Vault）
定期轮换密钥

2. 网络安全

使用 HTTPS（TLS/SSL）
配置防火墙规则
限制数据库访问
使用 VPC/VNet

3. 应用安全

启用 CORS 限制
实施速率限制
使用 API 密钥认证
定期更新依赖

4. 数据安全

加密敏感数据
定期备份
实施访问控制
审计日志

备份和恢复

数据库备份

# 创建备份
pg_dump rag_system > backup.sql

# 恢复备份
psql rag_system < backup.sql

# 自动备份脚本
0 2 * * * pg_dump rag_system > /backups/rag_$(date +\%Y\%m\%d).sql

向量数据库备份

参考各向量数据库的官方文档：

Infinity: [备份文档]
Elasticsearch: [Snapshot API]

扩展和优化

水平扩展

应用层:
- 增加 worker 数量
- 部署多个实例
- 使用负载均衡器
数据库层:
- 配置读写分离
- 使用连接池
- 实施缓存策略
向量数据库层:
- 配置集群
- 分片策略
- 副本配置

性能优化

应用优化:
- 启用异步处理
- 使用连接池
- 实施缓存
数据库优化:
- 创建索引
- 优化查询
- 调整配置参数
网络优化:
- 使用 CDN
- 启用压缩
- 优化 API 响应

支持

如需帮助，请参考：

deployment.md 11 KB Permalink History Raw

Deployment Guide

目录

环境要求

最低要求

依赖服务

配置管理

环境变量

必需配置

本地部署

1. 安装依赖

2. 启动依赖服务

使用 Docker Compose（推荐）

手动启动

3. 初始化数据库

4. 启动应用

5. 验证部署

Docker 部署

使用 Docker Compose（推荐）

1. 构建镜像

2. 启动所有服务

3. 查看日志

4. 停止服务

使用 Docker（单容器）

1. 构建镜像

2. 运行容器

3. 查看日志

生产环境部署

使用 Kubernetes

1. 创建配置文件

2. 部署到 Kubernetes

使用云服务

AWS 部署

Azure 部署

Google Cloud 部署

数据库迁移

使用 Alembic

1. 初始化 Alembic（已完成）

2. 创建迁移

3. 应用迁移

生产环境迁移流程

监控和日志

日志配置

日志聚合

使用 ELK Stack

使用云服务

性能监控

使用 Prometheus

告警配置

Prometheus Alertmanager

故障排查

常见问题

1. 应用无法启动

2. 数据库连接失败

3. 向量数据库连接失败

4. 性能问题

调试模式

健康检查

安全最佳实践

1. 环境变量

2. 网络安全

3. 应用安全

4. 数据安全

备份和恢复

数据库备份

向量数据库备份

扩展和优化

水平扩展

性能优化

支持

deployment.md 11 KB

Permalink History Raw