跳到主要内容

连接错误

本页汇总 OPL 数据空间中常见的连接问题、产生原因以及排查方法。

HTTPS、TLS、CORS 与 WebSocket​

如果你在反向代理或 HTTPS 场景下使用 OPL 数据空间，连接问题往往来自 CORS、TLS、WebSocket 或 Cookie 配置不完整。

常见症状​

  • 聊天里返回空对象，如 "{}"
  • 流式响应解析报错，如 "Unexpected token ... is not valid JSON"
  • 流式输出时 markdown 乱码
  • 浏览器控制台出现 WebSocket 连接失败
  • CLI 日志里出现 WebSocket 失败
  • 登录状态异常或会话丢失
  • 浏览器开发者工具里出现 CORS 错误
  • HTTPS 页面里出现 mixed content 警告

HTTPS + 反向代理的关键配置​

WEBUI_URL=https://your-open-webui-domain.com

CORS_ALLOW_ORIGIN="https://yourdomain.com;http://yourdomain.com;https://yourip;http://localhost:3000"

WEBUI_SESSION_COOKIE_SECURE=true
WEBUI_AUTH_COOKIE_SECURE=true

WEBUI_SESSION_COOKIE_SAME_SITE=lax
WEBUI_AUTH_COOKIE_SAME_SITE=lax

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

要点：

  • WEBUI_URL 对 OAuth / SSO 尤其关键
  • CORS_ALLOW_ORIGIN 要覆盖所有访问方式，包括域名、IP、localhost、HTTP/HTTPS 与端口
  • 开启 HTTPS 时，要同步打开 cookie 的 secure

WEBUI_URL 的注意事项​

它是 PersistentConfig。若实例已经启动过，再改环境变量可能不会立即生效。常见处理方式：

  • 临时关闭 ENABLE_PERSISTENT_CONFIG
  • 在管理面板中直接修改 WebUI URL
  • 在首次启动前就写对

反向代理 / TLS​

如果你需要更完整的反向代理和 HTTPS 配置示例，可查看 HTTPS Reference。

WebSocket 排查​

WebSocket 排查​

v0.5.0 以后， OPL 数据空间强依赖 WebSocket。若它无法工作：

  1. 检查反向代理是否正确转发 Upgrade 与 Connection 头
  2. 检查 CORS 设置
  3. 看浏览器控制台里的 WebSocket 报错
  4. 临时绕过代理，直接连 OPL 数据空间，确认问题是否来自代理层
  5. 如果使用 HAProxy 或 Nginx，确认没有因为 HTTP/2 和 WebSocket 的兼容问题导致卡死

多实例部署下，必须配 Redis：

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

更多内容可参考：

快速检查清单​

  • 正确设置 WEBUI_URL
  • CORS_ALLOW_ORIGIN 覆盖全部入口
  • HTTPS 下开启安全 Cookie
  • 反向代理支持 WebSocket
  • 正确设置 X-Forwarded-Proto
  • 配置 HTTP → HTTPS 跳转
  • 如果使用 Nginx，关闭代理缓冲

流式响应 markdown 乱码​

如果在流式输出中看到了裸露的 ##、** 等 markdown 片段，而关闭 streaming 后又恢复正常，原因通常是 Nginx proxy buffering。

解决方式是在反向代理里关闭缓冲：

location / {
    proxy_pass http://your-open-webui-upstream;
    proxy_buffering off;
    proxy_cache off;
    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;
}

关闭缓冲不仅能修复 markdown 断裂，也会显著改善流式速度。

前端连接与后端连接的差异​

OPL 数据空间里很多功能既支持“用户直连”，也支持“管理员全局连接”。这两者的网络位置不同。

请求发起方localhost 指向哪里典型场景
浏览器（前端）用户当前使用的那台机器用户自定义工具、直连终端、Direct Connections
OPL 数据空间后端运行 OPL 数据空间的宿主机或容器全局工具服务、管理员终端、Ollama / OpenAI 连接

因此，同一个 URL 在前端能用、在后端却失败是很常见的。

后端连接应优先使用：

  • Docker service name，例如 http://open-terminal:8000
  • host.docker.internal
  • 内网 IP

这个规律适用于 Tool Server、Open Terminal、Ollama、OpenAI API 端点等所有由后端代发请求的连接。

连接 Ollama 失败​

连接 Ollama 失败​

如果 OPL 数据空间连不上 Ollama，通常是因为 Ollama 只监听了 127.0.0.1。

处理方式：

  1. 设置 OLLAMA_HOST=0.0.0.0
  2. 确认它真的生效在 systemd、Docker 或 shell 配置中
  3. 重启 Ollama

其他常见连接问题​

模型列表加载问题：界面缓慢或端点不可达​

如果你保存了一个不可达的模型端点，管理设置页可能会因为反复拉取模型列表而变慢甚至卡住。常见处理方式：

  • 暂时把 AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST 调小
  • 用后端视角可访问的地址替换不可达 URL
  • 对外部 provider 使用模型白名单，减少 /models 请求的成本

内部工具的 SSL 证书问题​

如果内部工具、代理服务或公司内网 HTTPS 端点出现证书错误，通常需要补充信任链或配置自定义 CA。详见 自定义 CA 证书库。

如果你遇到的是模型列表加载缓慢、不可达端点导致设置页卡死、后台代理 URL 指向错误、SSE 被反向代理截断等问题，可以优先从以下方向排查：

  • 端点 URL 是否从后端视角可达
  • /v1 之类的必需路径是否遗漏
  • 代理是否改写或缓存了流式响应
  • CORS 与 Cookie 是否覆盖了真实访问路径
  • 多副本部署下是否已接好 Redis 与共享状态