Kubernetes 与 Helm 部署

在任何主流的 Kubernetes 发行版（如 EKS、AKS、GKE、OpenShift、Rancher 或自建集群）上，使用官方的 Open WebUI Helm Chart 进行生产级部署。

前提条件

在继续之前，请确保您已配置好共享基础设施组件要求——PostgreSQL、Redis、向量数据库、共享存储和内容提取服务。

何时选择此部署模式

• 您的组织已经在运行 Kubernetes，且具备成熟的平台工程技术栈。
• 您需要通过声明式基础设施即代码（IaC）实施 GitOps 持续交付工作流。
• 您需要高级的水平扩展（HPA）、平滑滚动更新和 Pod 破坏预算（Pod Disruption Budgets）。
• 您正在为关键业务环境中的数百到数千名活跃用户进行大规模部署。

架构图

Helm Chart 配置

# 添加 Helm 仓库
helm repo add open-webui https://open-webui.github.io/helm-charts
helm repo update

# 使用自定义的 values.yaml 进行安装
helm install openwebui open-webui/open-webui -f values.yaml

您的 values.yaml 文件应该覆盖默认值以指向您的共享基础设施组件。Helm Chart 针对许多常见设置提供了专用的配置项——在可用时，请使用这些配置项代替原始的环境变量：

# 示例 values.yaml 覆写（完整的 Schema 配置参见 Helm Chart 官方文档）
replicaCount: 3

# -- 数据库：配置使用外部 PostgreSQL 实例
databaseUrl: "postgresql://user:password@db-host:5432/openwebui"

# -- WebSocket 与 Redis：Helm Chart 支持在集群内部自动部署 Redis，
#    或者您也可以通过 websocket.url 指向外部的 Redis 实例
websocket:
  enabled: true
  manager: redis
  # url: "redis://my-external-redis:6379/0"  # 若使用外部 Redis，请取消注释并配置
  redis:
    enabled: true  # 若使用外部 Redis，请将其设为 false

# -- Tika 文档提取：支持在集群内部自动部署 Tika
tika:
  enabled: true

# -- Ollama：若使用外部模型 API 或独立的 Ollama 部署，请将其关闭
ollama:
  enabled: false

# -- 持久化存储：多副本部署下请使用对象存储来代替本地的 PVC
persistence:
  provider: s3  # 或选择 "gcs" / "azure"
  s3:
    bucket: "my-openwebui-bucket"
    region: "us-east-1"
    accessKeyExistingSecret: "openwebui-s3-creds"
    accessKeyExistingAccessKey: "access-key"
    secretKeyExistingSecret: "openwebui-s3-creds"
    secretKeyExistingSecretKey: "secret-key"
  # -- 或者，使用共享文件系统 (RWX PVC) 来代替对象存储：
  # provider: local
  # accessModes:
  #   - ReadWriteMany
  # storageClass: "efs-sc"

# -- Ingress 路由：如果通过 Ingress 控制器向外暴露服务，请进行如下配置
ingress:
  enabled: true
  class: "nginx"
  host: "ai.example.com"
  tls: true
  existingSecret: "openwebui-tls"
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "open-webui-session"
    nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"

# -- 针对其他没有专用 Chart 配置项的变量，在此处统一覆写
extraEnvVars:
  - name: WEBUI_SECRET_KEY
    valueFrom:
      secretKeyRef:
        name: openwebui-secrets
        key: secret-key
  - name: VECTOR_DB
    value: "pgvector"
  - name: PGVECTOR_DB_URL
    valueFrom:
      secretKeyRef:
        name: openwebui-secrets
        key: database-url
  - name: UVICORN_WORKERS
    value: "1"
  - name: ENABLE_DB_MIGRATIONS
    value: "false"
  - name: RAG_EMBEDDING_ENGINE
    value: "openai"

水平扩展策略

• 水平 Pod 自动伸缩 (HPA)：基于 CPU 利用率或内存占用进行自动弹性伸缩。保持每个 Pod 的 UVICORN_WORKERS=1，并让 Kubernetes 全权管理副本数量。
• 资源请求与限制 (Requests/Limits)：设置合理的 CPU 和内存 Request，以确保调度器能正确地分配 Pod，并确保 HPA 具有准确的度量指标。
• Pod 破坏预算 (PDB)：配置 PDB，以确保在发生主动驱逐（如节点排空、集群升级）期间，集群中始终保持最少数量的可重用 Pod 实例。

升级流程

升级时的关键流程控制

当运行多个 Pod 副本时，您在每次升级时必须严格遵守以下步骤流程：

1. 将 Deployment 副本数缩容至 1 个副本（replicaCount: 1）。
2. 应用新的容器镜像版本（确保此时该单一副本上设置了 ENABLE_DB_MIGRATIONS=true）。
3. 耐心等待该 Pod 完全健康就绪（这意味着底层的数据库迁移已完全顺利结束）。
4. 将 Deployment 重新扩容至您所期望的副本数量（此时其他扩展出来的 Pod 副本应保持 ENABLE_DB_MIGRATIONS=false）。

跳过此流程，极易因为并发的数据迁移而导致数据库损坏。

关键注意事项

注意事项	细节详情
存储配置	上传的文件必须使用 ReadWriteMany (RWX) 共享文件系统（如 EFS, CephFS, NFS）或对象存储（如 S3, GCS, Azure Blob）。ReadWriteOnce（RWO）类型的卷在多 Pod 部署下无法正常工作。
Secrets 秘钥	将敏感凭证安全地存储在 Kubernetes Secrets 中，并通过 secretKeyRef 进行引用。对于 GitOps 交付流，建议与外部 Secret 编排器（如 External Secrets, Sealed Secrets）进行深度集成。
数据库	生产环境推荐使用外部托管的 PostgreSQL 服务（如 RDS, Cloud SQL, Azure DB）。虽然集群内自建的 PostgreSQL Operator（如 CloudNativePG, Zalando）可行，但会增加额外的日常运维负担。
Redis 服务	对于大多数部署，将单个 Redis 实例配置 timeout 1800 和 maxclients 10000 即可完全满足性能需求。只有在 Redis 本身需要高可用时，才需要配置 Redis Sentinel 哨兵模式或 Redis Cluster 集群。
网络延迟	保持所有服务组件在同一个可用区（Availability Zone）内运行。力求数据库网络延迟限制在 < 2 毫秒。合理审计网络策略（Network Policies），确保 Pod 可以顺畅连接到 PostgreSQL、Redis 和存储后端。

关于完整的 Helm 安装步骤，请参阅 快速入门指南。关于多副本部署故障排查，请参阅 多副本故障排查。

---

在规划企业级部署时需要帮助？ 我们的团队正与全球各地的组织紧密合作，设计并实施生产级的 Open WebUI 环境。

联系企业销售 → sales@openwebui.com