Spring Boot 连接 Docker 中 MySQL 失败排查指南：从报错分类到配置修复

如果你也遇到过，项目在 IDE 里跑得好好的，打包部署后控制台忽然开始刷红色异常，从Communications link failure到Connection refused，再到Access denied for user……先别怀疑自己的代码写得有问题，这种“Spring Boot 连接 Docker 中的 MySQL 连接失败”的场景，十有八九是连接链路、网络模式、账号授权或配置细节上出了岔子。

这个标题我见过太多次，几乎每个准备把应用容器化的人都会在同一个地方栽跟头。问题本身不难，难的是你被一大堆报错信息带着跑，一会儿怀疑密码，一会儿怀疑端口，一会儿又怀疑驱动版本，结果查了一下午，其实只是一个小参数没对齐。这篇博文我打算按实际排查的顺序，把“宿主机访问容器数据库、Spring Boot 访问容器数据库、Spring Boot 容器访问 MySQL 容器”这几类场景拆开讲清楚。不管你是刚入门 Docker，还是已经部署过两三个服务，照着我这个思路过一遍，基本上都能把问题定位到某一层。

1. 先给报错分类：同样是连不上，原因可能南辕北辙

拿到连接失败异常，第一件事不是改配置，而是看报错的关键词。我见过很多人把一整屏堆栈贴到群里，但里面真正有用的信息往往在前三行。Spring Boot + MySQL 连接失败，常见的报错大致可以分成三类：“连接被拒绝”、“认证失败”、“连接中途断开”。这三类问题排查方向完全不同，混在一起谈会很乱。

1.1 Connection refused：网络层根本没打通

这类报错的典型特征是：

java.net.ConnectException: Connection refused

或者：

Can't connect to MySQL server on '127.0.0.1' (10061)

出现Connection refused，基本可以断定：你要连的那个 IP 和端口，在目标机器上没有任何服务在监听，或者请求根本没到目标机器。常见原因包括几种情况：MySQL 容器没起来；容器起来了但端口没映射到宿主机；Spring Boot 配置的 IP 写错了；防火墙拦截了端口。

一个极易踩的坑是：MySQL 容器明明在运行，但docker run的时候忘了加-p 3306:3306，或者只写了-P随意映射。这时候容器内部 MySQL 是正常的，可你在宿主机上用127.0.0.1:3306去连，服务根本不在宿主机端口上监听，自然就Connection refused。

快速定位方式：

docker ps | grep mysql docker port 容器名

如果docker port输出为空，说明没有端口映射，或者映射方式和你预期不一样。这跟 Spring Boot 关系不大，先修容器再调代码。

1.2 Access denied：账号没毛病，但权限作用域不对

另一类很典型的报错：

Access denied for user 'root'@'172.17.0.1' (using password: YES)

注意报错里的@后面跟着谁。如果root@localhost能连，root@172.17.0.1被拒绝，说明 MySQL 用户表里没有允许这个来源 IP 登录。Docker 容器环境下，应用所在机器的 IP、容器网关 IP，和 MySQL 初始化时默认的localhost经常对不上。MySQL 用户授权不仅看用户名，还要看来源 host。

所以遇到 Access denied，先不要怀疑密码写错，进 MySQL 容器里看一眼：

docker exec -it 容器名 mysql -uroot -p

然后再查：

SELECT user, host FROM mysql.user;

如果root对应的 host 只有localhost，那你从其他 IP 连接当然被拒。需要授权时，可以创建专门用户或修改 host。另一个隐藏点：MySQL 8 默认认证插件是caching_sha2_password，如果驱动版本太旧，会在认证阶段报Public Key Retrieval is not allowed之类的错误，这个问题后面驱动部分细说。

1.3 Communications link failure：链路建立到一半断了

第三种报错模糊很多，常见为：

Communications link failure The last packet sent successfully to the server was 0 milliseconds ago.

这种异常可以发生在 TCP 连接建立之前、建立过程中，或者空闲连接被服务端断开之后。对应的问题包括：JDBC URL 里的serverTimezone缺失导致握手失败；MySQL 的wait_timeout把空闲连接关了；网络质量差；防火墙把长连接重置了；还有连接池里的“死连接”被继续使用。

遇到这类问题，别先改大连接池参数，先把 URL 里的参数加全：

jdbc:mysql://127.0.0.1:3306/testdb?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true

useSSL=false是为了避免 SSL 握手拖慢连接，本地开发一般不需要加密；serverTimezone不配置的话，在新版驱动里经常直接报时区错误；allowPublicKeyRetrieval=true是为了配合 MySQL 8 的caching_sha2_password认证流程。这三个参数几乎是我见过的连接失败高频原因。

