k8s上部署open-webUI

作者：吴业亮

博客：wuyeliang.blog.csdn.net

基于 Kubernetes (K8s) 部署 Open-WebUI（原 Open-ChatUI）是实现其高可用、可扩展部署的最佳方式。以下是完整的部署指南，包含资源定义、依赖配置、部署步骤 和关键优化。

一、前置条件

1. K8s 集群（1.24+ 版本，单节点/多节点均可）
2. kubectl 已配置并能访问集群
3. 集群内有持久化存储（如 PV/PVC 支持，如 hostPath、NFS、Ceph 等）
4. 可选：Ingress 控制器（如 Nginx Ingress）用于外部访问
5. 可选：Docker 镜像仓库（若需私有化部署镜像）

二、核心部署架构

Open-WebUI 核心依赖：

• Open-WebUI 应用容器（提供 Web 界面和 API）
• 持久化存储（保存配置、聊天记录、模型缓存）
• 可选：LLM 后端（如 Ollama、OpenAI 等，可独立部署或外部对接）

三、部署步骤

步骤 1：创建命名空间（可选）

为隔离资源，建议创建独立命名空间：

kubectl create namespace open-webui

步骤 2：创建持久化存储（PVC）

Open-WebUI 需要持久化存储保存配置和数据，创建 pvc.yaml：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: open-webui-pvc
  namespace: open-webui
spec:
  accessModes:
    - ReadWriteOnce  # 单节点读写，多节点可改用 ReadWriteMany（需存储支持）
  resources:
    requests:
      storage: 10Gi  # 根据实际需求调整
  # 若集群有存储类（StorageClass），取消注释并指定
  # storageClassName: "nfs-storage"  # 替换为你的存储类名称

应用 PVC：

kubectl apply -f pvc.yaml

步骤 3：部署 Open-WebUI Deployment

创建 deployment.yaml，核心配置如下：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: open-webui
  namespace: open-webui
spec:
  replicas: 1  # 初始1副本，高可用可调整为2+
  selector:
    matchLabels:
      app: open-webui
  template:
    metadata:
      labels:
        app: open-webui
    spec:
      containers:
      - name: open-webui
        # 官方镜像（支持AMD64/ARM64）
        image: ghcr.io/open-webui/open-webui:main
        imagePullPolicy: Always
        ports:
        - containerPort: 8080  # Open-WebUI默认端口
        env:
        # 核心环境变量配置
        - name: OLLAMA_BASE_URL
          value: "http://ollama-service:11434"  # 对接集群内Ollama（若部署）
        - name: OPENAI_API_KEY
          value: "your-openai-key"  # 可选：对接OpenAI
        - name: WEBUI_SECRET_KEY
          value: "your-secret-key"  # 自定义密钥，建议随机生成
        - name: ENABLE_SIGNUP
          value: "false"  # 关闭注册（生产环境建议）
        # 持久化存储挂载
        volumeMounts:
        - name: open-webui-storage
          mountPath: /app/backend/data  # Open-WebUI数据目录
        # 资源限制（根据集群配置调整）
        resources:
          requests:
            cpu: 500m
            memory: 1Gi
          limits:
            cpu: 2000m
            memory: 4Gi
        # 健康检查
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
      volumes:
      - name: open-webui-storage
        persistentVolumeClaim:
          claimName: open-webui-pvc

应用 Deployment：

kubectl apply -f deployment.yaml

步骤 4：创建 Service 暴露服务

创建 service.yaml，支持集群内访问或 NodePort 外部访问：

apiVersion: v1
kind: Service
metadata:
  name: open-webui-service
  namespace: open-webui
spec:
  selector:
    app: open-webui
  ports:
  - port: 80
    targetPort: 8080
    protocol: TCP
  type: NodePort  # 测试环境用NodePort，生产环境建议用ClusterIP+Ingress
  # type: ClusterIP  # 仅集群内访问

应用 Service：

kubectl apply -f service.yaml

步骤 5：（可选）Ingress 配置（生产环境）

