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 中 的主要測試工作流執行以下順序：

1. 靜態分析 ：使用 Ruff 進行 Python 代碼質量檢查 （ .github/workflows/tests.yml 52-56 ）
2. Docker 構建 ：創建精簡和完整變體 （ .github/workflows/tests.yml 58-66 ）
3. 多后端測試 ：針對 Elasticsearch 和 Infinity 存儲引擎進行測試
4. 測試類別 ：
   • 通過 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 中 定義的兩種類型的版本：

1. 版本發布 ：通過創建 v*.. 標簽觸發，發布穩定版本
2. 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（） 函數實現了分層版本解析：

1. 緩存檢查 ：如果已解析，則返回緩存版本
2. VERSION 文件 ：從 Docker 構建生成的 VERSION 文件（ api/versions.py 27-34 ）中讀取
3. Git 回退 ： git describe --tags --match=v* --first-parent --always 用于開發 （ api/versions.py 42-52 ）
4. 構建變體 ：根據 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 ）：

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 庫。