2. 容器侧排查清单：数据库没“通”，Spring Boot 再对也不行

很多人在 Spring Boot 的配置上反复折腾，最后发现数据库容器本身状态就不对。这里的顺序一定要记住：先确认 MySQL 能正常接受连接，再谈 Spring Boot 连接串。

2.1 容器是否真的在正常运行

先看状态，别凭感觉。用：

docker ps -a

docker ps只能看到正在运行的容器，docker ps -a才能看到已经退出的。如果 MySQL 容器状态是Exited，后面所有操作都是白搭。

为什么 MySQL 容器会起不来？常见原因之一是环境变量没传对。比如有人创建 MySQL 容器只写了端口映射，没传MYSQL_ROOT_PASSWORD，MySQL 官方镜像初始化时根本不知道密码该怎么设置，导致容器反复重启。还有挂载数据目录时宿主机目录权限不对，容器内mysqld无法写入，也会启动失败。

确认容器在运行之后，还要看日志：

docker logs --tail 100 容器名

日志里如果有ERROR、Aborting之类的关键字，按日志内容去搜，比瞎改配置有效得多。我遇到过问题出在曾经创建过同名容器，老容器占用了数据卷和数据目录，新容器启动后密码初始化用的还是旧数据，导致 Spring Boot 里配置的密码和数据卷里实际密码对不上。

2.2 端口映射：启动参数里的-p是连接成功的第一步

如果容器状态没问题，接着排查端口。Docker 的端口映射语法是：

-p 宿主机端口:容器端口

启动 MySQL 时常用：

docker run -d --name mysql \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=123456 \ mysql:8.0

但很多人漏了两个细节。

第一，如果宿主机 3306 已经被本机安装的 MySQL 占用了，那 Docker 的 3306 是映射不上去的。这时候要么改宿主机端口，比如-p 3307:3306，Spring Boot 的 URL 跟着改成3307；要么先把宿主机自带的 MySQL 服务停掉。

第二，MySQL 容器内的 mysqld 可能监听了127.0.0.1而不是0.0.0.0。这种一般出现在你手动指定--bind-address的时候。如果 bind-address 只绑定了容器的回环地址，即使端口映射做了，宿主机也访问不到。所以容器启动参数或 MySQL 配置文件里，最好保证监听地址是0.0.0.0或至少是容器内的实际网卡地址。

检查端口映射是否生效：

docker port 容器名 netstat -an | grep 3306 ss -lntp | grep 3306

2.3 MySQL 初始化环境变量与授权

用官方镜像跑 MySQL，环境变量基本决定了初始库和账号。常用的有：

MYSQL_ROOT_PASSWORD MYSQL_DATABASE MYSQL_USER MYSQL_PASSWORD

新手特别容易踩的坑：设置了MYSQL_USER和MYSQL_PASSWORD，但 Spring Boot 配置里用的却是 root 账号，而且MYSQL_ROOT_PASSWORD设的是一个值，之后手动改 root 密码没改对。还有一种情况：用docker exec进容器修改了 MySQL 的 root 密码，但没执行FLUSH PRIVILEGES，新连接还是提示密码错误，旧密码反而能进去。

容器创建之后，环境变量不是随便改改就能生效的。如果你需要改密码、加用户、调参数，优先进容器里用 SQL 操作，或者重建容器。重建容器时要注意，如果挂了数据卷，旧数据仍会保留，新的环境变量不会覆盖已初始化的数据库用户。

2.4 别忽略防火墙和 SELinux

这个问题在个人电脑上不明显，在云服务器上特别典型。很多人本地的 Docker MySQL 连得好好的，搬到云端后 Spring Boot 连不上，一查云厂商安全组没放行 3306。Docker 端口映射只是把端口暴露到宿主机，外部能不能访问还要看系统防火墙、安全组策略。

Linux 下检查防火墙状态：

sudo ufw status sudo firewall-cmd --list-all

如果开启了防火墙，要么放行端口，要么先临时关闭验证。这个问题不是 Docker 配置问题，但经常跟 Docker MySQL 连接失败混在一起，排查成本很高。我的习惯是：看到连接失败，先主动问一句“这台机器的防火墙规则最近动过没有”，很多时候一下子就省掉半小时。

3. Spring Boot 侧配置：把连接参数调到“能落地”的状态

