3.2 · Docker 部署选项（Docker Deployment Options）

Docker 部署选项（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/3.2-docker-deployment-options

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

翻译模型：deepseek-chat

原文字符数：10101

项目：Open WebUI (open-webui)

---

Docker 部署选项

相关源文件

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

• .env.example
• .github/workflows/integration-test.disabled
• Dockerfile
• Makefile
• backend/dev.sh
• backend/open_webui/retrieval/web/firecrawl.py
• backend/open_webui/retrieval/web/utils.py
• backend/open_webui/storage/provider.py
• backend/open_webui/test/apps/webui/storage/test_provider.py
• backend/requirements-min.txt
• backend/requirements.txt
• backend/start.sh
• backend/start_windows.bat
• confirm_remove.sh
• docker-compose.api.yaml
• docker-compose.data.yaml
• docker-compose.gpu.yaml
• docker-compose.playwright.yaml
• docker-compose.yaml
• pyproject.toml
• run-compose.sh
• src/lib/constants.ts
• update_ollama_models.sh
• uv.lock

本文档涵盖了 Open WebUI 基于 Docker 的部署配置，包括容器镜像变体、Docker Compose 编排、卷管理以及多服务部署。有关环境变量配置，请参阅环境配置。有关 Docker 之外的通用安装方法，请参阅安装方法。

容器镜像变体

Open WebUI 提供多种 Docker 镜像变体，以支持不同的部署场景和硬件架构。

基础镜像

主要的生产镜像包含完整的前后端集成应用栈：

ghcr.io/open-webui/open-webui:main

该镜像包含：

• 预构建的 SvelteKit 前端资源 Dockerfile:27-44
• 带有完整依赖集的 FastAPI 后端 Dockerfile:46-161
• 嵌入式 SQLite 数据库支持 Dockerfile:191-201
• ChromaDB 向量数据库支持 Dockerfile:120-121
• 所有文档处理库 Dockerfile:127-133

架构支持：该镜像为多种架构构建，包括 linux/amd64 和 linux/arm64。通过固定 torch<=2.9.1 来避免 SIGILL 错误，从而包含针对 Raspberry Pi 4 等 ARM 设备的特定优化 Dockerfile:145。

镜像构建参数

Dockerfile 支持多个构建时参数，用于自定义生成的镜像：

参数	默认值	描述
USE_CUDA	false	启用 NVIDIA GPU 支持 Dockerfile:4
USE_OLLAMA	false	在容器内包含 Ollama 二进制文件 Dockerfile:5
USE_SLIM	false	跳过预下载嵌入/Whisper 模型 Dockerfile:6
USE_CUDA_VER	cu128	指定 Torch 的 CUDA 版本 Dockerfile:9
USE_EMBEDDING_MODEL	sentence-transformers/all-MiniLM-L6-v2	设置默认的 RAG 嵌入模型 Dockerfile:14

来源：Dockerfile:1-25, Dockerfile:142-146

基本 Docker 部署

独立容器

最简单的部署方式是在单个 Docker 容器中运行 Open WebUI，并实现本地数据持久化：

docker run -d \
  -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

端口映射：容器内部暴露端口 8080 Dockerfile:65，映射到主机端口 3000 以供 Web 访问。

卷挂载：命名卷 open-webui 持久化以下数据：

• SQLite 数据库文件（webui.db）
• ChromaDB 向量数据库（chroma.sqlite3）
• /app/backend/data 中的上传文件和用户数据 Dockerfile:164

容器生命周期

容器初始化序列由 start.sh 脚本管理：

标题：容器初始化序列

sequenceDiagram
    participant Docker as "Docker Engine"
    participant Entry as "backend/start.sh"
    participant Ollama as "ollama serve"
    participant Backend as "open_webui.main:app"
    participant DB as "SQLite/Postgres"

    Docker->>Entry: "启动容器"
    Entry->>Entry: "若缺少 WEBUI_SECRET_KEY 则生成"
    Note over Entry: [backend/start.sh:25-36]

    opt USE_OLLAMA_DOCKER=true
        Entry->>Ollama: "生成进程"
        Note over Entry: [backend/start.sh:38-41]
    end

    Entry->>Backend: "exec uvicorn open_webui.main:app"
    Note over Entry: [backend/start.sh:83-87]
    Backend->>DB: "运行迁移并初始化"
    Backend-->>Docker: "在端口 8080 就绪"

密钥管理：如果未通过环境变量提供 WEBUI_SECRET_KEY，启动脚本会使用 /dev/random 生成一个随机密钥，并将其存储在持久化数据目录中的 .webui_secret_key 文件内 backend/start.sh:25-36。

来源：backend/start.sh:25-41, backend/start.sh:83-87, Dockerfile:65-164

Docker Compose 配置

标准编排

