# Deployment Guide

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

## 目录

- [环境要求](#环境要求)
- [配置管理](#配置管理)
- [本地部署](#本地部署)
- [Docker 部署](#docker-部署)
- [生产环境部署](#生产环境部署)
- [数据库迁移](#数据库迁移)
- [监控和日志](#监控和日志)
- [故障排查](#故障排查)

## 环境要求

### 最低要求

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

### 依赖服务

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

## 配置管理

### 环境变量

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

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

# 编辑配置
nano .env
```

### 必需配置

```bash
# 应用配置
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
```

详细配置选项请参考 [配置指南](configuration.md)。

## 本地部署

### 1. 安装依赖

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

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

### 2. 启动依赖服务

#### 使用 Docker Compose（推荐）

```bash
cd docker
docker-compose up -d postgres infinity
```

#### 手动启动

**PostgreSQL**:
```bash
# Ubuntu/Debian
sudo apt-get install postgresql
sudo systemctl start postgresql

# macOS
brew install postgresql
brew services start postgresql
```

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

### 3. 初始化数据库

```bash
# 创建数据库
createdb rag_system

# 运行迁移
alembic upgrade head
```

### 4. 启动应用

```bash
# 开发模式
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. 验证部署

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

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

## Docker 部署

### 使用 Docker Compose（推荐）

#### 1. 构建镜像

```bash
cd docker
docker-compose build
```

#### 2. 启动所有服务

```bash
docker-compose up -d
```

这将启动：
- RAG 应用（端口 8000）
- PostgreSQL（端口 5432）
- Infinity（端口 23817）
- Redis（端口 6379）

#### 3. 查看日志

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

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

#### 4. 停止服务

```bash
docker-compose down

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

### 使用 Docker（单容器）

#### 1. 构建镜像

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

#### 2. 运行容器

```bash
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. 查看日志

```bash
docker logs -f rag-system
```

## 生产环境部署

### 使用 Kubernetes

#### 1. 创建配置文件

**deployment.yaml**:
```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**:
```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

```bash
# 创建 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 部署

1. **使用 ECS/Fargate**:
   - 推送镜像到 ECR
   - 创建 ECS 任务定义
   - 配置 ALB 负载均衡器
   - 设置 Auto Scaling

2. **数据库**:
   - 使用 RDS for PostgreSQL
   - 使用 OpenSearch（Elasticsearch）

3. **文件存储**:
   - 使用 S3

#### Azure 部署

1. **使用 Azure Container Instances**:
   - 推送镜像到 ACR
   - 创建容器实例
   - 配置 Application Gateway

2. **数据库**:
   - 使用 Azure Database for PostgreSQL
   - 使用 Azure Cognitive Search

#### Google Cloud 部署

1. **使用 Cloud Run**:
   - 推送镜像到 GCR
   - 部署到 Cloud Run
   - 配置 Cloud Load Balancing

2. **数据库**:
   - 使用 Cloud SQL for PostgreSQL
   - 使用 Vertex AI Vector Search

## 数据库迁移

### 使用 Alembic

#### 1. 初始化 Alembic（已完成）

```bash
alembic init alembic
```

#### 2. 创建迁移

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

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

#### 3. 应用迁移

```bash
# 升级到最新版本
alembic upgrade head

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

# 回滚一个版本
alembic downgrade -1

# 查看当前版本
alembic current

# 查看迁移历史
alembic history
```

### 生产环境迁移流程

1. **备份数据库**:
   ```bash
   pg_dump rag_system > backup_$(date +%Y%m%d).sql
   ```

2. **测试迁移**:
   ```bash
   # 在测试环境先运行
   alembic upgrade head
   ```

3. **应用迁移**:
   ```bash
   # 在生产环境运行
   alembic upgrade head
   ```

4. **验证**:
   ```bash
   # 检查应用是否正常
   curl http://localhost:8000/health
   ```

## 监控和日志

### 日志配置

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

```bash
# 配置日志级别
export LOG_LEVEL=INFO

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

### 日志聚合

#### 使用 ELK Stack

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

2. **启动 Filebeat**:
   ```bash
   filebeat -e -c filebeat.yml
   ```

#### 使用云服务

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

### 性能监控

#### 使用 Prometheus

1. **配置指标端点**:
   ```python
   # 已在 /metrics 端点实现
   ```

2. **配置 Prometheus**:
   ```yaml
   scrape_configs:
     - job_name: 'rag-system'
       static_configs:
         - targets: ['localhost:8000']
   ```

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

### 告警配置

#### Prometheus Alertmanager

```yaml
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. 应用无法启动

**检查日志**:
```bash
# Docker
docker logs rag-system

# Kubernetes
kubectl logs <pod-name>

# 本地
tail -f logs/app.log
```

**常见原因**:
- 数据库连接失败
- 配置错误
- 端口被占用

#### 2. 数据库连接失败

**检查连接**:
```bash
# 测试 PostgreSQL 连接
psql -h $DB_HOST -p $DB_PORT -U $DB_USERNAME -d $DB_DATABASE

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

**解决方案**:
- 检查数据库是否运行
- 验证连接参数
- 检查防火墙规则

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

**检查 Infinity**:
```bash
curl http://$INFINITY_HOST:$INFINITY_PORT/health
```

**检查 Elasticsearch**:
```bash
curl http://$ES_HOST:$ES_PORT/_cluster/health
```

#### 4. 性能问题

**检查资源使用**:
```bash
# CPU 和内存
docker stats

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

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

### 调试模式

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

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

# 重启应用
```

### 健康检查

```bash
# 基本健康检查
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. 数据安全

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

## 备份和恢复

### 数据库备份

```bash
# 创建备份
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]

## 扩展和优化

### 水平扩展

1. **应用层**:
   - 增加 worker 数量
   - 部署多个实例
   - 使用负载均衡器

2. **数据库层**:
   - 配置读写分离
   - 使用连接池
   - 实施缓存策略

3. **向量数据库层**:
   - 配置集群
   - 分片策略
   - 副本配置

### 性能优化

1. **应用优化**:
   - 启用异步处理
   - 使用连接池
   - 实施缓存

2. **数据库优化**:
   - 创建索引
   - 优化查询
   - 调整配置参数

3. **网络优化**:
   - 使用 CDN
   - 启用压缩
   - 优化 API 响应

## 支持

如需帮助，请参考：
- [架构文档](architecture.md)
- [配置指南](configuration.md)
- [API 文档](api.md)
- [GitHub Issues](https://github.com/YOUR_USERNAME/YOUR_REPO/issues)