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

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

复杂文档理解与引用检索 · 本章是 RAGFlow DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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
翻译时间：2026-05-27T08:44:31.525Z
翻译模型：deepseek-chat
原文字符数：8402
项目：RAGFlow (ragflow)

--- 好的，作为一名资深技术文档翻译专家，我将严格遵循您的要求，对这份 DeepWiki 技术文档进行全文翻译和润色。

---

Kubernetes 和 Helm 部署

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

  • .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 资源到代码实体的映射

graph TD
    subgraph "Kubernetes 空间"
        H_VALS["values.yaml"]
        H_ENV["env.yaml (Secret)"]
        H_RF["ragflow.yaml (Deployment)"]
        H_INF["infinity.yaml (StatefulSet)"]
        H_RED["redis.yaml (StatefulSet)"]
        H_ING["ingress.yaml (Ingress)"]
    end

    subgraph "代码实体空间"
        C_CONF["local.service_conf.yaml"]
        C_ENV[".env / 环境变量"]
        C_APP["ragflow_server.py"]
        C_TASK["rag/svc/task_executor.py"]
        C_DB["MySQL / Infinity / Valkey"]
    end

    H_VALS -- "填充" --> H_ENV
    H_ENV -- "注入到" --> H_RF
    H_RF -- "运行" --> C_APP
    H_RF -- "运行" --> C_TASK
    H_INF -- "提供" --> C_DB
    H_RED -- "提供" --> C_DB
    H_VALS -- "覆盖" --> C_CONF

来源： 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 服务互联

graph LR
    subgraph "前端访问"
        ING["Ingress"] --> SVC_RF["ragflow-svc"]
    end

    subgraph "应用层"
        SVC_RF --> POD_RF["ragflow-pod"]
        POD_RF -- "Redis Streams" --> POD_RED["redis-pod"]
    end

    subgraph "持久化层"
        POD_RF -- "向量搜索" --> POD_INF["infinity-pod"]
        POD_RF -- "元数据" --> POD_SQL["mysql-pod"]
        POD_RF -- "对象存储" --> POD_MIN["minio-pod"]
    end

    POD_RED -- "任务队列" --> POD_RF

来源： 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