K8s(Kubernetes )是一个分布式的容器的管理平台,提供:

  • 负载均衡:将流量合理的分配到不同节点的容器上,从而使部署稳定。
  • 存储管理:自动挂载你选择的存储系统,例如本地存储、公共云提供商等
  • 自动部署和回滚:每次部署会分配一个版本号,创建新容器, 删除现有容器并将它们的所有资源用于新容器。
  • 自动分配资源(装箱计算):配置容器需要的 CPU 和内存 (RAM),K8s可以将这些容器按实际情况调度到你的节点上,以最佳方式利用你的资源。
  • 自我修复:Kubernetes 将重新启动失败的容器、替换容器、杀死不响应用户定义的运行状况检查的容器, 并且在准备好服务之前不将其通告给客户端。
  • 密钥存储和管理:允许你存储和管理敏感信息,例如密码、OAuth 令牌和 SSH 密钥。 你可以在不重建容器镜像的情况下部署和更新密钥和应用程序配置,也无需在堆栈配置中暴露密钥。

ragflow官方有提供单机部署的镜像,这里推荐使用Ragflow官方仓库中的helm进行部署

修改配置文件(values.yaml)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
# Based on docker compose .env file

# Global image pull secrets configuration
global:
# Global image repo prefix to render all images from a mirror/registry.
# Example: "registry.example.com/myproj"
# When set, template will replace the registry part of each image and keep the path.
# Leave empty to use per-image repositories as-is.
repo: ""
# Global image pull secrets for all pods
imagePullSecrets: []

env:
# The type of doc engine to use.
# Available options:
# - `elasticsearch` (default)
# - `infinity` (https://github.com/infiniflow/infinity)
# - `opensearch` (https://github.com/opensearch-project/OpenSearch)
# DOC_ENGINE: elasticsearch
DOC_ENGINE: infinity
# DOC_ENGINE: opensearch

# The version of Elasticsearch.
STACK_VERSION: "8.11.3"

# The password for Elasticsearch
ELASTIC_PASSWORD: infini_rag_flow_helm

# The password for OpenSearch.
# At least one uppercase letter, one lowercase letter, one digit, and one special character
OPENSEARCH_PASSWORD: infini_rag_flow_OS_01

# The password for MySQL
MYSQL_PASSWORD: infini_rag_flow_helm
# The database of the MySQL service to use
MYSQL_DBNAME: rag_flow
# External MySQL host (only required when mysql.enabled=false)
# MYSQL_HOST: ""
# External MySQL port (defaults to 3306 if not set)
# MYSQL_PORT: "3306"
# External MySQL user (only when mysql.enabled=false), default is root if omitted
# MYSQL_USER: "root"

# The username for MinIO.
MINIO_ROOT_USER: rag_flow
# The password for MinIO
MINIO_PASSWORD: infini_rag_flow_helm
# External MinIO host
# MINIO_HOST: ""
# External MinIO port (defaults to 9000 if not set)
# MINIO_PORT: "9000"

# The password for Redis
REDIS_PASSWORD: infini_rag_flow_helm
# External Redis host (only required when redis.enabled=false)
# REDIS_HOST: ""
# External Redis port (defaults to 6379 if not set)
# REDIS_PORT: "6379"

# The local time zone.
TZ: "Asia/Shanghai"

# Uncomment the following line if you have limited access to huggingface.co:
# HF_ENDPOINT: https://hf-mirror.com

# The maximum file size for each uploaded file, in bytes.
# You can uncomment this line and update the value if you wish to change 128M file size limit
# MAX_CONTENT_LENGTH: "134217728"
# After making the change, ensure you update `client_max_body_size` in nginx/nginx.conf correspondingly.

# The number of document chunks processed in a single batch during document parsing.
DOC_BULK_SIZE: 4

# The number of text chunks processed in a single batch during embedding vectorization.
EMBEDDING_BATCH_SIZE: 16

ragflow:
image:
repository: infiniflow/ragflow
tag: v0.27.0
pullPolicy: IfNotPresent
pullSecrets: []
# Optional service configuration overrides
# to be written to local.service_conf.yaml
# inside the RAGFlow container
# https://ragflow.io/docs/dev/configurations#service-configuration
service_conf:

# Optional yaml formatted override for the
# llm_factories.json file inside the RAGFlow
# container.
llm_factories:
# factory_llm_infos:
# - name: OpenAI-API-Compatible
# logo: ""
# tags: "LLM,TEXT EMBEDDING,SPEECH2TEXT,MODERATION"
# status: "1"
# llm:
# - llm_name: my-custom-llm
# tags: "LLM,CHAT,"
# max_tokens: 100000
# model_type: chat
# is_tools: false

