🔐 OAUTH / SSO 问题故障排除
OAUTH 或单点登录 (SSO) 允许您使用现代身份验证来保护 Open WebUI，但当用户遇到登录问题时，如果知道从何查起，解决方案通常很简单。大多数情况下，以下关键问题之一是罪魁祸首。以下是快速查找并解决 SSO 难题的方法！🚦
常见的 OAUTH/SSO 问题及解决方法 🛠️
1. WebUI URL 未在管理面板中配置 🚪🔒
大多数 OAUTH 流程要求提供应用程序的外部 URL（“重定向 URI”），以便服务提供商知道登录后将用户发送到何处。如果缺少此项，OAUTH 将无法完成！
✅ 解决方案
- 导航至：管理设置 > 通用
- 确保您的 WebUI URL 字段已填写并指向您的部署实例（例如，
https://yourwebui.yourdomain.com）📌 提示：检查拼写错误！OAUTH 非常严格——URL 必须完全匹配，包括https://。
2. 环境变量配置不正确 📝🚫
这是导致 OAUTH 失败的最常见原因。如果您拼写错误、遗漏或设置了错误的环境变量（尤其是 OIDC/OAUTH 配置），身份验证将无法工作。
✅ 解决方案
- 仔细检查您的部署环境
- 确保所有必需的环境变量都已设置（请参阅文档了解
OIDC_CONFIG、OAUTH_CLIENT_ID等名称） - 如果是自托管，请确认这些变量存在于您的 Docker Compose、Kubernetes 清单或
.env文件中。
- 确保所有必需的环境变量都已设置（请参阅文档了解
- 更改变量后重启您的后端/应用程序，以便加载新值。
📌 提示：大多数 OAUTH 错误（循环、401 错误、无响应）是由于环境变量设置不正确或完全缺失造成的！
3. 服务提供商侧的 OAUTH 配置错误 🏢🔗
有时问题出在身份提供商（例如 Google、Okta、Auth0、Azure AD）未与您的 WebUI 设置对齐。
✅ 解决方案
- 验证您的应用程序已在 OAUTH 提供商处正确注册。确认
- 重定向 URI 与您部署的 WebUI 地址完全匹配
- 客户端 ID 和密钥与您的环境设置中给定的值匹配
- Scope（范围）和允许的授权类型（例如，
authorization_code）已按照 Open WebUI 的要求设置
- 检查提供商的日志——配置错误的应用程序通常会在那里显示清晰的错误消息。
📌 提示：如有疑问，请重新检查您的提供商注册信息，并在需要时重新生成客户端密钥。
4. 服务器端缓存（一个隐藏的麻烦点！）🧊🚦
一个新的棘手问题：如果您使用 NGINX（或其他反向代理）进行服务器端缓存，OAUTH 端点可能会出现异常行为。结果不总是完全失败——通常，用户会遇到随机或“奇怪”的登录错误，这些错误几乎无法调试。
✅ 解决方案
- 在您的 NGINX（或代理）配置中
- 确保将以下端点排除在服务器端缓存之外
/api、/oauth、/callback、/login、/ws、/websocket
- 任何关键的登录/身份验证端点都必须保持不缓存！
- 确保将以下端点排除在服务器端缓存之外
- 更改后重新加载代理配置。
📌 警告：切勿缓存 OAUTH 或登录端点！缓存可能会“污染”会话或提供过时的令牌，导致奇怪的身份验证错误。
🧪 专业提示：始终检查日志
- 查看后端日志和浏览器网络错误。第一个错误通常指向配置错误（重定向 URI 不匹配、变量缺失/无效、提供商侧错误或缓存问题）。
- 如果不确定问题出在哪一方，请尝试从隐身浏览器窗口登录，并留意是否有任何被阻止或失败的请求。
总结清单 ✅
| 问题 | 解决方法 |
|---|---|
| 🔗 WebUI URL 缺失或错误 | 在管理面板中设置正确的 WebUI URL |
| 📝 环境变量拼写错误或缺失 | 仔细检查并设置所有 OAUTH/SSO 环境变量 |
| 🏢 提供商配置错误 | 确认应用程序注册、URI 及客户端 ID/密钥 |
| 🧊 代理缓存干扰 | 将 OAUTH 端点从所有服务器端缓存中排除 |
| 仍然卡住？ | 查看日志并进行无缓存测试 |
通过仔细配置您的 OAUTH 提供商和 WebUI 环境——并使关键登录端点不受缓存影响——您将消除几乎所有 SSO/OAUTH 登录问题。不要让拼写错误或隐藏的缓存阻止您的用户无缝、安全地访问 AI！🦾