Bitnami Keycloak 26.0.5 连接外部Infinispan失败求助

问题背景 #

我对Keycloak外部配置搭建较为陌生，已花费数周时间尝试搭建Bitnami Keycloak 26.0.5连接外部Infinispan实例的演示环境，但始终未能成功。查阅了多篇教程，包括：

• Keycloak Cluster using JDBC_PING for Distributed Caching
• Keycloak Cluster Setup with Docker Compose and JDBC_PING
• Keycloak Quarkus Distribution with Standalone Infinispan Setup

遗憾的是，这些教程大多已过时，包含Keycloak 26已弃用的配置或缺失步骤，每次尝试都会遇到无法解决的错误。在配置过程中，我了解了相关术语，也对infinispan.xml和cache-ispn.xml文件有了基础认知，但仍无法实现Keycloak与Infinispan的成功连接。

前置准备 #

先启动一个外部Infinispan测试实例，添加到你的docker-compose.yml中：

services:
  # ... 原有服务 ...
  infinispan:
    image: infinispan/server:15.0.10.Final
    ports:
      - "11222:11222"
      - "11211:11211"
    environment:
      - USER=admin
      - PASS=admin
    extra_hosts:
      - "host.docker.internal:host-gateway"

步骤1：修改Keycloak配置 #

1.1 更新Dockerfile #

调整Dockerfile，添加Infinispan依赖、缓存配置文件及自定义提供商（需提前下载对应文件到指定路径）：

FROM bitnami/keycloak:26.0.5

# 复制HTTPS证书文件
COPY ./keycloak/truststores/server.crt.pem /opt/keycloak/conf/truststores/server.crt.pem
COPY ./keycloak/truststores/server.key.pem /opt/keycloak/conf/truststores/server.key.pem

# 复制Infinispan客户端依赖（版本需与Infinispan服务器一致，推荐15.0.10.Final）
COPY ./keycloak/providers/infinispan-client-hotrod-15.0.10.Final.jar /opt/bitnami/keycloak/providers/
COPY ./keycloak/providers/infinispan-commons-15.0.10.Final.jar /opt/bitnami/keycloak/providers/

# 复制自定义Apple身份提供商JAR包
COPY ./keycloak/providers/apple-identity-provider-1.13.0.jar /opt/bitnami/keycloak/providers/apple-identity-provider-1.13.0.jar

# 复制Infinispan缓存配置文件
COPY ./keycloak/conf/cache-ispn.xml /opt/keycloak/conf/cache-ispn.xml

1.2 编写Infinispan缓存配置文件 #

在./keycloak/conf目录下创建cache-ispn.xml，配置远程Infinispan连接及Keycloak所需缓存：

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

    <cache-container name="keycloak">
        <transport cluster="keycloak"/>
        <remote-cache-container name="remote" statistics="true">
            <remote-server host="infinispan" port="11222"/>
            <security>
                <authentication username="admin" password="admin"/>
            </security>
        </remote-cache-container>

        <!-- Keycloak核心缓存配置 -->
        <local-cache name="realms">
            <encoding>
                <key media-type="application/x-java-object"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <remote-store cache="realms" cache-container="remote" preload="true" purge="false"/>
        </local-cache>

        <local-cache name="users">
            <encoding>
                <key media-type="application/x-java-object"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <remote-store cache="users" cache-container="remote" preload="true" purge="false"/>
        </local-cache>

        <local-cache name="sessions">
            <encoding>
                <key media-type="application/x-java-object"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <remote-store cache="sessions" cache-container="remote" preload="true" purge="false"/>
        </local-cache>

        <local-cache name="authenticationSessions">
            <encoding>
                <key media-type="application/x-java-object"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <remote-store cache="authenticationSessions" cache-container="remote" preload="true" purge="false"/>
        </local-cache>

        <local-cache name="offlineSessions">
            <encoding>
                <key media-type="application/x-java-object"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <remote-store cache="offlineSessions" cache-container="remote" preload="true" purge="false"/>
        </local-cache>

        <local-cache name="clientSessions">
            <encoding>
                <key media-type="application/x-java-object"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <remote-store cache="clientSessions" cache-container="remote" preload="true" purge="false"/>
        </local-cache>

        <local-cache name="offlineClientSessions">
            <encoding>
                <key media-type="application/x-java-object"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <remote-store cache="offlineClientSessions" cache-container="remote" preload="true" purge="false"/>
        </local-cache>

        <local-cache name="loginFailures">
            <encoding>
                <key media-type="application/x-java-object"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <remote-store cache="loginFailures" cache-container="remote" preload="true" purge="false"/>
        </local-cache>

        <local-cache name="authorization">
            <encoding>
                <key media-type="application/x-java-object"/>
                <value media-type="application/x-java-object"/>
            </encoding>
            <remote-store cache="authorization" cache-container="remote" preload="true" purge="false"/>
        </local-cache>
    </cache-container>
</infinispan>

1.3 更新docker-compose.yml中的Keycloak环境变量 #

在keycloak-1-26的environment中添加Infinispan相关配置，同时添加服务依赖：

services:
  keycloak-1-26:
    # ... 原有配置 ...
    environment:
      # ... 原有环境变量 ...
      # Infinispan配置
      - KC_CACHE=ispn
      - KC_CACHE_CONFIG_FILE=cache-ispn.xml
      - KC_TRANSPORT_STACK=udp
      - KC_TRANSPORT_NODE_NAME=keycloak-node-1
    depends_on:
       - postgresdb_18
       - infinispan

步骤2：启动服务 #

执行命令启动所有服务：

docker-compose up --build -d

步骤3：验证连接 #

1. 访问Keycloak管理控制台（https://localhost:9444/admin），确认能正常登录和操作
2. 访问Infinispan控制台（http://localhost:11222/console），登录后查看realms、users等缓存是否有数据写入
3. 查看Keycloak日志，确认无连接错误：

docker-compose logs -f keycloak-1-26

日志中出现Connected to server infinispan/xxx.xxx.xxx.xxx:11222字样时，说明连接成功。

常见问题排查 #

• 版本不兼容：确保Infinispan客户端与服务器版本一致（推荐15.0.10.Final，与Keycloak 26兼容）
• 网络不通：检查Docker容器间网络连通性，确保Keycloak能访问Infinispan的11222端口
• 认证失败：确认Infinispan的用户名、密码与cache-ispn.xml中的配置一致
• 配置文件路径错误：确保cache-ispn.xml被正确复制到Keycloak的/opt/keycloak/conf目录下

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