Skip to main content

服务器连接问题

我们在这里协助您顺利完成所有设置并运行。下面，您将找到针对不同场景量身定制的分步说明，以解决常见的连接问题。

🔐 HTTPS, TLS, CORS & WebSocket 问题​

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

常见症状​

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

  • 聊天中出现类似 "{}" 的空响应
  • 出现类似 "Unexpected token 'd', "data: {"id"... is not valid JSON" 的错误
  • 浏览器控制台中出现 WebSocket 连接失败
  • CLI 日志中出现 WebSocket 连接失败
  • 登录问题或会话问题
  • 浏览器开发者工具中出现 CORS 错误
  • 通过 HTTPS 访问时出现混合内容警告

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 暂时禁用持久化配置
  • 在“管理员面板 > 设置 > 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，以隔离问题

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

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

测试您的配置​

要验证您的设置是否生效：

  1. 检查 HTTPS：访问您的域名并确保看到有效的证书，且没有浏览器警告
  2. 测试 WebSocket：打开浏览器开发者工具，进入“网络 (Network)”选项卡，按“WS”过滤，并验证 WebSocket 连接已建立
  3. 验证 CORS：检查浏览器控制台是否有任何与 CORS 相关的错误
  4. 测试功能：发送一条消息并确保流式响应正常工作

快速修复清单​

  • ✓ 在启用 OAuth 之前，将 WEBUI_URL 设置为您的实际 HTTPS 域名
  • ✓ 确保您的反向代理已配置为转发 WebSocket 流量
  • ✓ 验证 CORS_ALLOW_ORIGIN 包含您的完整域名
  • ✓ 如果在本地测试 HTTPS，请在浏览器中启用不安全来源的标志