共享同一数据库的Keycloak实例不同步问题解决方案咨询

核心原因 #

你的问题本质是Keycloak默认使用本地Infinispan缓存，公共实例会将用户、角色等数据缓存到本地内存，不会主动监听数据库的变更，只有重启时才会重新加载数据。

最佳方案：调整缓存集群配置 #

直接配置Keycloak的分布式缓存集群是最省心、通用的解决方案，无需额外开发，就能实现缓存实时同步。

1. 启用分布式缓存与JDBC集群发现 #

因为两个实例共享同一数据库，推荐使用JDBC_PING作为集群发现机制，无需额外的集群服务（比如ZooKeeper）。Docker部署时，给两个实例添加以下环境变量：

# 启用Infinispan分布式缓存
KC_CACHE=ispn
# 使用JDBC_PING做集群发现
KC_CACHE_STACK=jdbc-ping
# 数据库连接信息（和你的实例配置一致）
KC_DB_URL=jdbc:postgresql://你的数据库地址:5432/keycloak
KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=你的数据库密码

配置后，两个Keycloak实例会自动通过数据库做集群成员发现，任何一个实例的缓存更新（比如管理实例修改用户属性）都会实时同步到集群内的其他实例，公共实例会立即获取最新数据。

2. 临时过渡方案：缩短缓存TTL（不推荐长期使用） #

如果暂时无法配置集群，可以通过缩短用户缓存的过期时间，让公共实例定期从数据库拉取最新数据。添加以下环境变量：

# 用户缓存过期时间（单位：秒）
KC_CACHE_USER_TTL=300
# 用户缓存最大空闲时间（单位：秒）
KC_CACHE_USER_MAX_IDLE=300

这种方式不是实时同步，只是减少重启频率，适合临时过渡，长期使用会增加数据库查询压力。

事件/钩子的适用场景 #

事件和钩子属于自定义扩展方案，仅适用于有特殊业务需求的场景，不是通用最佳实践：

• 事件监听：可以监听管理实例的用户修改事件，然后调用公共实例的/admin/realms/{realm}/clear-cache接口主动刷新缓存，但需要自己开发监听逻辑或借助第三方工具，复杂度高。
• SPI钩子：通过自定义Keycloak SPI扩展缓存加载逻辑，同样需要开发成本，没必要用在基础的缓存同步场景。

验证方法 #

在管理实例修改用户属性后，直接通过公共实例的API或客户端查询该用户，确认属性已更新，无需重启公共实例即可生效。

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