Open WebUI：自托管 LLM Web 界面（类 ChatGPT）｜部署与使用全指南

Open WebUI —— 自托管 LLM Web 界面（类 ChatGPT，可对接 Ollama / OpenAI 兼容接口）

适配场景：Windows 10/11 + WSL2（Ubuntu 24.04）本地部署；RTX 3070 8GB / RTX 4090 24GB 均可使用。Open WebUI 本身只是"前端 + 管理面板"，不自带大模型，需要对接本机 Ollama、llama.cpp 或任意 OpenAI 兼容接口。

项目定位与基本信息

• 一句话定位：一个可完全离线运行、功能丰富、面向自托管场景的 AI 平台界面（官方原文："a self-hosted AI platform … built to run entirely offline"），原生支持 Ollama 与 OpenAI 兼容 API，为本地模型与云端模型提供与 ChatGPT 类似的对话体验，并内置知识库（RAG）、插件、工具调用等能力。
• 开源许可：Open WebUI License（自定义许可，非标准 MIT/Apache/GPL）。
• 出处：官方仓库 LICENSE 文件（https://raw.githubusercontent.com/open-webui/open-webui/main/LICENSE ，已下载核验）与 README "License" 一节（https://github.com/open-webui/open-webui ）。
• 关键条款（依据 LICENSE 文件原文概括）：允许源码/二进制再分发与修改，但必须保留版权声明；不得在未经书面许可的情况下使用版权方/贡献者名义为衍生品背书；必须保留 "Open WebUI" 品牌（名称、Logo 及界面标识）——例外情形为：① 任意连续 30 天内终端用户不超过 50 人；② 获得版权方书面许可；③ 取得正式企业许可。代码库中沿用历史许可的旧组件，按各自原始许可条款执行（见仓库 LICENSE_HISTORY）。
• 官方 GitHub 仓库：https://github.com/open-webui/open-webui
• 官方官网：https://openwebui.com/ （品牌与产品介绍站，HTTP 200 已核验）。
• 官方文档站：https://docs.openwebui.com/ （安装、配置、RAG、排障等全部官方说明，HTTP 200 已核验）。
• 版本说明：截至 2026-10-25，官方最新 release 为 v0.12.4（发布时间 2026-10-25 08:07 UTC，来源：https://github.com/open-webui/open-webui/releases/tag/v0.12.4 ）；PyPI 包 open-webui 最新版本同为 0.12.4（来源：https://pypi.org/project/open-webui/ ，requires_python：<3.13.0a1,>=3.11）。

官方图片

两张图均来自官方文档站 docs.openwebui.com 的官方资源目录，使用 curl -L 下载，已用 file 命令核验为 PNG 且体积大于 20KB；未使用任何 AI 生成图或非官方截图。

图 09-1 Open WebUI 全新对话界面（官方文档截图）

• 来源 URL：https://docs.openwebui.com/assets/images/new-chat-placeholder-be568eb047e004bf0757ff35e34b4289.png
• 下载方式：curl -L -o 09_openwebui_ui.png "https://docs.openwebui.com/assets/images/new-chat-placeholder-be568eb047e004bf0757ff35e34b4289.png"
• 核验：file 显示 PNG image data, 3000 x 2000, 8-bit/color RGB，体积 148,827 字节（>20KB）。

图 09-2 Open WebUI 知识库（Knowledge）管理界面（官方文档截图）

• 来源 URL：https://docs.openwebui.com/assets/images/knowledge-list-011c5b77c36082462e8e714d02d3e53b.png
• 下载方式：curl -L -o 09_openwebui_knowledge.png "https://docs.openwebui.com/assets/images/knowledge-list-011c5b77c36082462e8e714d02d3e53b.png"
• 核验：file 显示 PNG image data, 3000 x 2000, 8-bit/color RGB，体积 128,307 字节（>20KB）。

环境要求

说明：Open WebUI 是界面与应用层，本地大模型推理的显存/内存需求取决于你外接的 Ollama / llama.cpp 模型，而不是 Open WebUI 本身。下表需求仅针对 Open WebUI 应用本体。

