3.1 · 安装方式（Installation Methods）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节3.1 状态全文译文模块测试、发布与运维、界面与交互、工具、记忆与模型调用、检索、召回与知识系统

项目要点页2.5 参考项目项目章节目录Open WebUI DeepWiki 原始章节Installation Methods 上一章3 下一章3.2

源码线索

CODE_OF_CONDUCT.md
README.md
TROUBLESHOOTING.md
backend/dev.sh
backend/open_webui/retrieval/web/testdata/brave.json
backend/start.sh
run-ollama-docker.sh
run.sh
src/lib/apis/images/index.ts
src/lib/components/admin/Settings/Interface/Banners.svelte

模块标签

测试、发布与运维
界面与交互
工具、记忆与模型调用
检索、召回与知识系统
接口与服务契约

中文译文

安装方式（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/3.1-installation-methods

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

翻译模型：deepseek-chat

原文字符数：10137

项目：Open WebUI (open-webui)

---

安装方法

目的与范围

本文档记录了 Open WebUI 的主要安装方法：Docker 容器部署、Python pip 安装以及本地开发环境搭建。每种方法针对不同的运维需求，涵盖从隔离的生产环境到活跃的代码贡献场景。Open WebUI 是一个可扩展、功能丰富的自托管 AI 平台，设计为完全离线运行，同时支持 Ollama 和兼容 OpenAI 的 API 等多种 LLM 运行器 README.md:15-16。

---

安装概览

Open WebUI 采用 SvelteKit 前端与 FastAPI 后端通信的架构。不同安装方法在打包和执行这两个组件时有所区别，尤其是在 RAG、Whisper（语音转文字）以及多种文本转语音引擎等 AI 功能的依赖管理方面 README.md:42-50。

标题：安装决策与执行流程

graph TB
    ["用户/开发者"] -- "生产/隔离环境" --> ["Docker 容器（推荐）"]
    ["用户/开发者"] -- "直接 OS/虚拟环境" --> ["pip install"]
    ["用户/开发者"] -- "贡献/修改代码" --> ["开发环境搭建"]

    subgraph Docker_Execution ["Docker 执行"]
        ["docker run ghcr.io/open-webui/open-webui"] --> ["挂载: /app/backend/data"]
        ["挂载: /app/backend/data"] --> ["端口: 3000:8080"]
        ["端口: 3000:8080"] --> ["访问: localhost:3000"]
    end

    subgraph pip_Execution ["pip 执行"]
        ["pip install open-webui"] --> ["open-webui serve"]
        ["open-webui serve"] --> ["访问: localhost:8080"]
    end

    subgraph Development_Execution ["开发环境执行"]
        ["npm run build (SvelteKit)"] --> ["python -m uvicorn open_webui.main:app"]
        ["python -m uvicorn open_webui.main:app"] --> ["访问: localhost:8080"]
    end

来源： README.md:30-33、Dockerfile:27-46、backend/start.sh:83-87、backend/dev.sh:1-3

---

安装方法 1：Docker（推荐）

Docker 是生产环境的首选方法，因为它将 Python 环境、Node.js 构建产物以及系统依赖（如 ffmpeg、pandoc 和 gcc）打包成一个不可变的镜像 Dockerfile:127-133。

Docker 镜像变体

Dockerfile 支持多个构建参数，以便针对特定硬件和功能集定制镜像：

参数	默认值	描述
`USE_CUDA`	`false`	启用 NVIDIA GPU 支持，用于本地 RAG/Whisper `Dockerfile:4`。
`USE_OLLAMA`	`false`	将 Ollama 二进制文件打包到容器内 `Dockerfile:5`。
`USE_EMBEDDING_MODEL`	`sentence-transformers/all-MiniLM-L6-v2`	RAG 的默认模型 `Dockerfile:14`。
`USE_CUDA_VER`	`cu128`	指定 PyTorch 的 CUDA 版本（默认 cu128 对应 CUDA 12）`Dockerfile:8-9`。
`USE_SLIM`	`false`	跳过预下载模型以减小镜像体积 `Dockerfile:6`。

标准部署

运行标准镜像（连接到外部 Ollama 或 OpenAI 实例）：

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

数据持久化与流程

容器期望在 /app/backend/data 处挂载持久化卷 Dockerfile:164。该目录存储 SQLite 数据库、用于 RAG 的上传文档以及 Whisper 和 Embeddings 的缓存模型 Dockerfile:89-102。

标题：容器数据流与持久化

