Open WebUI 全指南

一、平台介绍

1. 基础数据

• 开源协议：遵循 Apache2.0 开源协议，开源免费。
• 社区规模：GitHub 拥有 140K+ Star，41.9 万社区成员，全球下载量 2.9 亿+。
• 版本迭代：当前为最新 v0.8+ 版本（注：资料提及 2026 年更新），社区活跃，持续迭代。
• 技术架构：
• 前端：Svelte
• 后端：Python
• 系统支持：Windows / macOS / Linux
• 部署方式：Docker / K8s 容器部署 / GPU 硬件加速
• 核心定位：自主可控 AI 操作台。不租用云端 AI，数据全部留存本地。支持离线单机运行或云端服务器部署，统一管理本地、Ollama、OpenAI、Anthropic、OpenRouter 等全兼容 API 模型。
• 官网地址：openwebui.com

2. 核心优势

• 隐私安全：数据私有化，不上传云端。
• 全兼容：统一接口对接各类模型。
• 灵活部署：单机或服务器均可运行。

二、核心主要功能

1. 多模型统一接入（核心功能）

单界面统一对接所有主流大模型，支持一键切换与配置：

• 本地模型类：支持 Ollama、LM Studio、vLLM、HuggingFace 本地部署模型。
• 云端 API 类：支持 OpenAI、DeepSeek、Anthropic、Groq、OpenRouter 等所有 OpenAI 兼容接口。
• 配置方式：右上角头像进入管理员面板，直接配置 API 密钥与接口地址。

2. 内置 RAG 私有知识库（王牌功能）

• 文档支持：支持 PDF、Word、TXT、Excel 等多种格式上传。
• 向量库对接：支持 Chroma、PGVector、Qdrant 等 9 种向量数据库。
• 功能亮点：
• 聊天时自动检索私有文档。
• 提供引用来源标注。
• 适合搭建企业内部知识库问答系统。

3. AI 增强工具集

• 联网搜索：内置 15+ 搜索源（如 DuckDuckGo、Bing），支持自建 SearXNG 免费本地搜索，AI 可实时查询外网信息。
• 多模态能力：支持语音输入输出、图片识图、AI 绘图。
• 内容渲染：支持 Markdown 排版、LaTeX 公式渲染、代码高亮、代码运行沙箱。
• 自定义扩展：支持 Python 自定义函数/工作流、加载社区共享提示词、插件及工具脚本。

4. 企业级用户与权限管控

• 权限管理：RBAC 细粒度权限控制，管理员可新建分组。
• 功能限制：可限制用户可用模型、知识库、搜索功能。
• 安全登录：支持 SSO 单点登录、OAuth 第三方登录、聊天审计日志、注册白名单，适合金融/政企等合规行业。

5. 社区生态 & 配套

• 内置社区 Hub：免费下载社区分享的提示词、模型配置、自定义工具、角色人设。
• 模型竞技场：支持多模型同台对比回答效果。
• 移动端访问：支持 PWA 移动端访问，手机离线使用。

三、适用人群

1. 推荐用户

1. 个人 AI 爱好者/程序员：本地免费跑开源大模型（如 Llama3、Qwen、Mistral），自建私有 ChatGPT，保护对话隐私。
2. 职场/科研人员：上传行业资料构建知识库，AI 辅助论文、文档、资料检索。
3. 中小企业/创业团队：私有化部署团队 AI 中台，内部文档问答，避免企业数据外流至第三方 AI 平台。
4. AI 服务商/运维：统一管理多渠道 API 模型（OpenAI+ 本地开源混合部署），管控员工调用权限、统计 Token 消耗。
5. 教育/实验室：构建课堂私有化 AI 环境，支持离线教学大模型实训。

2. 不适合人群

• 零硬件条件用户：无法自备服务器或电脑的普通用户。
• 不想部署用户：只想开箱即用云端 AI 服务的用户。
• 无模型资源用户：无法下载本地模型资源，完全依赖外部网络的用户。

四、免费&付费详情

1. 全功能永久免费（99% 用户适用）

• 软件本体：100% 开源免费。
• 功能范围：所有核心功能（聊天、RAG、多模型接入、权限、搜索、自定义插件）无功能阉割、无试用期限、无广告。
• 商用权利：个人/商用完全免费，可二次修改源码。
• 社区资源：社区提示词、工具、配置全部免费下载。

2. 唯一隐性成本：模型本身费用

• 本地 Ollama 开源模型：完全免费，仅消耗本机硬件（CPU/GPU）资源。
• 对接云端 API：按平台官方 Token 计费（如 OpenAI、DeepSeek 等），Open WebUI 平台本身不抽成。

3. 付费项目说明（企业增值服务）

• 官方无软件订阅费：不存在软件收费订阅。
• 付费内容：仅为企业商业技术支持。
• 服务项目：包括定制部署、安全加固、7×24 运维、合规审计服务、私有化定制开发等（按需采购，个人用户完全不需要）。

