在Kubernetes中部署Open WebUI:使用Helm Chart配置持久化存储与GPU调度

文章导读
如果已经确定要在 Kubernetes 里跑 Open WebUI,最要紧的是想清楚两件事:Open WebUI 的持久化数据放在哪里,以及 GPU 真正给谁用。Open WebUI 本身是前端和网关,它默认把 SQLite 数据库和上传文件存在应用目录下;而 GPU 主要消耗在模型推理的后端服务上,比如 vLLM、Ollama 这类 OpenAI 兼容接口。下面按前置条件、安装配置、验证、失败回
📋 目录
  1. Ⅰ 前置条件检查
  2. Ⅱ 使用 Helm 安装并配置持久化
  3. Ⅲ 配置 GPU 调度
  4. Ⅳ 验证安装结果
  5. Ⅴ 失败时如何回退
A A

如果已经确定要在 Kubernetes 里跑 Open WebUI,最要紧的是想清楚两件事:Open WebUI 的持久化数据放在哪里,以及 GPU 真正给谁用。Open WebUI 本身是前端和网关,它默认把 SQLite 数据库和上传文件存在应用目录下;而 GPU 主要消耗在模型推理的后端服务上,比如 vLLM、Ollama 这类 OpenAI 兼容接口。下面按前置条件、安装配置、验证、失败回退四个阶段整理一套可执行的步骤。

前置条件检查

动手之前先确认集群具备以下条件,避免装完才发现调度不上去:

  • Kubernetes 集群可写,并且有 Helm 客户端:helm version 能正常返回。
  • 如果要用 GPU 调度,节点上必须已经安装 NVIDIA 驱动和 NVIDIA Device Plugin,并且可以用 kubectl describe node <节点名> 看到类似 nvidia.com/gpu 的可分配资源。没有这一项,后面给 Pod 写资源限制也不会生效。
  • 确认集群有没有默认 StorageClass。执行 kubectl get storageclass,如果输出为空,需要预先准备一个可用的 StorageClass,否则 PVC 会一直处于 Pending 状态。

上面三项里,GPU 检查是很多人跳过的步骤。Device Plugin 没有就绪时,即使 YAML 里写了 GPU 资源,Pod 也会卡在 Pending,并且描述信息里不会出现明确的“节点无 GPU”提示,排查起来反而费时间。

使用 Helm 安装并配置持久化

Open WebUI 官方 Chart 的 values 里,持久化主要涉及 persistence.enabled、persistence.size、persistence.storageClass。建议创建一个独立的 values 文件,而不是在命令行里堆一堆 `--set`,后续升级和回退都更可控。

# open-webui-values.yaml
persistence:
  enabled: true
  size: 10Gi
  storageClass: ""   # 留空表示使用默认 StorageClass;如果需要指定,填集群里的名称
service:
  type: ClusterIP   # 外部访问用 Ingress 暴露,不要直接开 LoadBalancer

执行安装:

helm repo add open-webui https://helm.openwebui.com/
helm repo update
helm install open-webui open-webui/open-webui -n open-webui `--create-namespace` -f open-webui-values.yaml

关于 storageClass 的取舍:如果集群里只有 local-path 或 hostPath 这类单节点存储,PVC 可以绑定,但 Open WebUI 的 Pod 会被钉在那台节点上,重启后不能漂移。多节点集群建议使用网络存储或 CSI 驱动,避免 Pod 被调度到别的节点后数据目录为空。这个选择没有绝对对错,但需要结合集群实际情况确认。

配置 GPU 调度

这里要分清楚:Open WebUI 前端 Pod 通常不需要 GPU,给它配 GPU 是浪费。GPU 应该留给后端的推理服务,例如单独部署的 vLLM 或 Ollama。Open WebUI 通过 OPENAI_API_BASE_URL 这类环境变量连接外部推理端点,所以真正要调度的对象是后端服务的 Deployment。

以后端服务为例,在 Deployment 里这样请求 GPU:

在Kubernetes中部署Open WebUI:使用Helm Chart配置持久化存储与GPU调度
resources:
  limits:
    nvidia.com/gpu: 1
  requests:
    nvidia.com/gpu: 1
nodeSelector:
  nvidia.com/gpu.present: "true"

如果希望 Open WebUI 的 Pod 和推理服务尽量靠近,可以在 Open WebUI 的 values 里加 nodeSelector 或 topologySpreadConstraints,但这不是硬性要求。“负载高时前端会不会拖垮 GPU 节点”这类问题,取决于推理服务的资源隔离做得如何,和 Open WebUI 放在哪台机器没有直接关系。

验证安装结果

安装完成后按以下顺序检查,每一项都有明确的通过标准:

  1. Pod 状态:kubectl get pod -n open-webui 应显示 Running 或 Ready,而不是 CrashLoopBackOff。
  2. PVC 状态:kubectl get pvc -n open-webui 应显示 Bound。如果一直 Pending,去查 StorageClass 的 provisioner 是否可用。
  3. 数据目录挂载:kubectl exec -n open-webui deploy/open-webui -- ls /app/backend/data 能看到目录存在即可,不需要看到具体文件。这一步确认 PVC 真正挂载到了 Open WebUI 读取的路径。
  4. GPU 分配:kubectl describe pod <推理服务Pod名> 的 Events 里应包含成功分配 nvidia.com/gpu 的记录;同时到推理服务日志里确认显存已初始化。
  5. 业务联通:在 Open WebUI 管理后台添加一个指向推理服务地址的 OpenAI 兼容连接,发送一条短消息。能收到回复才算链路完整。

最后一步最容易忽略:即使 Open WebUI 页面能打开,如果后端连接配置不对,发送消息时会直接报错。验证业务链路一定放在 UI 验证之后。

失败时如何回退

Helm 管理的部署回退比较简单。如果是配置写错导致启动失败,直接用 Helm 回滚:

helm list -n open-webui
helm rollback open-webui <上一个修订号> -n open-webui

如果决定彻底移除部署:

helm uninstall open-webui -n open-webui

注意一个边界:Helm uninstall 默认不会删除 PVC,数据会保留在存储里。这是故意设计的,避免误删数据。如果确认要连数据一起清理,需要手动删除 PVC,但删除后数据无法恢复,执行前要确认没有其他服务引用同一个卷。

如果 GPU 调度不上去,先不要改 Helm values。优先回到前置检查,确认节点上可分配的 nvidia.com/gpu 资源数量不为零,并且后端 Pod 没有把 GPU 请求写进 requests 之外的错误字段。最常见的失败原因是 YAML 里只写了 limits 没写 requests,或者节点亲和性写反了。