graph LR
    subgraph Host_System ["宿主机系统"]
        ["Docker 卷: open-webui"]
    end

    subgraph Container_Space ["容器空间"]
        direction TB
        ["/app/backend"] --> ["/app/backend/data"]
        ["/app/backend/data"] --> ["/app/backend/data/cache"]

        ["静态文件: /app/backend/open_webui/frontend"]
        ["FastAPI (open_webui.main:app)"]
    end

    ["Docker 卷: open-webui"] <--> ["/app/backend/data"]
    ["/app/backend/data"] --> ["webui.db (SQLite)"]
    ["/app/backend/data/cache"] --> ["Embedding/Whisper 模型"]
    ["FastAPI (open_webui.main:app)"] --> ["静态文件: /app/backend/open_webui/frontend"]

来源： Dockerfile:109-124、Dockerfile:164-165、backend/start.sh:83-87、run.sh:12-17

---

安装方法 2：pip（Python 包）

对于希望直接在宿主机或 Python 虚拟环境中运行的用户，Open WebUI 以 PyPI 包形式提供。

要求

Python 3.11：项目使用 Python 3.11 作为生产镜像的基础 Dockerfile:46。
系统依赖：某些功能需要 ffmpeg（用于语音）、pandoc（用于文档处理）以及 libmariadb-dev（用于数据库支持）Dockerfile:127-133。
核心库：依赖包括用于快速包管理的 uv、用于本地推理的 torch 以及用于 RAG 的 sentence-transformers Dockerfile:142-152。

执行

安装后，通常使用 uvicorn 命令启动应用程序。start.sh 脚本展示了生产启动序列，包括在未通过环境变量提供 WEBUI_SECRET_KEY 时生成该密钥 backend/start.sh:25-36。

# start.sh 中的示例执行命令
python3 -m uvicorn open_webui.main:app --host 0.0.0.0 --port 8080

来源： Dockerfile:46-165、backend/start.sh:17-44、backend/start.sh:83-87

---

安装方法 3：开发环境搭建

开发环境搭建用于修改源代码时。它需要同时运行前端和后端，以支持热重载。

后端开发

后端可以使用带 --reload 标志的 uvicorn 启动。dev.sh 脚本设置 CORS_ALLOW_ORIGIN，允许 SvelteKit 开发服务器（通常运行在端口 5173）与 FastAPI 后端通信 backend/dev.sh:1-3。

# 从 backend 目录执行
export CORS_ALLOW_ORIGIN="http://localhost:5173;http://localhost:8080"
uvicorn open_webui.main:app --port 8080 --host 0.0.0.0 --reload

前端开发

前端使用 Vite 和 SvelteKit。

安装依赖：npm ci --force Dockerfile:39
构建生产版本：npm run build Dockerfile:43
开发时通常使用 npm run dev（虽未在 Dockerfile 中明确说明）。

构建流程集成

Dockerfile 展示了从开发到生产的过渡：

构建阶段：使用 node:22-alpine 运行 npm run build，将 Svelte 组件编译为静态资源 Dockerfile:27-43。
生产阶段：FastAPI 后端提供生成的静态文件。

标题：代码实体到运行时的映射

graph TD
    subgraph Natural_Language_Space ["自然语言空间"]
        ["源代码"]
        ["构建过程"]
        ["运行时应用"]
    end

    subgraph Code_Entity_Space ["代码实体空间"]
        ["src/ (SvelteKit)"]
        ["backend/open_webui/main.py"]
        ["backend/requirements.txt"]
        ["backend/start.sh"]
        ["open_webui.main:app"]
    end

    ["src/ (SvelteKit)"] -->|"npm run build"| ["静态资源"]
    ["backend/requirements.txt"] -->|"pip install"| ["Python 环境"]
    ["backend/open_webui/main.py"] --> ["open_webui.main:app"]
    ["静态资源"] -->|"由...提供"| ["open_webui.main:app"]
    ["backend/start.sh"] -->|"执行"| ["open_webui.main:app"]

来源： Dockerfile:27-44、backend/start.sh:83-87、backend/dev.sh:1-3

---

验证与版本管理

安装完成后，可以在设置菜单的"关于"部分验证版本和构建状态 src/lib/components/chat/Settings/About.svelte:47-55。

版本组件

版本逻辑由 About.svelte 和 constants.ts 管理：

WEBUI_VERSION：语义化版本号（例如 v0.5.0）src/lib/constants.ts:18。
WEBUI_BUILD_HASH：用于故障排查的特定构建或 git 哈希值 src/lib/constants.ts:19。
Ollama 版本：如果已连接，UI 会显示从 Ollama API 获取的版本 src/lib/components/chat/Settings/About.svelte:100-111。

健康检查

后端提供一个健康检查端点，部署脚本使用它来确保服务已就绪 backend/start.sh:56。

GET /health：返回服务状态。

来源： src/lib/components/chat/Settings/About.svelte:16-44、src/lib/constants.ts:18-20、backend/start.sh:56-58