五、详细使用教程（2 种主流安装方式，新手优先 Docker）

1. 环境最低配置

• 内存：≥4GB（推荐 8GB+）
• 磁盘：≥20GB
• GPU 建议：跑 7B 以上大模型建议 8G+ 独立显存 GPU
• 系统：Windows / macOS / Ubuntu / CentOS

前置准备：如需本地跑模型，建议提前安装 Ollama。 安装命令：curl -fsSL https://ollama.com/install.sh | sh

2. 方式 1：Docker 一键部署（推荐，全平台通用）

bash

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
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

• 参数详解：
• 3000：访问端口（可自行修改）。
• open-webui：本地数据持久化挂载目录。
• main：镜像版本标签。
• 启动后：浏览器访问 http://localhost:3000。
• 首次注册：注册账号后自动成为超级管理员。

3. 方式 2：Python pip 原生安装（无 Docker 环境）

bash

# 1. 安装 Python 3.10~3.11，创建虚拟环境
pip install open-webui

# 2. 启动服务
open-webui serve

# 访问：http://localhost:8080
# 1. 安装 Python 3.10~3.11，创建虚拟环境
pip install open-webui

# 2. 启动服务
open-webui serve

# 访问：http://localhost:8080

• 升级服务：pip install -U open-webui 一键更新版本。

4. 初次配置三步

• 对接 Ollama 本地模型路径：右上角头像 → 管理员面板 → 设置 → 模型
• Ollama 地址：默认填写 http://host.docker.internal:11434
• 操作：提前在 Ollama 运行 ollama pull qwen:7b 下载模型。
• 对接云端 API同页面添加 OpenAI 密钥（API Key）及接口地址。
• 新建知识库（RAG）路径：侧边栏“知识库” → 新建 → 上传文档 → 创建向量库。
• 聊天时：在聊天页选择对应知识库即可实现 RAG 问答。

六、部署&使用避坑清单（高频踩坑汇总）

1. 网络&连接坑（最高发）

• Docker 容器连不上宿主机 Ollama原因：容器无法访问宿主机 127.0.0.1。
• 解决：Ollama 启动前配置 OLLAMA_HOST=0.0.0.0 并运行 ollama serve；或 Docker 使用 --network host 宿主机网络模式启动容器。
• HuggingFace 模型下载失败解决：Docker 启动添加镜像环境变量 -e HF_ENDPOINT=https://hf-mirror.com，走国内 HF 镜像加速下载。
• 远程服务器无法访问 WebUI 页面解决：服务器防火墙放行端口（如 3000/8080）：ufw allow 3000/tcp，云服务器安全组放行对应端口。

2. 端口&存储坑

• 端口被占用启动报错 Address already in use解决：修改 docker 参数 -p 自定义端口:8080（如 -p3001:8080）；使用 lsof -i:端口号 查询占用进程并关闭。
• Docker 数据丢失警示：不要删除挂载目录 open-webui。重装容器时，保留挂载卷（Volume）即可保留聊天记录与知识库。

3. 硬件&性能坑

• 低配置电脑卡顿、模型加载失败建议：4G 内存仅推荐 1.5B 小模型；7B 及以上模型必须 8G+ 显存 GPU；无 GPU 仅 CPU 跑模型速度极慢。
• RAG 文档过大报错限制：单文件不建议超 500MB；超大文档建议拆分上传。
• 优化：关闭「全文直传」，开启分块向量化。

4. 配置&使用坑

• API 调用报错密钥无效排查：核对接口地址/密钥；OpenRouter 等第三方 API 地址不要写错。
• AI 回答乱码/非中文解决：全局系统提示词添加：你全程使用中文回复用户问题。
• 升级后功能异常建议：升级前备份挂载目录数据；大版本跨代升级建议重建容器。

5. 安全避坑

• 公网直接裸奔 8080 端口风险：外网部署直接暴露端口存在安全风险。
• 加固：务必使用 Nginx 反向代理 + HTTPS 证书，设置高强度管理员密码，关闭公开注册，开启注册白名单。
• Ollama 默认全外网开放风险：内网使用限制 IP 访问，避免公网随意调用本地模型。

七、补充小贴士

1. 国内模型推荐：优先搭配 Ollama + 通义千问/Qwen/DeepSeek 开源本地模型，实现零 API 费用。
2. 免费联网搜索：需部署 SearXNG 对接 Open WebUI，无需购买付费搜索 API。
3. 移动端体验：浏览器打开网页添加到桌面，开启 PWA，实现类 APP 使用体验。
4. 模型选择建议：

• 入门体验：Qwen-7B / Llama3-8B。
• 企业知识库：建议使用 Qwen-14B 或更大模型以获得更好的中文理解能力。