# Kubernetes configuration
deployment:
strategy:
resources:
service:
# Use LoadBalancer to expose the web interface externally
type: NodePort
nodePort: 30800
admin:
# Enable Admin Service
enabled: true
# Admin Service port configuration
port: 9381
# Admin Service type
serviceType: ClusterIP
api:
service:
enabled: true
type: ClusterIP

infinity:
image:
repository: infiniflow/infinity
tag: v0.7.3-x64-v3
pullPolicy: IfNotPresent
pullSecrets: []
storage:
className: managed-nfs-storage
capacity: 5Gi
deployment:
strategy:
resources:
service:
type: ClusterIP

elasticsearch:
image:
repository: elasticsearch
tag: "8.11.3"
pullPolicy: IfNotPresent
pullSecrets: []
initContainers:
alpine:
repository: alpine
tag: latest
pullPolicy: IfNotPresent
busybox:
repository: busybox
tag: latest
pullPolicy: IfNotPresent
storage:
className: managed-nfs-storage
capacity: 20Gi
deployment:
strategy:
resources:
requests:
cpu: "4"
memory: "16Gi"
service:
type: ClusterIP

opensearch:
image:
repository: opensearchproject/opensearch
tag: 2.19.1
pullPolicy: IfNotPresent
pullSecrets: []
initContainers:
alpine:
repository: alpine
tag: latest
pullPolicy: IfNotPresent
busybox:
repository: busybox
tag: latest
pullPolicy: IfNotPresent
storage:
className: managed-nfs-storage
capacity: 20Gi
deployment:
strategy:
resources:
requests:
cpu: "4"
memory: "16Gi"
service:
type: ClusterIP

minio:
enabled: true
image:
repository: pgsty/silo
tag: RELEASE.2026-08-06T00-00-00Z
pullPolicy: IfNotPresent
pullSecrets: []
storage:
className: managed-nfs-storage
capacity: 5Gi
deployment:
strategy:
resources:
service:
type: ClusterIP

mysql:
enabled: true
image:
repository: mysql
tag: 8.0.40
pullPolicy: IfNotPresent
pullSecrets: []
storage:
className: managed-nfs-storage
capacity: 5Gi
deployment:
strategy:
resources:
service:
type: ClusterIP

redis:
enabled: true
image:
repository: valkey/valkey
tag: 8
pullPolicy: IfNotPresent
pullSecrets: []
storage:
className: managed-nfs-storage
capacity: 5Gi
persistence:
enabled: true
# Set's the retention policy for the persistent storage (only available in k8s 1.32 or later)
# https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#persistentvolumeclaim-retention
# retentionPolicy:
# whenDeleted: Delete
# whenScaled: Delete
deployment:
strategy:
resources:
service:
type: ClusterIP


# This block is for setting up web service ingress. For more information, see:
# https://kubernetes.io/docs/concepts/services-networking/ingress/
ingress:
enabled: false
className: ""
annotations: {}
# kubernetes.io/ingress.class: nginx
# kubernetes.io/tls-acme: "true"
hosts:
- host: chart-example.local
paths:
- path: /
pathType: ImplementationSpecific
tls: []
# - secretName: chart-example-tls
# hosts:
# - chart-example.local

主要修改项:

  1. 服务类型

    1
    2
    3
    service:
    enabled: true
    type: ClusterIP

    仅限集群内访问:该服务无法从集群外部(如公网或外部网络)直接访问,专门用于集群内部 Pod 之间的通信。

  2. 存储类,查看集群支持的存储类:

    1
    2
    3
    4
    5
    [root@k8s-master ~]# kubectl get storageclasses -o custom-columns=NAME:.metadata.name,RECLAIM_POLICY:.reclaimPolicy
    NAME RECLAIM_POLICY
    managed-nfs-storage Retain
    moosefs-block-storage Delete
    moosefs-storage Delete

    这里选择:

    1
    2
    storage:
    className: managed-nfs-storage

    1. managed-nfs-storage 对应 Retain(保留)策略

    • 含义:当删除与该 StorageClass 绑定的 PVC 时,底层的 PV 和实际存储数据不会被删除。PV 的状态会变为 Released(已释放),数据完好保留。
    • 适用场景:这是一种安全的数据保护机制。通常用于生产环境中的核心业务数据库或重要文件存储,防止因误删 PVC 或执行 kubectl delete namespace 等操作导致重要数据永久丢失。

    2. moosefs-block-storage 对应 Delete(删除)策略

    • 含义:当删除 PVC 时,底层的 PV 以及 MooseFS 上的块存储资源会被自动级联删除,数据将永久丢失。
    • 适用场景:通常用于测试环境、临时缓存数据、日志文件等不需要长期保留的数据。这种策略可以自动清理存储资源,避免产生闲置成本。

    3. moosefs-storage 对应 Delete(删除)策略

    • 含义:与上面的块存储类似,当删除 PVC 时,MooseFS 上的普通存储资源和数据也会被自动级联删除
    • 适用场景:同样适用于非关键业务数据、临时文件等,依赖自动清理机制来管理存储生命周期。
