Docker环境下Spring Boot应用无法连接PostgreSQL问题排查

核心问题 #

从异常java.net.UnknownHostException: db及现象来看，核心原因有两个：

1. 数据库服务未就绪：Docker Compose的depends_on仅保证容器启动顺序，不确保PostgreSQL服务完全就绪可接受连接。当Spring Boot应用启动并执行ddl-auto=create时，数据库还未完成初始化，导致连接失败；改为none时，Hibernate不会在启动阶段立即执行DDL，避开了初始化时的连接校验。
2. 密码配置不匹配：PostgreSQL容器通过POSTGRES_PASSWORD_FILE读取密码，但Spring Boot应用的配置中使用默认密码db-wrz2z，与数据库实际密码不一致，后续即使主机解析正常，也会出现认证失败。

分步解决方案 #

1. 为PostgreSQL添加健康检查，确保服务就绪后启动应用 #

修改docker-compose.yml，给db服务添加健康检查，让backend仅在数据库真正可用后启动：

services:
  backend:
    build: .
    ports:
      - 8080:8080
    environment:
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password  # 让应用读取密码文件
    networks:
      - spring-postgres
    depends_on:
      db:
        condition: service_healthy  # 依赖db的健康状态
  db:
    image: postgres
    restart: always
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - spring-postgres
    environment:
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    expose:
      - 5432
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d example"]
      interval: 5s
      timeout: 5s
      retries: 5
  # pgadmin配置保持不变
volumes:
  db-data:
  pgadmin4:
secrets:
  db-password:
    file: db/password.txt
networks:
  spring-postgres:

2. 修正Spring Boot数据源配置 #

更新application.properties，让应用正确读取密码文件，并添加连接重试机制：

spring.jpa.properties.hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect
spring.jpa.hibernate.ddl-auto=create
spring.jpa.hibernate.show-sql=true

spring.datasource.url=jdbc:postgresql://db:5432/${POSTGRES_DB}
spring.datasource.username=postgres
# 从密码文件读取密码， fallback到默认值
spring.datasource.password=${file:/run/secrets/db-password:db-wrz2z}
# Hikari连接池重试配置
spring.datasource.hikari.connection-timeout=20000
spring.datasource.hikari.maximum-pool-size=5
spring.datasource.hikari.connection-test-query=SELECT 1
spring.datasource.hikari.validation-timeout=3000
# 延迟数据源初始化到应用启动后（Spring Boot 2.5+支持）
spring.jpa.defer-datasource-initialization=true

3. 验证操作 #

修改后重新启动容器：

docker-compose down -v
docker-compose up --build

此时应用应能正常连接数据库并执行DDL创建表结构。

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