最详细部署步骤（Windows 与 WSL2 两种视角，精确命令）

方式 A：Docker 一键部署（官方推荐路径）

A-1 依赖安装（Windows 视角）

1. 安装 Docker Desktop for Windows，安装过程中勾选 "Use WSL 2 instead of Hyper-V"（WSL2 backend）。安装包来源：https://www.docker.com/products/docker-desktop/ （官方 Quick Start 的 WSL 指南引用）。
2. 打开 Docker Desktop → Settings → Resources → WSL Integration，勾选 "Enable integration with my default WSL distro"；若使用非默认发行版，在列表中勾选对应 Ubuntu 24.04。保存后重启 Docker Desktop。
3. （可选，使用 :cuda 镜像时）WSL2 内安装 NVIDIA Container Toolkit 并安装显卡驱动；仅对接外部 Ollama / OpenAI 接口时不需要。

官方 WSL 指南硬性提示：始终从 WSL 终端（Ubuntu 24.04）执行 docker 命令，不要在 PowerShell 或 CMD 里执行；使用 -v 挂载卷时，路径必须对 WSL 发行版可达。 依据：https://docs.openwebui.com/getting-started/quick-start/ （Using Docker with WSL → Step 1–4、Important Notes）

A-2 拉取镜像并启动（WSL2 视角，Ubuntu 24.04 终端内执行）

官方默认命令（Ollama 安装在本机 Windows/WSL 上的场景，已按官方文档带 --add-host 与 WEBUI_SECRET_KEY）：

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

命令参数对照（均来自官方 Quick Start 文档）：

常用镜像标签（官方 Quick Start "Tag / Use case" 表）：

GPU 加速变体（官方文档命令，NVIDIA 机型可选）：

docker run -d -p 3000:8080 --gpus all \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  -e WEBUI_SECRET_KEY=your-secret-key \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:cuda

仅使用 OpenAI 等云端 API（本机不跑 Ollama）：

docker run -d -p 3000:8080 \
  -e OPENAI_API_KEY=your_secret_key \
  -v open-webui:/app/backend/data \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

捆绑 Ollama 的一体化镜像（GPU 版）：

docker run -d -p 3000:8080 --gpus=all \
  -v ollama:/root/.ollama \
  -v open-webui:/app/backend/data \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:ollama

CPU-only 版本去掉 --gpus=all 即可（官方文档命令一致）。

A-3 模型 / 依赖下载

• Ollama 模型：先在本机安装 Ollama（https://ollama.com/ ）并拉取模型，例如 ollama pull qwen2.5:7b；Open WebUI 启动后可在模型选择框直接输入模型名触发拉取，也可在 Settings → Admin → Connections → Manage Ollama API Connections → Manage 面板中下载/管理模型（官方 Ollama 指南）。
• 本地嵌入模型（RAG 用）：默认 sentence-transformers/all-MiniLM-L6-v2，首次启动知识库上传流程时自动从 Hugging Face 下载；无网络/离线环境可设置 HF_HUB_OFFLINE=1 禁止联网下载（README Offline Mode 一节）。

A-4 国内网络加速（可验证的通用思路，非官方指定镜像）

• 嵌入模型等 Hugging Face 资源下载慢 / SSL 报错：官方排障文档给出的示例做法是在 docker run 中增加 HF_ENDPOINT 环境变量指向镜像站：

bash docker run -d -p 3000:8080 \ -e HF_ENDPOINT=https://hf-mirror.com/ \ --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

依据：https://docs.openwebui.com/troubleshooting/connection-error （SSL Connection Issue with Hugging Face 一节，原文示例命令即 HF_ENDPOINT=https://hf-mirror.com/）。 - ghcr.io 镜像拉取慢：官方文档说明同一组镜像也镜像到 Docker Hub 仓库 openwebui/open-webui（仅部分标签：latest、latest-<variant>、裸 <variant> 如 slim/cuda/ollama，以及 X.Y.Z / X.Y 版本号标签；:main、:dev、:vX.Y.Z、:git-<sha> 仅存在于 ghcr.io）。可改用 Docker Hub 仓库拉取，例如：