容器没问题了，接着就应该怀疑 Spring Boot 自身的配置。这里的坑比容器侧还多，因为配置项分散在application.yml、Maven 依赖、连接池参数里，任何一个不匹配都会报连接失败。

3.1 jdbcUrl：localhost、127.0.0.1 和容器名不是一回事

Spring Boot 的数据源配置核心是jdbc-url。常见的错误配置是：

spring: datasource: url: jdbc:mysql://localhost:3306/testdb

这句配置在“应用在宿主机、MySQL 容器也在宿主机且映射了端口”时是可以的，因为localhost指向宿主机本身，Docker 的端口映射正好在宿主机上。

但如果 Spring Boot 应用本身也跑在 Docker 容器里，这个localhost指向的是应用容器自己，容器里根本没有 MySQL，肯定连不上。所以必须搞清楚：你的 Spring Boot 进程到底在哪运行。

典型的几种正确姿势：

• 应用在宿主机 JVM 跑，MySQL 容器映射了 3306：jdbc:mysql://127.0.0.1:3306/testdb
• 应用在容器 A，MySQL 容器 B，两个容器在同一 Docker 网络：jdbc:mysql://容器B的名称:3306/testdb
• 应用在容器 A，MySQL 容器 B，但不在同一网络：jdbc:mysql://宿主机IP:3306/testdb或借助host.docker.internal

我见过太多人把“localhost”当万能钥匙，结果项目一旦容器化就直接翻车。为了让自己少纠结，建议在配置注释里写清楚这个 IP 对应的是宿主机、数据库容器名还是本机回环地址。

3.2 驱动依赖版本：Spring Boot 2.x 和 3.x 差得远

MySQL 连接失败还有一种隐蔽原因：驱动依赖没加对。Spring Boot 2.x 时代常用的是：

<dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <scope>runtime</scope> </dependency>

Spring Boot 3.x 之后，官方驱动坐标换了：

<dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency>

如果你用的 Spring Boot 3.x 还在配旧的mysql:mysql-connector-java，可能因为依赖管理里已经不再管理这个坐标，导致版本冲突或驱动类加载异常。轻则报ClassNotFoundException，重则在连接握手阶段和 MySQL 8 的认证插件不兼容。

还要注意驱动版本和 MySQL 版本的匹配。MySQL 8.0 对应的驱动可以用 8.0.x，如果你还在用 5.1.x 的老驱动，连接 MySQL 8 时会遇到各种怪问题，比如握手协议错误、时间戳不对、字符集乱码。

3.3 账号密码特殊字符：配置里的小坑，连接时的另一个坑

很多开发者图省事，直接在application.yml里写：

spring: datasource: username: root password: 123456

开发环境没问题，但一旦密码里带@、&、:这些特殊字符，就很容易出问题。比如密码是P@ssw0rd，在 JDBC URL 里出现时，@会被解析成主机名的一部分；在 YAML 里尾部带:也可能被解析成结构。

更稳妥的做法是通过环境变量注入：

spring: datasource: username: ${DB_USERNAME} password: ${DB_PASSWORD}

启动容器时再用-e DB_USERNAME=root -e DB_PASSWORD=...传进去。这样既避免特殊字符被配置文件解析，也能防止密码不小心提交到仓库。

还有一个容易忽略的账号问题：MySQL 里root账号默认 host 可能是localhost。从宿主机 IP 访问会报 Access denied，需要单独授权。建议不要过度依赖 root，而是创建专用账号：

CREATE USER 'app'@'%' IDENTIFIED BY 'app_password'; GRANT ALL PRIVILEGES ON testdb.* TO 'app'@'%'; FLUSH PRIVILEGES;

'app'@'%'表示允许任意来源主机用该账号登录。注意在云环境里，%权限范围比较大，生产环境建议限定具体网段或 IP。

3.4 连接池参数：启动失败和运行中断由不同参数决定

Spring Boot 默认用的是 HikariCP，它非常快，但参数没配对也会带来困惑。

• initialization-fail-timeout：默认是 1，表示连接池初始化时只要连不上数据库，应用启动会直接失败。有些人觉得启动失败很痛苦，把它设成负数，结果应用起来了，但接口一访问就报找不到数据库连接，问题反而更难定位。
• connection-timeout：默认 30000 毫秒，如果网络不通，日志会卡在这里很久。
• maximum-pool-size：默认 10，一般够用。如果数据库连接数不够，错误可能是连接获取超时，而不是连接被拒绝。
• max-lifetime：如果比 MySQL 的wait_timeout长，空闲连接可能被数据库服务端断开，下次请求时 HikariCP 如果有“死连接”就会抛异常。

