装好 Ollama 之后，很多人卡在「命令行对话太原始」这一步。Open WebUI 是一个开源的本地大模型可视化平台，提供类 ChatGPT 的网页界面、多模型切换、知识库 RAG 与工具调用，一条 Docker 命令即可跑起来，是本地大模型从「能跑」到「好用」的关键一环。
一、为什么需要 Open WebUI
用 ollama run llama3 在终端里对话，最大的痛点是：没有聊天历史、没有多会话、不能上传文件、没有检索增强。Open WebUI 把这些能力一次性补齐——聊天记录持久化、用户体系、文档问答、联网搜索、Function Calling，而且界面体验接近商业产品。
更重要的是，它对接的是 OpenAI 兼容接口。这意味着 Ollama、vLLM、以及自建的 One API 这类大模型 API 网关都能作为后端接进来，前端与后端彻底解耦，你可以随时换底座而不用换界面。
对隐私敏感的场景，本地部署的价值尤为突出：企业内网文档、个人笔记、代码仓库都不必上传到任何第三方云端，全部在自有服务器上完成推理，数据真正做到不出域。这也是越来越多团队选择自建 Open WebUI 而非使用 SaaS 聊天产品的核心原因。
二、Docker 一键启动（推荐）
最省事的方式是使用官方 all-in-one 镜像，它把 Open WebUI 和 Ollama 打包在同一个容器里：
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:ollama生产环境更推荐用 docker-compose 做持久化与可维护的配置（镜像与卷的持久化思路可参考本站 Docker 容器化部署实战）：
services:
open-webui:
image: ghcr.io/open-webui/open-webui:main
container_name: open-webui
ports:
- "8080:8080"
volumes:
- open-webui:/app/backend/data
environment:
- WEBUI_SECRET_KEY=请改成随机长字符串
- OLLAMA_BASE_URL=http://host.docker.internal:11434
extra_hosts:
- "host.docker.internal:host-gateway"
restart: unless-stopped
volumes:
open-webui:连接外部 Ollama
如果 Ollama 已经独立运行在宿主机，给 Open WebUI 设置 OLLAMA_BASE_URL，并用 extra_hosts 把 host.docker.internal 指向宿主机网关，容器就能访问到宿主机的 11434 端口。本地模型先拉取一份：
ollama pull llama3.1
ollama pull nomic-embed-text # 用于知识库向量化三、镜像选择与 GPU 支持
默认 :main 镜像是 CPU 推理；若服务器有 NVIDIA 显卡，应改用 :cuda 镜像并在 docker run 时加 --gpus all，让 Ollama 走 GPU 获得数倍提速。个人部署 7B~14B 量化模型，一张 8G 显存的卡就够用；若用 70B 级别则需要多卡或高显存，具体量化收益可参考 本地大模型量化部署：GGUF 与 llama.cpp 调优。
四、首次配置与用户管理
启动后访问 http://服务器IP:8080，第一个注册的用户会自动成为管理员。务必设置 WEBUI_SECRET_KEY：若留空，容器每次重启都会重新生成会话密钥，导致已登录用户全部掉线。
管理员可在「设置 → 通用」中关闭开放注册（ENABLE_SIGNUP=false），改为手动邀请，适合团队内部使用。多用户体系下，每个人的聊天记录和知识库彼此隔离，管理员可在后台统一查看与清理。
五、模型管理：下载、切换与显存规划
Open WebUI 界面右上角可直接切换已安装的模型，无需回到命令行。查看本机模型列表用：
ollama list # 列出已下载模型
ollama run qwen2.5 # 临时拉取并运行建议按「主力对话模型 + 轻量 embedding 模型 + 可选重排序模型」的组合规划显存：对话模型选 Q4_K_M 量化的 7B/14B，embedding 用 nomic-embed-text，这样单卡即可流畅支撑「对话 + 知识库」两条链路。
六、知识库 RAG：上传文档就能问
Open WebUI 内置 RAG 能力：上传 PDF、Word、Markdown 后，系统自动切块、向量化并建立索引。对话时在输入框选择对应知识库，模型就会基于文档内容作答，并给出引用来源。默认使用 Ollama 的 embedding 模型（如 nomic-embed-text）完成向量化；也可在设置中改为任意 OpenAI 兼容的 embedding 服务。
体验不佳时，可微调两个关键参数：RAG_TOP_K 控制每次检索召回的片段数（默认 3~5，文档较长时调到 7~10），以及分块大小（chunk size）。若上传文档后检索不到内容，多半是 embedding 模型尚未下载，先 ollama pull nomic-embed-text 即可。
七、工具与 Function Calling
在「设置 → 工具」中可启用原生 Function Calling 与联网搜索函数，让模型具备实时查天气、查股价、调内部 API 的能力。进阶玩家还能通过 Functions / Pipelines 机制用 Python 或 JS 编写自定义工具，扩展出定时任务、数据库查询等玩法，把 Open WebUI 变成一个带界面的 AI Agent 工作台。
八、用 Nginx 反向代理暴露到公网
直接把 8080 端口暴露在公网并不安全，正确做法是用 Nginx 做反向代理并配置 HTTPS。这里最关键的是必须转发 WebSocket 的 Upgrade 头，否则流式输出（打字机效果）会失效。反向代理的基础配置可参考 Nginx 反向代理实战。
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 支持流式输出所需的 WebSocket 升级
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_http_version 1.1;
}九、与 One API 多模型网关集成
如果你已经在用 One API 自建大模型 API 网关，只需在 Open WebUI 的「设置 → 连接」里把 API Base URL 指向网关地址，模型名填网关中配置的模型即可。这样 Open WebUI 只负责前端交互，后端的模型调度、配额、多供应商聚合全部交给 One API，架构更清晰，也方便统一计费。
十、三种后端连接方式对比
| 后端类型 | 配置方式 | 适用场景 |
|---|---|---|
| Ollama 本地 | OLLAMA_BASE_URL 指向本机 11434 | 单机把玩、隐私优先 |
| vLLM 服务 | 填 OpenAI 兼容 Base URL | 高并发推理、多卡部署 |
| One API 网关 | Base URL 指向网关 | 多模型聚合、统一配额 |
十一、数据备份与迁移
所有用户数据、聊天记录、知识库索引都落在 /app/backend/data 这个挂载卷里。备份就是备份这个目录：停容器后打包卷所在路径，迁移到新机器时挂载同名卷即可完整恢复。建议配合定时任务定期归档，避免磁盘故障丢数据。
十二、常见问题排障
| 现象 | 根因 | 解决办法 |
|---|---|---|
| 连不上 Ollama | 容器内访问不到宿主机 11434 | 配 OLLAMA_BASE_URL + extra_hosts host-gateway |
| 流式不输出 | Nginx 未转发 WebSocket | 补 Upgrade / Connection 头 |
| 上传文档不检索 | embedding 模型未下载 | ollama pull nomic-embed-text |
| 重启后用户掉线 | 未设 WEBUI_SECRET_KEY | 补环境变量后重启 |
十三、小结
Open WebUI 把本地大模型从「命令行玩具」变成了「可用产品」：Docker 一键部署、多模型后端、知识库问答、工具调用、公网反代一条龙。配合 Dify + Ollama 搭建私有 AI 工作流 与 One API 网关，就能在自家服务器上搭出一套完整的私有 AI 平台。需要更高并发推理时，把后端换成 One API 聚合的多供应商模型即可弹性扩展。
