# RAG 服务架构与部署方案

## 一、系统架构概览

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              前端应用                                        │
│                         (Vue/React Web/App)                                 │
└─────────────────────────────────────┬───────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              后端网关                                        │
│                    (Nginx / API Gateway / Spring Cloud)                     │
│                                                                             │
│  职责：                                                                      │
│  • 用户认证 (登录/Token验证)                                                 │
│  • 权限控制 (角色/部门/接口权限)                                              │
│  • Header 注入 (X-User-ID, X-User-Role, X-User-Department)                  │
│  • 请求路由与负载均衡                                                        │
└─────────────────────────────────────┬───────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    │                                   │
                    ▼                                   ▼
┌───────────────────────────────┐   ┌───────────────────────────────────────┐
│        后端业务服务            │   │            RAG 服务                    │
│    (Java/Spring Boot/Go)      │   │        (Python/Flask)                 │
│                               │   │                                       │
│  职责：                        │   │  职责：                                │
│  • 用户账户管理                 │   │  • 向量存储 (ChromaDB)                │
│  • 组织架构/角色权限            │   │  • BM25 索引                          │
│  • 会话管理 (对话历史)          │   │  • 文档解析与分块                      │
│  • 审计日志                    │   │  • 知识库问答 (RAG)                    │
│  • 反馈记录                    │   │  • 文档同步与向量化                    │
│  • 业务主数据 (学生/课程等)     │   │  • 出题能力                            │
│  • 题库/试卷管理               │   │                                       │
│                               │   │                                       │
│  数据库：                      │   │  数据存储：                            │
│  • MySQL/PostgreSQL           │   │  • ChromaDB (向量库)                   │
│                               │   │  • 文件系统 (documents/)               │
│                               │   │  • SQLite (同步状态哈希)               │
└───────────────────────────────┘   └───────────────────────────────────────┘
```

---

## 二、职责分工详解

### 2.1 RAG 组（本项目）负责

| 模块 | 功能 | 数据存储 |
|------|------|----------|
| **向量存储** | ChromaDB 向量库管理 | `vector_store/chroma/` |
| **BM25 索引** | 关键词检索 | 内存/文件 |
| **文档解析** | PDF/Word/Excel 解析与分块 | 临时处理 |
| **知识库问答** | Agentic RAG 问答引擎 | - |
| **文档同步** | 文件变更检测与向量化 | SQLite (哈希记录) |
| **出题能力** | 基于知识库生成题目 | 无状态 |

### 2.2 后端组负责

| 模块 | 功能 | 数据存储 |
|------|------|----------|
| **用户认证** | 登录/注册/Token 管理 | MySQL/PostgreSQL |
| **权限控制** | 角色/部门/接口权限 | MySQL/PostgreSQL |
| **会话管理** | 对话历史记录 | MySQL/PostgreSQL |
| **审计日志** | 操作日志记录 | MySQL/PostgreSQL |
| **反馈系统** | 用户反馈收集 | MySQL/PostgreSQL |
| **业务主数据** | 学生/课程/组织架构 | MySQL/PostgreSQL |
| **题库管理** | 题目存储/试卷管理 | MySQL/PostgreSQL |
| **网关路由** | 请求路由/Header 注入 | - |

### 2.3 数据归属对照表

| 数据类型 | 存储位置 | 管理方 | 说明 |
|----------|----------|--------|------|
| 向量数据 | ChromaDB | RAG 组 | 文档 embedding（每个知识库独立实例） |
| 文档哈希 | SQLite (knowledge.db) | RAG 组 | 同步状态检测 |
| 原始文档 | 文件系统 | RAG 组 | documents/ 目录 |
| 反馈记录 | SQLite (feedback.db) | RAG 组 | 用户反馈、黑名单 |
| 会话数据 | SQLite (session.db) | RAG 组 | 会话管理 |
| 出题数据 | SQLite (exam.db) | RAG 组 | 题目/批阅 |
| 用户账户 | MySQL/PG | 后端组 | 账号密码信息 |
| 审计日志 | MySQL/PG | 后端组 | 操作日志 |
| 题库数据 | MySQL/PG | 后端组 | 题目/试卷 |

---

## 三、接口协作规范

### 3.1 后端调用 RAG 服务

后端通过 HTTP 调用 RAG API，需注入 Header：

```
X-User-ID: 用户唯一标识
X-User-Name: 用户名（可选）
X-User-Role: 用户角色（可选）
X-User-Department: 部门（可选）
```

### 3.2 RAG 服务提供的接口

#### 问答接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `/chat` | POST | 普通聊天 |
| `/rag` | POST | 知识库问答 |
| `/search` | POST | 混合检索 |

#### 向量库管理
| 接口 | 方法 | 说明 |
|------|------|------|
| `/collections` | GET | 向量库列表 |
| `/collections` | POST | 创建向量库 |
| `/collections/<name>` | PUT | 修改向量库 |
| `/collections/<name>` | DELETE | 删除向量库 |

#### 文档管理
| 接口 | 方法 | 说明 |
|------|------|------|
| `/documents/upload` | POST | 上传文件 |
| `/documents/batch-upload` | POST | 批量上传 |
| `/documents/list` | GET | 文档列表 |
| `/documents/<path>` | DELETE | 删除文档 |
| `/documents/<path>/status` | GET | 处理状态 |

#### 切片管理
| 接口 | 方法 | 说明 |
|------|------|------|
| `/documents/<path>/chunks` | GET | 查看切片 |
| `/chunks` | POST | 新增切片 |
| `/chunks/<id>` | PUT | 修改切片 |
| `/chunks/<id>` | DELETE | 删除切片 |

#### 同步服务
| 接口 | 方法 | 说明 |
|------|------|------|
| `/sync` | POST | 触发同步 |
| `/sync/status` | GET | 同步状态 |

#### 出题接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `/exam/generate` | POST | 生成题目 |
| `/exam/grade` | POST | 批改答案 |

### 3.3 后端需要提供的接口

RAG 服务可能需要调用后端获取用户信息：

```
GET /api/users/{user_id}

