Keycloak15.0.2域模式连远程MariaDB从节点报错排查

使用MariaDB作为外部数据库，在域模式下部署Keycloak v15.0.2：

• MariaDB部署在10.0.0.1服务器，已通过修改主节点domain.xml中的KeycloakDS数据源及对应驱动配置，完成10.0.0.1主节点部署
• 参照官方域模式部署说明，修改domain.xml与host-slave.xml配置文件，计划在10.0.0.2节点部署从节点
• 连通性验证正常：从10.0.0.2节点telnet访问10.0.0.1的3306端口无拦截
• 相同数据源配置写入standalone-ha.xml时，standalone-ha模式可正常启动运行
• 已参考公开的Keycloak域集群部署教程完成配置操作

主节点domain.xml中KeycloakDS数据源配置如下：

<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS"> 
    <connection-url>jdbc:mariadb://10.0.0.1:3306/keycloak</connection-url> 
    <driver>mariadb</driver> 
    <security>
        <user-name>myuser</user-name>
        <password>mypassword</password>
    </security>
</datasource>

启动10.0.0.2从节点时持续抛出连接错误：

Caused by: java.sql.SQLNonTransientConnectionException: 
Socket fail to connect to host:address=(host=localhost)(port=3306)(type=primary). Connection refused: connect

该故障核心原因是域模式下从节点未加载到正确的数据源配置，仍在使用默认指向localhost 3306的旧配置，按以下步骤逐一排查：

1. 纠正配置修改位置：域模式下所有公共配置（数据源、驱动、全局部署项）仅在域控制器（主节点）的domain.xml中修改生效，从节点本地的domain.xml不会被运行时加载，如果你仅修改了从节点本地的domain.xml，配置完全不生效，必须将正确的数据源配置写到主节点的domain.xml中，且修改后重启主节点加载新配置。
2. 检查从节点到主节点的管理通道连通性：打开从节点host-slave.xml，找到<domain-controller>配置段，确认配置的主节点管理地址、管理端口（默认9990）正确，且主节点防火墙放通了从节点的管理端口访问。如果从节点无法连接主节点同步配置，会自动读取本地缓存的旧配置，旧配置默认数据源就是指向localhost 3306。
3. 清理从节点旧配置缓存：停掉从节点服务，删除从节点domain/configuration/domain.cached-remote.xml缓存文件，该文件存储了上次从主节点同步的全量配置，删除后重启从节点会强制重新拉取主节点最新配置，避免旧缓存干扰。
4. 校验profile匹配：检查主节点domain.xml中是否在多个profile（如default、full-ha等）下存在同名KeycloakDS配置，确认从节点所属server-group绑定的profile下，数据源地址确实配置为10.0.0.1，没有遗漏修改其他profile下的同名数据源。
5. 启动验证：从节点启动时明确指定使用host-slave.xml配置，启动命令为./domain.sh --host-config=host-slave.xml，启动后在日志中搜索KeycloakDS关键字，确认加载的JDBC连接地址为10.0.0.1:3306而非localhost。

注意：从节点仅需要修改本地host-slave.xml中的节点标识、域控制器地址、本地网络绑定等节点专属配置，不需要修改本地其他全局配置文件。

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