若需外部域名访问，创建 ingress.yaml（需提前部署 Nginx Ingress）：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: open-webui-ingress
  namespace: open-webui
  annotations:
    # Nginx Ingress 注解
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/ssl-redirect: "true"  # 强制HTTPS
spec:
  ingressClassName: nginx  # 替换为你的IngressClass名称
  rules:
  - host: open-webui.example.com  # 替换为你的域名
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: open-webui-service
            port:
              number: 80
  tls:
  - hosts:
    - open-webui.example.com
    secretName: open-webui-tls  # 提前创建SSL证书Secret

创建 SSL 证书 Secret（示例）：

kubectl create secret tls open-webui-tls -n open-webui \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key

应用 Ingress：

kubectl apply -f ingress.yaml

步骤 6：（可选）部署 Ollama 作为 LLM 后端

若需在集群内部署 Ollama 对接 Open-WebUI，创建 ollama-deployment.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ollama
  namespace: open-webui
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ollama
  template:
    metadata:
      labels:
        app: ollama
    spec:
      containers:
      - name: ollama
        image: ollama/ollama:latest
        ports:
        - containerPort: 11434
        volumeMounts:
        - name: ollama-storage
          mountPath: /root/.ollama  # Ollama数据目录
        resources:
          requests:
            cpu: 1000m
            memory: 2Gi
          limits:
            cpu: 4000m
            memory: 8Gi
      volumes:
      - name: ollama-storage
        persistentVolumeClaim:
          claimName: ollama-pvc  # 需提前创建Ollama的PVC
---
apiVersion: v1
kind: Service
metadata:
  name: ollama-service
  namespace: open-webui
spec:
  selector:
    app: ollama
  ports:
  - port: 11434
    targetPort: 11434
  type: ClusterIP

创建 Ollama PVC：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: ollama-pvc
  namespace: open-webui
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi  # 模型存储需更大空间
  # storageClassName: "nfs-storage"

应用 Ollama 部署：

kubectl apply -f ollama-deployment.yaml

四、验证部署

1. 检查 Pod 状态：

kubectl get pods -n open-webui
# 正常输出应为 Running

2. 检查 Service 端口：

kubectl get svc -n open-webui
# NodePort 类型会显示端口（如 30080），可通过 NodeIP:Port 访问

3. 访问 Open-WebUI：
   • NodePort 方式：http://<NodeIP>:<NodePort>
   • Ingress 方式：https://open-webui.example.com

五、关键配置优化

1. 资源调整 ：根据集群规模调整 Deployment 的 resources（CPU/内存），避免资源不足。
2. 高可用 ：
   • 增加 Deployment replicas 数量（≥2）。
   • 使用 ReadWriteMany 类型的 PVC（如 NFS），支持多副本共享存储。
3. 环境变量扩展 ：
   • OLLAMA_BASE_URL：对接外部 Ollama 服务（如 http://ollama.example.com:11434）。
   • DEFAULT_MODEL：设置默认加载的模型（如 llama3）。
   • DISABLE_OLLAMA：仅对接 OpenAI 时设置为 true。
4. 日志收集：添加日志注解，对接 ELK/EFK 栈：

annotations:
  logging.k8s.io/fluentd-parser: json

5. 监控 ：通过 Prometheus + Grafana 监控 Pod 资源使用率，添加 prometheus.io/scrape: "true" 注解。

六、常见问题排查

1. Pod 启动失败 ：
   • 检查 PVC 是否绑定成功：kubectl get pvc -n open-webui。
   • 查看 Pod 日志：kubectl logs <pod-name> -n open-webui。
2. 无法访问 Ollama ：
   • 检查 Ollama Service 地址是否正确（ollama-service.open-webui.svc.cluster.local:11434）。
   • 测试集群内网络连通性：kubectl exec -it <open-webui-pod> -n open-webui -- curl http://ollama-service:11434。
3. Ingress 访问 404 ：
   • 检查 IngressClass 名称是否匹配：kubectl get ingressclasses。
   • 查看 Ingress 日志：kubectl logs -n ingress-nginx <nginx-ingress-pod>。

七、卸载部署

若需清理资源，执行：

kubectl delete ns open-webui
# 或单独删除资源
kubectl delete deployment,svc,pvc,ingress -n open-webui --all

以上部署方案兼顾了测试和生产环境，可根据实际需求（如仅对接 OpenAI、私有化镜像）调整配置。