SpringBoot连接Docker部署的PostgreSQL失败求助

从基础配置入手，一步步缩小问题范围：

1. 确认PostgreSQL容器的端口映射是否正确 #

运行docker ps查看容器的PORTS列，必须显示类似0.0.0.0:5432->5432/tcp的映射——这代表宿主机的5432端口已关联到容器内部的5432端口。如果没有这个映射，SpringBoot无法访问容器内的数据库。

• 若之前启动容器未加端口映射，重新启动时补充参数：docker run -p 5432:5432 -e POSTGRES_PASSWORD=password postgres
• 先手动测试连接：执行psql -h localhost -U postgres并输入密码password，如果能成功连接，说明容器本身无问题，问题出在SpringBoot配置或依赖上。

2. 核对SpringBoot的application.properties配置 #

重点检查以下核心配置项，避免拼写错误：

spring.datasource.url=jdbc:postgresql://localhost:5432/postgres
spring.datasource.username=postgres
spring.datasource.password=password
spring.datasource.driver-class-name=org.postgresql.Driver

• 若SpringBoot和容器不在同一台机器，需将url中的localhost替换为容器所在宿主机的IP地址
• 若启动容器时通过POSTGRES_DB环境变量指定了自定义数据库名，要同步修改url中的数据库名称

3. 检查pom.xml的PostgreSQL依赖 #

确保依赖配置正确，SpringBoot项目中推荐使用如下配置：

<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

• 无需手动指定版本（SpringBoot父依赖会自动匹配兼容的驱动版本），若手动指定版本，需保证与容器内PostgreSQL版本对应（比如容器用postgres:15，驱动版本不要过于老旧）

4. 排查Docker网络问题（若SpringBoot也运行在Docker中） #

如果你的SpringBoot也部署在Docker容器内，不能用localhost访问PostgreSQL——需确保两个容器在同一网络下，通过容器名或内部IP连接：

• 启动PostgreSQL容器时指定名称：docker run --name my-postgres -p 5432:5432 -e POSTGRES_PASSWORD=password postgres
• 将SpringBoot的数据库url修改为jdbc:postgresql://my-postgres:5432/postgres（默认桥接网络下，容器名可直接被解析）

5. 通过容器日志确认数据库状态 #

运行docker logs <你的容器ID或名称>，查找是否有database system is ready to accept connections的日志，确认数据库已完全启动且无初始化错误。如果日志中出现密码错误、权限不足等提示，直接对应调整即可。

关于Docker Compose #

它不是必须的，只是能将容器的启动参数、网络配置写成配置文件，实现一键启动，简化管理流程。当前问题无需依赖Compose即可解决，后续若觉得手动启动容器繁琐，再考虑使用也可。

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