默认的 docker-compose.yaml 定义了一个包含两个服务的栈：open-webui 和 ollama。

标题：Docker Compose 服务架构

graph TB
    subgraph "Docker_Compose_网络"
        OpenWebUI["open_webui.main:app<br/>(容器: open-webui)"]
        Ollama["ollama/ollama:latest<br/>(容器: ollama)"]
    end

    subgraph "存储层"
        WebUIVol["open-webui 卷<br/>/app/backend/data"]
        OllamaVol["ollama 卷<br/>/root/.ollama"]
    end

    OpenWebUI -->|"OLLAMA_BASE_URL"| Ollama
    OpenWebUI -.->|"挂载"| WebUIVol
    Ollama -.->|"挂载"| OllamaVol

服务通信：open-webui 通过内部 Docker 网络连接到 ollama，使用环境变量 OLLAMA_BASE_URL=http://ollama:11434 docker-compose.yaml:24。

自动化配置脚本

run-compose.sh 脚本提供了一个高级 CLI，用于管理复杂的 Compose 设置，包括自动 GPU 检测和功能开关。

选项	效果	实现方式
--enable-gpu	检测 NVIDIA/AMD/Intel 驱动	追加 docker-compose.gpu.yaml run-compose.sh:178
--enable-api	暴露 Ollama API 端口	追加 docker-compose.api.yaml run-compose.sh:181
--playwright	启用基于浏览器的抓取	追加 docker-compose.playwright.yaml run-compose.sh:191
--data	绑定主机文件夹用于模型	追加 docker-compose.data.yaml run-compose.sh:187

GPU 检测逻辑：脚本使用 lspci 和 nvidia-smi 识别主机驱动（例如 nvidia、amdgpu、i915），并相应地导出 OLLAMA_GPU_DRIVER run-compose.sh:13-50。

来源：docker-compose.yaml:1-33, run-compose.sh:13-50, run-compose.sh:165-202

Docker 中的 GPU 加速

Dockerfile 支持构建带有 CUDA 支持的镜像，用于硬件加速的嵌入和 Whisper 转录。

docker build \
  --build-arg USE_CUDA=true \
  --build-arg USE_CUDA_VER=cu121 \
  -t open-webui:cuda .

运行时配置：

• Torch：当 USE_CUDA 为 true 时，容器会从 download.pytorch.org 安装带有指定 CUDA 版本索引的 torch Dockerfile:146。
• 库路径：start.sh 脚本会自动将 NVIDIA 库路径追加到 LD_LIBRARY_PATH，以包含 torch/lib 和 nvidia/cudnn/lib backend/start.sh:43-46。
• 模型预加载：在构建过程中，镜像会使用 Python 命令将嵌入模型和 Whisper 模型预下载到缓存目录 Dockerfile:148-152。

来源：Dockerfile:143-152, backend/start.sh:43-46

使用 Playwright 进行 Web 抓取

对于需要高级 Web 内容提取的部署，Open WebUI 通过 WEB_LOADER_ENGINE 支持 Playwright 集成 backend/open_webui/retrieval/web/utils.py:39。

启动逻辑：如果 WEB_LOADER_ENGINE 设置为 playwright 且未提供外部 PLAYWRIGHT_WS_URL，start.sh 脚本会自动在容器内安装 Chromium 浏览器及其系统依赖 backend/start.sh:7-12。

远程集成：在 Compose 环境中，建议使用专用的 Playwright 服务，以保持主容器轻量化 run-compose.sh:190-192。

来源：backend/start.sh:7-12, run-compose.sh:190-192, backend/open_webui/retrieval/web/utils.py:36-49

资源管理与存储提供程序

为了生产环境的稳定性，应应用 Docker 资源约束和灵活的存储后端。

存储抽象

Open WebUI 通过 StorageProvider 类抽象存储，使 Docker 用户能够从本地卷迁移到云存储 backend/open_webui/storage/provider.py:40-56。

提供程序	代码实体	配置
本地	LocalStorageProvider	默认，使用 /app/backend/data backend/open_webui/storage/provider.py:58
S3	S3StorageProvider	S3_ACCESS_KEY_ID、S3_BUCKET_NAME backend/open_webui/storage/provider.py:101
Azure	AzureStorageProvider	AZURE_STORAGE_ENDPOINT backend/open_webui/storage/provider.py:27

健康检查

• 环境持久化：所有应用数据存储在 /app/backend/data 中。这包括用于 Whisper 和 sentence-transformers 等模型的 cache 目录 Dockerfile:89-102。
• 健康检查：start.sh 脚本为 HuggingFace Space 部署提供了一个逻辑路径，其中包括一个健康检查循环，等待 http://localhost:${PORT}/health 变为可用 backend/start.sh:55-58。

来源：backend/open_webui/storage/provider.py:40-101, Dockerfile:89-102, backend/start.sh:55-58