Spring Boot连接Docker PostgreSQL密码认证失败问题求助

1. 核对配置一致性（最常见问题） #

把docker-compose.yml和application.properties里的核心配置一一对应，确保完全匹配：

• Docker侧的POSTGRES_USER必须等于Spring Boot侧的spring.datasource.username
• Docker侧的POSTGRES_PASSWORD必须等于Spring Boot侧的spring.datasource.password
• Docker侧的POSTGRES_DB必须等于Spring Boot侧spring.datasource.url里的数据库名（比如jdbc:postgresql://localhost:5432/xxx里的xxx）

注意：Docker容器启动时会一次性创建用户和数据库，之后修改docker-compose.yml里的环境变量不会生效，必须删除容器重新构建：

docker-compose down -v  # -v会删除关联的卷，确保重置数据库状态
docker-compose up -d

2. 验证Docker PostgreSQL的可访问性 #

先跳过Spring Boot，用工具手动测试连接：

• 用psql命令：

psql -h localhost -p 5432 -U 你的用户名 -d 你的数据库名

• 或者用DBeaver、Navicat等可视化工具，填入和Spring Boot相同的连接参数
  如果手动连接也失败，说明问题出在Docker PostgreSQL配置上；如果手动能连上，再排查Spring Boot侧。

3. 检查Docker网络与端口映射 #

• 确保docker-compose.yml里PostgreSQL的端口映射正确：

ports:
  - "5432:5432"  # 主机端口:容器端口，不要写错

• Spring Boot的spring.datasource.url主机部分要对应：如果是本地运行Spring Boot，用localhost；如果Spring Boot也在Docker容器里，要用PostgreSQL容器的名称作为主机名（比如jdbc:postgresql://postgres:5432/xxx，前提是两个容器在同一Docker网络）

4. 排查pg_hba.conf配置（新手易踩坑） #

官方PostgreSQL镜像默认的pg_hba.conf已经允许所有IP用md5密码连接（规则是host all all 0.0.0.0/0 md5），如果你手动修改过容器内的这个文件，可能导致认证失败：

• 进入容器查看当前配置：

docker exec -it 你的postgres容器名 bash
cat /var/lib/postgresql/data/pg_hba.conf

• 如果配置不对，可以在docker-compose.yml里挂载自定义的pg_hba.conf，或者重置容器（用docker-compose down -v重新创建）

5. 检查密码特殊字符转义 #

如果密码包含@、$、#等特殊字符，在application.properties里需要用双引号括起来，避免被解析成配置项的一部分：

spring.datasource.password="your#password$with@specialchars"

6. 核对Spring Boot依赖与驱动版本 #

确保pom.xml里的PostgreSQL驱动依赖正确，且版本和Docker里的PostgreSQL版本兼容：

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

• PostgreSQL 12+建议用驱动版本42.2.x及以上；PostgreSQL 15+建议42.5.x及以上
• 不要随便修改驱动版本，除非你确认版本兼容问题

7. 查看日志定位细节 #

• 查看Docker PostgreSQL的启动日志，确认用户和数据库是否正常创建：

docker logs 你的postgres容器名

找类似这样的日志：

database system is ready to accept connections
CREATE ROLE helpme ...
CREATE DATABASE ...

• 查看Spring Boot的错误日志，确认具体的认证失败原因（比如是否是用户名不存在、密码错误，还是连接超时）

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