在 Unraid 上运行 Open WebUI（初学者安全型）
注意
本教程为社区贡献，Open WebUI 团队不提供官方支持。它仅作为如何针对您的特定使用场景自定义 Open WebUI 的演示。想要贡献？请查看贡献教程。
本指南适用于希望通过持久化数据和安全升级来实现稳定 Docker 部署的 Unraid 初学者。
您将做些什么
- 在 Unraid 中创建 Open WebUI 容器。
- 为
/app/backend/data配置持久化存储。 - 将 Open WebUI 连接到 Ollama。
- 在不丢失数据的情况下更新 Open WebUI。
- 排查反向代理和持久化问题。
开始之前
- Unraid 中已启用 Docker。
- 您拥有一个持久化的 appdata 路径，例如：
/mnt/user/appdata/open-webui。 - 可选：Ollama 正在以下位置之一运行：
- Unraid 主机上，或
- 另一台可访问的机器上。
important
将 /app/backend/data 持久化到主机路径。如果您跳过此步骤，在容器重建后聊天记录/设置可能会丢失。
1. 在 Unraid 中创建容器
在 Docker > Add Container 中，使用：
| 字段 | 值 |
|---|---|
| Name | open-webui |
| Repository | ghcr.io/open-webui/open-webui:main |
| Network Type | bridge |
| Restart Policy | always |
| Container Port | 8080 |
| Host Port | 3000（或另一个空闲端口） |
添加路径映射：
| 配置类型 | 容器路径 | 主机路径 |
|---|---|---|
| Path | /app/backend/data | /mnt/user/appdata/open-webui |
2. 配置 Ollama 连接性
选择一种配置方式。
在 Unraid 主机上运行 Ollama
- 额外参数：
--add-host=host.docker.internal:host-gateway
- 环境变量：
OLLAMA_BASE_URL=http://host.docker.internal:11434
在另一台机器上运行 Ollama
- 环境变量：
OLLAMA_BASE_URL=http://<ollama-lan-ip>:11434
在另一个容器中运行 Ollama
- 将两个容器放在同一个自定义 Docker 网络中。
- 设置：
OLLAMA_BASE_URL=http://<ollama-container-name>:11434
3. 首次启动验证
- 启动容器。
- 打开
http://<unraid-ip>:3000。 - 完成初始管理员设置。
- 打开 Settings > Admin Settings > Connections 并验证 Ollama 终结点。
- 确认模型显示在模型选择器中。
4. 持久卷注意事项
- Open WebUI 状态存储在
/app/backend/data中。 - 在您的 Unraid 模板中设置固定的
WEBUI_SECRET_KEY，并在重建过程中保持一致，以避免不必要的会话失效。 - 在更新/重建过程中保持主机映射一致。
- 使用目录映射，而不是文件映射。
- 如果持久化失败，请检查
/mnt/user/appdata/open-webui的文件夹权限。
5. 升级步骤（安全工作流）
- 备份
/mnt/user/appdata/open-webui。 - 确保您的模板保留相同的
WEBUI_SECRET_KEY。 - 更新/拉取您的 Open WebUI 镜像标签 (image tag)。
- 使用相同的模板和相同的
/app/backend/data映射进行重建。 - 验证聊天记录/设置是否完好无损。
- 如有必要，回滚到上一个镜像并恢复备份。
有关更广泛的更新选项，请参阅更新 Open WebUI。
问题排查
无法连接至 Ollama
现象：
- Open WebUI 中出现
Connection error错误 - 模型无法加载
检查项：
- 确认从 Open WebUI 容器内部可以访问
OLLAMA_BASE_URL。 - 如果使用宿主机上的 Ollama，确认
--add-host=host.docker.internal:host-gateway存在。 - 如果
host.docker.internal失败，请使用您的 Unraid 主机局域网 (LAN) IP。
host.docker.internal 无法解析
- 添加
--add-host=host.docker.internal:host-gateway。 - 保存模板更改后重启容器。
- 备用方案：
OLLAMA_BASE_URL=http://<unraid-lan-ip>:11434。
反向代理子路径问题 (/openwebui)
现象：
- 登录/静态资源返回
404错误 - WebSocket 断开连接或处于卡住的加载状态
检查项：
- 确保代理转发了 WebSocket 升级标头 (upgrade headers)。
- 确保子路径路由一致（在转发前剥离或重写前缀）。
- 设置不带尾部斜杠的
WEBUI_URL，例如：WEBUI_URL=https://example.com/openwebui
- 如果子路径仍然不稳定，请首选子域名：
WEBUI_URL=https://ai.example.com
有关更广泛的反向代理调试，请参阅连接错误。
更新/重建后数据丢失
- 验证映射是否完全是将
/app/backend/data映射到您的持久化主机文件夹。 - 确认没有因拼写错误而创建第二个空文件夹。
- 确认 Unraid 权限允许读/写。