一套适合本地验证的配置：

spring: datasource: hikari: connection-timeout: 30000 initialization-fail-timeout: 10000 maximum-pool-size: 5 max-lifetime: 1800000

initialization-fail-timeout设成 10000 的意思是：启动时最多等 10 秒，连不上就快速失败，避免日志无限重试。这个行为对比默认能省很多排查时间。

4. 网络模型再深挖：宿主机连接、容器内连接、容器间连接

到了这一步，如果你还是连不上，那就得冷静分析 Docker 的网络模型了。很多人没弄明白“宿主机看到的 localhost”“容器看到的 localhost”根本不是一个东西，连接失败自然在所难免。

4.1 bridge 网络下的数据走向

默认情况下，Docker 用 bridge 网络。MySQL 容器在 bridge 网络里有一个内部 IP，通常是172.17.0.x，这个 IP 只有 Docker 内部网络能直接访问。你在宿主机执行docker inspect mysql能看到这个 IP，但直接拿它去连接并不总可靠，因为容器重建后 IP 会变。

当你使用-p 3306:3306时，Docker 会在宿主机上开一个端口，把宿主机收到的流量转发到容器的 3306 端口。所以宿主机上的应用只要连127.0.0.1:3306就行，不需要知道容器的内部 IP。

但如果你在另一个容器里访问 MySQL，逻辑就不一样了。这个容器有自己的网络命名空间，访问localhost只会到达它自己。此时应该走“容器名即主机名”的 Docker 内置 DNS，只要两个容器在同一用户自定义网络里，mysql这个名字就能被解析成 MySQL 容器的 IP。

4.2 三个关键词：localhost、127.0.0.1、host.docker.internal

localhost是一个语义性的主机名，通常解析到本机；127.0.0.1是回环地址；host.docker.internal是 Docker Desktop 提供的一个特殊域名，用于从容器内部访问宿主机。

在 Linux 上原生安装 Docker 时，没有默认的host.docker.internal。如果想让容器里的应用访问宿主机，可以在运行容器时手动加上：

docker run -d --add-host=host.docker.internal:host-gateway my-spring-app

加了这个参数，容器内应用里写jdbc:mysql://host.docker.internal:3306/testdb就会转发到宿主机的 3306。前提是宿主机能访问 MySQL 容器，也就是端口映射已经存在。

用host-gateway关键字的好处是，Docker 会自动把它替换成宿主机的网关 IP，省去手写具体 IP 的麻烦。

4.3 容器间应用访问 MySQL：两种推荐姿势

如果你的 Spring Boot 也容器化了，最优解是让两个容器加入同一个自定义网络，然后用容器名访问。这样配置最稳定，不依赖宿主机 IP，也不会因为重启导致 IP 变化。

创建网络并启动容器：

docker network create app-network

启动 MySQL：

docker run -d --name mysql \ --network app-network \ -e MYSQL_ROOT_PASSWORD=123456 \ -e MYSQL_DATABASE=testdb \ mysql:8.0

启动 Spring Boot 容器：

docker run -d --name app \ --network app-network \ -p 8080:8080 \ -e DB_HOST=mysql \ my-spring-app:latest

Spring Boot 配置里：

spring: datasource: url: jdbc:mysql://${DB_HOST:localhost}:3306/testdb?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true

这样应用容器里访问mysql:3306，Docker 内置 DNS 会自动解析到 MySQL 容器。再也不用关心 IP 到底是 172.17.0.2 还是 172.18.0.3。

另一类场景是 MySQL 容器没有加入自定义网络，仍在默认 bridge。那 Spring Boot 容器访问它时，最好用宿主机 IP 加映射端口，也就是从容器访问宿主机上暴露出来的端口。这时 MySQL 容器必须映射端口，且防火墙要放行。

4.4 为什么硬编码容器 IP 不可取

有些人用docker inspect mysql拿到一个 IP，比如172.17.0.2，填到 Spring Boot 里，当场能通，于是觉得很爽。但容器一旦重启、重建或者 Docker 网络重新分配，这个 IP 就可能变成别的值。到时候应用还是连不上，你根本不会去怀疑这个“看起来很具体”的 IP 可能已经失效。

我见过最经典的翻车现场：某次服务器重启，Docker 自动把旧容器重新拉起，IP 顺序变了，应用日志开始报连接失败，运维查了几个小时没头绪，最后发现配置文件里写死了一个早已不存在的容器 IP。所以只要涉及容器间通信，统一用容器名、服务名或者域名，不要用具体 IP。

