open-webui/open-webui · 上手攻略
- 仓库：open-webui/open-webui
- 链接：https://github.com/open-webui/open-webui
- 分类：AI 交互界面 / LLM 前端（llm-infra）
- 作者：Jay
- 更新：2026-07-05
它是什么
Open WebUI 是一个可扩展、功能丰富、用户友好的自托管 AI 交互界面。它的核心目标是让你完全离线运行自己的 AI 界面，同时支持连接任意 OpenAI API 兼容的模型（包括本地 Ollama、私有化部署的 vLLM、LM Studio 等）。
用一张图来理解它的位置：
用户浏览器 ←→ Open WebUI ←→ Ollama / OpenAI API / vLLM / Groq / Mistral ... ←→ LLM 模型
Open WebUI 是 2024-2025 年增长最快的开源 AI UI 项目之一，GitHub Stars 已超过 14.4 万，并发展出包括桌面端、终端集成、知识库同步工具在内的完整生态圈。
核心能力亮点：
- 🚀 支持 Ollama、OpenAI、兼容 OpenAI API 的任意提供商
- 🔐 细粒度 RBAC + 用户组权限管理
- 🧩 插件系统：Filters、Actions、Pipes、Tools、Skills（MCP 兼容）
- 🤖 自定义 Agent 构建，导入社区 Preset
- 📚 内置 RAG（支持 9 种向量数据库）
- 📅 日历 + AI 调度，Channels 团队协作空间
- 🎤 语音/视频通话，多 STT/TTS 引擎
- 📊 用量分析 + 模型评估 Arena
解决什么问题
- Ollama 原生 UI 太简陋：没有用户管理、没有 RAG、没有多模型对比
- 想用 OpenAI API 但不想数据出境：私有部署，数据完全在自己服务器
- 团队需要一个共享的 AI 工作台：需要多用户、权限控制、知识库共享
- 想给 AI 接各种工具和插件：缺乏可扩展性，自己写很麻烦
- 需要完整 LLMOps 视角：用量统计、Token 消耗、模型评估
快速安装
方案一：Docker（推荐，最简单）
前置条件
- Docker 和 Docker Compose 已安装
- 若使用 GPU，需安装 NVIDIA CUDA Container Toolkit
基本安装（连接本机 Ollama）
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
启动后访问 http://localhost:3000 完成初始化注册。
带 Ollama 的 all-in-one（不需要本机已装 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
docker run -d -p 3000:8080 \
-v ollama:/root/.ollama \
-v open-webui:/app/backend/data \
--name open-webui \
--restart always \
ghcr.io/open-webui/open-webui:ollama
连接远程 Ollama 或其他 API
# 连接远程 Ollama
docker run -d -p 3000:8080 \
-e OLLAMA_BASE_URL=https://your-ollama-server.com \
-v open-webui:/app/backend/data \
--name open-webui \
--restart always \
ghcr.io/open-webui/open-webui:main
# 只用 OpenAI API
docker run -d -p 3000:8080 \
-e OPENAI_API_KEY=sk-xxxx \
-v open-webui:/app/backend/data \
--name open-webui \
--restart always \
ghcr.io/open-webui/open-webui:main
# NVIDIA GPU 加速
docker run -d -p 3000:8080 --gpus all \
--add-host=host.docker.internal:host-gateway \
-v open-webui:/app/backend/data \
--name open-webui \
--restart always \
ghcr.io/open-webui/open-webui:cuda
⚠️ 网络问题：如果遇到 Ollama 连接问题，Docker 容器默认无法访问宿主机的 127.0.0.1，需加
--add-host=host.docker.internal:host-gateway，或使用--network=host模式（注意端口会从 3000 变为 8080）。
方案二：pip 安装（非 Docker 环境）
# Python 3.11+ required
pip install open-webui
open-webui serve
# 访问 http://localhost:8080
方案三：uv 安装
uv pip install open-webui
open-webui serve
核心用法
1. 初始化配置
首次访问 http://localhost:3000，注册管理员账号。
进入 「设置」→「模型」，确认 Ollama 已连接：
OLLAMA_BASE_URL: http://host.docker.internal:11434
点「刷新」获取 Ollama 中已下载的模型列表。
2. 添加外部 API 模型（如 GPT-4、Mistral）
进入 「设置」→「连接」→「OpenAI」：
API Key: sk-xxxx
Base URL: https://api.openai.com/v1 （或其他兼容端点）
保存后可在对话中切换不同模型。
支持的兼容 API 端点：LM Studio、Groq Cloud、Mistral API、OpenRouter、vLLM 等，设置方式类似。
3. 构建自定义 Agent
进入 「设置」→「Agent」：
1. 选择基础模型
2. 添加 System Prompt（角色设定）
3. 添加工具（Tools）：Web 搜索、代码执行、MCP 工具等
4. 挂载知识库（# 引用）
5. 设置访问控制（哪些用户/用户组可用）
Agent 可从 Open WebUI Community 导入他人分享的 Preset。
4. RAG 知识库
1. 进入「知识库」标签
2. 上传文档（PDF、Word、网页、Markdown 等）
3. 选择向量数据库（默认 ChromaDB，可切换 PGVector/Qdrant/Milvus 等）
4. 等待索引完成
在对话中用 # 引用知识库内容：
#knowledge:内部文档
帮我总结这份文档的核心要点
5. Web 搜索集成
在 「设置」→「连接」→「Web Search」 配置搜索提供商（支持 SearXNG、Google PSE、Brave、Kagi、Tavily、DuckDuckGo 等数十种）。
开启后可在对话中实时搜索网络，RAG 也会使用搜索结果增强。
6. 插件系统
进入 「设置」→「插件」，可安装：
| 插件类型 | 说明 |
|---|---|
| Filters | 过滤/修改输入/输出内容 |
| Actions | 触发外部动作（Webhook 等） |
| Pipes | 自定义模型接入管道 |
| Tools | 扩展 Agent 可用工具集 |
| Skills | Agent Skill 包（支持 MCP/MCPO） |
7. Open WebUI API
Open WebUI 所有功能均有 REST API 支持，可在 「设置」→「API」 中查看文档。
8. 更新方法
# Docker 方式
docker stop open-webui
docker rm open-webui
docker pull ghcr.io/open-webui/open-webui:main
# 重新运行（注意保留 -v 数据卷）
docker run -d -p 3000:8080 ...（同安装命令）
# pip 方式
pip install --upgrade open-webui
建议设置 WEBUI_SECRET_KEY 环境变量，避免每次更新后被迫重新登录。
典型适用场景
- 本地 AI 工作站：在 Mac/PC 上用 Ollama + Open WebUI 搭建完全离线的 AI 助手
- 团队共享 AI 平台：多用户、权限控制、知识库共享，适合企业内部部署
- LLM 模型评测：内置 Arena + A/B 测试 + ELO 排行榜，系统性评估模型
- AI 应用开发调试：快速切换模型、配置 Agent、测试 Prompt
- RAG 应用原型：上传文档，用自然语言查询，无需写一行代码
- 语音/视频 AI 助手：hands-free 交互，支持多种 STT/TTS 引擎
坑与注意
| 坑 | 说明 |
|---|---|
| 端口冲突 | Docker 默认端口 3000（外部）/ 8080（内部），本机如有服务占用需调整 -p 参数 |
| Ollama 网络 | Docker 容器访问宿主机 Ollama 必须加 --add-host=host.docker.internal:host-gateway，或使用 --network=host（此时访问端口变为 8080） |
| Python 3.11 | pip 方式安装要求 Python ≥ 3.11，低版本无法运行 |
| 生产环境 PostgreSQL | 默认 SQLite，生产环境建议切换 PostgreSQL（配置见文档） |
| 数据卷必挂 | Docker 安装时必须挂载 open-webui:/app/backend/data 卷，否则重启后数据丢失 |
| 多 Worker 部署 | Redis 支持水平扩展，需自行配置 |
| 插件安全 | 第三方插件来源需核实，建议只在内部网络使用 |
| 更新丢 key | 建议设置 WEBUI_SECRET_KEY 环境变量，防止更新后被迫重新登录 |
与同类对比
| 工具 | 类型 | 定位 | vs Open WebUI |
|---|---|---|---|
| Open WebUI | 自托管 AI UI | 功能完整、支持离线、可扩展 | 本工具 |
| Ollama Web UI | Ollama 官方 UI | 极简、功能有限 | Open WebUI 是 Ollama Web UI 的功能超集 |
| Chatbot UI / Open Assistant | 开源 ChatGPT 替代 | 仅 UI，无 Agent/RAG 能力 | 功能差距显著 |
| Lobe Chat | 开源 AI UI | 功能接近，也有插件和 RAG | 生态插件数 Open WebUI 更多 |
| Jan | 本地 AI 桌面 | 完全离线的桌面应用 | Jan 更偏向个人轻量使用，Open WebUI 适合团队 |
| OneChat / FastGPT | 国内 AI UI | 主要面向国内用户 | Open WebUI 国际生态更丰富 |
| Text Generation WebUI (oobabooga) | 本地 LLM UI | 专注模型推理，非对话 UI | 面向不同场景，Open WebUI 更适合 Agent 对话 |
Open WebUI 在「功能完整度 × 开源生态 × 易用性」三角中处于非常领先的位置，是目前自托管 AI UI 的事实标准。
一句话推荐结论
无论你想在本地跑一个完全私密的 AI 助手，还是给团队搭建一个支持多模型、RAG、插件和权限管理的 AI 工作台，Open WebUI 都是目前功能最完整、安装最简单、插件生态最丰富的开源选择。
来源
- GitHub README（https://github.com/open-webui/open-webui）
- Open WebUI 官方文档（https://docs.openwebui.com）
- Open WebUI 更新指南（https://docs.openwebui.com/getting-started/updating）
- Open WebUI GitHub Releases
- WeavAI Blog：Open WebUI 2026 Setup Guide（2026-04）
- Web 搜索：open-webui 2026 最新版本与功能（2026-07）