Open WebUI 是 ollama 生态里使用量最大的网页界面（GitHub 150k+ star）。它解决的是「模型有了，但只能敲命令行」的问题：把本地 ollama 变成浏览器里可用的 ChatGPT 式界面——多用户账号、会话管理、模型切换、本地知识库 RAG、联网搜索都有。

什么时候用：

• 你已装 ollama（或想用云端模型），想要一个网页界面给多人用/自己用；
• 你要本地知识库问答（上传文档后提问）——见组合包 combo-local-rag（ollama + open-webui 是其中一条路径）；
• 你要搭本地大模型环境——见组合包 combo-local-llm-finetune（open-webui 是默认界面）。

什么时候别用：只要命令行调模型（直接 curl ollama 的 API 更轻）；只需要简单 UI 且不想要 Docker（pip 形态 Python 3.11~3.12 限制多，见下）。

国内网络的关键：Docker 镜像走 ghcr 国内镜像站（ghcr.nju.edu.cn 实测可用）；pip 形态全部历史版本要求 Python 3.11~3.12，Python 3.14 实测装不上。

一条命令起容器（国内实测路径：ghcr.nju.edu.cn 镜像前缀 + 挂载 volume）：

# 来源: Trove 详细指南 · 验证于 2026-09-01
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.nju.edu.cn/open-webui/open-webui:main

预期输出: 一串容器 ID；docker ps 里 open-webui 状态 Up（约 1~2 分钟后转 healthy）

跑完浏览器打开 http://localhost:3000，第一次打开让你注册管理员账号（首个注册用户自动是 admin）。

前置条件：

• 已装 Docker（本环境实测 Docker 29.1.3）；
• 内存 ≥ 4GB（建议 8GB+，模型推理另算）；
• 磁盘 ≥ 10GB 空闲；镜像首次拉取约 1.8GB（2026-08-30 组合包路径实测 7.16GB 含多层传输）。

装好确认：

• docker ps 显示 healthy（短暂 unhealthy 属正常，初始化要 1~2 分钟）；
• 浏览器 http://localhost:3000 出现登录/注册页；
• 注册首个账号后能进主界面。

Open WebUI 是 Python 应用（FastAPI + uvicorn + SQLite），对外两种形态：

• Docker 镜像形态：镜像自带全部依赖和数据目录（/app/backend/data），一条 docker run 拉起。推荐路径——因为镜像可以通过 ghcr 国内镜像站拉取。
• pip 形态：pip install open-webui 直接跑在系统 Python。全部历史版本要求 Python 3.11~3.12（Requires-Python <3.13.0a1,>=3.11，实测 2026-09-01）。Ubuntu 24.04 默认 Python 3.12 可以；手动装的新版 Python（3.13/3.14）pip 直接拒绝——这是最常见的「装不上」原因。

两个关键机制：

• OLLAMA_BASE_URL（或界面「连接设置」）：open-webui 自己不跑模型，它通过这个地址调 ollama 的 API（默认 http://localhost:11434）。Docker 形态下容器里访问宿主 ollama，要用 host.docker.internal 或宿主网段地址（实测 172.17.0.1）。
• 数据都在 webui.db（SQLite）+ uploads/ + vector_db/：账号、会话、上传文档、RAG 向量库全在里面。Docker 形态务必挂载 volume，删容器不丢数据。

装完它动哪里：Docker volume（数据目录）；pip 形态 = Python 包（site-packages）+ 数据目录（默认 ~/.open-webui/）。端口 8080（容器内），宿主映射自选（示例 3000）。

第 1 步：首次打开 + 注册管理员

讲解：open-webui 首个注册用户自动是 admin，注册即管理员；后续用户由 admin 管理。

# 来源: Trove 详细指南 · 验证于 2026-09-01
docker ps --filter name=open-webui

预期输出: 容器 Up（healthy 状态，2026-09-01 实测：约 1~2 分钟从 unhealthy 转 healthy）

浏览器打开 http://localhost:3000 → 注册页填邮箱/密码 → 进入主界面。

卡住怎么办：

• 容器反复 unhealthy → 等 1~2 分钟再看（初始化慢是正常）；还不行看 docker logs open-webui 尾部错误；
• 端口被占 → 换映射端口（-p 3001:8080）；
• 注册后白屏 → 硬刷新；确认浏览器能到 3000 端口（非代理拦截）。

第 2 步：连上 ollama（自动 + 手动）

讲解：open-webui 默认自动探测 localhost:11434；Docker 形态容器里的 localhost 是容器自己，需要指向宿主。

# 来源: Trove 详细指南 · 验证于 2026-09-01
curl -s http://localhost:3000/api/models

预期输出: 模型列表 JSON（连上 ollama 后能看到 ollama 的模型；2026-09-01 实测 signin 后 /api/models 见 ollama 模型）

卡住怎么办：

• 没有模型 → 界面「设置 → 连接设置」把 OLLAMA_BASE_URL 改为 http://172.17.0.1:11434（容器访问宿主）；snap 版 ollama 还要 sudo snap set ollama host=0.0.0.0:11434 + restart（见 ollama 详细指南第 4 节）；
• 模型列表空但 ollama 有模型 → 确认 ollama serve 在跑、base_url 可达（容器内 curl 172.17.0.1:11434/api/version 测试）。