模板文件修改(增加service-name)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: {{ include "ragflow.fullname" . }}-infinity
labels:
{{- include "ragflow.labels" . | nindent 4 }}
app.kubernetes.io/component: infinity
spec:
serviceName: {{ include "ragflow.fullname" . }}-infinity
replicas: 1
selector:
matchLabels:
{{- include "ragflow.selectorLabels" . | nindent 6 }}
app.kubernetes.io/component: infinity
{{- with .Values.infinity.deployment.strategy }}
updateStrategy:
{{- . | toYaml | nindent 4 }}
{{- end }}

执行脚本

1
helm install ragflow ./helm -n ragflow --create-namespace

更新配置

1
helm upgrade ragflow ./helm -n ragflow

查看pod启动状态

1
kubectl get pods -n ragflow -w

查看pod日志

1
2
kubectl logs -f ragflow-56d494b667-8nl8l -n ragflow
kubectl describe pod ragflow-56d494b667-8nl8l -n ragflow

遇到问题1:前期存储类设置错了,现在修改

尝试将名为 ragflow-infinity 的 PVC 的 StorageClassNamemanaged-nfs-storage 更改为 moosefs-storage

在 Kubernetes 中,PVC 一旦创建,其 spec 中的大部分字段(包括 StorageClassName)都是不可变的(Immutable),唯一允许修改的字段是已绑定 PVC 的 resources.requests(即存储容量)。因此,你无法通过简单的 helm upgradekubectl apply 来直接更改它。

要解决这个问题并成功切换存储类,你需要删除旧的 PVC 并重新创建它。以下是具体的操作步骤:

  1. 备份数据(非常重要)
    删除 PVC 会导致其绑定的底层存储卷被释放(取决于 PV 的回收策略 persistentVolumeReclaimPolicy)。如果里面存有重要数据,请务必先将数据备份或拷贝出来。

  2. 删除旧的 PVC
    使用 kubectl 删除当前的 PVC:

    bash

    编辑

    1
    1kubectl delete pvc ragflow-infinity

    注意:如果 PVC 处于 Terminating 状态卡住,通常是因为有 Pod 还在挂载它。你需要先删除或停止使用该 PVC 的 Pod。

  3. 重新部署/升级
    PVC 删除后,重新运行你的 Helm 升级或安装命令:

    bash

    编辑

    1
    1helm upgrade ragflow ... # 你的原始升级命令

    此时,Helm 会根据新的配置(moosefs-storage)重新创建一个全新的 PVC。

遇到问题2:NSTALLATION FAILED: cannot re-use a name that is still in use

  1. 清理残留的 Helm 发布记录

Helm 记录了 ragflow 这个安装任务,即使它失败了。你需要先清除这个记录,才能重新安装。

1
1helm uninstall ragflow -n ragflow

执行后,Helm 会尝试清理所有与 ragflow 相关的资源。即使有些资源(如 PVC)已经不存在,这个命令也能清除 Helm 自身的记录。

  1. 确认并删除所有残留的 PVC

你的 values.yaml 文件中定义了多个组件(infinity, minio, mysql 等)都使用 PVC。上次的失败安装可能已经创建了部分 PVC。

首先,检查 ragflow 命名空间下所有残留的 PVC:

1
1kubectl get pvc -n ragflow

然后,删除所有与 ragflow 相关的 PVC。你可以逐个删除,也可以使用一条命令全部删除:

1
2
1# 警告:此命令会删除 ragflow 命名空间下的所有 PVC,请确保其中没有重要数据
2kubectl delete pvc -n ragflow --all
  1. 重新安装

完成以上清理步骤后,你的环境就恢复到了“干净”状态。现在可以重新运行安装命令:编辑

1
1helm install ragflow . -n ragflow

这次安装将会根据你 values.yaml 中新的 moosefs-storage 配置,创建全新的 PVC