你会遇到什么

你已经用 ollama run qwen2.5>>> 在命令行里聊上天了，但界面只有黑底白字——想传个文档让它基于资料回答、想用鼠标切换模型、想看看历史会话，命令行都做不到。于是你搜到 open-webui，照着文档敲 pip install open-webui>>>，结果等来一句 Could not find a version that satisfies the requirement open-webui>>>。或者 Docker 用户更惨：docker pull ghcr.io/open-webui/open-webui>>> 拉到一半转圈超时。 这篇指南是实测过的完整路径：Docker 形态走国内 ghcr 镜像（ghcr.nju.edu.cn，实测可用），pip 形态先把 Python 降到 3.11/3.12 再装。装完你得到：浏览器里的聊天界面（http://localhost:3000 或自选端口）、和 ollama 的自动连接、可选的本地知识库。 什么时候用：

• 你要给本地大模型一个网页聊天界面（比命令行直观，支持会话历史、多模型切换）；
• 你要做本地知识库 RAG：把文档喂进去，基于你的资料回答（2026-08-30 组合包 combo-local-llm-finetune 已实测全链路）；
• 你要给团队/家庭提供局域网内的大模型聊天入口（注意：50 人以内个人使用没限制，见 FAQ 许可证条）。

什么时候别用：只要命令行对话，`ollama run>>> 已经够；要企业级多租户/权限审计，open-webui 不是专为这个设计的。

本文路径：快速修复（一条命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）→ 日常使用（长期操作）→ 卸载。赶时间直接跳到「快速修复」。

为什么会这样

open-webui 是 ollama 生态里使用量最大的网页界面（GitHub 150k+ star）。它是个 Python 应用（FastAPI + uvicorn + SQLite），对外提供两种形态：

• Docker 镜像形态：镜像自带全部依赖和数据目录（/app/backend/data），一条 `docker run>>> 拉起。这是推荐路径，也是国内用户最省心的路径——因为镜像可以通过 ghcr 国内镜像站拉取。
• pip 形态：pip install open-webui>>>，直接跑在系统 Python 里。注意：open-webui 全部历史版本都要求 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/）。

一步步来

第 1 步：Docker 形态装起来

讲解：镜像自带 Python 与全部依赖，绕开 pip 形态的 Python 版本限制。国内网络的关键是镜像前缀：官方是 ghcr.io>>>（直连实测超时），换成 ghcr.nju.edu.cn>>>（南京大学镜像，2026-08-30 组合包实测拉取成功、本次 2026-09-01 复用缓存镜像启动成功）。数据挂到 volume open-webui>>>，删容器不丢账号和会话。--add-host=host.docker.internal:host-gateway>>> 让容器里能用 `host.docker.internal>>> 指回宿主（连 ollama 用）。 `agent 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（如 5e7e82f26c89…，2026-09-01 实测）

装好确认：

• docker ps | grep open-webui>>> 状态 Up>>>；
• 首次启动要初始化数据库，约 1~2 分钟内健康检查从 starting>>> 转 healthy>>>（期间短暂 `unhealthy>>> 是正常现象，实测第 18 次检查转 healthy）。

卡住怎么办：

• 镜像拉不动（ghcr.io 超时）→ 把前缀换成 `ghcr.nju.edu.cn>>>（2026-08-30/09-01 实测可用）；或先开代理拉一次缓存后再用国内前缀启动。
• 端口 3000 被占 → 改宿主映射 `-p 3001:8080>>>，浏览器开 http://localhost:3001。
• Docker 没装 → 先装 Docker（`curl -fsSL https://get.docker.com | sh>>> 或发行版包管理器），再回来跑。

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

讲解：open-webui 的第一个注册用户自动是管理员（实测 signup 接口返回 role=admin）。之后别人注册是普通用户。如果是给局域网共享，可以在「设置 → 界面」里关掉注册开关。 `bash

浏览器打开

http://localhost:3000

或命令行验证注册接口（首个用户即管理员）

curl -s -X POST http://localhost:3000/api/v1/auths/signup \ -H "Content-Type: application/json" \ -d '{"name":"tester","email":"you@example.com","password":"your-password","role":"admin"}'

>>

预期输出: 浏览器出现注册/登录页；curl 返回 `{"id":"…","role":"admin","token":"eyJ…"}>>>（2026-09-01 实测）

卡住怎么办：

• 注册接口返回 405 Method Not Allowed → 确认用 POST 且 URL 是 /api/v1/auths/signup；登录用 /api/v1/auths/signin（2026-09-01 实测两者端点不同，登录写错成 signup 会 405）。
• 注册页转圈/打不开 → 等健康检查变 healthy（`docker inspect open-webui --format '{{.State.Health.Status}}'>>>）再刷新。
• 局域网别人注册成普通用户 → 管理员在「设置 → 界面」关掉注册开关。

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

讲解：open-webui 自己不跑模型。Docker 形态启动时没指定 OLLAMA_BASE_URL>>> 的话，默认连 http://host.docker.internal:11434>>>（容器里访问宿主的默认地址）。加 `-e OLLAMA_BASE_URL=http://host.docker.internal:11434>>> 可以显式指定。装完在界面「设置 → 连接」里也能改。 `bash