第 3 步：网页聊天与模型切换

讲解：界面右上角选模型，输入即聊；会话在左侧栏管理。多模型时切换即用。

# 来源: Trove 详细指南 · 验证于 2026-09-01
curl -s http://localhost:3000/api/health

预期输出: 健康检查 OK（{"status":true} 形态；2026-09-01 实测 /health 200）

卡住怎么办：

• 回答慢/不输出 → 看 ollama 侧（ollama ps 确认模型已加载）；小模型首轮加载慢正常；
• 模型不出现 → 见第 2 步连接设置。

第 4 步：命令行调 open-webui 的 OpenAI 兼容 API

讲解：open-webui 提供 OpenAI 兼容端点 /api/chat（需 token；本环境实测 signin 后取 token 调 /api/models 成功）。

# 来源: Trove 详细指南 · 验证于 2026-09-01
# 登录拿 token（示例；实际用你的管理员账号）
curl -s -X POST http://localhost:3000/api/auths/signin -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"yourpass"}' | python3 -c "import sys,json;print(json.load(sys.stdin)["token"])"

预期输出: JWT token 串（2026-09-01 实测 signin 成功；后续请求带 Authorization: Bearer <token>）

卡住怎么办：

• signin 失败 → 确认已注册账号；密码错误检查大小写；
• 403 → token 过期/无效，重新 signin。

与工具页矩阵同源；完整对子、状态与证据见 冲突对子（共装矩阵）。已知关联：

• open-webui × ollama = compatible（实测 verified）：2026-09-01 全链路实测（容器连宿主 ollama 推理成功，/api/models 见模型）；
• open-webui × MaxKB：同 RAG 场景的替代关系（combo-local-rag 用 MaxKB 作默认成员，open-webui 也可做 RAG），不冲突；
• 与其余 26 工具：静态判定 possible-compatible（写面不重叠）。

• 症状：pip install open-webui 报 Could not find a version → Python 必须 3.11~3.12（3.13/3.14 实测拒绝）；换 Docker 形态
• 症状：Docker 容器 unhealthy 反复 → 初始化 1~2 分钟正常；看 docker logs 尾部
• 症状：界面没有模型 → OLLAMA_BASE_URL 指向 172.17.0.1:11434（容器场景）；snap ollama 需 host=0.0.0.0
• 症状：镜像拉不动 → ghcr.nju.edu.cn 换其他 ghcr 镜像（ghcr.dockerproxy.com）或等代理窗口
• 症状：删容器后数据没了 → 必须挂 volume（-v open-webui:/app/backend/data），数据全在 volume 里

四段式全文（症状→原因→解法→验证证据）：站内文档（如已收录）

# 来源: Trove 详细指南 · 验证于 2026-09-01
docker stop open-webui && docker rm open-webui
docker volume rm open-webui

预期输出: 容器停止/删除成功；volume 删除后 docker volume ls 不再显示 open-webui

注意：volume 删除 = 账号/会话/文档/RAG 向量库全没。想保留数据就只删容器不删 volume（重新 run 时同名 volume 自动复用）。

• 问：为什么 pip 装不上？答：open-webui 全部历史版本要求 Python 3.11~3.12；Python 3.13/3.14 实测拒绝（Could not find a version）。不想折腾就用 Docker 形态（推荐）。
• 问：容器里连不上 ollama？答：容器里的 localhost 是容器自己。连接设置用 http://172.17.0.1:11434（或 host.docker.internal）；snap 版 ollama 需 host=0.0.0.0 + restart。
• 问：数据存哪、删容器会丢吗？答：全在 volume（webui.db + uploads/ + vector_db/）。挂载 -v open-webui:/app/backend/data 后删容器不丢；不挂卷就丢。
• 问：首次注册的账号是什么角色？答：首个注册用户自动是 admin，之后注册的是普通用户。
• 问：能接云端模型吗？答：能，连接设置支持 OpenAI 兼容远程地址（未实测，界面能力）。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

• 版本：main（manifest 记录 main 跟踪标签；实测 2026-09-01 镜像）。
• 环境：Docker 29.1.3（WSL2 Ubuntu 实测）；内存 ≥4GB 建议 8GB+；磁盘 ≥10GB。
• 网络：镜像 ghcr.nju.edu.cn 实测可用（两次）；pip 形态 Python 3.11~3.12。
• 写面：Docker volume open-webui（/app/backend/data）；pip 形态 ~/.open-webui/。
• 端口：容器内 8080，宿主映射自选（示例 3000）；OLLAMA 互通 11434。

• 条目签名：open-webui/open-webui（Open WebUI License：BSD-3 基础 + 品牌条款：≤50 用户/30 天可改品牌，以上需书面/企业授权）

• 实测：实测复现日志（2026-09-01）（Docker 全链路：ghcr.nju 镜像 → healthy → /health 200 → signup admin → signin → /api/models 见 ollama 模型 → chat 真实推理）
• 未实测：pip 形态正常路径（本环境 Python 3.14 装不上，如实标注）；远程 OpenAI 兼容模型接入；多用户权限管理细节。