Open WebUI + Ollama 对接四大崩溃：Server Connection Error、Docker 网络隔离、CORS 拒绝——逐一修复

装上 Ollama 能跑模型之后，99% 的人下一步就是装 Open WebUI——一个 ChatGPT 风格的本地聊天界面。然后第一个画面往往是红字：「Server Connection Error」。

一、Open WebUI 的架构坑：为什么"明明 Ollama 在跑，WebUI 就是连不上"

Open WebUI 是 Docker 容器，Ollama 跑在宿主机上。请求路径：

浏览器 → Open WebUI 容器 (:8080) → /ollama 路由 → OLLAMA_BASE_URL → Ollama (:11434)

Open WebUI 不是从浏览器直接连 Ollama——它从前端发请求到自己的后端，后端再转发给 Ollama。所以：

• 你在宿主机 curl localhost:11434 能通 ≠ Open WebUI 容器内能通
• Open WebUI 容器默认不知道宿主机在哪儿

这就是 90% 的 "Server Connection Error" 的根因。

二、四大崩溃场景

崩溃 1：Server Connection Error——Docker 网络隔离（最常见）

报错特征：

Open WebUI: Server Connection Error
Connection Issue or Update Needed
It seems like your Ollama needs a little attention. 
Ensure you're on the latest Ollama version (version 0.1.16 or higher) 
or check your connection.

环境：Ollama 宿主机运行正常、curl localhost:11434 返回 "Ollama is running"、Open WebUI Docker 容器已启动

根因：Open WebUI 容器内的 localhost:11434 指向容器自己的 localhost，不是宿主机的。Docker 默认 bridge 网络模式下，容器与宿主机是隔离的。

修复方案（按推荐顺序）：

1. --network=host（最简单，Linux 专用）： bash docker run -d --network=host \ -v open-webui:/app/backend/data \ -e OLLAMA_BASE_URL=http://127.0.0.1:11434 \ --name open-webui --restart always \ ghcr.io/open-webui/open-webui:main 容器直接使用宿主机网络栈，127.0.0.1:11434 就是宿主机的 Ollama。

2. host.docker.internal（macOS/Windows）： bash docker run -d -p 3000:8080 \ --add-host=host.docker.internal:host-gateway \ -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \ -v open-webui:/app/backend/data \ --name open-webui --restart always \ ghcr.io/open-webui/open-webui:main

3. Linux 下用宿主机局域网 IP： bash docker run -d -p 3000:8080 \ -e OLLAMA_BASE_URL=http://192.168.1.100:11434 \ -v open-webui:/app/backend/data \ --name open-webui --restart always \ ghcr.io/open-webui/open-webui:main 确保 Ollama 监听 0.0.0.0： bash OLLAMA_HOST=0.0.0.0 ollama serve

崩溃 2：Docker Compose 部署后 Web 界面打不开

报错特征（open-webui#19857）：

docker compose up -d 后容器状态正常，但访问 http://localhost:3000 显示"无法连接"或白屏。

根因：Docker Compose 默认创建独立网络，ports 映射可能被防火墙或已有容器占用。此外，OLLAMA_BASE_URL 在 compose 文件中配置不正确。

修复方案：

1. 检查端口占用： bash ss -tlnp | grep 3000 # 如果 3000 被占用，改映射

2. 正确的 docker-compose.yml： yaml services: open-webui: image: ghcr.io/open-webui/open-webui:main container_name: open-webui network_mode: host # Linux 用这个 volumes: - open-webui:/app/backend/data environment: - OLLAMA_BASE_URL=http://127.0.0.1:11434 restart: always

3. 检查日志： bash docker logs open-webui 2>&1 | tail -50 看是否有 Connection refused 或 OLLAMA_BASE_URL 解析失败的日志。

崩溃 3：HTTPS/反向代理后 CORS + WebSocket 报错

报错特征：

浏览器控制台显示：

https://yourdomain.com is not an accepted origin
WebSocket connection failed

环境：Nginx/Caddy 反向代理 + HTTPS

根因：Open WebUI 需要 CORS 和 WebSocket 支持。反向代理默认不转发 WebSocket 升级请求，且 Open WebUI 需要 WEBUI_URL 环境变量声明自己的域名。

修复方案：

1. 设置 WEBUI_URL： bash docker run -d ... -e WEBUI_URL=https://your-open-webui-domain.com ...

2. Nginx 配置： ```nginx server { listen 443 ssl; server_name ai.yourdomain.com;

   location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering off; } } `` 关键是proxy_set_header Upgrade和Connection "upgrade"`——缺了这两行 WebSocket 直接断。

3. Caddy 配置（更简单）： ai.yourdomain.com { reverse_proxy 127.0.0.1:8080 } Caddy 默认支持 WebSocket，不需要额外配置。

崩溃 4：RAG 不工作——上传了文档但模型说"我无法访问该文件"

特征：Open WebUI 的文件上传和 RAG 功能已开启，但询问文档内容时模型返回"我没有关于该文档的信息"。

根因（三重可能性）：

1. Embedding 模型未配置：RAG 需要独立的 embedding 模型做向量化——Ollama 的聊天模型不会自动做 embedding
2. OLLAMA_BASE_URL 的 embedding 路由有问题：Open WebUI 的 /ollama/api/embeddings 被反向代理截断
3. 文档解析失败：PDF/Office 文档需要额外依赖

修复方案：

1. 安装 embedding 模型： bash ollama pull nomic-embed-text 在 Open WebUI 管理后台 → 文档设置 → 选择 nomic-embed-text 作为 embedding 模型。

2. 检查 embedding API 可达性： bash curl http://localhost:11434/api/embeddings -d '{"model":"nomic-embed-text","prompt":"test"}'

3. 文档格式兼容性： Open WebUI 支持 PDF、TXT、MD、CSV。Word/PowerPoint 需要先转 PDF。

三、Open WebUI 部署参数速查

四、总结

Open WebUI 的核心困境就一个：Docker 容器与宿主机之间的网络鸿沟。 90% 的问题用一个 --network=host 就能解决。

记住这条规则：

搭配我们推理引擎系列前四篇（vLLM V1 / SGLang / Dify + vLLM / Ollama），你现在有了从推理引擎到聊天前端的完整排障体系。

本文参考了 Open WebUI GitHub Issues #377、#19857、#5979。

附：Open WebUI + Ollama 对接速查表（付费资源）

Docker 网络配置四方案 + CORS/WebSocket Nginx 配置模板 + embedding 模型配置。打印放终端旁边。

📥 下载 Open WebUI 部署速查表

本文由 admin 原创，转载请注明出处。