2.4 · 构建系统与 CI/CD（Build System and CI/CD）

构建系统与 CI/CD

构建系统与持续集成/持续部署（CI/CD）

相关源文件

本章引用的主要源码文件：

• .github/workflows/release.yml
• .github/workflows/tests.yml
• Dockerfile
• Dockerfile.deps
• admin/client/http_client.py
• admin/client/parser.py
• admin/client/ragflow_cli.py
• admin/client/ragflow_client.py
• admin/client/user.py
• build.sh
• docker/docker-compose-base.yml
• docker/infinity_conf.toml
• download_deps.py
• go.mod
• go.sum
• helm/values.yaml
• internal/dao/database.go
• internal/dao/license.go
• internal/dao/time_record.go
• internal/engine/engine.go
• internal/handler/auth.go
• internal/handler/kb.go
• internal/handler/tenant.go
• internal/utility/convert.go
• pyproject.toml
• sdk/python/pyproject.toml
• sdk/python/uv.lock
• uv.lock

概述

RAGFlow 构建系统使用现代化工具链，实现可重现的容器化构建，并具备快速的依赖解析能力。该系统包含以下组件：

• UV 包管理器：用于 Python 依赖管理，支持锁文件 pyproject.toml:188-203。
• 多阶段 Docker 构建：最小化生产镜像体积，并处理复杂的系统依赖 Dockerfile:1-160。
• 自动化 CI/CD 管线：针对多种文档存储后端（Elasticsearch、Infinity、OpenSearch）运行全面测试 .github/workflows/tests.yml:168-220。
• 多语言编译：涉及 Python、Go（服务层）和 C++（RAGAnalyzer/分词器）.github/workflows/tests.yml:132-142。
• 依赖预缓存：支持离线安装和镜像加速 download_deps.py:21-45。

使用 UV 进行包管理

RAGFlow 使用 UV（一个用 Rust 编写的高性能 Python 包安装器和解析器）来替代传统的 pip 和 poetry 工作流，显著提升依赖解析和安装速度。

项目配置

项目元数据和依赖在 pyproject.toml 中定义 pyproject.toml:1-167。

[project]
name = "ragflow"
version = "0.25.4"
requires-python = ">=3.13,<3.15"
dependencies = [
    "audioop-lts>=0.2.1",
    "aiosmtplib>=5.0.0",
    "anthropic==0.34.1",
    "infinity-sdk==0.7.0-dev7",
    "agentrun-sdk>=0.0.16,<1.0.0",
    # ... 150+ 个依赖
]

[dependency-groups]
test = [
    "hypothesis>=6.132.0",
    "pytest>=8.3.5",
    "pytest-asyncio>=1.3.0",
    "pytest-playwright>=0.7.2",
    # ... 仅测试用的依赖
]

关键点：

• Python 版本约束：要求 3.13 至 3.15 版本 pyproject.toml:8。
• 依赖分组：为 CI 和本地开发设置独立的 test 组 pyproject.toml:169-186。
• 约束依赖：UV 强制指定特定版本以保障安全，例如 pyasn1>=0.6.3 用于修复 CVE-2026-30922 pyproject.toml:189-192。
• 平台特定依赖：根据架构条件选择 onnxruntime 或 onnxruntime-gpu pyproject.toml:76-77。

锁文件

uv.lock uv.lock:1-11 包含所有传递依赖的固定版本及校验和，确保构建的可重现性。它还包含针对不同 Python 版本和平台的解析标记 uv.lock:4-11。

Docker 中的 UV 安装

UV 在 Docker 构建过程中安装 Dockerfile:67-81。

安装过程：

1. 如果设置了 NEED_MIRROR=1，则配置镜像 Dockerfile:69-75。
2. 检测架构（x86_64 或 aarch64）Dockerfile:76-77。
3. 从 ragflow_deps 镜像中提取预下载的 UV 二进制文件 Dockerfile:78-80。
4. 通过 uv python install 3.13 安装 Python 3.13 Dockerfile:81。

来源： pyproject.toml:1-203，uv.lock:1-11，Dockerfile:67-81

多阶段 Docker 构建

生产 Docker 镜像使用多阶段构建过程，将构建时工具（如 Node.js 和 Rust）与最终运行时环境分离。

构建管线图

来源： Dockerfile:1-160

多语言编译

除了 Python 之外，RAGFlow 还需要编译 Go 和 C++ 组件。

1. C++ 编译：ragflow_build 容器使用 infiniflow/infinity_builder 通过 ./build.sh --cpp 编译 C++ 资源（如分词器）.github/workflows/tests.yml:132-138。
2. Go 编译：通过 ./build.sh --go 构建 Go 服务 .github/workflows/tests.yml:139。
3. Rust 编译：在 uv sync 过程中，对于包含 Rust 扩展的 Python 包（例如 sqlglotrs、ormsgpack）需要 Rust 编译 pyproject.toml:115, 82。

来源： Dockerfile:44-55，.github/workflows/tests.yml:132-142

依赖预缓存

为了支持网络受限的环境并加速 CI，RAGFlow 使用 download_deps.py 脚本缓存大型资源 download_deps.py:1-82。

缓存的资源

来源： download_deps.py:21-51，Dockerfile:11-25，Dockerfile:116-123

CI/CD 工作流（GitHub Actions）

CI 管线在 .github/workflows/tests.yml 中定义，并在标记为 ragflow-test 的自托管运行器上执行 .github/workflows/tests.yml:32-37。

管线逻辑

1. 静态分析：运行 ruff 检查进行 Python 代码风格检查 .github/workflows/tests.yml:94-98。
2. 二进制构建：编译 Go 和 C++ 组件 .github/workflows/tests.yml:132-142。
3. 镜像构建：使用 Docker BuildKit 构建 ragflow:nightly 镜像 .github/workflows/tests.yml:144-150。
4. 集成测试：

• 使用不同的 DOC_ENGINE 设置（Elasticsearch、Infinity、OpenSearch）通过 docker-compose 部署系统 .github/workflows/tests.yml:168-220。
• 运行 SDK 测试：验证 Python SDK ragflow-sdk .github/workflows/tests.yml:223-230。
• 运行 Web API 测试：验证内部 Quart 应用端点 .github/workflows/tests.yml:232-239。
• 运行 HTTP API 测试：验证公共 REST API .github/workflows/tests.yml:241-248。

自动化发布

release.yml 工作流在标签（v*.*.*）或每日计划时触发 .github/workflows/release.yml:3-11。

• Docker Hub：将镜像推送到 infiniflow/ragflow .github/workflows/release.yml:85-91。
• PyPI：使用 uv build 和 uv publish 发布 ragflow-sdk 和 ragflow-cli .github/workflows/release.yml:93-101。

CI/CD 到代码实体的映射

来源： .github/workflows/tests.yml:1-150，.github/workflows/release.yml:85-101，sdk/python/pyproject.toml:1-10

测试基础设施

测试通过 pytest 管理，配置在 pyproject.toml 中。

测试分类

服务管理

测试工作流确保环境通过 docker-compose-base.yml 正确设置，该文件定义了核心服务，如 es01、infinity 和 mysql docker/docker-compose-base.yml:1-230。

来源： sdk/python/pyproject.toml:26-31，docker/docker-compose-base.yml:1-230，docker/infinity_conf.toml:1-57，helm/values.yaml:13-75