5. 完整排查流程与踩坑记录

前四节是按知识模块讲的，但这节我按照真正动手排查时的顺序重新梳理一遍，你可以把每一步当成 checklist。

5.1 十分钟排查顺序

第一步，执行docker ps -a，确认 MySQL 容器是不是Up状态。如果状态是Exited或者反复重启，先看docker logs，解决容器本身问题。

第二步，执行docker port mysql 3306，确认端口映射存在。如果输出为空，说明你可能忘了-p，重建容器时要加上。

第三步，在宿主机上直接用 mysql 客户端测试连接：

mysql -h 127.0.0.1 -P 3306 -u root -p

如果能连上，说明数据库和端口都没有问题；如果连不上，问题基本在容器配置或 MySQL 用户权限上，先不用看 Spring Boot。

第四步，查看 MySQL 用户表：

SELECT user, host FROM mysql.user;

对照 Spring Boot 里的用户名和来源 IP，确认是否存在没有对应 host 授权的用户。

第五步，检查 Spring Boot 配置。看jdbc-url的 IP 是否匹配实际运行环境：应用在宿主机，就是宿主机端口；应用在容器里，优先使用容器名或网络别名。

第六步，检查依赖。确认驱动 artifact 和 Spring Boot 版本匹配，以及 MySQL 服务器版本与驱动版本之间没有不兼容问题。

第七步，看看连接池日志。如果应用起来但运行一段时间后连接失败，把max-lifetime调成小于 MySQLwait_timeout，避免死连接。

5.2 配置速查表

下表是我根据常见场景整理出来的配置参考，方便直接对照抄作业：

运行场景	推荐 jdbc-url	网络与账号注意点
Spring Boot 在宿主机 JVM，MySQL 在容器	jdbc:mysql://127.0.0.1:3306/testdb	必须配置-p 3306:3306
Spring Boot 在容器 A，MySQL 在容器 B，同网络	jdbc:mysql://mysql:3306/testdb	两个容器加入同一个docker network
Spring Boot 在容器，想访问宿主机上的 MySQL	jdbc:mysql://host.docker.internal:3306/testdb	Linux 需要--add-host=host.docker.internal:host-gateway
远程部署，数据库端口未开放	检查防火墙和安全组	不要只检查 Docker，还要看外部网络策略

另外，不管哪种场景，URL 后段推荐带上：

?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true

这个组合能规避一大半 MySQL 8 连接过程中的怪问题。

5.3 三个亲历踩坑记录

第一个坑是端口映射忘加。某次我在服务器上平滑迁移，把 MySQL 容器重新跑起来，没注意到新命令里漏了-p。应用日志一直报Connection refused，我以为是新网络环境问题，反复修改 Spring Boot 配置。直到执行docker port才发现根本没有映射，前后浪费了四十多分钟。后来我把docker port检查固定成了第一反应。

第二个坑是时区问题。当时应用在容器里，数据库也在容器里，网络通了、账号也没问题，但应用启动时抛了异常，原因指向serverTimezone。原因是 MySQL 驱动在解析日期类型时发现客户端和服务器时区不一致，不确定用什么时区。那个报错信息出现在异常堆栈最底部，不仔细看很容易忽略。后来我把时区参数固定下来，问题再没出现。

第三个坑是旧数据卷残留。我为了修改 root 密码，重建了 MySQL 容器，但忘了之前挂载了宿主机目录./mysql-data:/var/lib/mysql。新容器起来后用新密码连，怎么连都报 Access denied。因为旧数据卷里保存的还是旧密码认证信息，环境变量只在初始化时生效，不会自动覆盖已有用户。最后我删除旧数据卷重新初始化，恢复干净状态才解决。

5.4 一个小习惯，能帮你少踩一半的坑

我个人在实际操作中养成了一个习惯：只要遇到 Spring Boot 连不上 MySQL，都会先在宿主机上手工输入同样的 JDBC 参数，用mysql命令行客户端试一次。如果命令行能连上，说明数据库层没问题，回去查 Spring Boot 配置、驱动和连接池；如果命令行也连不上，那就是网络、端口或权限问题，按容器侧和授权顺序排查。

别小看这个操作，它能把“应用代码问题”和“环境网络问题”快速切开。很多人一头扎进连接池参数、事务配置里改来改去，却始终没验证最基础的 TCP 链路有没有通。一次命令行测试，往往比盯着半屏堆栈猜原因高效得多。下次再遇到连接失败，不妨先试试这个笨办法。