3.5 · Kubernetes 部署（Kubernetes Deployment）

Kubernetes 部署（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/3.5-kubernetes-deployment

翻译时间：2026-06-09T16:07:53.534Z

翻译模型：deepseek-chat

原文字符数：7771

项目：Open WebUI (open-webui)

---

Kubernetes 部署

相关源文件

以下文件为本 Wiki 页面的生成提供了上下文：

• .env.example
• .github/workflows/build-release.yml
• .github/workflows/docker-build.yaml
• .github/workflows/format-backend.yaml
• .github/workflows/format-build-frontend.yaml
• .github/workflows/lint-backend.disabled
• .github/workflows/lint-frontend.disabled
• .github/workflows/release-pypi.yml
• Dockerfile
• Makefile
• backend/dev.sh
• backend/start.sh
• backend/start_windows.bat
• confirm_remove.sh
• docker-compose.api.yaml
• docker-compose.data.yaml
• docker-compose.gpu.yaml
• docker-compose.yaml
• hatch_build.py
• run-compose.sh
• src/lib/constants.ts
• update_ollama_models.sh
• vite.config.ts

本文档记录了 Open WebUI 在 Kubernetes 环境中的技术实现与配置。涵盖部署架构、Helm Chart 配置、持久化存储需求以及分布式环境下的扩缩容考量。

---

部署架构

Open WebUI 以容器化 FastAPI 应用的形式部署，同时提供 SvelteKit 前端和 Python 后端服务 Dockerfile:43-46。在 Kubernetes 环境中，该应用通常作为由 Helm Chart 管理的 Deployment 运行，并与持久化存储交互以保存数据库和缓存数据。

Kubernetes 实体映射

下图展示了 Kubernetes 资源空间与内部代码实体及数据流之间的对应关系。

graph TD
    subgraph "Kubernetes集群"
        Ingress["Ingress Controller<br/>(nginx/traefik)"]
        Service["Service<br/>(ClusterIP/NodePort)"]

        subgraph "Pod:open-webui"
            Main["FastAPI App<br/>open_webui.main:app"]
            Static["SPAStaticFiles<br/>(main.py)"]
            Socket["Socket.IO Server<br/>(socket.main:app)"]
        end

        PVC["PersistentVolumeClaim<br/>(/app/backend/data)"]
    end

    subgraph "外部依赖"
        Ollama["Ollama API<br/>(OLLAMA_BASE_URL)"]
        OpenAI["OpenAI/External APIs"]
        Redis["Redis<br/>(用于多节点同步)"]
    end

    Ingress -->|"HTTP/WS"| Service
    Service -->|"Port 8080"| Main

    Main --> Static
    Main --> Socket

    Main -->|"SQLite/Uploads"| PVC
    Main -->|"模型请求"| Ollama
    Main -->|"模型请求"| OpenAI
    Socket <-->|"Pub/Sub"| Redis

来源： Dockerfile:65-77，backend/start.sh:83-87，docker-compose.yaml:11-29

---

配置值

部署行为由传递给容器的环境变量驱动。start.sh 脚本负责初始化环境，包括在未提供 WEBUI_SECRET_KEY 时生成密钥 backend/start.sh:25-36。

Kubernetes 关键环境变量

变量	描述	默认值/来源
PORT	FastAPI 应用的容器端口	8080 backend/start.sh:23
OLLAMA_BASE_URL	Ollama 服务的内部或外部 URL	/ollama Dockerfile:76
WEBUI_SECRET_KEY	JWT/会话签名密钥。所有副本必须保持一致。	由 start.sh 生成 backend/start.sh:31
DATA_DIR	持久化数据路径（SQLite、缓存、上传文件）	/app/backend/data Dockerfile:161
UVICORN_WORKERS	每个 Pod 的工作进程数	1 backend/start.sh:73
WEB_LOADER_ENGINE	网页抓取引擎（例如 playwright）	可配置 backend/start.sh:7-15

来源： backend/start.sh:7-36，Dockerfile:76-161

---

持久卷声明（PVC）

Open WebUI 需要为 Dockerfile 中定义的多个关键目录提供持久化存储。如果没有 PVC，Pod 重启后用户账户、聊天历史和已下载模型将丢失。

存储路径与数据流

graph LR
    subgraph "容器文件系统"
        DB["/app/backend/data/webui.db<br/>(SQLite 数据库)"]
        Cache_Embed["/app/backend/data/cache/embedding<br/>(HF 模型)"]
        Cache_Whisper["/app/backend/data/cache/whisper<br/>(TTS 模型)"]
        Uploads["/app/backend/data/uploads<br/>(RAG 文档)"]
    end

    subgraph "代码实体"
        RAG["RAG 管道<br/>(RAG_EMBEDDING_MODEL)"]
        Config["环境配置<br/>(WEBUI_SECRET_KEY)"]
    end

    DB --- Config
    Cache_Embed --- RAG
    Uploads --- RAG

    DB -.->|"挂载到"| PVC["K8s PersistentVolume"]
    Cache_Embed -.->|"挂载到"| PVC
    Uploads -.->|"挂载到"| PVC

来源： Dockerfile:89-102，Dockerfile:161，backend/start.sh:20-36

---

Ingress 与网络

Kubernetes Ingress 必须配置为支持流式传输和 WebSocket 的长连接。

WebSocket 支持

后端使用 WebSocket 实现实时更新和流式响应。在 Kubernetes 中，这些服务的 API 端点相对于基础 URL 定义 src/lib/constants.ts:8-14。Ingress 控制器（如 NGINX）需要特定的注解来处理 Upgrade 头：

• nginx.org/websocket-services："open-webui"
• proxy-read-timeout："600"（防止长时间 LLM 生成期间超时）

代理头

应用使用 FORWARDED_ALLOW_IPS 来确定信任哪些代理 IP 以处理 X-Forwarded-For 等头信息。在 Kubernetes 中，通常通过 start.sh 将其设置为 *，以适应动态的内部 IP 范围 backend/start.sh:86-87。

来源： src/lib/constants.ts:8-14，backend/start.sh:86-87

---

扩缩容与多节点同步

当 Open WebUI 扩展到多个 Pod（replicas > 1）时，需要同步实时事件。

Redis 用于分布式状态

标准部署使用本地内存处理 Socket.IO。对于 Kubernetes 水平扩缩容，必须提供 Redis 实例。这使得 Pod 能够跨整个集群广播事件（如聊天状态或协作笔记更新）。

会话一致性

• 密钥：WEBUI_SECRET_KEY 必须作为 Kubernetes Secret 提供，并在所有 Pod 间共享，以确保任何副本都能验证 JWT 令牌 backend/start.sh:83-87。
• 数据库：为实现高可用性，建议从默认的 SQLite 迁移到外部数据库（例如通过 DATABASE_URL 使用 PostgreSQL），因为 SQLite 不支持多个 Pod 安全地并发写入。

来源： backend/start.sh:83-87

---

资源管理

Dockerfile 提供了不同的构建目标，这些目标会影响 Kubernetes 中的资源请求：

• 仅 CPU：默认基础镜像，使用带有 CPU 索引的 torch Dockerfile:154。
• CUDA：通过 USE_CUDA=true 启用，需要 NVIDIA Container Runtime 并在 Pod 规范中设置 GPU 资源限制 Dockerfile:143-146。
• Ollama：可通过 USE_OLLAMA=true 在同一 Pod 中捆绑，该选项会在容器内以后台进程方式启动 ollama serve backend/start.sh:38-41。

来源： Dockerfile:4-9，Dockerfile:143-154，backend/start.sh:38-46，docker-compose.gpu.yaml:1-12