Keycloak 常见问题排查
本节收录 Keycloak 生产环境高频问题与排查方案。案例文章已移入 Blog，本页保留症状索引与通用排查思路：先按症状在「快速索引」里定位，再进对应文章。
快速索引
| 症状 | 关键词 | 解决方案 |
|---|---|---|
登录后报 HTTPS required / Invalid parameter: redirect_uri | HTTPS、反向代理、proxy | HTTPS / 反向代理问题 |
| 启动卡在 Liquibase / 数据库初始化失败 | Liquibase、MySQL Group Replication、锁 | Liquibase 与 MySQL 组复制 |
| K8s 环境导入导出 Realm 迁移失败 | 导入导出、Helm、Operator | K8s 导入导出迁移 |
| 登录后无限重定向 / 401 Unauthorized | ERR_TOO_MANY_REDIRECTS、Cookie、SameSite | Keycloak 重定向循环与 401 排错指南 |
浏览器报 CORS 错误 / 服务端 403 Invalid origin | Web Origins、Origin 头、26.6.3 行为变更 | IAM 前端跨域排错：Keycloak Web Origins 与 CORS 边界 |
SAML 应用报 Client not found. / Invalid redirect uri / 签名校验失败 | SAML Client、EntityID、ACS URL、NameID、签名开关 | Keycloak 作为 SAML IdP 接入应用 |
通用排查思路
- 看日志：
kc.sh start --log-level=DEBUG或容器kubectl logs，优先找ERROR/WARN与异常栈。 - 分层定位：浏览器（302/redirect_uri）→ 反代（X-Forwarded-* 头）→ Keycloak（Realm/Client 配置）→ 数据库（连接/锁/迁移）。
- 复现：用
curl -v复现 OIDC 授权请求，观察Location头与参数。 - 核对版本：Keycloak 大版本间（WildFly → Quarkus）配置项与默认路径变化大，先确认版本。
常见根因分类
- 反向代理头缺失或未清洗：
X-Forwarded-Proto/Host未透传，或代理追加了客户端伪造值，导致 Keycloak 生成http://回调、错误域名或错误审计来源。现代 Keycloak 按版本配置KC_PROXY_HEADERS，并限制可信代理；具体检查见 Keycloak 重定向循环与 401 排错指南。 - 数据库迁移锁：Liquibase 在多节点同时启动或 MySQL Group Replication 下加锁失败。需串行启动或调整锁表配置。
- Realm 导入格式/路径：Helm/Operator 导入期望
keycloakConfig或 volume 挂载路径，与命令行--import行为不同。 - Client redirect_uri 不匹配：精确匹配，避免通配；回调路径区分大小写与尾部斜杠。
- 缓存不一致：集群
loginFailures/users缓存栈配置不当，导致暴力检测或用户更新跨节点不生效。
更多案例见上方索引。新问题欢迎提交 Issue 补充。