响应:
{
  "user_id": "xxx",
  "username": "用户名",
  "name": "真实姓名",
  "role": "admin/manager/user",
  "department": "部门名称"
}
```

---

## 四、合并前准备工作

### 4.1 RAG 组需完成

- [x] 权限控制简化（依赖后端网关）
- [x] 移除会话管理依赖
- [x] 移除审计日志依赖
- [x] 更新 API 文档
- [ ] 清理测试数据和临时文件
- [ ] 整理依赖列表 (requirements.txt)
- [ ] 准备环境变量配置模板 (`deploy/.env.production`)
- [ ] 编写 Dockerfile.prod 和 docker-compose.prod.yml

### 4.2 后端组需完成

- [ ] 设计数据库表结构
- [ ] 实现用户认证接口
- [ ] 实现会话管理接口
- [ ] 实现审计日志接口
- [ ] 配置网关路由和 Header 注入
- [ ] 提供 RAG 服务调用的接口

### 4.3 双方需确认

- [ ] 接口协议和字段格式
- [ ] 错误码规范
- [ ] 部署环境和网络配置
- [ ] 文件存储方案（本地/NFS/OSS）

---

## 五、Linux 部署方案（Docker）

### 5.1 服务器规格

| 项目 | 配置 |
|------|------|
| 操作系统 | Ubuntu 22.04 LTS |
| CPU | 4 vCPU |
| 内存 | 8 GB |
| 部署路径 | `/opt/rag-agent` |
| 容器运行时 | Docker + Docker Compose |

### 5.2 部署架构

```
┌─────────────────────────────────────────────────────────────────┐
│                       Linux 服务器 (Ubuntu 22.04)                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Docker (rag-service 容器)                    │   │
│  │                                                          │   │
│  │  ┌──────────────────────────────────────────────────┐    │   │
│  │  │  Gunicorn (gthread worker)                       │    │   │
│  │  │  └── Flask App :5001                             │    │   │
│  │  └──────────────────────────────────────────────────┘    │   │
│  │                                                          │   │
│  │  数据卷挂载：                                             │   │
│  │  • vector_store/   → 向量库持久化                        │   │
│  │  • documents/      → 原始文档                            │   │
│  │  • models/         → 本地模型文件                        │   │
│  │  • .data/          → 运行时缓存                          │   │
│  │  • data/           → SQLite 同步状态                     │   │
│  └──────────────────────────────────────────────────────────┘   │
│         ▲                                                       │
│         │ :5001                                                 │
│  ┌──────┴──────┐                                                │
│  │  后端网关    │  (Nginx / Spring Cloud Gateway)               │
│  │  :80/443    │                                                │
│  └─────────────┘                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 5.3 项目目录结构

```
/opt/rag-agent/
├── deploy/
│   ├── Dockerfile.prod          # 生产镜像定义
│   ├── docker-compose.prod.yml  # 编排文件
│   └── .env.production          # 生产环境变量
├── app/                         # 应用源码
├── vector_store/                # ChromaDB 向量库（持久化）
├── documents/                   # 原始文档（持久化）
├── models/                      # 本地模型文件（持久化）
├── .data/                       # 运行时缓存
└── data/                        # SQLite 同步状态
```

### 5.4 Dockerfile.prod

```dockerfile
# deploy/Dockerfile.prod
FROM python:3.10-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# 安装 CPU-only PyTorch（减小镜像体积）
RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu

# 安装 Python 依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

EXPOSE 5001

# 使用 Gunicorn gthread 模式启动
CMD ["gunicorn", \
     "--bind", "0.0.0.0:5001", \
     "--workers", "2", \
     "--threads", "4", \
     "--worker-class", "gthread", \
     "--timeout", "300", \
     "main:app"]
```

### 5.5 docker-compose.prod.yml

```yaml
# deploy/docker-compose.prod.yml
version: "3.8"

services:
  rag-service:
    build:
      context: ..
      dockerfile: deploy/Dockerfile.prod
    container_name: rag-service
    ports:
      - "5001:5001"
    env_file:
      - .env.production
    volumes:
      - ../vector_store:/app/vector_store
      - ../documents:/app/documents
      - ../models:/app/models
      - ../.data:/app/.data
      - ../data:/app/data
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 6G
```