bash # Docker Hub 官方镜像备选（标签集合见上） docker pull openwebui/open-webui:latest docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway \ -v open-webui:/app/backend/data --name open-webui --restart always \ openwebui/open-webui:latest

依据：https://docs.openwebui.com/getting-started/quick-start/ （Docker Hub 镜像说明一节）；仓库页面 https://hub.docker.com/r/openwebui/open-webui （HTTP 200 已核验，当前含 0.12.4、0.12.4-cuda 等标签）。 - 其余通用可验证思路（非官方指定镜像）：① 在 Docker Desktop → Settings → Docker Engine 的 registry-mirrors 中配置本机网络可达的 Docker Registry 镜像（Docker 官方通用能力，文档：https://docs.docker.com/desktop/settings/windows/ ），重启 Docker Desktop 后重试；② 网络条件允许时改用下文 pip 方式安装，规避容器镜像；③ 换用 :slim 标签减小下载体积。以上为通用部署建议，不代表 Open WebUI 官方背书某个第三方镜像站。

A-5 验证启动

docker logs -f open-webui        # 等待日志出现 "Application startup complete"（官方 Quick Start 就绪判据）

浏览器访问 http://localhost:3000 ，首次进入出现 "Get started with Open WebUI" 欢迎页并提供 "Create Admin Account" 入口即部署成功（首个注册账号自动成为管理员）。若页面长时间不加载，按 09.6 第 1、6 条排查连接与端口。

方式 B：pip 轻量部署（WSL2 Ubuntu 24.04 或 Windows 本机 Python 环境）

B-1 依赖安装（WSL2 Ubuntu 24.04 视角）

1. 安装 Python 3.11 或 3.12（不要用 3.13，官方明确暂不支持）；建议使用虚拟环境隔离：

sudo apt update
sudo apt install -y python3 python3-venv python3-pip
python3 -m venv ~/open-webui-venv
source ~/open-webui-venv/bin/activate

2. 无 NVIDIA GPU 的机器先装 CPU 版 PyTorch（官方文档要求，避免拉入 CUDA 运行库）：

pip install torch --index-url https://download.pytorch.org/whl/cpu

B-2 项目安装

pip install open-webui
open-webui serve

• 官方 README 同样给出该命令组合；文档补充：可先 pip install open-webui，再执行 open-webui serve。
• 升级命令：pip install -U open-webui。
• 卸载：pip uninstall open-webui；数据目录默认 site-packages/open_webui/data，卸载不会自动删除，需手动清理。

Windows 本机 Python 视角：命令相同（pip install open-webui → open-webui serve）；官方文档提示命令找不到时，先激活安装该包的虚拟环境——open-webui 可执行文件位于环境的 bin（Windows 为 Scripts）目录。Windows 本机建议 Python 3.12。

B-3 关键启动参数与环境变量

# 指定数据目录（避免数据落在 site-packages 内）
DATA_DIR=~/.open-webui open-webui serve

# 自定义监听地址与端口（默认 http://localhost:8080）
open-webui serve --host 0.0.0.0 --port 3000

B-4 验证启动

浏览器访问 http://localhost:8080（--port 3000 时访问 http://localhost:3000 ）。

关键配置项总表（Docker / pip 通用环境变量，来源：官方 Env Configuration 文档）

使用方法

启动方式速查

界面操作步骤

