Keycloak从19升级到25后JDBC_PING分布式缓存异常问题

问题概述 #

AWS ECS容器部署的Keycloak，原通过JDBC-PING实现分布式缓存服务发现。升级至25版本后，所有业务功能正常，但分布式缓存集群无法形成，出现JGroups初始化失败错误，JGROUPSPING表可正常写入节点记录。

核心错误信息 #

java.lang.IllegalStateException: Failed to start JGroups channel
Caused by: org.jgroups.protocols.JGroupsException: failed to join cluster [keycloak]

补充日志 #

JGRP000013: Failed to join cluster [keycloak], exception: java.lang.IllegalStateException: failed to start channel
JGRP000034: Received discovery response for cluster keycloak from null: no physical address found

当前Infinispan配置 #

<infinispan
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="urn:infinispan:config:15.0 http://www.infinispan.org/schemas/infinispan-config-15.0.xsd"
      xmlns="urn:infinispan:config:15.0">

  <!-- 自定义JGroups栈配置 -->
  <jgroups>
    <stack name="jdbc-ping-tcp" extends="tcp">
      <JDBC_PING connection_driver="org.postgresql.Driver"
                 connection_username="${env.KC_DB_USERNAME}" connection_password="${env.KC_DB_PASSWORD}"
                 connection_url="jdbc:postgresql://${env.KC_DB_URL_HOST}/${env.KC_DB_URL_DATABASE}"
                 initialize_sql="CREATE TABLE IF NOT EXISTS JGROUPSPING (own_addr varchar(200) NOT NULL, cluster_name varchar(200) NOT NULL, ping_data BYTEA, constraint PK_JGROUPSPING PRIMARY KEY (own_addr, cluster_name));"
                 info_writer_sleep_time="500"
                 remove_all_data_on_view_change="true"
                 stack.combine="REPLACE"
                 stack.position="MPING" />
    </stack>
  </jgroups>
  
  <cache-container name="keycloak">
    <transport lock-timeout="60000" stack="jdbc-ping-tcp"/>
    <local-cache name="realms" simple-cache="true">
      <encoding>
        <key media-type="application/x-java-object"/>
        <value media-type="application/x-java-object"/>
      </encoding>
      <memory max-count="10000"/>
    </local-cache>
    <local-cache name="users" simple-cache="true">
      <encoding>
        <key media-type="application/x-java-object"/>
        <value media-type="application/x-java-object"/>
      </encoding>
      <memory max-count="10000"/>
    </local-cache>
    <distributed-cache name="sessions" owners="2">
      <expiration lifespan="-1"/>
    </distributed-cache>
    <distributed-cache name="authenticationSessions" owners="2">
      <expiration lifespan="-1"/>
    </distributed-cache>
    <distributed-cache name="offlineSessions" owners="2">
      <expiration lifespan="-1"/>
    </distributed-cache>
    <distributed-cache name="clientSessions" owners="2">
      <expiration lifespan="-1"/>
    </distributed-cache>
    <distributed-cache name="offlineClientSessions" owners="2">
      <expiration lifespan="-1"/>
    </distributed-cache>
    <distributed-cache name="loginFailures" owners="2">
      <expiration lifespan="-1"/>
    </distributed-cache>
    <local-cache name="authorization">
      <encoding>
        <key media-type="application/x-java-object"/>
        <value media-type="application/x-java-object"/>
      </encoding>
      <memory max-count="10000"/>
    </local-cache>
    <replicated-cache name="work">
      <expiration lifespan="-1"/>
    </replicated-cache>
    <local-cache name="keys">
      <encoding>
        <key media-type="application/x-java-object"/>
        <value media-type="application/x-java-object"/>
      </encoding>
      <expiration max-idle="3600000"/>
      <memory max-count="1000"/>
    </local-cache>
    <distributed-cache name="actionTokens" owners="2">
      <encoding>
        <key media-type="application/x-java-object"/>
        <value media-type="application/x-java-object"/>
      </encoding>
      <expiration max-idle="-1" lifespan="-1" interval="300000"/>
      <memory max-count="-1"/>
    </distributed-cache>
  </cache-container>
</infinispan>

解决方案建议 #

1. 适配JDBC-PING表结构 #

新版本JGroups的节点地址字段长度可能超出原配置的200字符，修改initialize_sql中的own_addr字段长度：

CREATE TABLE IF NOT EXISTS JGROUPSPING (own_addr varchar(300) NOT NULL, cluster_name varchar(200) NOT NULL, ping_data BYTEA, constraint PK_JGROUPSPING PRIMARY KEY (own_addr, cluster_name));

2. 修复TCP栈IP绑定配置 #

AWS ECS容器IP动态分配，需明确指定JGroups绑定地址，在自定义栈中添加TCP配置：

<stack name="jdbc-ping-tcp" extends="tcp">
  <TCP bind_addr="${env.JGROUPS_BIND_ADDR:0.0.0.0}" bind_port="${env.JGROUPS_BIND_PORT:7800}" />
  <JDBC_PING ... />
</stack>

同时在Keycloak启动参数中添加：-e JGROUPS_BIND_ADDR=0.0.0.0，确保容器能监听所有网卡。

3. 移除冲突配置项 #

remove_all_data_on_view_change="true"在新版本中可能引发集群视图异常，暂时移除该配置，后续手动清理JGROUPSPING表历史数据。

4. 验证网络连通性 #

• 确保ECS安全组和网络ACL放行7800端口的TCP流量，允许容器间互通。
• 若使用Fargate，需采用awsvpc网络模式，让容器获取独立私有IP，避免端口映射冲突。

5. 确认依赖完整性 #

Keycloak 25基于Quarkus重构，需确保PostgreSQL驱动已正确引入：启动时添加参数--db=postgres，或在容器镜像中手动加入驱动依赖。

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