Spring Boot无法连接本地Docker部署的MariaDB，SQL客户端可正常连接

问题场景 #

本地Docker运行的MariaDB，SQL客户端使用相同凭据可正常连接，但Spring Boot启动时无法建立数据库连接。

常见错误表现 #

• 连接超时（Connection timeout）
• 连接被拒绝（Connection refused）
• 无法从连接池获取可用连接

应用配置（参考截图） #

通常包含以下核心配置：

# JDBC配置
spring.datasource.url=jdbc:mariadb://localhost:3306/your_database
spring.datasource.username=root
spring.datasource.password=your_password
spring.datasource.driver-class-name=org.mariadb.jdbc.Driver

# R2DBC配置（若使用）
spring.r2dbc.url=r2dbc:mariadb://localhost:3306/your_database
spring.r2dbc.username=root
spring.r2dbc.password=your_password

依赖配置 #

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.mariadb.jdbc</groupId>
        <artifactId>mariadb-java-client</artifactId>
    </dependency>
    <dependency>
        <groupId>org.mariadb</groupId>
        <artifactId>r2dbc-mariadb</artifactId>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>mariadb</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

排查与解决步骤 #

1. 核对Docker端口映射 #

执行docker ps查看MariaDB容器的端口映射，确认宿主机端口（如3306）已正确映射到容器的3306端口（格式应为0.0.0.0:3306->3306/tcp）。若映射了其他端口，需同步修改Spring配置中的端口号。

2. 修正数据库连接地址 #

• MacOS/Linux环境下，localhost可能无法穿透到Docker宿主机，将连接地址替换为host.docker.internal：
  • JDBC URL：jdbc:mariadb://host.docker.internal:3306/your_database
  • R2DBC URL：r2dbc:mariadb://host.docker.internal:3306/your_database

3. 检查MariaDB绑定地址 #

进入容器查看配置文件（通常为/etc/mariadb/mariadb.conf.d/50-server.cnf），确认bind-address设置为0.0.0.0（允许所有IP访问），而非127.0.0.1（仅容器内部访问）。修改后执行docker restart <容器ID>重启服务。

4. 验证数据库用户权限 #

登录MariaDB执行以下命令，确认用户允许从宿主机IP访问：

SELECT host, user FROM mysql.user WHERE user = 'root';

若host为localhost或127.0.0.1，执行授权语句开放权限：

GRANT ALL PRIVILEGES ON your_database.* TO 'root'@'%' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;

5. 排查防火墙限制 #

临时关闭宿主机防火墙测试：

• Linux：systemctl stop firewalld
• MacOS：系统设置-网络-防火墙-关闭
  若关闭后可连接，需在防火墙上添加3306端口的入站规则。

6. 避免JDBC与R2DBC配置冲突 #

若仅使用其中一种连接方式，删除多余的配置项，避免Spring Boot加载无效连接池导致冲突。

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