【RAGFlow代码详解-30】构建系统和 CI/CD

Docker 构建系统

RAGFlow 使用主 Dockerfile 1-214 中定义的复杂多阶段 Docker 构建过程，该过程创建应用程序的完整和精简变体。

多阶段构建架构

Docker 构建过程

构建过程由 Dockerfile 2-214 中定义的三个主要阶段组成：

基础阶段 （ Dockerfile 2-139 ）：使用系统依赖项（包括 Python 3.10、Node.js 20、Rust 工具链和数据库驱动程序）设置 Ubuntu 22.04 基础。
构建器阶段 （ Dockerfile 142-179 ）：使用 uv 包管理器处理依赖项安装，并使用 npm 构建 React 前端。
生产阶段 （ Dockerfile 181-214 ）：通过复制构建的项目和应用程序代码来创建最终的运行时映像。

构建变体

系统支持由 LIGHTEN` build 参数控制的两个构建变体：

完整映像：包括所有 ML 模型和嵌入 （ Dockerfile 21-26 ）
Slim Image：排除大型嵌入模型以减小图像大小 （ Dockerfile 158-162 ）

依赖关系管理

RAGFlow 通过专用的下载脚本和预构建的依赖关系映像来管理外部依赖项。

外部依赖项下载

依赖项类别
download_deps.py 1-78 脚本管理几类依赖项：

ML 模型：通过 （ download_deps.py 50-53 ） 下载 huggingface_hub.snapshot_download()
系统库：SSL 证书、用于数据库连接的 ODBC 驱动程序
文档处理：Apache Tika 服务器和 Chrome 浏览器，用于 PDF/Web 内容处理
NLP 数据：用于文本处理的 NLTK 语料库 （ download_deps.py 70-73 ）

该脚本支持针对基于中国的部署（ download_deps.py 20-40 ）进行镜像选择。

持续集成

RAGFlow 通过测试多种配置和存储后端的 GitHub Actions 工作流实现全面的 CI。

测试工作流架构

测试执行流程

.github/workflows/tests.yml 1-176 中的主要测试工作流执行以下顺序：

静态分析：使用 Ruff 进行 Python 代码质量检查 （ .github/workflows/tests.yml 52-56 ）
Docker 构建：创建精简和完整变体 （ .github/workflows/tests.yml 58-66 ）
多后端测试：针对 Elasticsearch 和 Infinity 存储引擎进行测试
测试类别：
- 通过 pytest 进行 SDK API 测试 （ .github/workflows/tests.yml 96 ）
- 前端 API 测试 （ .github/workflows/tests.yml 106 ）
- HTTP API 测试 （ .github/workflows/tests.yml 121 ）

测试配置

根据触发器类型配置了不同的测试级别：

Pull Request/Push：P2 级测试 （ .github/workflows/tests.yml 94 ）
定时运行：P3 级综合测试（ .github/workflows/tests.yml 92 ）

发布自动化

RAGFlow 通过专用的 GitHub Actions 工作流自动发布，该工作流处理版本控制、Docker 映像发布和 PyPI 包分发。

发布管道架构

发布类型

系统支持 .github/workflows/release.yml 1-119 中定义的两种类型的版本：

版本发布：通过创建 v*.. 标签触发，发布稳定版本
Nightly Releases：使用可变的 nightly 标签计划每日构建

Docker 镜像发布

该工作流发布两个 Docker 变体：

全图： infiniflow/ragflow:$RELEASE_TAG （ .github/workflows/release.yml 86-94 ）
超薄图像： infiniflow/ragflow:$RELEASE_TAG-slim （ .github/workflows/release.yml 96-104 ）

PyPI 包分发

对于版本发布，工作流使用 uv build 和 pypa/gh-action-pypi-publish （ .github/workflows/release.yml 106-118 ） 构建 Python SDK 并将其发布到 PyPI。

版本管理

RAGFlow 实现了一个灵活的版本跟踪系统，该系统适用于开发和生产环境。

版本解析逻辑

版本解析流程

api/versions.py 23-39 中的 get_ragflow_version（） 函数实现了分层版本解析：

缓存检查：如果已解析，则返回缓存版本
VERSION 文件：从 Docker 构建生成的 VERSION 文件（ api/versions.py 27-34 ）中读取
Git 回退： git describe --tags --match=v* --first-parent --always 用于开发 （ api/versions.py 42-52 ）
构建变体：根据 LIGHTEN 环境变量 （ api/versions.py 37-38 ） 附加"slim"或"full"后缀

运行时集成

版本信息通过调用 get_ragflow_version（） （ api/db/runtime_config.py 37-38 ） 的 RuntimeConfig.init_env（） 集成到运行时配置中。

Docker 构建版本生成

在 Docker 构建期间，使用 Git 命令捕获版本并写入 VERSION 文件 （ Dockerfile 171-178 ）：

sh 复制代码

version_info=$(git describe --tags --match=v* --first-parent --always)
echo $version_info > /ragflow/VERSION

构建优化

缓存策略

Docker 构建实现了全面的缓存以提高构建性能：

APT 缓存：持久包缓存 （ Dockerfile 45 ）
UV 缓存：Python 包缓存 （ Dockerfile 152 ）
NPM 缓存：Node.js 包缓存 （ Dockerfile 166 ）

多架构支持

构建系统处理不同的 CPU 架构：

x86_64：标准 Intel/AMD 处理器
ARM64/AArch64：Apple Silicon 和 ARM 服务器 （ Dockerfile 109-117 ）

特定于体系结构的包是动态选择的，特别是对于 ODBC 驱动程序和 SSL 库。