Keycloak启动时修改Infinispan缓存配置的合法性及复制验证方法

一、配置方式的合法性 #

你当前的操作完全合法：

• Keycloak原生支持通过自定义cache-ispn.xml配置文件调整Infinispan缓存参数，包括分布式缓存的owner数。
• 构建镜像时预设基础配置、部署阶段根据集群规模动态修改并挂载覆盖的方式，符合Keycloak的配置加载逻辑——挂载的外部配置优先级高于镜像内的默认文件。
• 注意：owner数建议设置为集群节点数的一半向上取整（比如3节点集群设为2），避免数据冗余过高或可用性不足，你根据节点数动态调整的思路是合理的。

二、验证缓存复制生效的具体方法 #

1. 先确认配置是否被正确加载 #

• 日志排查：在TRACE级别日志中搜索cache-ispn.xml，找到类似Loading configuration from /opt/keycloak/conf/cache-ispn.xml的条目，同时查看是否有Parsed cache configuration with owners=X的内容，确认X是你部署时设置的数值。
• 命令验证：进入任意Keycloak Pod执行kc.sh show-config，查看cache-config-file对应的实际路径，确认指向挂载的外部配置文件而非镜像内的默认文件。

2. 指标验证（聚焦关键指标） #

启用Infinispan指标后，重点从Keycloak的/metrics端点获取以下指标：

• infinispan_cache_distribution_owners：直接显示当前缓存配置的owner数，检查是否与部署时设置的一致。
• infinispan_cache_number_of_entries：在节点A创建一个测试用户/会话后，查看其他节点的该指标变化：如果owner数为N，应该有N个节点的条目数同步增加（对应负责存储该条目的owner节点）。
• infinispan_cache_replications_total：执行写入操作（如创建用户）时，该指标的增量应等于owner数-1（因为需要复制给其他owner节点），说明复制操作正在执行。
• infinispan_cache_cluster_size：确认集群节点数与预期一致，这是缓存复制的基础前提。

3. 日志验证（缩小排查范围） #

调整日志级别后，聚焦以下关键词和日志条目：

• 配置加载日志：搜索owner、cache-ispn.xml，确认加载的配置参数正确。
• 复制操作日志：搜索Replicating entry、Cache entry replicated，这类日志会明确显示缓存条目被复制到哪些节点，直接验证复制行为。
• 集群通信日志：查看org.infinispan.remoting.transport.jgroups.JGroupsTransport下的日志，节点间的缓存同步通信会在这里输出，比如Sent message to [node-id]的条目。
• 集群视图日志：搜索Cluster view changed，确认所有节点都在集群视图中，避免因节点未加入集群导致复制失效。

4. 手动功能验证 #

最直接的验证方式：

1. 绕过负载均衡，直接访问节点A的管理API创建一个测试用户。
2. 直接访问节点B的管理API，查询该用户是否存在：
   • 如果owner数>1，节点B应能查到该用户（说明缓存副本已同步）。
   • 如果owner数=1，只有负责该条目的节点能查到，其他节点会从数据库加载（此时复制不生效，符合配置预期）。
3. 模拟节点故障：删除节点A，访问其他节点查看是否能正常访问该用户（owner数>1时，其他owner节点会保留副本，服务不受影响）。

内容的提问来源于stack exchange，提问作者Sirish Kumar Bethala