rag/docs/架构与部署方案.md

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 组需完成

• 权限控制简化（依赖后端网关）
• 移除会话管理依赖
• 移除审计日志依赖
• 更新 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 环境准备

# 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 服务部署

# 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 服务配置

# 创建服务文件
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 配置

# /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：

// 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 接口测试

# 测试 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 日志管理

# RAG 服务日志
tail -f /home/rag/rag-service/logs/rag.log

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

7.2 健康检查

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

7.3 备份策略

# 备份向量库
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 或内存
服务启动慢	模型加载	预热模型或使用更小模型