3 · 安装与部署（Installation and Deployment）

安装与部署（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/3-installation-and-deployment

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

翻译模型：deepseek-chat

原文字符数：9201

项目：Open WebUI (open-webui)

---

安装与部署

相关源文件

以下文件为本 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 的完整安装与部署说明，涵盖部署方式、环境配置、硬件加速及生产环境部署注意事项。

关于整体系统架构与组件设计，请参见架构概览。部署后 RAG、认证等功能的具体配置，请参见环境配置。

---

部署架构概览

Open WebUI 是一个统一应用，由 FastAPI 后端服务预构建的 SvelteKit 前端。它设计为高度可移植，默认使用本地 SQLite 存储，同时支持企业级外部数据库与分布式缓存。

部署架构图

graph TB
    subgraph "客户端访问"
        Browser["Web 浏览器"]
        Mobile["移动端 PWA 客户端"]
    end

    subgraph "反向代理层（可选）"
        Nginx["nginx / Apache / Caddy<br/>SSL 终止<br/>WebSocket 升级"]
    end

    subgraph "应用层（FastAPI）"
        MainApp["open_webui.main:app<br/>端口 8080"]
        SocketIOServer["python-socketio<br/>实时事件"]
        Uvicorn["Uvicorn ASGI 服务器"]
    end

    subgraph "配置管理"
        EnvVars["环境变量<br/>WEBUI_*, RAG_*, OAUTH_*"]
        SecretKeyFile[".webui_secret_key<br/>缺失时自动生成"]
    end

    subgraph "数据持久化"
        SQLDB["SQL 数据库<br/>SQLAlchemy / Peewee<br/>SQLite / Postgres / MariaDB"]
        VectorDB["向量数据库<br/>ChromaDB / Qdrant / Milvus<br/>RAG 嵌入"]
        Redis["Redis（可选）<br/>starsessions / 多节点同步"]
        FileStorage["文件存储<br/>本地 / S3 / Azure / GCS"]
    end

    subgraph "外部提供商"
        Ollama["Ollama API<br/>OLLAMA_BASE_URL"]
        OpenAI["OpenAI 兼容 API<br/>OPENAI_API_BASE_URL"]
        WebLoaders["网页抓取器<br/>Playwright / Firecrawl"]
    end

    Browser --> Nginx
    Mobile --> Nginx
    Nginx --> Uvicorn
    Uvicorn --> MainApp
    Uvicorn --> SocketIOServer

    MainApp --> EnvVars
    MainApp --> SecretKeyFile

    MainApp --> SQLDB
    MainApp --> VectorDB
    SocketIOServer --> Redis
    MainApp --> FileStorage

    MainApp --> Ollama
    MainApp --> OpenAI
    MainApp --> WebLoaders

来源： backend/open_webui/main.py:1-87，src/lib/constants.ts:6-14

---

安装方式

方式一：Docker 安装（推荐）

Docker 是主要部署方式，可确保 RAG（检索增强生成）和图像处理的所有依赖正确配置。Dockerfile 支持多个构建参数，用于硬件加速和镜像体积优化 Dockerfile:4-7。

基础 Docker 运行

标准镜像监听 8080 端口 Dockerfile:65，并使用持久化卷存储后端数据 Dockerfile:164。

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

带硬件加速的 Docker

镜像可构建或运行特定驱动，以支持本地嵌入和 whisper 模型。start.sh 脚本检测 USE_CUDA_DOCKER 并配置 LD_LIBRARY_PATH，包含 torch、cudnn 和 cublas 所需的 NVIDIA 库 backend/start.sh:43-46。

来源： Dockerfile:1-165，backend/start.sh:1-87，docker-compose.yaml:11-29

方式二：Docker Compose

对于集成部署，docker-compose.yaml 将 Open WebUI 与 Ollama 服务关联 docker-compose.yaml:1-29。项目包含实用脚本 run-compose.sh，可自动检测 GPU 驱动（NVIDIA、AMD 或 Intel）并选择正确的 Compose 覆盖文件 run-compose.sh:13-50, 166-179。

