# 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 | RAG 组 | 同步状态检测 |
| 原始文档 | 文件系统 | RAG 组 | documents/ 目录 |
| 用户账户 | MySQL/PG | 后端组 | 账号密码信息 |
| 会话历史 | MySQL/PG | 后端组 | 对话记录 |
| 审计日志 | 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 | 知识库问答 |
| `/rag/stream` | 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)
- [ ] 准备环境变量配置模板

### 4.2 后端组需完成

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

### 4.3 双方需确认

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

---

## 五、Linux 部署方案

### 5.1 部署架构

```
┌─────────────────────────────────────────────────────────────────┐
│                       Linux 服务器                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
│  │   Nginx     │    │  后端服务    │    │     RAG 服务        │ │
│  │   :80/443   │───▶│   :8080     │    │       :5001        │ │
│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
│         │                  │                     │              │
│         │                  ▼                     ▼              │
│         │           ┌─────────────┐       ┌─────────────┐      │
│         │           │  MySQL/PG   │       │  ChromaDB   │      │
│         │           └─────────────┘       └─────────────┘      │
│         │                                                      │
│         ▼                                                      │
│  ┌─────────────┐                                               │
│  │ documents/  │  ◀── 文档存储目录                              │
│  └─────────────┘                                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 5.2 环境准备

```bash
# 1. 系统依赖
sudo apt update
sudo apt install -y python3.10 python3.10-venv python3-pip

# 2. 创建部署用户
sudo useradd -m -s /bin/bash rag
sudo su - rag

# 3. 创建目录结构
mkdir -p /home/rag/rag-service/{app,documents,vector_store,logs}
```

### 5.3 RAG 服务部署

```bash
# 1. 上传代码
cd /home/rag/rag-service
# 将项目代码上传到 app/ 目录

# 2. 创建虚拟环境
python3.10 -m venv venv
source venv/bin/activate

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

# 4. 配置环境变量
cat > .env << EOF
# 生产环境配置
DEV_MODE=false
DOCUMENTS_PATH=/home/rag/rag-service/documents
VECTOR_STORE_PATH=/home/rag/rag-service/vector_store

# API 配置（如果需要）
DASHSCOPE_API_KEY=your_api_key
EOF

# 5. 初始化向量库
python -c "from knowledge.manager import get_kb_manager; get_kb_manager()"

# 6. 测试启动
cd app && python main.py --port 5001
```

### 5.4 Systemd 服务配置

```bash
# 创建服务文件
sudo cat > /etc/systemd/system/rag-service.service << 'EOF'
[Unit]
Description=RAG Knowledge Service
After=network.target

[Service]
Type=simple
User=rag
Group=rag
WorkingDirectory=/home/rag/rag-service/app
Environment="PATH=/home/rag/rag-service/venv/bin"
EnvironmentFile=/home/rag/rag-service/.env
ExecStart=/home/rag/rag-service/venv/bin/python main.py --port 5001
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable rag-service
sudo systemctl start rag-service

# 查看状态
sudo systemctl status rag-service
```

### 5.5 Nginx 配置

```nginx
# /etc/nginx/sites-available/rag-service
upstream rag_backend {
    server 127.0.0.1:5001;
}

server {
    listen 80;
    server_name your-domain.com;

    # 请求体大小限制（文件上传）
    client_max_body_size 50M;

    # RAG API 代理
    location /rag-api/ {
        proxy_pass http://rag_backend/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # 注入用户信息（由认证模块设置）
        proxy_set_header X-User-ID $http_x_user_id;
        proxy_set_header X-User-Name $http_x_user_name;
        proxy_set_header X-User-Role $http_x_user_role;
        proxy_set_header X-User-Department $http_x_user_department;

        # SSE 支持
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
    }

    # 图片文件
    location /images/ {
        alias /home/rag/rag-service/documents/images/;
    }
}
```

### 5.6 网关 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
# RAG 服务日志
tail -f /home/rag/rag-service/logs/rag.log

# Systemd 日志
journalctl -u rag-service -f
```

### 7.2 健康检查

```bash
# 添加到监控脚本
curl -f http://localhost:5001/health || alert "RAG service down"
```

### 7.3 备份策略

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

# 备份文档
rsync -av documents/ backup/documents/

# 备份同步状态
sqlite3 data/knowledge.db ".backup backup/knowledge.db"
```

---

## 八、故障排查

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 401 未认证 | 缺少 X-User-ID | 检查网关 Header 注入 |
| 向量检索失败 | ChromaDB 损坏 | 重建向量库 |
| 文件上传失败 | 权限/空间问题 | 检查目录权限和磁盘空间 |
| 内存不足 | 向量模型占用 | 增加 swap 或内存 |
| 服务启动慢 | 模型加载 | 预热模型或使用更小模型 |