agentic_huge_data_base / wiki
页面 RAGFlow · 2.5 Kubernetes 与 Helm 部署·DeepWiki 中文全文译文
DeepWiki 中文译文 / RAGFlow / 2.5

2.5 · Kubernetes 与 Helm 部署（Kubernetes and Helm Deployment）

复杂文档理解与引用检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目RAGFlow 章节2.5 状态全文译文 模块安装与启动、测试、发布与运维、存储与持久化、界面与交互
项目要点页2.5 参考项目 项目章节目录RAGFlow DeepWiki 原始章节Kubernetes and Helm Deployment 上一章2.4 下一章3
源码线索
  • .github/workflows/release.yml
  • .github/workflows/tests.yml
  • Dockerfile
  • Dockerfile.deps
  • docker/docker-compose-base.yml
  • docker/infinity_conf.toml
  • download_deps.py
  • helm/.helmignore
  • helm/Chart.yaml
  • helm/README.md
模块标签
  • 安装与启动
  • 测试、发布与运维
  • 存储与持久化
  • 界面与交互
  • 系统架构

章节正文

Kubernetes 与 Helm 部署

原始 DeepWiki 页面https://deepwiki.com/infiniflow/ragflow/2.5-kubernetes-and-helm-deployment

Kubernetes 和 Helm 部署

相关源文件

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

  • .github/workflows/release.yml
  • .github/workflows/tests.yml
  • Dockerfile
  • Dockerfile.deps
  • docker/docker-compose-base.yml
  • docker/infinity_conf.toml
  • download_deps.py
  • helm/.helmignore
  • helm/Chart.yaml
  • helm/README.md
  • helm/templates/_helpers.tpl
  • helm/templates/elasticsearch-config.yaml
  • helm/templates/elasticsearch.yaml
  • helm/templates/env.yaml
  • helm/templates/infinity.yaml
  • helm/templates/ingress.yaml
  • helm/templates/minio.yaml
  • helm/templates/mysql-config.yaml
  • helm/templates/mysql.yaml
  • helm/templates/opensearch-config.yaml
  • helm/templates/opensearch.yaml
  • helm/templates/ragflow.yaml
  • helm/templates/ragflow_config.yaml
  • helm/templates/redis.yaml
  • helm/templates/tests/test-connection.yaml
  • helm/values.yaml
  • pyproject.toml
  • sdk/python/pyproject.toml
  • sdk/python/uv.lock
  • uv.lock

RAGFlow Helm Chart 提供了一种生产就绪的编排机制，用于将完整的 RAG 引擎部署到 Kubernetes 集群上。它通过 values.yaml 提供统一的配置接口，抽象了管理多个异构持久化层（MySQL、Redis、MinIO）和文档检索引擎（Infinity、Elasticsearch 或 OpenSearch）的复杂性。

部署架构

Helm 部署镜像了 RAGFlow 的多层架构，将容器服务转换为 Kubernetes 工作负载。主要的应用逻辑位于 ragflow 部署中，它与一组有状态服务通信，这些服务通常部署为 StatefulSets，以确保数据持久性和稳定的网络标识符。

代码到系统的映射

下图将 Kubernetes 资源定义映射到核心系统组件及其对应的容器配置。

图：Kubernetes 资源到代码实体的映射

RAGFlow · 代码到系统的映射 · 图 1
RAGFlow · 代码到系统的映射 · 图 1

来源： helm/values.yaml:13-123, helm/templates/ragflow.yaml:1-100, helm/templates/ragflow.yaml:67-71

Helm Chart 结构

该 Chart 被组织成多个模板，用于处理核心 RAGFlow 应用及其强制依赖项。

