Keycloak 26集群配置异常：自定义端口与物理IP未生效

以下是针对配置未生效问题的排查和修复步骤：

1. 确认缓存配置文件的加载逻辑 #

• 检查keycloak.conf中是否正确指定缓存配置文件：

  cache-config-file=cache-ispn-tcpping.xml
  cache-stack=tcpping
  

  若配置文件不在Keycloak默认的conf目录下，需填写完整路径，比如file:/opt/keycloak/custom-config/cache-ispn-tcpping.xml。
• 启动时也可通过命令行参数强制指定配置文件，覆盖conf中的设置：

  ./kc.sh start --cache-config-file=cache-ispn-tcpping.xml
  

2. 修正cache-ispn-tcpping.xml核心配置 #

确保XML中TCP绑定和TCPPING发现配置完全匹配你的物理IP和端口：

<infinispan>
  <cache-container name="keycloak">
    <transport lock-timeout="60000">
      <!-- 明确指定物理IP和端口 -->
      <TCP bind-address="10.0.0.5" bind-port="7805"/>
      <!-- TCPPING的initial-hosts需与绑定地址一致 -->
      <TCPPING initial-hosts="10.0.0.5[7805]" port-range="0" timeout="3000" num-initially-connected-nodes="1" up-time="5000"/>
    </transport>
    <!-- 其他缓存配置... -->
  </cache-container>
</infinispan>

3. 排查Docker环境的冲突配置 #

• 端口映射：启动容器时必须映射7805端口到宿主机对应IP，否则容器内部端口无法被外部访问：

  docker run -p 10.0.0.5:7805:7805 -p 8080:8080 -v /path/to/your/conf:/opt/keycloak/conf quay.io/keycloak/keycloak:26.0 start
  

• 环境变量覆盖：Keycloak环境变量优先级高于XML配置，检查是否设置了以下冲突变量：
  • KC_CACHE_TRANSPORT_TCP_BIND_ADDRESS：会覆盖XML中的bind-address
  • KC_CACHE_TRANSPORT_TCP_BIND_PORT：会覆盖XML中的bind-port
    确保启动容器时未传入这些变量，或将其设置为你需要的10.0.0.5和7805。

4. 验证配置是否生效 #

启动Keycloak后，查看日志（容器内日志可通过docker logs <container-id>查看），搜索关键词JGroups或transport，正常会输出类似内容：

ISPN000078: Starting JGroups channel ISPN
JGRP000015: the local address is 10.0.0.5:7805

若日志显示172.17.0.1:7800，说明配置文件未被正确加载，需检查路径、权限或启动参数。

5. 额外注意事项 #

• 确保宿主机防火墙开放7805端口，允许集群节点间TCP通信；
• 测试环境可使用Docker的host网络模式（--network host）避免端口映射问题，生产环境不推荐；
• 确认Keycloak进程对cache-ispn-tcpping.xml有读取权限，Docker容器内文件需设置为keycloak用户可访问。

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