Docker部署的Keycloak登录报错‘An error occurred, please login again through your application (invalidCodeMessage)’如何解决？

我之前帮不少开发者排查过这个Keycloak的invalidCodeMessage问题，结合你用的jboss/keycloak:11.0.3和PostgreSQL13.2环境，给你整理几个最常见的解决方向：

这个错误最常见的原因就是授权码过期或者存储丢失：

• 调长授权码有效期：Keycloak 11.0.3默认授权码只有60秒有效期，如果用户登录操作（比如输入验证码、二次验证）耗时太久，就会触发过期错误。你可以登录Keycloak后台，进入对应Realm的设置 → Tokens，找到Authorization Code Lifespan选项，把时长调整到120秒或180秒试试。
• 确认授权码存储到PostgreSQL：如果你的Keycloak是多实例部署或者容器频繁重启，默认的内存存储会导致授权码丢失。检查standalone.xml（或standalone-ha.xml）的persistence配置，确保已经启用JDBC存储并正确指向你的PostgreSQL实例，这样授权码会持久化到数据库，不会随容器重启丢失。

Keycloak依赖时间戳判断授权码有效性，如果容器和数据库时区不一致，会导致时间计算错误，误以为授权码过期：

• 给Keycloak容器设置时区：启动容器时添加环境变量，比如-e TZ=Asia/Shanghai（替换成你的实际时区）。
• 检查PostgreSQL时区：连接数据库执行SQL SHOW timezone;，如果和Keycloak时区不一致，可以修改postgresql.conf里的timezone参数，或者在Keycloak的JDBC连接URL后追加?serverTimezone=Asia/Shanghai。

Cookie传递异常也会导致授权码验证失败：

• 调整SameSite属性：如果你的应用是跨域场景，在Realm设置 → Security Defenses → Cookie里，把SameSite属性设置为None（注意必须配合HTTPS使用），或者根据你的部署场景调整为Lax。
• 确认Cookie域名匹配：Cookie的Domain设置要和Keycloak的访问域名完全一致，避免浏览器无法正确携带Cookie到Keycloak服务器。

Keycloak不会自动清理过期的授权码记录，时间久了表数据堆积会导致查询变慢，偶尔出现验证超时：

• 手动清理过期数据：连接PostgreSQL，找到code表（如果有表前缀就是keycloak_code），执行SQL：

  DELETE FROM code WHERE expiration < NOW();
  

• 设置定时清理任务：可以用PostgreSQL的定时任务（比如pg_cron扩展）定期执行上面的清理语句，避免数据堆积。

如果你的Keycloak前面有Nginx之类的代理，可能存在以下问题：

• 开启会话粘性：多实例部署时，负载均衡器必须开启会话粘性（Sticky Session），确保同一个用户的请求始终发到同一个Keycloak实例（如果用内存存储授权码的话，这一点至关重要）。
• 正确传递请求头：确保代理正确传递X-Forwarded-For、X-Forwarded-Proto等头信息，Keycloak需要这些头来生成正确的回调URL和Cookie。

你可以先从时区和授权码有效期这两个最容易排查的点入手，大部分情况下调整后就能解决这个偶尔出现的错误。如果问题还存在，建议查看Keycloak的容器日志和PostgreSQL的数据库日志，找更具体的错误信息来进一步定位。

内容的提问来源于stack exchange，提问作者majid kakavandi