组件资源类型用途
RAGFlowDeployment主应用服务器和任务执行器。包含 Nginx 边车逻辑和可选的 Admin Server helm/templates/ragflow.yaml:2-56。
InfinityStatefulSet用于向量和全文搜索的 AI 原生数据库。默认文档引擎 helm/values.yaml:20-20, helm/values.yaml:124-138。
MySQLStatefulSet元数据的关系型存储。使用 mysql:8.0.39 helm/values.yaml:209-214。
RedisStatefulSet使用 valkey/valkey:8 进行任务排队（Redis Streams）和缓存 helm/values.yaml:225-231。
MinIOStatefulSet用于原始文档的 S3 兼容对象存储 helm/values.yaml:193-208。
ElasticsearchStatefulSet备选文档引擎（版本 8.11.3）helm/values.yaml:139-165。
数据流与服务交互

该部署确保 Python 后端和任务执行器能够通过从 env-config 密钥注入的环境变量，一致地访问存储层 helm/templates/ragflow.yaml:77-79。

图：Helm 服务互联

RAGFlow · 数据流与服务交互 · 图 2
RAGFlow · 数据流与服务交互 · 图 2

来源： helm/templates/ragflow.yaml:92-149, helm/values.yaml:13-60, docker/docker-compose-base.yml:1-230

配置与自定义

values.yaml 接口

values.yaml 文件充当主要配置源，直接映射到 RAGFlow 容器所需的环境变量 helm/values.yaml:1-12。关键配置区域包括：

  1. 文档引擎选择：用户可以通过设置 env.DOC_ENGINE 在 infinity、elasticsearch 或 opensearch 之间切换 helm/values.yaml:13-21。
  2. 服务覆盖：ragflow.service_conf 块允许用户为容器内部的 local.service_conf.yaml 提供 YAML 格式的覆盖配置 helm/values.yaml:87-92。
  3. 大语言模型（LLM）工厂：可以通过覆盖 llm_factories 块来注册自定义的大语言模型（LLM）提供商，该块会被挂载到 /ragflow/conf/llm_factories.json helm/templates/ragflow.yaml:72-76。
存储与持久化

持久化通过 PersistentVolumeClaims 进行管理。该 Chart 支持为每个后端服务设置特定的 storageClassName 和 capacity helm/values.yaml:130-132。对于 Redis，如果使用 Kubernetes 1.32+ 版本，可以配置 PVC 的 retentionPolicy helm/values.yaml:237-241。

Ingress 与网络

ingress.yaml 模板提供了标准路由。请注意，Ingress 控制器中的 client_max_body_size 应与 MAX_CONTENT_LENGTH（默认 128M）匹配，以支持大文件上传 helm/values.yaml:66-70。ragflow 部署暴露了三个端口：

  • 80 (http)：主 Web 界面。
  • 9380 (http-api)：后端 API。
  • 9381 (admin)：管理服务（通过 --enable-adminserver 参数启用）helm/templates/ragflow.yaml:44-56。

资源管理

该 Chart 允许对资源请求和限制进行精细控制。为生产环境中的重负载组件提供了默认配置：

  • Elasticsearch/OpenSearch：默认请求 4 个 CPU 和 16Gi 内存 helm/values.yaml:160-162, helm/values.yaml:187-189。
  • Redis/Valkey：配置了 maxmemory 限制为 128mb 和 allkeys-lru 逐出策略 helm/templates/redis.yaml:63-63。
  • Infinity：默认存储容量设置为 5Gi helm/values.yaml:132-132。

构建与依赖集成

Kubernetes 部署依赖于通过项目 Dockerfile Dockerfile:1-152 构建的镜像。构建过程利用 uv 进行高性能的 Python 依赖管理 Dockerfile:68-81，并包含预下载的资源，例如 nltk_data 和来自 HuggingFace 的特定模型快照 Dockerfile:10-23。

来源：

  • helm/values.yaml:1-266
  • helm/templates/ragflow.yaml:1-150
  • helm/templates/redis.yaml:1-135
  • docker/docker-compose-base.yml:1-230
  • Dockerfile:1-152