信息层级：【有据可查】= 附官方文档或可信来源链接；【社区共识】= 社区用户普遍经验，未经官方确认；【待考察/推测】= 推测或暂未能核实，请谨慎对待。
1. 它是什么？
【有据可查】Open WebUI 是可自托管的 AI 聊天界面，可连接 Ollama 与任意 OpenAI 兼容 API，支持多用户、知识库（RAG）、工具等。来源：GitHub、文档
【有据可查】许可证要点：自 v0.6.6（2025 年 4 月）起采用"Open WebUI License"——在宽松许可基础上增加品牌保护条款：不得更改/移除"Open WebUI"品牌标识，除非（i）滚动 30 天内终端用户不超过 50 人，（ii）获得书面许可，或（iii）持有企业许可。v0.6.5 及之前合入的代码仍为 BSD-3。来源：LICENSE、License 说明
2. Docker 安装【有据可查：Quick Start】
docker run -d -p 3000:8080 \
--add-host=host.docker.internal:host-gateway \
-v open-webui:/app/backend/data \
-e WEBUI_SECRET_KEY=$(openssl rand -hex 32) \
--name open-webui --restart always \
ghcr.io/open-webui/open-webui:main
| 参数 | 作用 |
|---|---|
-p 3000:8080 |
主机 3000 转到容器 8080，默认发布到所有主机地址；仅本机练习时用 -p 127.0.0.1:3000:8080；占用时改主机端口 |
--add-host=host.docker.internal:host-gateway |
添加宿主网关的名字与地址映射；还要求 Ollama 在容器能到达的地址监听，不能保证穿过宿主回环限制 |
-v open-webui:/app/backend/data |
聊天、用户、设置都在这个卷里；不要省略 |
WEBUI_SECRET_KEY |
固定下来；不固定的话每次重建容器所有人都会被登出 |
⚠️ 上面命令里
$(openssl rand -hex 32)每次运行都会生成新值。更稳妥的做法是先生成一次、保存起来，再填进命令或 compose 文件。
其他方式：pip install open-webui 后 open-webui serve（默认 http://localhost:8080）。
访问 http://localhost:3000，当前官方 Quick Start 说明首次创建的是管理员账号，创建后注册默认关闭；允许新用户注册需手动开启，新增账号先处于 Pending 等待批准。【有据可查，以部署版本界面核对】
3. 连接模型
| 来源 | 在哪里配 | 填什么 |
|---|---|---|
| Ollama | 管理面板 → 设置 → 连接 | http://host.docker.internal:11434 |
| OpenAI 兼容 API | 同上，添加 OpenAI 连接 | Base URL（如 https://api.deepseek.com/v1）+ Key |
| 自建 New API（New API 部署与使用：渠道、令牌、额度和备份） | 同上 | 你的网关地址 + 令牌 |
【社区共识】菜单位置随版本变化，以界面为准。
4. 值得用的功能
| 功能 | 说明 |
|---|---|
| 多模型对比 | 同一问题同时问几个模型（配合模型能力实测：固定条件、题库与评分表 实测） |
| 知识库 / 文档 | 上传文档做 RAG 问答 |
| 用户与权限 | 家庭/小团队共用，管理员可控制可用模型 |
| 自定义模型（预设） | 给某个模型绑定系统提示词与参数 |
5. 安全清单【社区共识】
- ☐ 关闭公开注册，或开启"新用户需审批"
- ☐ 需远程访问时放在 HTTPS 反向代理后（VPS 入门：连接、账号、防火墙与日常维护），不要直接暴露 3000 端口
- ☐ 定期备份
open-webui数据卷 - ☐ 若供 50 人以上使用，不要修改品牌标识（许可证要求）
- ☐ 上传到知识库的文档会存在服务器上——注意敏感数据
6. 常见问题【有据可查：Quick Start 排错部分】
| 现象 | 处理 |
|---|---|
| 页面打不开 | docker logs -f open-webui，等出现 Application startup complete（首次启动约需一分钟） |
| 看不到 Ollama 模型 | 分别检查容器地址解析、宿主监听、连接设置和容器内可达性；只有支持并已正确启用 host 网络的环境才能另用 --network=host，此时 -p 无效，按应用实际监听的 8080 端口与地址核对 |
| 端口冲突 | 改 -p 左侧端口 |
| 更新后被登出 | 未固定 WEBUI_SECRET_KEY |
7. 本篇无法核实/需谨慎的点
- 当前官方 Quick Start 已说明首个账号为管理员、随后关闭注册、重新开启后新用户为 Pending；旧版或既有数据库的状态仍以实际部署核对。
- 许可证条款的法律解释（如"终端用户"的计算），商用前请咨询专业人士。
小白练习：把本文流程逐项走通
练习目标：在私有访问范围连接一个模型，并验证资料问答。
上文已介绍概念、配置和操作示例。下面侧重第一次实际操作时的顺序、检查点和结果核对；需要查具体参数时回到对应小节。命令逐条输入，看到上一条的结果后再继续。
-
先单独检查 Docker 可用，再确认主机端口未被其他服务占用。只给自己访问时使用回环端口绑定。
-
先生成并安全保存固定的 WEBUI_SECRET_KEY，再配置持久化卷；重建容器不要临时换掉这两个值。
-
启动后查看容器日志，等服务准备好再打开浏览器页面，及时建立管理员账户。
-
连接 Ollama 时区分容器与宿主机地址，并检查宿主机的实际监听范围；host.docker.internal 只是地址映射，不会自动改变服务监听。
-
先发一个简单问题确认模型连通，再上传一份无隐私的短文做知识库测试。
-
要求答案指出资料依据，回到原文核对；最后检查注册策略、账号权限和持久化数据备份。
保留原例，先确认四个部署条件
第一，原命令为 Bash 语法，Windows PowerShell 不能直接照抄反斜杠换行。先区分宿主机、容器和浏览器三个位置；仅本机练习在启动前将原例发布项改为 -p 127.0.0.1:3000:8080。已经创建的容器要用所用部署工具重建后才能改变发布配置，保留原数据卷。
第二，先在宿主机确认 Ollama 的 /api/tags 能返回，再在容器中检查 http://host.docker.internal:11434/api/tags。例如在宿主终端执行 docker exec open-webui python -c "import urllib.request; print(urllib.request.urlopen('http://host.docker.internal:11434/api/tags', timeout=5).status)"。返回 200 才说明这段网络请求通了，之后还要在管理连接中保存地址、刷新模型并发一次测试。
【有据可查；网络条件为文档推导】Docker 的 host-gateway 只建立名称到网关 IP 的映射，Ollama 默认只监听宿主 127.0.0.1。Linux 桥接网络下，两者不能自动互通；可按官方方案在同一容器网络部署 Ollama，或使用受支持的 host 网络，或限制好网络访问后再配置宿主监听。不要直接把监听改成 0.0.0.0 当成通用修复。Docker Desktop 的具体转发行为仍需在本机验证。
第三，原例的 $(openssl rand -hex 32) 每次执行都会生成新密钥。按官方说明单独生成一次，把同一个值保存在仅部署者可读的环境配置里，后续重建继续使用；原有数据卷与密钥都要按用途备份。不要把密钥值贴进公开笔记或截图。
第四，先完成管理员创建并核对注册开关，再考虑多人访问。主机上能打开页面不证明容器能访问 Ollama；有登录界面也不证明端口只在本机开放。远程访问仍按原步骤配置认证与 HTTPS，并独立检查实际端口绑定。
核对来源：Open WebUI 官方：Quick Start；Open WebUI 官方：Environment Variable Configuration · WEBUI_SECRET_KEY；Docker 官方：Port publishing and mapping；Docker 官方：docker run · --add-host；Docker 官方：Host network driver；Ollama 官方：FAQ。