如果已经确定要在 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:
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 放在哪台机器没有直接关系。
验证安装结果
安装完成后按以下顺序检查,每一项都有明确的通过标准:
- Pod 状态:
kubectl get pod -n open-webui应显示 Running 或 Ready,而不是 CrashLoopBackOff。 - PVC 状态:
kubectl get pvc -n open-webui应显示 Bound。如果一直 Pending,去查 StorageClass 的 provisioner 是否可用。 - 数据目录挂载:
kubectl exec -n open-webui deploy/open-webui -- ls /app/backend/data能看到目录存在即可,不需要看到具体文件。这一步确认 PVC 真正挂载到了 Open WebUI 读取的路径。 - GPU 分配:
kubectl describe pod <推理服务Pod名>的 Events 里应包含成功分配 nvidia.com/gpu 的记录;同时到推理服务日志里确认显存已初始化。 - 业务联通:在 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,或者节点亲和性写反了。