Docker部署Keycloak无法连接宿主机本地MariaDB问题排查求助

1. 自定义Docker网络未配置宿主机地址解析 #

• 原因：host.docker.internal是Docker为默认桥接网络提供的内置域名，你自行创建的staticNet自定义静态网络默认不会自动解析这个域名，导致容器无法找到宿主机地址。
• 修复方案：在原有docker run命令中新增参数--add-host=host.docker.internal:host-gateway，修改后的完整启动命令如下：

docker run -d --name keycloak -p 8443:8443 \
-v /opt/keycloak/certs:/etc/x509/https \
--net staticNet --ip 172.18.0.10 \
--add-host=host.docker.internal:host-gateway \
-e KEYCLOAK_USER=admin \
-e KEYCLOAK_PASSWORD='password' \
-e DB_VENDOR=mariadb \
-e DB_ADDR=host.docker.internal \
-e DB_DATABASE=keycloak \
-e DB_USERNAME=keycloak \
-e DB_PASSWORD='dbUserPassword' \
jboss/keycloak

2. MariaDB服务未配置远程访问权限 #

• 原因：默认MariaDB只监听127.0.0.1本地回环地址，且数据库用户默认只允许本地登录，会拒绝来自Docker容器网段的访问请求。
• 修复步骤：
  • 修改MariaDB配置文件（通常路径为/etc/mysql/mariadb.conf.d/50-server.cnf），将bind-address参数从127.0.0.1改为0.0.0.0，修改完成后重启MariaDB服务。
  • 登录MariaDB执行授权命令，允许keycloak用户从Docker子网访问数据库：

  GRANT ALL PRIVILEGES ON keycloak.* TO 'keycloak'@'172.18.0.%' IDENTIFIED BY 'dbUserPassword';
  FLUSH PRIVILEGES;
  

3. 宿主机防火墙拦截数据库端口访问 #

• 原因：宿主机的防火墙默认可能未开放3306端口，或者拒绝172.18.0.0/16网段的访问请求。
• 修复方案：根据你使用的防火墙工具开放对应规则，以ufw为例，执行命令：ufw allow in from 172.18.0.0/16 to any port 3306。

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