来源： docker-compose.yaml:1-33，run-compose.sh:112-202

---

系统要求与依赖

后端技术栈

后端为 Python 应用，核心功能依赖以下关键库：

类别	关键包	作用
Web 框架	uvicorn	ASGI 服务器与 API 路由 backend/start.sh:83-87
构建系统	uv	高性能 Python 包安装器 Dockerfile:142
RAG / 嵌入	sentence-transformers	本地嵌入生成 Dockerfile:148
转录	faster-whisper	本地语音转文字处理 Dockerfile:150
AI 客户端	ollama	本地 LLM 管理 Dockerfile:171

前端技术栈

前端使用 SvelteKit 构建 Dockerfile:27,43，通过常量中定义的 WEBUI_API_BASE_URL 与后端通信 src/lib/constants.ts:8。构建过程使用 vite 注入版本号和构建哈希 vite.config.ts:19-22。

来源： Dockerfile:27-165，src/lib/constants.ts:1-112，vite.config.ts:1-32

---

环境配置系统

Open WebUI 使用环境变量进行安全配置和启动引导。

配置引导流程图

graph LR
    subgraph "启动流程"
        SH["backend/start.sh"]
        CHECK_KEY["密钥逻辑"]
        UVI["Uvicorn 执行"]
    end

    subgraph "变量与文件"
        ENV_SEC["WEBUI_SECRET_KEY"]
        ENV_FILE["WEBUI_SECRET_KEY_FILE"]
        LOCAL_FILE[".webui_secret_key"]
    end

    SH --> CHECK_KEY
    CHECK_KEY -->|如果环境变量缺失| ENV_FILE
    ENV_FILE -->|默认使用| LOCAL_FILE
    CHECK_KEY -->|如果文件缺失| GEN["生成随机密钥"]
    GEN --> LOCAL_FILE
    LOCAL_FILE --> UVI
    ENV_SEC --> UVI

关键安全变量

• WEBUI_SECRET_KEY：用于签名 JWT 令牌。如果未通过环境变量提供，系统会查找 WEBUI_SECRET_KEY_FILE 指定的文件，或默认使用 .webui_secret_key backend/start.sh:17-36。
• PORT：定义后端监听端口，默认为 8080 backend/start.sh:23。
• FORWARDED_ALLOW_IPS：在反向代理后运行时必需，用于正确识别客户端 IP，默认为 * backend/start.sh:86。

来源： backend/start.sh:17-87，backend/start_windows.bat:20-50，.env.example:1-22

---

生产环境部署注意事项

反向代理与 SSL

生产环境建议使用反向代理（Nginx、Caddy 等）。代理必须支持 WebSocket 升级以处理 Socket.IO 连接。后端使用 uvicorn 并启用 --ws auto 标志处理 WebSocket 协议 backend/start_windows.bat:50。

网页抓取引擎

如果使用网页搜索或文档抓取功能，系统可使用 playwright。当 WEB_LOADER_ENGINE 设置为 playwright 时，start.sh 脚本会自动安装 Chromium 浏览器及其依赖 backend/start.sh:7-12。

自动化部署

项目包含 GitHub Workflows，用于自动构建支持 amd64 和 arm64 架构的 Docker 镜像，以及针对 GPU 环境的 cuda 标签 .github/workflows/docker-build.yaml:25-28, 175。

来源： backend/start.sh:7-15，.github/workflows/docker-build.yaml:1-210

---

子页面

• 安装方式 — Docker、Pip 及开发环境搭建的详细说明。
• Docker 部署选项 — 高级 Docker Compose、GPU（NVIDIA/AMD）及精简镜像配置。
• 环境配置 — 所有 WEBUI_*、RAG_* 和 OAUTH_* 变量的参考指南。
• 反向代理设置 — Nginx、Caddy 和 Apache 的配置示例。
• Kubernetes 部署 — 使用 Helm Chart 和持久化卷管理的部署方案。