1. 注册管理员：浏览器打开实例地址，首屏 "Create Admin Account" 创建账号；首个账号自动成为管理员（拥有用户管理与全部实例级设置权限），创建后注册自动关闭。后续如需开放注册：头像 → Settings → Admin → Authentication 打开 New Sign Ups；新账号默认 Pending 待管理员审批。 - 依据：https://docs.openwebui.com/getting-started/quick-start/ （Create the admin account）；https://docs.openwebui.com/features/authentication-access/rbac/roles/ （Initial Setup：首个账号自动分配 Admin 角色）。
2. 连接 Ollama： - 本机 Ollama 在 Docker 模式下默认探测 http://host.docker.internal:11434；pip 模式默认探测 http://localhost:11434。 - 手动管理：头像 → Settings → Admin → Connections，在 Manage Ollama API Connections 中查看/新增/编辑地址；在该面板的 Manage 对话框内可拉取、更新、删除模型，也可基于已有模型 Create Model。 - 多实例负载均衡：在 OLLAMA_BASE_URLS 中配置多个 URL，随机分配；各实例模型 ID 需完全一致才能合并显示。
3. 连接 OpenAI 兼容接口 / llama.cpp / vLLM / LM Studio 等： - Settings → Admin → Connections → Manage OpenAI API Connections → ＋ Add Connection。 - 填入 URL 与 API Key 后保存；模型列表自动获取。部分服务商不提供 /models 端点，需在连接设置的 Model IDs 白名单中手动填写模型 ID 后保存。 - llama.cpp 示例：llama-server --model /path/model.gguf --port 10000 --ctx-size 1024 --n-gpu-layers 40 启动后，容器内 WebUI 连接地址填 http://host.docker.internal:10000/v1（注意末尾 /v1）；本机 pip 模式填 http://127.0.0.1:10000/v1；无密钥服务器 Auth 选 None；高级选项 Provider 下拉选 llama.cpp 可解锁模型加载指示与卸载按钮。 - 依据：https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-llama-cpp ；https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible 。
4. 建立知识库（博客文章私有 RAG）：
5. 左侧 Workspace → Knowledge → 右上角 Create，填写知识库名称与描述。
6. 上传 PDF / TXT / Markdown / Word / Excel / PowerPoint / CSV / JSON / HTML / SVG 等文件，等待处理完成。
7. 在聊天框输入 # 引用知识库；也可在 Workspace → Models → Edit 中把知识库绑定到某个模型，使该模型只能检索挂载内容。
8. 检索模式：Focused Retrieval（默认 RAG） 按查询语义取回相关分片；Full Context 把整篇文档全文注入每条消息，适合短篇参考文档。 - 依据：https://docs.openwebui.com/features/workspace/knowledge （含上传流程、两种检索模式、原生工具调用说明）。
9. 发送首条消息：New Chat → 在输入框右下角模型选择器中选模型 → 输入问题 → 回车；可在对话中通过附件按钮挂载单个文件，就该文件单独提问（支持格式见知识库文档）。

常用参数说明表

端到端示例：把博客 Markdown 文章做成私有问答知识库

前置条件：Docker 实例已运行，本机 Ollama 已 ollama pull qwen2.5:7b（示例模型，可替换为 3070 8GB 可流畅运行的模型）。

1. 浏览器打开 http://localhost:3000 ，完成管理员注册。
2. Settings → Admin → Connections 确认 Ollama 连接地址为 http://host.docker.internal:11434（Docker）或 http://localhost:11434（pip）；模型选择框中能看到 qwen2.5:7b。
3. Workspace → Knowledge → Create，命名 Blog-KB，把博客导出的若干 .md / .pdf 文章拖入上传，等待处理完成。
4. 新建对话，模型选择 qwen2.5:7b，在输入框输入 #Blog-KB 引用知识库。
5. 提问示例："根据我上传的博客文章，总结一下 WSL2 下部署本地大模型的常见步骤，并引用对应文章原文段落。"
6. 对照原文核验回答与引用来源；若模型检索不到内容，按 09.6 排障：检查嵌入引擎、切换 Hybrid Search、或在模型编辑中确认知识库已挂载。

常见坑（现象 + 原因 + 解决）

