Docker容器中Spring项目无法连接PostgreSQL数据库问题

核心问题分析 #

你遇到的Connection to localhost:5432 refused错误，本质是Docker容器网络环境与本地环境的差异：

• 本地运行时，localhost指向你的物理机器，PostgreSQL服务在本地端口监听，因此可以连接。
• Docker Compose环境中，每个容器都是独立的网络节点，localhost仅指向容器自身，而PostgreSQL在db容器中，所以必须用容器名/服务名作为连接地址。但即便配置了正确的地址，仍可能因PostgreSQL未完成初始化导致连接失败。

分步解决方案 #

1. 修复服务启动顺序（最关键） #

depends_on仅保证db容器先启动，但不确保PostgreSQL服务已就绪接受连接。Spring启动时会立即尝试连接，此时Postgres可能还在初始化数据库/用户，导致连接拒绝。

修改docker-compose.yml，添加健康检查与依赖条件：

services:
  db:
    image: postgres
    restart: always
    container_name: database
    environment:
      POSTGRES_DB: portfolio
      POSTGRES_USER: <数据库用户名>
      POSTGRES_PASSWORD: <数据库密码>
    ports:
      - "5432:5432"
    # 添加Postgres健康检查
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5

  back-end:
    # ... 其他配置保持不变
    depends_on:
      db:
        condition: service_healthy # 仅在db健康检查通过后启动

2. 验证连接配置一致性 #

确保application.properties与docker-compose.yml的Postgres配置完全匹配：

• spring.datasource.url必须为jdbc:postgresql://database:5432/portfolio（database是Postgres容器的container_name，在Docker Compose默认网络中可直接访问）
• spring.datasource.username和spring.datasource.password需与POSTGRES_USER、POSTGRES_PASSWORD完全一致，注意不要有多余空格或特殊字符问题。

3. 检查镜像构建正确性 #

确认Docker构建时使用了正确的配置文件：

1. 进入back-end容器验证内置配置：

docker exec -it portfolio-back cat /app/BOOT-INF/classes/application.properties

2. 如果配置错误，修改本地application.properties后重新构建镜像：

docker compose build back-end

4. 测试容器间网络连通性 #

若以上步骤无效，手动验证网络是否正常：

1. 启动db容器：docker compose up -d db
2. 用临时容器测试连接（替换<项目网络名>，可通过docker network ls查看，默认是项目目录名_default）：

docker run --rm --network <项目网络名> postgres psql -h database -U <数据库用户名> -d portfolio

如果能成功连接，说明网络无问题，问题仍出在服务启动顺序或Spring配置上。

5. 添加Spring连接重试机制 #

在application.properties中添加HikariCP重试配置，避免因Postgres初始化慢导致的连接失败：

# 数据库连接池重试配置
spring.datasource.hikari.connection-timeout=20000
spring.datasource.hikari.maximum-pool-size=5
spring.datasource.hikari.initialization-fail-timeout=0 # 无限重试直到连接成功
spring.jpa.properties.hibernate.connection.provider_disables_autocommit=true

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