init: RAG 知识库服务初始提交

- 后端 API（Flask + Gunicorn） - RAG 引擎（混合检索 + 云端 Reranker + 引用溯源） - 文档解析（MinerU + 多格式支持） - Docker 生产部署配置 - 排除前端项目、敏感配置、模型文件
2026-06-04 17:35:27 +08:00
commit 100d1a06eb
158 changed files with 64534 additions and 0 deletions
--- a/deploy/.dockerignore
+++ b/deploy/.dockerignore
@@ -0,0 +1,62 @@
+# .dockerignore
+venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# 环境变量
+.env
+.env.*
+!.env.production
+
+# 数据库（不打包到镜像）
+*.db
+*.db-shm
+*.db-wal
+data/
+knowledge/vector_store/
+.data/
+models/
+
+# 日志
+*.log
+logs/
+
+# 文档
+docs/
+*.md
+!README.md
+
+# 测试
+tests/
+test_*.py
+*_test.py
+
+# 临时文件
+*.tmp
+*.bak
+.DS_Store
+Thumbs.db
+
+# Claude Code
+.claude/
+CLAUDE.md
+UPLOAD_CHECKLIST.md
--- a/deploy/Dockerfile
+++ b/deploy/Dockerfile
@@ -0,0 +1,47 @@
+# Dockerfile
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# 使用阿里云镜像源
+RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources \
+    && sed -i 's/security.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources
+
+# 系统依赖
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    poppler-utils \
+    libmagic1 \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Python依赖（使用阿里云 pip 镜像）
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt \
+    -i https://mirrors.aliyun.com/pypi/simple/ \
+    && pip install gunicorn>=21.0.0 \
+    -i https://mirrors.aliyun.com/pypi/simple/
+
+# 应用代码
+COPY . .
+
+# 创建 MinerU 配置文件（生产环境）
+RUN echo '{\n\
+  "models-dir": {\n\
+    "pipeline": "/app/models/mineru/pipeline",\n\
+    "vlm": "/app/models/mineru/vlm"\n\
+  },\n\
+  "config_version": "1.3.1"\n\
+}' > /root/mineru.json
+
+# 设置 MinerU 环境变量
+ENV MINERU_MODEL_SOURCE=local
+ENV MINERU_TOOLS_CONFIG_JSON=/root/mineru.json
+
+# 创建数据目录（生产环境可能不需要，但保留以防万一）
+RUN mkdir -p data knowledge/vector_store .data documents models
+
+EXPOSE 5001
+
+# 生产模式启动（使用配置文件）
+CMD ["gunicorn", "-c", "deploy/gunicorn.conf.py", "deploy.wsgi:app"]
--- a/deploy/Dockerfile.prod
+++ b/deploy/Dockerfile.prod
@@ -0,0 +1,62 @@
+# Dockerfile.prod - 生产环境优化版
+# ================================
+# 特点：CPU-only、精简依赖、最小化镜像
+
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# 使用阿里云镜像源
+RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources \
+    && sed -i 's/security.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources
+
+# 系统依赖（精简版）
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    poppler-utils \
+    libmagic1 \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# ==================== PyTorch（CPU 模式） ====================
+# 先从阿里云安装 PyTorch 依赖（避免从 PyPI 下载超时）
+RUN pip install --no-cache-dir networkx sympy mpmath typing-extensions \
+    -i https://mirrors.aliyun.com/pypi/simple/
+# 再从 PyTorch 官方源下载 CPU-only 版本（约 200MB），跳过依赖解析
+RUN pip install --no-cache-dir --no-deps torch --index-url https://download.pytorch.org/whl/cpu
+
+# 设置 PyTorch 使用 CPU 模式
+ENV CUDA_VISIBLE_DEVICES=""
+
+# ==================== Python 依赖 ====================
+COPY requirements-prod.txt .
+RUN pip install --no-cache-dir -r requirements-prod.txt \
+    -i https://mirrors.aliyun.com/pypi/simple/
+
+# ==================== 应用代码 ====================
+COPY . .
+
+# ==================== MinerU 配置 ====================
+# 生产环境使用本地模型
+RUN mkdir -p /root && echo '{\n\
+  "models-dir": {\n\
+    "pipeline": "/app/models/mineru/pipeline",\n\
+    "vlm": "/app/models/mineru/vlm"\n\
+  },\n\
+  "config_version": "1.3.1"\n\
+}' > /root/mineru.json
+
+ENV MINERU_MODEL_SOURCE=local
+ENV MINERU_TOOLS_CONFIG_JSON=/root/mineru.json
+
+# ==================== 数据目录 ====================
+RUN mkdir -p knowledge/vector_store documents models .data
+
+# ==================== 环境变量 ====================
+ENV APP_ENV=prod
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 5001
+
+# 生产模式启动
+CMD ["gunicorn", "-c", "deploy/gunicorn.conf.py", "deploy.wsgi:app"]
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -0,0 +1,219 @@
+# 部署文件说明
+
+本目录包含所有部署相关的配置文件。
+
+---
+
+## 📁 文件清单
+
+### Docker 部署
+
+| 文件 | 说明 |
+|------|------|
+| `Dockerfile` | Docker 镜像构建文件 |
+| `docker-compose.yml` | Docker Compose 编排配置 |
+| `.dockerignore` | Docker 构建忽略文件 |
+| `.env.production` | 生产环境变量配置 |
+
+### Web 服务器
+
+| 文件 | 说明 |
+|------|------|
+| `gunicorn.conf.py` | Gunicorn WSGI 服务器配置 |
+| `wsgi.py` | WSGI 应用入口 |
+| `nginx.conf` | Nginx 反向代理配置（可选） |
+
+---
+
+## 🚀 快速部署
+
+### 方式 1：Docker Compose（推荐）
+
+```bash
+# 1. 构建并启动
+docker-compose up -d
+
+# 2. 查看日志
+docker-compose logs -f
+
+# 3. 停止服务
+docker-compose down
+```
+
+### 方式 2：Docker 手动部署
+
+```bash
+# 1. 构建镜像
+docker build -f deploy/Dockerfile -t rag-service:latest .
+
+# 2. 运行容器
+docker run -d \
+  -p 5001:5001 \
+  -v $(pwd)/data:/app/data \
+  -v $(pwd)/documents:/app/documents \
+  -v $(pwd)/knowledge:/app/knowledge \
+  --name rag-service \
+  rag-service:latest
+
+# 3. 查看日志
+docker logs -f rag-service
+```
+
+### 方式 3：直接部署（服务器）
+
+```bash
+# 1. 安装依赖
+pip install -r requirements.txt
+pip install gunicorn
+
+# 2. 启动服务
+gunicorn -c deploy/gunicorn.conf.py deploy.wsgi:app
+```
+
+---
+
+## ⚙️ 配置说明
+
+### Dockerfile
+
+**关键配置**：
+- 基础镜像：`python:3.10-slim`
+- 工作目录：`/app`
+- 暴露端口：`5001`
+- 启动命令：`gunicorn -c deploy/gunicorn.conf.py deploy.wsgi:app`
+
+**环境变量**：
+```dockerfile
+ENV MINERU_MODEL_SOURCE=local
+ENV MINERU_TOOLS_CONFIG_JSON=/root/mineru.json
+ENV APP_ENV=prod
+ENV ENABLE_SESSION=false
+```
+
+### docker-compose.yml
+
+**服务配置**：
+- 端口映射：`5001:5001`
+- 数据卷挂载：`./data`, `./documents`, `./knowledge`
+- 自动重启：`unless-stopped`
+
+### gunicorn.conf.py
+
+**性能配置**：
+- Workers：`CPU核心数 × 2 + 1`
+- Worker类型：`sync`（同步）
+- 超时时间：`120秒`
+- 最大请求数：`1000`（防止内存泄漏）
+
+### nginx.conf
+
+**反向代理配置**（可选）：
+- 负载均衡：`least_conn`
+- 请求限流：`10r/s`
+- 超时配置：`120s`
+- SSE 流式支持：已启用
+
+---
+
+## 🔧 环境变量
+
+### 必需变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `APP_ENV` | 环境标识 | `prod` |
+| `MINERU_MODEL_SOURCE` | 模型来源 | `local` |
+| `DASHSCOPE_API_KEY` | 通义千问 API Key | 无 |
+
+### 可选变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `ENABLE_SESSION` | 会话管理 | `false` |
+| `ENABLE_FEEDBACK` | 反馈系统 | `true` |
+| `GUNICORN_WORKERS` | Worker 数量 | 自动计算 |
+
+---
+
+## 📊 资源要求
+
+### 最小配置
+
+- CPU：2 核
+- 内存：4 GB
+- 磁盘：20 GB（含模型）
+
+### 推荐配置
+
+- CPU：4 核
+- 内存：8 GB
+- 磁盘：50 GB
+
+---
+
+## 🔍 健康检查
+
+### Docker 健康检查
+
+```bash
+# 检查容器状态
+docker ps
+
+# 检查健康状态
+curl http://localhost:5001/health
+```
+
+### 服务端点
+
+| 端点 | 说明 |
+|------|------|
+| `/health` | 健康检查 |
+| `/stats` | 服务统计 |
+| `/rag` | RAG 问答（SSE 流式） |
+
+---
+
+## 🐛 故障排查
+
+### 容器无法启动
+
+```bash
+# 查看日志
+docker logs rag-service
+
+# 检查配置
+docker exec rag-service cat /root/mineru.json
+
+# 检查模型
+docker exec rag-service ls /app/models/mineru
+```
+
+### 性能问题
+
+```bash
+# 查看资源使用
+docker stats rag-service
+
+# 调整 Worker 数量
+# 修改 docker-compose.yml 中的 GUNICORN_WORKERS
+```
+
+### 端口冲突
+
+```bash
+# 修改端口映射
+# docker-compose.yml: "5002:5001"
+```
+
+---
+
+## 📚 相关文档
+
+- [部署指南](../docs/MinerU模型部署指南.md)
+- [配置说明](../docs/后端对接规范.md)
+- [故障排查](../docs/绝对路径修复总结.md)
+
+---
+
+**最后更新**: 2026-04-20  
+**维护者**: RAG 服务开发组
--- a/deploy/docker-compose.prod.yml
+++ b/deploy/docker-compose.prod.yml
@@ -0,0 +1,43 @@
+# docker-compose.prod.yml - 生产环境部署配置
+# ================================
+# 使用方式：
+#   docker-compose -f deploy/docker-compose.prod.yml up -d --build
+
+version: '3.8'
+
+services:
+  rag-service:
+    build:
+      context: ..
+      dockerfile: deploy/Dockerfile.prod
+    container_name: rag-service
+    env_file:
+      - .env.production
+    ports:
+      - "5001:5001"
+    volumes:
+      # 数据目录挂载（代码在镜像内，不挂载）
+      - ../knowledge/vector_store:/app/knowledge/vector_store
+      - ../documents:/app/documents
+      - ../models:/app/models
+      - ../.data:/app/.data
+      - ../data:/app/data
+    restart: unless-stopped
+    shm_size: '256m'
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+        reservations:
+          memory: 2G
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:5001/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -0,0 +1,36 @@
+version: '3.8'
+
+services:
+  rag-service:
+    build:
+      context: ..
+      dockerfile: deploy/Dockerfile
+    container_name: rag-service
+    ports:
+      - "5001:5001"
+    volumes:
+      - ../knowledge/vector_store:/app/knowledge/vector_store  # 向量索引（必须）
+      - ../.data:/app/.data                    # 上传文件
+      - ../documents:/app/documents            # 源文档
+      - ../models:/app/models                  # 嵌入模型
+      # 生产环境不挂载 data/ 目录（不使用SQLite）
+    environment:
+      - APP_ENV=prod
+      - DASHSCOPE_API_KEY=${DASHSCOPE_API_KEY}
+      - DASHSCOPE_MODEL=${DASHSCOPE_MODEL:-mimo-v2.5}
+      - RERANK_USE_ONNX=${RERANK_USE_ONNX:-false}
+    restart: unless-stopped
+    # 资源限制：Embedding模型加载需要较多内存
+    shm_size: '256m'  # Gunicorn 心跳文件需要
+    deploy:
+      resources:
+        limits:
+          memory: 6G
+        reservations:
+          memory: 2G
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:5001/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s  # 给启动和模型加载留出时间
--- a/deploy/gunicorn.conf.py
+++ b/deploy/gunicorn.conf.py
@@ -0,0 +1,56 @@
+# gunicorn.conf.py - Gunicorn生产配置
+
+import multiprocessing
+import os
+
+# 服务器绑定
+bind = "0.0.0.0:5001"
+
+# Worker配置
+# 单 worker 模式，适合资源有限环境
+workers = int(os.getenv("GUNICORN_WORKERS", 1))
+worker_class = "gthread"  # 线程worker，可发送心跳（原 sync）
+threads = 2  # 每个worker 2个线程
+worker_connections = 1000
+max_requests = 1000  # 每个worker处理1000个请求后重启（防止内存泄漏）
+max_requests_jitter = 50
+
+# 超时配置
+timeout = 120  # 优化后不应超过2分钟（原 300）
+graceful_timeout = 60
+keepalive = 5
+
+# 日志配置
+accesslog = "-"  # stdout
+errorlog = "-"   # stderr
+loglevel = "info"
+access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s" %(D)s'
+
+# 进程命名
+proc_name = "rag-service"
+
+# 预加载应用（gthread 模式下必须关闭，否则 fork 后线程资源死锁）
+preload_app = False
+
+# 守护进程（Docker中不需要）
+daemon = False
+
+# 临时文件目录
+worker_tmp_dir = "/dev/shm"  # 使用内存文件系统，提升性能
+
+# 钩子函数
+def on_starting(server):
+    """服务启动时"""
+    print(f"[INFO] Starting Gunicorn with {workers} workers")
+
+def on_reload(server):
+    """重载时"""
+    print("[INFO] Reloading Gunicorn")
+
+def worker_int(worker):
+    """Worker被中断时"""
+    print(f"[INFO] Worker {worker.pid} interrupted")
+
+def worker_abort(worker):
+    """Worker异常退出时"""
+    print(f"[ERROR] Worker {worker.pid} aborted")
--- a/deploy/nginx.conf
+++ b/deploy/nginx.conf
@@ -0,0 +1,60 @@
+# nginx.conf - RAG服务反向代理配置
+
+upstream rag_backend {
+    # 负载均衡策略：least_conn（最少连接）
+    least_conn;
+
+    # 多个RAG服务实例（可选，用于高可用）
+    server rag-service-1:5001 max_fails=3 fail_timeout=30s;
+    # server rag-service-2:5001 max_fails=3 fail_timeout=30s;
+    # server rag-service-3:5001 max_fails=3 fail_timeout=30s;
+}
+
+server {
+    listen 80;
+    server_name rag.example.com;
+
+    # 请求体大小限制（文档上传）
+    client_max_body_size 100M;
+
+    # 超时配置（RAG问答可能较慢）
+    proxy_connect_timeout 120s;
+    proxy_send_timeout 120s;
+    proxy_read_timeout 120s;
+
+    # RAG服务代理
+    location / {
+        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-Forwarded-Proto $scheme;
+
+        # SSE流式响应支持
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_http_version 1.1;
+        chunked_transfer_encoding on;
+    }
+
+    # 健康检查
+    location /health {
+        proxy_pass http://rag_backend/health;
+        access_log off;
+    }
+
+    # 请求限流（防止滥用）
+    limit_req_zone $binary_remote_addr zone=rag_limit:10m rate=10r/s;
+    limit_req zone=rag_limit burst=20 nodelay;
+}
+
+# HTTPS配置（推荐）
+server {
+    listen 443 ssl http2;
+    server_name rag.example.com;
+
+    ssl_certificate /etc/nginx/ssl/cert.pem;
+    ssl_certificate_key /etc/nginx/ssl/key.pem;
+
+    # 其他配置同上...
+}
--- a/deploy/wsgi.py
+++ b/deploy/wsgi.py
@@ -0,0 +1,24 @@
+"""
+Gunicorn WSGI 入口文件
+
+用于生产环境部署，通过 Gunicorn 启动 Flask 应用。
+
+使用方式:
+    gunicorn -c deploy/gunicorn.conf.py deploy.wsgi:app
+"""
+import os
+import sys
+
+# 添加项目根目录到 Python 路径
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from api import create_app
+
+# 确保环境变量已设置
+os.environ.setdefault('APP_ENV', 'prod')
+
+# 创建应用实例
+app = create_app()
+
+if __name__ == "__main__":
+    app.run()