ai

# Ragflow-Plus 基础设施与文档教程

1. 目的与范围 #

本文档详细介绍了 Ragflow-Plus 系统的基础设施配置、容器构建与部署、开发环境配置、文档系统实现和开发工作流基础设施。

有关部署说明，请参阅部署与配置。有关 Docker 部署，请参阅 Docker 部署。

2. 容器构建与部署基础设施 #

Ragflow-Plus 使用 Docker 进行容器化部署，支持 CPU 和 GPU 两种模式。

2.1 Dockerfile 结构 #

2.1.1 主服务 Dockerfile #

# Dockerfile
FROM python:3.10-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    && rm -rf /var/lib/apt/lists/*

# 复制依赖文件
COPY requirements.txt .

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

# 复制应用代码
COPY . .

# 暴露端口
EXPOSE 9380 80 443

# 启动服务
CMD ["python", "api/ragflow_server.py"]

2.1.2 管理后端 Dockerfile #

# management/server/Dockerfile
FROM python:3.10-slim

WORKDIR /app

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

# 复制代码
COPY management/server/ .

# 暴露端口
EXPOSE 5000

# 启动服务
CMD ["python", "app.py"]

2.1.3 前端构建 Dockerfile #

# web/Dockerfile
FROM node:18-alpine AS builder

WORKDIR /app

# 复制依赖文件
COPY web/package*.json ./

# 安装依赖
RUN npm ci

# 复制源代码
COPY web/ .

# 构建应用
RUN npm run build

# 生产镜像
FROM nginx:alpine

# 复制构建产物
COPY --from=builder /app/dist /usr/share/nginx/html

# 复制 nginx 配置
COPY web/nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

2.2 Docker Compose 配置 #

# docker-compose.yml
version: '3.8'

services:
  # 主服务
  ragflowplus-server:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "9380:9380"
      - "80:80"
      - "443:443"
    environment:
      - MYSQL_HOST=mysql
      - ES_HOST=es01
      - MINIO_ENDPOINT=minio:9000
      - REDIS_HOST=redis
    depends_on:
      - mysql
      - es01
      - minio
      - redis
    volumes:
      - ./data:/app/data

  # 管理后端
  ragflowplus-management-backend:
    build:
      context: .
      dockerfile: management/server/Dockerfile
    ports:
      - "5000:5000"
    environment:
      - MYSQL_HOST=mysql
      - MINIO_ENDPOINT=minio:9000
    depends_on:
      - mysql
      - minio

  # 管理前端
  ragflowplus-management-frontend:
    build:
      context: .
      dockerfile: management/web/Dockerfile
    ports:
      - "8888:80"
    depends_on:
      - ragflowplus-management-backend

  # MySQL
  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=infini_rag_flow
      - MYSQL_DATABASE=ragflow
    volumes:
      - mysql_data:/var/lib/mysql
    ports:
      - "3306:3306"

  # Elasticsearch
  es01:
    image: elasticsearch:8.11.0
    environment:
      - discovery.type=single-node
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
      - xpack.security.enabled=true
      - ELASTIC_PASSWORD=infini_rag_flow
    volumes:
      - es_data:/usr/share/elasticsearch/data
    ports:
      - "9200:9200"

  # MinIO
  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      - MINIO_ROOT_USER=rag_flow
      - MINIO_ROOT_PASSWORD=infini_rag_flow
    volumes:
      - minio_data:/data
    ports:
      - "9000:9000"
      - "9001:9001"

  # Redis
  redis:
    image: redis:7-alpine
    command: redis-server --requirepass infini_rag_flow
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"

volumes:
  mysql_data:
  es_data:
  minio_data:
  redis_data:

2.3 GPU 支持配置 #

# docker-compose.gpu.yml
version: '3.8'

services:
  ragflowplus-server:
    build:
      context: .
      dockerfile: Dockerfile.gpu
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

3. 开发环境配置 #

3.1 本地开发设置 #

3.1.1 环境要求 #

Python 3.10+
Node.js 18+
Docker & Docker Compose
MySQL 8.0+（可选，可使用 Docker）
Elasticsearch 8.11+（可选，可使用 Docker）

3.1.2 后端开发环境 #

# 1. 克隆仓库
git clone https://github.com/zstar1003/ragflow-plus.git
cd ragflow-plus

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

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

# 4. 配置环境变量
cp .env.example .env
# 编辑 .env 文件

# 5. 启动服务
python api/ragflow_server.py

3.1.3 前端开发环境 #

# 用户前端
cd web
npm install
npm run dev

# 管理前端
cd management/web
npm install
npm run dev

3.2 开发工具配置 #

3.2.1 VS Code 配置 #

// .vscode/settings.json
{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true
  }
}

3.2.2 Prettier 配置 #

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100
}

3.2.3 ESLint 配置 #

// .eslintrc.json
{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2020,
    "sourceType": "module",
    "ecmaFeatures": {
      "jsx": true
    }
  },
  "rules": {
    "react/react-in-jsx-scope": "off"
  }
}

3.3 调试配置 #

3.3.1 Python 调试 #

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Flask",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/api/ragflow_server.py",
      "env": {
        "FLASK_APP": "api/ragflow_server.py",
        "FLASK_ENV": "development"
      },
      "jinja": true
    }
  ]
}

3.3.2 前端调试 #

// .vscode/launch.json (前端)
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Chrome",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:5173",
      "webRoot": "${workspaceFolder}/web"
    }
  ]
}

4. 文档系统实现 #

4.1 代码文档规范 #

4.1.1 Python 文档字符串 #

def create_knowledgebase(
    name: str,
    tenant_id: str,
    embedding_model: str = 'bge-m3'
) -> dict:
    """
    创建知识库

    Args:
        name: 知识库名称，最大长度 255 字符
        tenant_id: 租户ID，必须是有效的租户ID
        embedding_model: 嵌入模型名称，默认为 'bge-m3'

    Returns:
        dict: 包含知识库信息的字典，格式为：
            {
                'id': str,  # 知识库ID
                'name': str,  # 知识库名称
                'tenant_id': str,  # 租户ID
                'create_time': str  # 创建时间
            }

    Raises:
        ValueError: 如果名称已存在或租户ID无效
        DatabaseError: 如果数据库操作失败

    Example:
        >>> kb = create_knowledgebase('我的知识库', 'tenant_123')
        >>> print(kb['id'])
        'kb_abc123'
    """
    pass

4.1.2 TypeScript 文档注释 #

/**
 * 发送聊天消息
 * 
 * @param knowledgeBaseId - 知识库ID
 * @param content - 消息内容
 * @returns Promise<Message> 返回助手回复的消息
 * 
 * @example
 * ```typescript
 * const message = await sendMessage('kb_123', '你好');
 * console.log(message.content);
 *

*/ export async function sendMessage( knowledgeBaseId: string, content: string ): Promise { // 实现 }


### 4.2 API 文档生成

#### 4.2.1 Swagger 配置

```python
# api/apps/__init__.py
from flasgger import Swagger

swagger_config = {
    "headers": [],
    "specs": [
        {
            "endpoint": "apispec",
            "route": "/apispec.json",
            "rule_filter": lambda rule: True,
            "model_filter": lambda tag: True,
        }
    ],
    "static_url_path": "/flasgger_static",
    "swagger_ui": True,
    "specs_route": "/api-docs"
}

swagger_template = {
    "swagger": "2.0",
    "info": {
        "title": "Ragflow-Plus API",
        "description": "Ragflow-Plus API 文档",
        "version": "1.0.0"
    },
    "basePath": "/api/v1",
    "schemes": ["http", "https"]
}

Swagger(app, config=swagger_config, template=swagger_template)

4.2.2 API 文档注释 #

@kb_bp.route('', methods=['POST'])
def create_knowledgebase():
    """
    创建知识库
    ---
    tags:
      - 知识库管理
    summary: 创建新的知识库
    description: 为指定租户创建新的知识库
    parameters:
      - in: body
        name: body
        required: true
        schema:
          type: object
          required:
            - name
            - tenant_id
          properties:
            name:
              type: string
              description: 知识库名称
              example: "我的知识库"
            tenant_id:
              type: string
              description: 租户ID
              example: "tenant_123"
            embedding_model:
              type: string
              description: 嵌入模型名称
              default: "bge-m3"
    responses:
      201:
        description: 创建成功
        schema:
          type: object
          properties:
            code:
              type: integer
              example: 0
            data:
              type: object
              properties:
                id:
                  type: string
                  example: "kb_abc123"
                name:
                  type: string
                  example: "我的知识库"
      400:
        description: 参数错误
      500:
        description: 服务器错误
    """
    pass

4.3 Markdown 文档 #

系统使用 Markdown 文档记录架构、API 和使用指南。

4.3.1 文档结构 #

docs/
├── architecture/      # 架构文档
├── api/              # API 文档
├── deployment/       # 部署文档
└── development/      # 开发文档

4.3.2 文档模板 #

# 标题

## 1. 目的与范围

本文档的用途和覆盖范围。

## 2. 主要内容

详细内容...

## 3. 示例

代码示例...

## 4. 总结

总结内容...

5. 开发工作流基础设施 #

5.1 Git 工作流 #

5.1.1 分支策略 #

main (生产环境)
  ↑
develop (开发环境)
  ↑
feature/* (功能分支)
bugfix/* (修复分支)
hotfix/* (热修复分支)

5.1.2 提交规范 #

使用 Conventional Commits 规范：

feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建/工具相关

示例：

feat: 添加知识库管理功能
fix: 修复对话历史加载问题
docs: 更新 API 文档

5.2 CI/CD 配置 #

5.2.1 GitHub Actions #

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.10'

    - name: Install dependencies
      run: |
        pip install -r requirements.txt
        pip install pytest pytest-cov

    - name: Run tests
      run: pytest --cov=api tests/

    - name: Lint
      run: |
        pip install pylint
        pylint api/

  build:
    runs-on: ubuntu-latest
    needs: test

    steps:
    - uses: actions/checkout@v3

    - name: Build Docker image
      run: docker build -t ragflow-plus:latest .

5.3 代码质量工具 #

5.3.1 Python 代码检查 #

# 使用 pylint
pylint api/

# 使用 black 格式化
black api/

# 使用 isort 排序导入
isort api/

5.3.2 TypeScript 代码检查 #

# 使用 ESLint
npm run lint

# 使用 Prettier 格式化
npm run format

# 类型检查
npm run type-check

5.4 测试基础设施 #

5.4.1 单元测试 #

# tests/test_knowledgebase_service.py
import pytest
from api.db.services.knowledgebase_service import KnowledgebaseService

class TestKnowledgebaseService:
    def test_create_knowledgebase(self):
        """测试创建知识库"""
        service = KnowledgebaseService()
        kb = service.create_knowledgebase('测试知识库', 'tenant_123')

        assert kb['name'] == '测试知识库'
        assert kb['tenant_id'] == 'tenant_123'

    def test_get_knowledgebase(self):
        """测试获取知识库"""
        service = KnowledgebaseService()
        kb = service.create_knowledgebase('测试知识库', 'tenant_123')

        result = service.get_knowledgebase(kb['id'])
        assert result is not None
        assert result['name'] == '测试知识库'

5.4.2 集成测试 #

# tests/integration/test_api.py
import pytest
from api.apps import create_app

@pytest.fixture
def client():
    app = create_app()
    app.config['TESTING'] = True
    with app.test_client() as client:
        yield client

def test_create_knowledgebase(client):
    """测试创建知识库 API"""
    response = client.post('/api/v1/knowledgebases', json={
        'name': '测试知识库',
        'tenant_id': 'tenant_123'
    })

    assert response.status_code == 201
    data = response.get_json()
    assert data['code'] == 0
    assert 'data' in data

6. 监控与日志 #

6.1 日志配置 #

# api/utils/logger.py
import logging
import sys
from logging.handlers import RotatingFileHandler

def setup_logger(name: str = 'ragflow', log_file: str = 'app.log'):
    """设置日志"""
    logger = logging.getLogger(name)
    logger.setLevel(logging.INFO)

    # 控制台处理器
    console_handler = logging.StreamHandler(sys.stdout)
    console_handler.setLevel(logging.INFO)
    console_formatter = logging.Formatter(
        '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
    )
    console_handler.setFormatter(console_formatter)

    # 文件处理器
    file_handler = RotatingFileHandler(
        log_file,
        maxBytes=10*1024*1024,  # 10MB
        backupCount=5
    )
    file_handler.setLevel(logging.INFO)
    file_formatter = logging.Formatter(
        '%(asctime)s - %(name)s - %(levelname)s - %(funcName)s:%(lineno)d - %(message)s'
    )
    file_handler.setFormatter(file_formatter)

    logger.addHandler(console_handler)
    logger.addHandler(file_handler)

    return logger

logger = setup_logger()

6.2 健康检查 #

# api/apps/health.py
from flask import Blueprint, jsonify

health_bp = Blueprint('health', __name__)

@health_bp.route('/health', methods=['GET'])
def health_check():
    """健康检查"""
    try:
        # 检查数据库连接
        from api.db.database import get_db_connection
        conn = get_db_connection()
        conn.ping()

        # 检查 Elasticsearch
        from api.db.elasticsearch_client import get_es_client
        es = get_es_client()
        es.ping()

        return jsonify({
            'status': 'healthy',
            'database': 'connected',
            'elasticsearch': 'connected'
        }), 200
    except Exception as e:
        return jsonify({
            'status': 'unhealthy',
            'error': str(e)
        }), 503

7. 部署脚本 #

7.1 部署脚本 #

#!/bin/bash
# deploy.sh

set -e

echo "开始部署 Ragflow-Plus..."

# 1. 停止现有服务
docker-compose down

# 2. 拉取最新代码
git pull

# 3. 构建镜像
docker-compose build

# 4. 启动服务
docker-compose up -d

# 5. 等待服务就绪
echo "等待服务启动..."
sleep 30

# 6. 健康检查
curl -f http://localhost:9380/health || exit 1

echo "部署完成！"

8. 总结 #

本文档介绍了 Ragflow-Plus 基础设施与文档的各个方面：

容器构建：Dockerfile 和 Docker Compose 配置
开发环境：本地开发环境设置和工具配置
文档系统：代码文档规范和 API 文档生成
工作流：Git 工作流和 CI/CD 配置
测试：单元测试和集成测试
监控：日志和健康检查

通过遵循本文档的指南，您可以建立完善的开发和部署基础设施。

导航菜单