docker-compose start后Spring Boot后端无法连接PostgreSQL数据库

问题现象 #

• 首次执行docker-compose up时，后端（shop容器）可正常连接PostgreSQL（postgresdb容器）
• 执行docker-compose stop后立即执行docker-compose start，后端无法连接数据库，但数据库容器本身运行正常
• 已验证数据库无异常，且shop容器依赖postgresdb容器，单独重启shop容器后问题依旧

附配置文件与报错日志 #

docker-compose.yml #

# 实际配置示例
version: '3.8'
services:
  postgresdb:
    image: postgres:14-alpine
    container_name: postgresdb
    environment:
      POSTGRES_USER: shop_user
      POSTGRES_PASSWORD: shop_pass
      POSTGRES_DB: shop_db
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    restart: unless-stopped

  shop:
    build: ./shop
    container_name: shop
    environment:
      SPRING_PROFILES_ACTIVE: prod
    depends_on:
      - postgresdb
    ports:
      - "8080:8080"
    restart: unless-stopped

volumes:
  postgres-data:

application-prod.properties #

# 实际配置示例
spring.datasource.url=jdbc:postgresql://postgresdb:5432/shop_db
spring.datasource.username=shop_user
spring.datasource.password=shop_pass
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

报错日志 #

org.postgresql.util.PSQLException: Connection to postgresdb:5432 refused. Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections.
    at org.postgresql.core.v3.ConnectionFactoryImpl.openConnectionImpl(ConnectionFactoryImpl.java:319) ~[postgresql-42.5.1.jar!/:42.5.1]
    ...
Caused by: java.net.ConnectException: Connection refused (Connection refused)
    at java.base/java.net.PlainSocketImpl.socketConnect(Native Method) ~[na:na]
    ...

可能原因与解决方案 #

1. 连接池持有失效连接未刷新 #

后端连接池（如HikariCP）在容器停止前可能持有已断开的数据库连接，重启后未自动检测连接有效性，导致使用失效连接。

解决：配置连接池有效性检测
在application-prod.properties中添加连接池验证参数（以HikariCP为例）：

# 连接测试查询
spring.datasource.hikari.connection-test-query=SELECT 1
# 验证超时时间（毫秒）
spring.datasource.hikari.validation-timeout=5000
# 空闲连接超时时间（毫秒），超时后自动回收
spring.datasource.hikari.idle-timeout=30000
# 最大生命周期（毫秒），强制刷新旧连接
spring.datasource.hikari.max-lifetime=1800000

2. Docker网络关联异常 #

docker-compose start仅启动现有容器，可能出现容器网络未正确关联的情况，导致shop容器无法解析postgresdb的域名。

解决：检查并重建网络

• 查看当前网络状态：

  docker network inspect $(basename $(pwd))_default
  

  （默认网络名为当前目录名加_default）
• 若网络异常，停止所有容器后删除网络再重建：

  docker-compose stop
  docker network rm $(basename $(pwd))_default
  docker-compose up -d
  

3. PostgreSQL连接数耗尽 #

首次启动时建立的连接未正常释放，导致重启后连接数达到上限，拒绝新连接。

解决：检查并调整连接数

• 进入postgres容器查看当前连接数：

  docker exec -it postgresdb psql -U shop_user -d shop_db -c "SELECT count(*) FROM pg_stat_activity;"
  

• 调整PostgreSQL最大连接数，在docker-compose.yml的postgresdb服务中添加环境变量：

  environment:
    POSTGRES_MAX_CONNECTIONS: 150
  

  （根据实际业务调整数值）

4. 后端未等待数据库完全就绪 #

docker-compose start启动容器时，shop容器可能在PostgreSQL完全初始化前就启动，导致连接失败。

解决：添加启动等待逻辑
在shop容器中使用pg_isready命令等待数据库就绪后再启动应用：
修改docker-compose.yml中shop服务的command：

command: sh -c "until pg_isready -h postgresdb -p 5432 -U shop_user; do sleep 2; done; java -jar shop-app.jar"

（需要确保shop镜像中已安装postgresql-client，若未安装，可在Dockerfile中添加RUN apk add --no-cache postgresql-client（Alpine镜像）或RUN apt-get update && apt-get install -y postgresql-client（Debian/Ubuntu镜像））

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