Spring Boot应用无法连接PostgreSQL数据库问题排查

云原生阿岚

2026-6-20

问题

Spring Boot项目配置PostgreSQL数据库时，启动Tomcat服务器出现异常，无法创建仓库Bean，核心报错如下：

Caused by: jakarta.persistence.PersistenceException: [PersistenceUnit: default] Unable to build Hibernate SessionFactory; nested exception is org.hibernate.exception.GenericJDBCException: Unable to open JDBC Connection for DDL execution [FATAL: password authentication failed for user "dev-user"] [n/a]
    at org.springframework.orm.jpa.AbstractEntityManagerFactoryBean.buildNativeEntityManagerFactory(AbstractEntityManagerFactoryBean.java:421) ~[spring-orm-6.1.11.jar:6.1.11]
    at org.springframework.orm.jpa.AbstractEntityManagerFactoryBean.afterPropertiesSet(AbstractEntityManagerFactoryBean.java:396) ~[spring-orm-6.1.11.jar:6.1.11]
    at org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean.afterPropertiesSet(LocalContainerEntityManagerFactoryBean.java:366) ~[spring-orm-6.1.11.jar:6.1.11]
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.invokeInitMethods(AbstractAutowireCapableBeanFactory.java:1853) ~[spring-beans-6.1.11.jar:6.1.11]
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.initializeBean(AbstractAutowireCapableBeanFactory.java:1802) ~[spring-beans-6.1.11.jar:6.1.11]
    ... 101 common frames omitted

项目配置文件（application.yml）：

spring:
 datasource:
   url: jdbc:postgresql://localhost:5432/authentication_db
   username: dev-user
   password: password
   driver-class-name: org.postgresql.Driver
 jpa:
   hibernate:
     ddl-auto: update
   show-sql: false
   properties:
     hibernate:
       format_sql: true
   database: postgresql
   database-platform: org.hibernate.dialect.PostgreSQLDialect

Docker Compose配置（docker-compose.yml）：

services:
 postgres:
   container_name: postgres-sql-pa
   image: postgres
   environment:
     POSTGRES_USER: dev-user
     POSTGRES_PASSWORD: password
     PGDATA: /var/lib/postgresql/data
     POSTGRES_DB: authentication_db
   volumes:
     - postgres:/data/postgres
   ports:
     - 5432:5432
   networks:
     - spring-demo
   restart: unless-stopped

Docker容器运行正常，已确认数据库名、用户名、密码配置一致，但仍出现密码认证失败异常，求原因及解决办法。

排查与解决方法

看起来配置一致但出现认证失败，大概率是以下几个隐藏问题导致，逐一排查：

Docker卷缓存旧数据：
你配置了postgres:/data/postgres的卷映射，如果之前启动过容器且用过不同的用户名/密码，卷内会保留旧的PostgreSQL用户配置，新容器启动时会复用旧数据而非重新初始化。解决步骤：
1. 停止并删除容器：docker-compose down
2. 查看并删除对应卷：先用docker volume ls找到postgres相关卷，再执行docker volume rm <卷名>
3. 重新启动容器：docker-compose up -d
网络连通性验证：
虽然端口映射到5432，但Spring Boot可能没正确连接到容器内的数据库。用本地PostgreSQL客户端测试连接：
```
psql -h localhost -p 5432 -U dev-user -d authentication_db
```
如果连接失败，检查容器是否真的监听5432端口，或者本地防火墙是否拦截了连接。
配置文件加载优先级冲突：
Spring Boot会加载多份配置（比如application-dev.yml、系统环境变量、命令行参数），可能存在高优先级配置覆盖了你当前application.yml的密码。启动时加--debug参数，查看Spring Boot实际加载的数据源配置，确认用户名和密码是否匹配。
YAML格式错误：
检查application.yml的缩进是否用空格而非制表符，YAML对格式要求严格，缩进错误可能导致配置未被正确读取。

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