AWS EC2部署Keycloak 20.0.2集群节点无法识别问题求助

1. 确认自定义配置文件加载逻辑 #

Keycloak 20基于Quarkus架构，启动时需明确指定自定义缓存配置，否则会自动 fallback 到默认配置：

• 启动命令必须通过--cache-config-file参数指定自定义cache-ispn.xml，或设置环境变量KC_CACHE_CONFIG_FILE=cache-ispn.xml
• 确保cache-ispn.xml和custom-jgroups-ec2.xml放在Keycloak的conf目录下，或使用绝对路径指定文件位置

2. 验证jgroups-aws依赖有效性 #

• 确认jgroups-aws-2.0.1.Final.jar已放入providers目录，执行kc.sh build后，检查quarkus-app/lib/main目录下是否存在该jar包（build过程会扫描providers目录并整合依赖到运行时类路径）
• 若build日志未出现加载该provider的记录，删除quarkus-app目录后重新执行kc.sh build

3. 检查custom-jgroups-ec2.xml配置 #

必须配置AWS_PING协议实现EC2节点发现，同时确保EC2实例的IAM角色拥有目标S3桶的读写权限（需包含s3:PutObject/s3:GetObject/s3:ListBucket权限）：

<config xmlns="urn:org:jgroups"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:org:jgroups http://www.jgroups.org/schema/jgroups-5.2.xsd">
    <TCP bind_port="7600" />
    <AWS_PING region="your-aws-region"
              bucket="your-cluster-s3-bucket" />
    <MERGE3 />
    <FD_SOCK />
    <FD_ALL timeout="3000" interval="1000" />
    <VERIFY_SUSPECT timeout="1500" />
    <pbcast.NAKACK2 use_mcast_xmit="false" />
    <UNICAST3 />
    <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000" max_bytes="4M" />
    <pbcast.GMS print_local_addr="true" join_timeout="2000" />
    <UFC max_credits="2M" min_threshold="0.4" />
    <MFC max_credits="2M" min_threshold="0.4" />
    <FRAG2 frag_size="60K" />
</config>

注：使用IAM角色时无需填写access_key/secret_access_key，JGroups会自动从EC2实例元数据获取临时凭证

4. 确保cache-ispn.xml引用自定义JGroups栈 #

在缓存配置文件中指定使用自定义JGroups栈，核心配置片段：

<infinispan xmlns="urn:infinispan:config:14.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="urn:infinispan:config:14.0 https://infinispan.org/schemas/infinispan-config-14.0.xsd">
    <jgroups>
        <stack-file name="ec2-cluster" path="custom-jgroups-ec2.xml" />
    </jgroups>
    <cache-container name="keycloak">
        <transport stack="ec2-cluster" node-name="keycloak-node-${HOSTNAME}"/>
        <!-- 分布式缓存配置，保证会话跨节点同步 -->
        <distributed-cache name="userSessions" owners="2" segments="256">
            <encoding>
                <key media-type="application/x-java-object"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <memory max-count="-1"/>
        </distributed-cache>
        <distributed-cache name="authenticationSessions" owners="2" segments="256">
            <encoding>
                <key media-type="application/x-java-object"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <memory max-count="-1"/>
        </distributed-cache>
        <!-- 保留其他必要缓存配置（realms、clients等） -->
    </cache-container>
</infinispan>

5. 启动命令示例 #

# 先执行build确保依赖和配置生效
./kc.sh build
# 启动节点，指定自定义配置和集群参数
./kc.sh start --cache-config-file=cache-ispn.xml --hostname=<节点内网IP> --cluster=ec2-cluster

6. 日志与权限排查 #

• 查看启动日志，搜索Loading configuration from file确认配置文件是否加载；搜索JGroupsTransport确认是否使用自定义栈（若出现Using stack default则配置未生效）
• 检查S3桶无记录的原因：IAM角色权限不足、区域/桶名配置错误、节点网络无法访问S3（可通过aws s3 ls <bucket-name>在EC2节点上测试S3访问权限）
• 验证EC2节点间7600端口连通性（安全组需允许同一组内节点访问7600/TCP端口）

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