验证宿主 ollama 在跑（容器外执行）

curl -s http://localhost:11434/api/tags

验证容器能连到宿主 ollama（容器内执行）

docker exec open-webui curl -s http://172.17.0.1:11434/api/tags

>>

预期输出: 各返回一个 `{"models":[…]}>>> 列表，里面有你拉过的模型（实测 qwen2.5-0.5b 可见）

卡住怎么办：

• 容器内 curl 失败/超时 → 确认 ollama 监听地址：WSL2 里 snap 版 ollama 默认监听 127.0.0.1 时容器访问不到，改用 OLLAMA_HOST=0.0.0.0>>> 重启 ollama 或用 --add-host>>> 直连宿主 IP（实测 172.17.0.1 可达）。
• 界面「连接设置」改地址后仍失败 → 改完保存后重启容器（`docker restart open-webui>>>），再回界面看模型列表。

第 4 步：pip 形态（不想用 Docker 时）

讲解：pip 形态等于把 Python 应用装进系统环境。硬性前置：Python 3.11 或 3.12。open-webui 所有版本 Requires-Python <3.13.0a1,>=3.11>>>——Python 3.13/3.14 直接装不上（2026-09-01 实测：3.14.4 + pip 25.1.1 报 Could not find a version that satisfies the requirement>>>）。Ubuntu 24.04 自带 3.12 没问题；手动装过新版 Python 的，用 pyenv 装 3.12 再建虚拟环境： `agent

先确认 Python 版本（必须 3.11 或 3.12）

python3 --version

Ubuntu 24.04 默认 3.12 可直接装；其他环境先装 pyenv + Python 3.12

pip install open-webui --index-url https://pypi.tuna.tsinghua.edu.cn/simple open-webui serve

>>

预期输出: `open-webui serve>>> 启动 uvicorn（默认端口 8080）；浏览器开 http://localhost:8080

卡住怎么办：

• Could not find a version that satisfies the requirement open-webui>>> → 不是网络问题，是 Python 版本不对。python3 --version>>> 如果是 3.13/3.14，先装 Python 3.12 再用它建虚拟环境（实测根因，2026-09-01）。
• 依赖重（PyTorch 等几百 MB）→ 国内用清华 PyPI 镜像（上面命令已带）。

怎么确认修好了

`bash

1. 健康检查（Docker 形态）

curl -s http://localhost:3000/health

预期输出: {"status":true}（2026-09-01 实测 http 200）

2. 登录拿 token

curl -s -X POST http://localhost:3000/api/v1/auths/signin \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com","password":"your-password"}'

预期输出: 包含 "token":"eyJ…" 的 JSON

3. open-webui 能看到 ollama 的模型（用上一步的 token）

curl -s http://localhost:3000/api/models -H "Authorization: Bearer <token>"

预期输出: {"data":[{"id":"qwen2.5-0.5b:latest","owned_by":"ollama",…}]}

4. 真实聊一句（走 open-webui → ollama 全链路）

curl -s http://localhost:3000/api/chat/completions \ -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \ -d '{"model":"qwen2.5-0.5b:latest","messages":[{"role":"user","content":"Say OK"}],"stream":false}'

预期输出: choices[0].message.content 为模型回答（实测 "OK, thank you."，6 输出 token）

>>

浏览器里：登录后能看到模型列表、能新建会话并得到回答，就算全链路通了。

其它环境的表现（常见变体）

• Windows（Docker Desktop + WSL2）：本文实测环境。docker run>>> 命令可直接用；浏览器访问 http://localhost:3000>>>；WSL2 里 ollama 装在宿主时容器用 172.17.0.1>>> 或 host.docker.internal>>> 访问（2026-09-01 实测 172.17.0.1 可达）。
• macOS：Docker Desktop 自带 host.docker.internal 解析，命令同上；Apple Silicon 无 NVIDIA GPU，推理走 ollama 的 Metal 加速（未实测，推断）。
• Linux 裸机：容器内访问宿主用 --add-host=host.docker.internal:host-gateway>>>（命令已带）；系统 Docker 用 systemd 管理时注意 --restart always>>> 的容器会在 Docker 启动时自动拉起。
• pip 形态：Python 3.11/3.12 环境里 pip install open-webui>>> + open-webui serve>>>，默认端口 8080；本机 Python 3.14 实测装不上（见 FAQ Q1）。
• 局域网访问：同网段设备用 `http://<宿主IP>:3000>>> 访问；首次注册的管理员账号在哪个设备登录都有效（数据在 volume 里）。

依赖警告

