跳到主要内容

连接错误

本页面介绍了常见的连接问题、其原因以及如何解决。

🔐 HTTPS, TLS, CORS 和 WebSocket 问题​

如果您在使用 Open WebUI 时遇到连接问题，特别是在使用反向代理或 HTTPS 时，这些问题通常源于不正确的 CORS、TLS、WebSocket 或 cookie 配置。以下是诊断和修复它们的方法。

常见症状​

如果您遇到以下情况，可能是遇到了这些问题：

  • 对话中出现像 "{}" 这样的空响应
  • 出现 "Unexpected token 'd', "data: {"id"... is not valid JSON" 这样的错误
  • 在流式传输过程中出现 Markdown 乱码（可见的 ##、**、损坏的排版格式）——参见 Markdown 乱码 / 流式响应损坏
  • 浏览器控制台中出现 WebSocket 连接失败
  • CLI 日志中出现 WebSocket 连接失败
  • 登录问题或会话问题
  • 浏览器开发者工具中出现 CORS 错误
  • 通过 HTTPS 访问时出现混合内容（mixed content）警告

HTTPS 与反向代理的必要配置​

关键环境变量

当在带有 HTTPS 的反向代理后运行 Open WebUI 时，您必须配置以下设置：

# 在首次启动前，将此项设置为您的实际域名（OAuth/SSO 以及正常运行所必需）
WEBUI_URL=https://your-open-webui-domain.com
# 如果您已经启动了 Open WebUI，不用担心，您也可以在管理员面板中设置此配置！

# CORS 配置 - 对 WebSocket 功能至关重要
# 包含用户可能用于访问您实例的所有方式
# 确保包含用户可以且可能访问 Open WebUI 的所有 IP、主机名和域名，以及请求是如何路由到您的 Open WebUI 实例的
# 例如：localhost、127.0.0.1、0.0.0.0、<您服务器/电脑的 IP>、公共域名 - 全部包含正确的端口，并支持 http 和 https
CORS_ALLOW_ORIGIN="https://yourdomain.com;http://yourdomain.com;https://yourip;http://localhost:3000"

# 针对 HTTPS 的 Cookie 安全设置
# 如果不使用 HTTPS，请禁用此项
WEBUI_SESSION_COOKIE_SECURE=true
WEBUI_AUTH_COOKIE_SECURE=true

# 对于 OAuth/SSO，您可能需要使用 'lax'（'strict' 可能会破坏 OAuth 回调）
WEBUI_SESSION_COOKIE_SAME_SITE=lax
WEBUI_AUTH_COOKIE_SAME_SITE=lax

# WebSocket 支持（如果使用 Redis）
# 如果您在配置了上述所有内容后仍然遇到 WebSocket 相关问题，可以尝试关闭 ENABLE_WEBSOCKET_SUPPORT
# 但这不推荐用于生产环境，官方也并不支持！
# 如果您遇到 WebSocket 问题，理想情况下应该通过反向代理提供 WebSocket 支持。
ENABLE_WEBSOCKET_SUPPORT=true
WEBSOCKET_MANAGER=redis
WEBSOCKET_REDIS_URL=redis://redis:6379/1

WEBUI_URL 配置

在启用 OAuth/SSO 之前，必须正确设置 WEBUI_URL。由于它是一个持久的配置变量，您只能通过以下方式更改它：

  • 临时禁用持久配置：ENABLE_PERSISTENT_CONFIG=false
  • 在 Admin Panel（管理员面板） > Settings（设置） > WebUI URL 中进行更改
  • 在首次启动前正确设置它

CORS 配置细节

CORS_ALLOW_ORIGIN 设置对于 WebSocket 功能至关重要。如果您在日志中看到诸如 "https://yourdomain.com is not an accepted origin" 或 "http://127.0.0.1:3000 is not an accepted origin" 的错误，您需要将该 URL 添加到您的 CORS 配置中。使用英文分号分隔多个源，并包含用户访问您实例的所有可能方式（域名、IP、localhost）。

反向代理 / SSL/TLS 配置​

关于反向代理和 TLS 设置，请查看我们的相关教程。

WebSocket 故障排除​

对于 Open WebUI v0.5.0 及更高版本，WebSocket 支持是必需的。如果 WebSocket 无法工作：

  1. 检查您的反向代理配置 — 确保正确设置了 Upgrade 和 Connection 请求头
  2. 验证 CORS 设置 — WebSocket 连接同样遵循 CORS 策略
  3. 检查浏览器控制台 — 寻找 WebSocket 连接错误
  4. 测试直接连接 — 尝试在不经过代理的情况下直接连接到 Open WebUI，以隔离问题
  5. 排查 HTTP/2 WebSocket 问题 — 某些代理（如 HAProxy 3.x）默认启用 HTTP/2。如果您的代理通过 HTTP/2 处理客户端连接，但后端/应用未正确支持 RFC 8441（通过 H2 的 WebSockets），则实例可能会“冻结”或停止响应。
    • HAProxy 修复方案：在您的配置中添加 option h2-workaround-bogus-websocket-clients，或者强制后端连接使用 HTTP/1.1。
    • Nginx 修复方案：确保在您的 location 块中使用了 proxy_http_version 1.1;（这在许多 Open WebUI 示例中都是默认的）。

对于多实例部署，配置 Redis 以进行 WebSocket 管理：

ENABLE_WEBSOCKET_SUPPORT=true
WEBSOCKET_MANAGER=redis
WEBSOCKET_REDIS_URL=redis://redis:6379/1

有关详细的 Redis 配置说明，请参阅 Redis WebSocket 支持。有关完整的多实例扩展指南，请参阅扩展 Open WebUI。如果您在多副本（multi-replica）设置中特别遇到 WebSocket 403 错误，请参阅扩展与高可用故障排除。

测试您的配置​

验证您的设置是否正常工作：

  1. 检查 HTTPS：访问您的域名并确保您能看到有效的证书，且浏览器无警告提示
  2. 测试 WebSocket：打开浏览器开发者工具，转到 Network（网络）标签页，通过 "WS" 进行筛选，并验证 WebSocket 连接是否成功建立
  3. 验证 CORS：检查浏览器控制台是否有任何与 CORS 相关的错误
  4. 测试功能：发送一条消息并确保流式响应能正常工作

快速修复核对清单​

  • ✓ 在启用 OAuth 之前，将 WEBUI_URL 设置为您的实际 HTTPS 域名
  • ✓ 配置 CORS_ALLOW_ORIGIN 以包含所有可能的访问 URL
  • ✓ 对 HTTPS 启用 WEBUI_SESSION_COOKIE_SECURE=true
  • ✓ 在您的反向代理配置中添加 WebSocket 相关的请求头
  • ✓ 在您的 SSL 配置中使用 TLSv1.2 或 TLSv1.3
  • ✓ 在反向代理中设置适当的 X-Forwarded-Proto 请求头
  • ✓ 确保 HTTP 到 HTTPS 的重定向已就绪
  • ✓ 配置 Let's Encrypt 以进行证书自动续期
  • ✓ 禁用代理缓冲（proxy buffering）以支持 SSE 流式传输（参见下文）

📝 乱码 Markdown / 流式响应损坏​

如果流式响应显示 Markdown 渲染乱码（例如，可见的 ##、** 或排版损坏），但禁用流式传输（streaming）能解决该问题，这通常是由 Nginx 代理缓冲（proxy buffering） 引起的。

常见症状​

  • 响应中能看到原始 Markdown 标记符（##、**、###）
  • 加粗标记显示不正确（显示为 ** Control:** 而不是 **Control:**）
  • 响应中随机丢失单词或部分内容
  • 禁用流式传输时格式能正确显示

原因：Nginx 代理缓冲​

当启用了 Nginx 的代理缓冲时，它会任意地对 SSE（Server-Sent Events）流进行重新分块。这会在块边界上切断 Markdown 标记符——例如，**bold** 被切分为独立的块 ** + bold + **，导致 Markdown 解析器解析失败。

解决方案：禁用代理缓冲​

在针对 Open WebUI 的 Nginx location 块中添加以下指令：

location / {
    proxy_pass http://your-open-webui-upstream;
    
    # 关键：对 SSE 流式传输禁用缓冲
    proxy_buffering off;
    proxy_cache off;
    
    # WebSocket 支持
    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-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
提示

禁用代理缓冲还可以显著提高流式传输速度，因为响应会逐字节直接流式传输到客户端，而无需经历 Nginx 的缓冲延迟。

针对其他反向代理​

  • HAProxy：确保对 SSE 接口未启用 option http-buffer-request
  • Traefik：检查压缩/缓冲中间件（middleware）的设置
  • Caddy：默认情况下通常能正确处理 SSE，但请检查是否有任何缓冲插件

🌐 前端与后端连接（localhost 混淆）​

多个 Open WebUI 功能提供了两种方式来配置连接：用户/直接方式（从浏览器发起）和管理员/全局方式（从后端发起）。它们工作在完全不同的网络层级，同一个 URL 可能会在其中一个成功，而在另一个失败。

核心规则​

请求发起方localhost 的含义谁会使用此项
浏览器 (client-side)运行浏览器的机器用户工具服务器 (User Tool Servers)、用户配置的终端 (User-Configured Terminals)、直接连接
后端 (server-side)运行 Open WebUI 的机器/容器全局工具服务器 (Global Tool Servers)、管理员配置的终端 (Admin-Configured Terminals)、Ollama 连接

为什么相同的 URL 会时而成功时而失败​

当您将诸如 https://myserver.com/api 的 URL 添加为用户/直接连接时，您的浏览器会解析 myserver.com 并直接建立连接。而当您将相同的 URL 添加为管理员/全局连接时，Open WebUI 后端会去解析该主机名——但在 Docker 容器内部，它可能会被解析为 127.0.0.1，从而完全绕过了您的反向代理。

常见症状：

  • 在管理员配置的连接上出现 502 Bad Gateway，而用户配置的连接却能正常工作
  • 后端日志中出现 Connect call failed ('127.0.0.1', ...)
  • 全局工具服务器上出现连接超时

修复方案：对于后端/管理员连接，请使用后端实际能够访问到的内部 URL：

  • Docker 服务名称（例如 http://open-terminal:8000）
  • host.docker.internal（从 Docker 容器内部访问宿主机）
  • 局域网/内部 IP（例如 http://192.168.1.50:8000）
提示

这适用于 Open WebUI 中所有由后端代理的连接——不仅仅是 Open Terminal。同样的模式会影响 Tool Server 连接、Open Terminal 管理员配置的连接 以及 Ollama/OpenAI API 接口。

连接至 Ollama 服务​

从 Open WebUI 访问 Ollama​

如果 Open WebUI 无法访问 Ollama，通常是因为 Ollama 仅监听了 127.0.0.1（localhost）。要修复此问题：

  1. 设置 OLLAMA_HOST=0.0.0.0，使 Ollama 监听所有网络接口。
  2. 确保该变量已在您的部署环境（systemd 服务、Docker、shell 配置文件）中设置。
  3. 重启 Ollama 以使更改生效。

重启后通过访问 WebUI 界面来验证连通性。有关详细指南，请参阅 Ollama 官方文档。

Docker 连接错误​

如果 Docker 中的 Open WebUI 无法连接到运行在宿主机上的 Ollama：

  1. 调整网络设置： 在您的 Docker 命令中使用 --network=host 标志。这会将您的容器直接连接到宿主机的网络。

  2. 更改端口： 请记住，容器内部的端口会从 3000 变为 8080。

示例 Docker 命令：

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

运行上述命令后，您的 WebUI 应该可以通过 http://localhost:8080 访问。

⏱️ 模型列表加载问题（UI 慢 / 接口无法访问）​

如果您的 Open WebUI 加载模型需要很长时间，或者模型选择器无限旋转，这可能是因为您的连接中配置了无法访问或响应缓慢的 API 接口。

常见症状​

  • 模型选择器长时间显示加载动画
  • /api/models 接口返回 500 Internal Server Error
  • 打开 Settings（设置）时 UI 变得无响应
  • Docker/服务器日志显示：Connection error: Cannot connect to host...

原因：接口无法访问​

当您配置了多个 Ollama 或 OpenAI 基础 URL（用于负载均衡或冗余）时，Open WebUI 会尝试从所有配置的接口中获取模型。如果其中任何一个接口无法访问，系统将等待完整的连接超时，然后才会返回结果。

默认情况下，Open WebUI 在获取模型列表时，针对每个无法访问的接口会等待 10 秒。如果有多个失效接口，这个延迟会不断叠加。

解决方案 1：调整超时时间​

使用 AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST 环境变量来降低获取模型列表时的超时时间：

# 设置更短的超时时间（单位为秒），以便在接口无法访问时更快失败
AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=3

这会减少 Open WebUI 在放弃并继续下一个接口之前为每个接口等待的时间。

解决方案 2：修复或移除无法访问的接口​

  1. 前往 Admin Settings → Connections
  2. 检查您的 Ollama 和 OpenAI 基础 URL
  3. 移除或修正任何无法访问的 IP 地址或主机名
  4. 保存配置

解决方案 3：从数据库持久化的错误配置中恢复​

如果您保存了一个无法访问的 URL，目前无法进入设置界面（Settings UI）来修复它，这是因为错误的配置已经持久化在数据库中，并且其优先级高于环境变量。请使用以下恢复方法之一：

选项 A：在启动时重置配置

# 强制环境变量在下次启动时覆盖数据库中的值
RESET_CONFIG_ON_START=true

选项 B：始终使用环境变量

# 防止数据库中的值覆盖环境变量（UI 中的修改将不会在重启后保留）
ENABLE_PERSISTENT_CONFIG=false

选项 C：手动清理数据库（高级）

如果使用的是 SQLite，请停止容器并运行：

sqlite3 webui.db "DELETE FROM config WHERE id LIKE '%urls%';"
注意

手动操作数据库应作为最后的手段。请务必在操作前先备份您的数据库。

变量默认值描述
AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER继承 AIOHTTP_CLIENT_TIMEOUT执行工具服务器 API 调用时的超时时间（秒）
AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER_DATA10加载工具服务器元数据/Spec数据时的超时时间（秒）
AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST10获取模型列表时的超时时间（秒）
AIOHTTP_CLIENT_TIMEOUT300通用的 API 请求超时时间
RESET_CONFIG_ON_STARTfalse启动时将数据库配置重置为环境变量的值
ENABLE_PERSISTENT_CONFIGtrue数据库配置是否优先于环境变量

请参阅环境变量配置文档获取更多详细信息。

🐢 低配硬件上的慢性能或超时​

如果您遇到了页面加载慢、API 超时或 UI 无响应的情况——尤其是在资源受限的系统上——这可能与数据库会话共享（session sharing）有关。

原因​

在并发负载下，数据库会话共享可能会压垮低配硬件（如树莓派、CPU 极少的容器等）或 SQLite 数据库。

解决方案​

禁用数据库会话共享：

DATABASE_ENABLE_SESSION_SHARING=false

如果是在性能足够的硬件上运行 PostgreSQL，启用此设置可能会提高性能。详情请参见 DATABASE_ENABLE_SESSION_SHARING 文档。

🔒 针对 Hugging Face 的 SSL 连接问题​

如果您在连接到 Hugging Face 时遇到 SSL 错误：

  1. 检查 Hugging Face 服务状态： 确认其官方是否存在已知的停机或故障。

  2. 切换镜像终结点： 如果 Hugging Face 访问受限，可在您的 Docker 命令中切换其 Endpoint。

针对连接问题的 Docker 运行示例命令：

docker run -d -p 3000:8080 -e HF_ENDPOINT=https://hf-mirror.com/ --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

🔐 内部工具的 SSL 证书问题​

如果您正在使用诸如 Tika、Ollama（用于 Embeddings）或带有自签名证书的外部 Reranker 等外部工具，您可能会遇到 SSL 验证错误。

常见症状​

  • 日志显示 [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate
  • Tika 文档摄取（ingestion）失败
  • 生成 Embedding 失败并伴有 SSL 错误
  • Reranking 失败并伴有 SSL 错误

解决方案​

您可以使用以下环境变量为这些内部工具的连接禁用 SSL 验证：

  1. 针对同步请求（Tika, 外部 Reranker）：

    REQUESTS_VERIFY=false

  2. 针对异步请求（Ollama Embeddings）：

    AIOHTTP_CLIENT_SESSION_SSL=false
注意

禁用 SSL 验证会降低安全性。仅在您完全信任网络以及所连接的服务时才这样做（例如，在安全的内部局域网内运行）。

🍏 MacOS 上的 Podman​

针对 MacOS 上的 Podman：

  1. 启用主机访问：Podman 5.0+ 默认使用 pasta，这简化了主机的回环访问。在较旧版本上，请使用 --network slirp4netns:allow_host_loopback=true。
  2. 将 OLLAMA_BASE_URL 设置为 http://host.containers.internal:11434。

示例 Podman 命令：

podman run -d -p 3000:8080 -e OLLAMA_BASE_URL=http://host.containers.internal:11434 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

🔐 网页搜索的 SSL/TLS 错误​

如果您在使用 Web Search（网页搜索）功能时遇到 SSL 错误，它们通常分为两类：代理配置问题或证书验证问题。

证书验证问题​

如果当 Open WebUI 尝试从网站获取内容时（Web Loader/网页加载器）您看到了 SSL 验证错误：

  • 症状：加载搜索结果时出现 [SSL: CERTIFICATE_VERIFY_FAILED]。
  • 解决方案：您可以专门为 Web Loader（网页抓取工具）禁用 SSL 验证。 
    ENABLE_WEB_LOADER_SSL_VERIFICATION=false

    注意：此设置仅适用于网页内容的获取（fetching）。如果您在搜索引擎本身（如本地 SearXNG）或随后的步骤（Embedding/Reranking）中遇到 SSL 问题，请参阅下面的部分。

代理配置问题​

如果您在使用网页搜索提供商（Bocha, Tavily 等）时看到类似于 UNEXPECTED_EOF_WHILE_READING 或 Max retries exceeded 的 SSL 错误：

常见症状​

  • SSLError(SSLEOFError(8, '[SSL: UNEXPECTED_EOF_WHILE_READING]'))
  • Max retries exceeded with url: /v1/web-search
  • 网页搜索在独立的 Python 脚本中能正常工作，但在 Open WebUI 中失败

原因：为 HTTPS 流量配置了 HTTP 代理​

这通常发生在您为 HTTPS 流量配置了 HTTP 代理时。HTTP 代理无法正确处理 TLS 连接，从而导致 SSL 握手失败。

检查您的环境是否存在这些变量：

  • HTTP_PROXY / http_proxy
  • HTTPS_PROXY / https_proxy

如果您的 https_proxy 指向的是 http://... (HTTP) 而不是 https://... (HTTPS)，SSL 握手将会失败，因为代理会意外地终止连接。

解决方案​

  1. 修正代理配置：对于 HTTPS 流量，使用支持 HTTPS 的代理；或者配置您的 HTTP 代理以正确支持针对 SSL 的 CONNECT 隧道（tunneling）。
  2. 对特定主机绕过代理：设置 NO_PROXY 环境变量： 
    NO_PROXY=api.bochaai.com,api.tavily.com,api.search.brave.com
  3. 如果不需要则禁用代理：完全取消（unset）代理环境变量的配置。

为什么单体脚本可以正常工作​

当您直接运行 Python 脚本时，它可能没有继承与您的 Open WebUI 服务相同的代理环境变量。该服务通常会从 systemd、Docker 或您的 shell 配置文件中继承环境变量，而这些地方可能有不同的代理设置。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.