1. 现象：Docker 中的 Open WebUI 报 Server Connection Error，模型列表为空，连不上本机 Ollama。 - 原因：容器内 127.0.0.1 指向容器自身而非宿主机；且 Ollama 默认只监听 127.0.0.1:11434。 - 解决：① 连接地址使用 http://host.docker.internal:11434（官方 README 与 Ollama 指南均要求 --add-host=host.docker.internal:host-gateway）；② 让 Ollama 监听全部网卡：设置 OLLAMA_HOST=0.0.0.0 后重启 Ollama 服务；③ 兜底方案：docker run --network=host，环境变量 OLLAMA_BASE_URL=http://127.0.0.1:11434，此时 WebUI 访问地址变为 http://localhost:8080。 - 依据：https://github.com/open-webui/open-webui （README Troubleshooting）；https://docs.openwebui.com/troubleshooting/connection-error （Connection to Ollama Server、Docker Connection Error）。

2. 现象：容器重启 / 升级后，聊天记录、用户账号、上传文件全部丢失。 - 原因：docker run 命令遗漏 -v open-webui:/app/backend/data 数据卷挂载。 - 解决：README 明确 WARNING——必须包含该卷；重建容器时保持同名卷与 WEBUI_SECRET_KEY 不变；更新前先备份数据卷。

3. 现象：模型列表间歇性清空、聊天偶发报 "Model not found"，日志出现 ClientConnectorDNSError；在部分 Windows 主机上启动后所有外部模型请求直接失败。 - 原因：旧版本使用 c-ares 解析器，在部分 Windows 主机上找不到可用 DNS 服务器，Docker 内也可能间歇性无法解析容器名（官方排障文档给出该机理说明）。 - 解决：升级到最新镜像版本；升级后名称解析默认走操作系统解析器，host.docker.internal、Compose extra_hosts、K8s hostAliases 行为恢复正常。 - 依据：https://docs.openwebui.com/troubleshooting/connection-error （Intermittent Name Lookup Failures 一节）。

4. 现象：pip 安装体积异常庞大，或非 NVIDIA 机器上启动报 CUDA 相关错误。 - 原因：PyPI 默认 torch 包携带 NVIDIA CUDA 运行库；无 NVIDIA GPU 环境不应直接安装默认 torch。 - 解决：虚拟环境内先执行 pip install torch --index-url https://download.pytorch.org/whl/cpu，再 pip install open-webui；AMD GPU 改装 ROCm 版 PyTorch（官方文档指引至 PyTorch 安装页）。 - 依据：https://docs.openwebui.com/getting-started/quick-start/ （No NVIDIA GPU? 一节）。

5. 现象：首次上传文档时报 Hugging Face SSL 错误 / 嵌入模型下载超时，知识库处理失败。 - 原因：本地默认嵌入模型 sentence-transformers/all-MiniLM-L6-v2 需从 Hugging Face 下载，网络不通或 SSL 中断。 - 解决：按 09.4.1 A-4 设置 HF_ENDPOINT=https://hf-mirror.com/；离线环境设 HF_HUB_OFFLINE=1 并提前预置模型；RAG 引擎也可切换为 ollama / openai / azure_openai（环境变量 RAG_EMBEDDING_ENGINE），把嵌入计算移到已有服务上。 - 依据：https://docs.openwebui.com/troubleshooting/connection-error ；https://docs.openwebui.com/reference/env-configuration （RAG_EMBEDDING_ENGINE、RAG_EMBEDDING_MODEL）。

6. 现象：docker run 后浏览器打不开，日志报 port is already allocated；或 pip 启动端口冲突。 - 原因：默认 3000（Docker 发布端口）/ 8080（pip、容器内端口）被其他程序占用。 - 解决：Docker 改左侧端口，如 -p 3002:8080；pip 模式 open-webui serve --port 9999。 - 依据：https://docs.openwebui.com/getting-started/quick-start/ （Port already taken 说明）。

本节来源清单

待验证 / 未写死项说明： - 官方文档未给出 Open WebUI 应用本体的硬性最低内存与磁盘数值；09.3 中内存为官方实测空闲值（已注明非最低要求），磁盘为官方镜像体积实测值。 - ghcr.io 第三方加速器地址不在任何 Open WebUI 官方文档中，本章未编造具体镜像域名，仅给出 Docker 通用 registry-mirrors 配置思路。