### 5.6 环境变量配置

所有环境变量通过 `deploy/.env.production` 文件注入，不在代码中硬编码：

```bash
# deploy/.env.production

# 运行模式
DEV_MODE=false

# 路径配置
DOCUMENTS_PATH=/app/documents
VECTOR_STORE_PATH=/app/vector_store

# API 密钥
DASHSCOPE_API_KEY=your_api_key_here

# 其他配置项按需添加...
```

### 5.7 首次部署

```bash
# 1. 在服务器上创建部署目录
sudo mkdir -p /opt/rag-agent
sudo chown $USER:$USER /opt/rag-agent

# 2. 上传项目代码到 /opt/rag-agent
scp -r ./rag-agent/* server:/opt/rag-agent/

# 3. 配置环境变量
cd /opt/rag-agent/deploy
cp .env.production.example .env.production
vim .env.production   # 填入实际的 API Key 等配置

# 4. 构建并启动容器
docker compose -f docker-compose.prod.yml up -d --build

# 5. 验证服务状态
docker ps
docker logs rag-service
curl -f http://localhost:5001/health
```

### 5.8 热更新流程

#### 小改动（配置文件、Prompt 模板等）

```bash
# 直接复制文件进容器并重启
docker cp ./app/config.py rag-service:/app/config.py
docker restart rag-service
```

#### 大改动（代码逻辑、依赖变更等）

```bash
# 重新构建镜像并启动（数据卷不受影响）
cd /opt/rag-agent/deploy
docker compose -f docker-compose.prod.yml up -d --build
```

### 5.9 网关 Header 注入示例

后端网关在转发请求到 RAG 服务时注入 Header：

```java
// Spring Cloud Gateway 示例
@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("rag-service", r -> r.path("/rag-api/**")
            .filters(f -> f
                .stripPrefix(1)
                .addRequestHeader("X-User-ID", "#{request.getAttribute('userId')}")
                .addRequestHeader("X-User-Role", "#{request.getAttribute('userRole')}")
                .addRequestHeader("X-User-Department", "#{request.getAttribute('userDept')}")
            )
            .uri("http://127.0.0.1:5001"))
        .build();
}
```

---

## 六、联调测试清单

### 6.1 后端接口测试

- [ ] 用户认证接口可用
- [ ] 网关正确注入 Header
- [ ] 会话管理接口可用

### 6.2 RAG 接口测试

```bash
# 测试 RAG 服务（带 Header）
curl -X POST http://localhost:5001/rag \
  -H "Content-Type: application/json" \
  -H "X-User-ID: test-user" \
  -H "X-User-Role: admin" \
  -d '{"message": "测试问题"}'

# 测试向量库列表
curl -X GET http://localhost:5001/collections \
  -H "X-User-ID: test-user"

# 测试文件上传
curl -X POST http://localhost:5001/documents/upload \
  -H "X-User-ID: test-user" \
  -F "file=@test.pdf" \
  -F "collection=public_kb"
```

### 6.3 端到端测试

- [ ] 前端 → 后端 → RAG 请求链路通
- [ ] 用户认证正确传递
- [ ] 权限控制生效
- [ ] 文件上传下载正常
- [ ] 问答功能正常

---

## 七、运维监控

### 7.1 日志管理

```bash
# 查看容器实时日志
docker logs -f rag-service

# 查看最近 100 行日志
docker logs --tail 100 rag-service

# 导出日志到文件
docker logs rag-service > /var/log/rag-service.log 2>&1
```

### 7.2 健康检查

```bash
# 手动检查
curl -f http://localhost:5001/health || echo "RAG service down"

# 可通过 docker-compose 配置自动健康检查（添加到 docker-compose.prod.yml）
# healthcheck:
#   test: ["CMD", "curl", "-f", "http://localhost:5001/health"]
#   interval: 30s
#   timeout: 10s
#   retries: 3
```

### 7.3 备份策略

```bash
# 备份向量库
tar -czf backup_vector_$(date +%Y%m%d).tar.gz /opt/rag-agent/vector_store/

# 备份文档
rsync -av /opt/rag-agent/documents/ backup/documents/

# 备份同步状态
cp /opt/rag-agent/data/knowledge.db backup/knowledge_$(date +%Y%m%d).db
```

---

## 八、故障排查

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 401 未认证 | 缺少 X-User-ID | 检查网关 Header 注入 |
| 向量检索失败 | ChromaDB 损坏 | 重建向量库 |
| 文件上传失败 | 权限/空间问题 | 检查目录权限和磁盘空间 |
| 内存不足 | 向量模型占用 | 调整 docker-compose 内存限制或增加服务器内存 |
| 服务启动慢 | 模型加载 | 预热模型或使用更小模型 |
| 容器启动失败 | 镜像构建问题 | `docker logs rag-service` 查看错误 |
| 容器 OOM Killed | 内存超限 | 增大 `deploy.resources.limits.memory` 或加 swap |
| 数据卷未挂载 | 路径配置错误 | `docker inspect rag-service` 检查 Mounts |