同机部署HAProxy与Keycloak 15.0.2出现服务运行异常问题

根因定位 #

该问题本质是standalone-ha模式默认配置的Keycloak套接字绑定策略与同机HAProxy流量转发逻辑冲突，对应报错的触发逻辑：

• standalone-ha.xml默认启用mod_cluster集群多播发现，未明确绑定地址时会尝试监听所有网卡的多播套接字，和HAProxy转发产生的临时套接字抢占地址资源，触发Can't assign requested address报错
• Keycloak底层XNIO NIO接收器默认绑定0.0.0.0全网卡，HAProxy同机转发时产生的半开TCP连接会被XNIO识别为无效参数连接，触发accept失败退避，直接导致8080端口无响应
• HAProxy日志中的cR-- +10002 408状态码，代表HAProxy到keycloak1的连接一直等待后端响应直到超时，完全符合Keycloak accept线程退避挂起的现象。停止本机Keycloak后其余节点正常，也能佐证冲突仅发生在同机部署的两个服务之间。

修复步骤 #

1. 调整Keycloak启动绑定参数 #

启动10.0.0.1节点的Keycloak时，追加以下启动参数，明确各服务的绑定地址，避免全网卡绑定带来的冲突：

./standalone.sh -c standalone-ha.xml \
  -b 127.0.0.1 \
  -bprivate=10.0.0.1 \
  -bmanagement=127.0.0.1 \
  -Djboss.modcluster.multicast.address=224.0.1.105 \
  -Djboss.node.name=keycloak1

参数说明：

• -b 127.0.0.1：将对外提供Web服务的8080端口绑定到回环地址，仅允许同机HAProxy访问，彻底避开物理网卡的套接字冲突
• -bprivate=10.0.0.1：将JGroups集群通信、节点同步的端口绑定到物理网卡，保证和10.0.0.2上的两个Keycloak节点正常组建集群
• -Djboss.modcluster.multicast.address：明确指定mod_cluster多播发现的合法地址，避免服务自动探测地址时触发绑定错误

如果不需要mod_cluster的自动节点发现（已经用HAProxy做固定节点负载），可以直接编辑standalone-ha.xml，找到modcluster子系统配置，将advertise="true"改为advertise="false"，彻底关闭多播监听，从根源避免多播套接字冲突。

2. 调整HAProxy配置 #

编辑haproxy.cfg的Keycloak backend块，修改为以下配置：

backend Keycloak
    balance roundrobin
    mode http
    option httpchk GET /auth/
    http-check expect status 200
    server  keycloak1 127.0.0.1:8080 check source 127.0.0.1
    server  keycloak2 10.0.0.2:8080 check
    server  keycloak3 10.0.0.2:8180 check

配置说明：

• 同机的keycloak1节点改用回环地址转发，指定源地址也为回环地址，跳过物理网卡的TCP参数校验
• 增加标准HTTP健康检查，替代默认的TCP半开连接检查，避免Keycloak XNIO接收器将健康检查的空连接识别为无效参数连接触发退避

3. 验证生效 #

• 先启动Keycloak，观察日志无XNIO008001、MODCLUSTER000033警告，确认端口监听正常
• 重载HAProxy配置，查看HAProxy统计页/日志，确认三个后端节点均为UP状态，无408超时日志
• 访问http://10.0.0.1/auth/验证服务正常，轮询转发无异常

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