• pip 形态 Python 版本：全部版本要求 3.11~3.12（`Requires-Python <3.13.0a1,>=3.11>>>）；3.13/3.14 实测装不上——这是最高频安装坑。
• Docker 镜像体积：首次拉取约 1.8GB（组合包先例实测含多层传输 7.16GB）；磁盘需 ≥10GB 空闲。
• 端口：容器内固定 8080；宿主映射端口（示例 3000）被占时改 `-p>>> 参数。
• 与 ollama 的依赖：open-webui 不跑模型，必须先有 ollama 服务（11434）；Docker 形态容器到宿主的网络需 --add-host>>> 或 OLLAMA_BASE_URL>>> 正确配置（2026-09-01 实测）。
• 许可证品牌条款：Open WebUI License 第 4 条——30 天滚动期内终端用户 ≤50 人可以改品牌；超过需书面/企业授权（2026-09-01 原文核对）。
• 内存：容器自身 ≥1GB；跑模型另算（模型推理内存 = 模型大小 + 上下文）。

日常使用

网页聊天与模型切换

登录后在顶部选模型（下拉里是 ollama 里所有模型），右侧新建会话。多模型可以随时切换，会话历史存在 webui.db。 `bash

查看当前版本（排查问题先报这个）

curl -s http://localhost:3000/api/version

预期输出: {"version":"0.11.1","deployment_id":""}（2026-09-01 实测；GitHub latest 为 v0.11.3）

>>

命令行调 open-webui 的 OpenAI 兼容 API

open-webui 暴露 OpenAI 兼容接口：base_url 指到 `http://localhost:3000/api>>>，key 用登录 token。脚本/Agent/IDE 插件都能接。 `bash

和 curl 直连 ollama 不同，走 open-webui 的接口需要 Bearer token

curl -s http://localhost:3000/api/chat/completions \ -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \ -d '{"model":"qwen2.5-0.5b:latest","messages":[{"role":"user","content":"你好"}],"stream":false}'

>>

预期输出: 与 ollama 直连格式一致的 chat.completion JSON（实测 2026-09-01）

本地知识库（RAG）

「工作区 → 新建知识库 → 上传文档」，回答时 @ 知识库。embedding 模型默认从 ollama 拉（nomic-embed-text），国内网络下首次拉取可能慢——先在命令行 `ollama pull nomic-embed-text>>> 拉好再进界面（2026-08-30 组合包已实测全链路）。

忘记管理员密码

管理员密码忘了，用容器内 CLI 重置（2026-08-30 问题域实测复现）： `bash docker exec -it open-webui python -c "from open_webui.utils.auth import update_password_by_email; update_password_by_email('you@example.com','new-password')"

>>

预期输出: 无输出（exit 0）；用新密码登录。详见问题域条目 open-webui-reset-password。

卸载

`bash

停容器

docker stop open-webui

删容器（数据还在 volume 里）

docker rm open-webui

彻底删数据（聊天记录、账号、知识库一起没，想清楚再执行）

docker volume rm open-webui

>>

预期输出: 前两条无输出（exit 0）；volume 删除输出 volume 名

pip 形态卸载：`pip uninstall open-webui>>>，数据目录（默认 ~/.open-webui/）需手动删。

FAQ

• 问：pip install open-webui 报 `Could not find a version>>>，是网络问题吗？

不是。open-webui 全部版本要求 Python 3.11~3.12（Requires-Python <3.13.0a1,>=3.11>>>），Python 3.13/3.14 一律装不上（2026-09-01 实测 3.14.4）。先 python3 --version>>>，不是 3.11/3.12 就先装 pyenv + Python 3.12 再建虚拟环境。

• 问：ghcr.io 镜像拉不动怎么办？

换国内 ghcr 镜像前缀：`ghcr.nju.edu.cn/open-webui/open-webui:main>>>（2026-08-30 与 2026-09-01 两次实测可用）。其他可选：ghcr.dockerproxy.com 等，没实测过，作为备选。

• 问：容器起来了但浏览器打不开？

确认映射端口：docker ps>>> 看 PORTS 列（0.0.0.0:3000->8080/tcp 表示宿主 3000 可用）；首次启动要 1~2 分钟初始化，docker inspect open-webui --format '{{.State.Health.Status}}'>>> 等到 `healthy>>> 再开。

• 问：界面显示连不上 ollama？

先确认宿主 ollama 在跑（curl -s http://localhost:11434/api/tags>>>）；再看容器内能否访问宿主（docker exec open-webui curl -s http://172.17.0.1:11434/api/tags>>>）；最后在界面「设置 → 连接」把 Ollama Base URL 改成实际可达地址。

• 问：我可以改掉 Open WebUI 的品牌名/Logo 部署吗？

许可证有专门条款（Open WebUI License 第 4 条）：30 天滚动期内终端用户不超过 50 人的部署可以改；超过 50 人必须取得版权方书面许可或企业授权，否则属于违约。个人/小团队内部用没问题，商业白标部署前先看 LICENSE（2026-09-01 原文核对）。

• 问：版本怎么跟随？

Docker 形态用 :main>>> tag 会跟随最新（当前实测容器内 0.11.1，GitHub latest 已到 v0.11.3，2026-08-31 发布）；要固定版本就拉具体 tag（如 :v0.11.3>>>）。pip 形态 pip install -U open-webui>>> 升级。升级前备份 volume（docker run --rm -v open-webui:/data -v $PWD:/backup alpine tar czf /backup/open-webui-backup.tgz -C /data .>>>）。