拉取Docker镜像后运行Spring Boot+Postgres应用遇连接失败错误

核心问题分析 #

拉取Docker Hub的Spring Boot镜像后单独运行时，主要遇到两类问题：容器网络无法互通、Postgres未就绪就发起连接，以下是针对性解决步骤：

1. 确保容器在同一网络互通 #

Docker默认的bridge网络中，容器无法通过名称直接访问，必须将Spring Boot和Postgres容器加入同一自定义网络：

方法1：用Docker命令手动运行 #

# 创建自定义网络
docker network create app-network

# 启动Postgres容器并加入网络
docker run --name persons-db --network app-network \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=12345 \
  -e POSTGRES_DB=persons \
  -e POSTGRES_HOST_AUTH_METHOD=trust \
  -p 5432:5432 \
  postgres

# 启动拉取的Spring Boot镜像，加入同一网络并传递正确的数据库地址
docker run --name persons-api --network app-network \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://persons-db:5432/persons \
  -e SPRING_DATASOURCE_USERNAME=postgres \
  -e SPRING_DATASOURCE_PASSWORD=12345 \
  -e SPRING_JPA_HIBERNATE_DDL_AUTO=create \
  -p 8080:8080 \
  你的DockerHub用户名/镜像名:标签

方法2：用Docker Compose管理（推荐） #

修改你的compose文件，直接拉取Docker Hub的镜像而非本地构建，同时指定自定义网络：

services:
  psql-db:
    image: postgres
    container_name: persons-db
    restart: always
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=12345
      - POSTGRES_DB=persons
      - POSTGRES_HOST_AUTH_METHOD=trust
    ports:
      - '5432:5432'
    networks:
      - app-net

  api:
    container_name: persons-api
    image: 你的DockerHub用户名/镜像名:标签  # 替换为你的Hub镜像地址
    ports:
      - '8080:8080'
    environment:
      - SPRING_DATASOURCE_URL=jdbc:postgresql://psql-db:5432/persons
      - SPRING_DATASOURCE_USERNAME=postgres
      - SPRING_DATASOURCE_PASSWORD=12345
      - SPRING_JPA_HIBERNATE_DDL_AUTO=create
    depends_on:
      - psql-db
    networks:
      - app-net

networks:
  app-net:
    driver: bridge

2. 解决Postgres未就绪导致的连接失败 #

depends_on仅保证容器启动顺序，不代表Postgres服务已完全初始化（比如数据库创建、用户配置完成）。添加健康检查确保Spring Boot在Postgres就绪后启动：

修改Docker Compose中的Postgres服务 #

psql-db:
  image: postgres
  container_name: persons-db
  restart: always
  environment:
    - POSTGRES_USER=postgres
    - POSTGRES_PASSWORD=12345
    - POSTGRES_DB=persons
    - POSTGRES_HOST_AUTH_METHOD=trust
  ports:
    - '5432:5432'
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres -d persons"]
    interval: 5s
    timeout: 5s
    retries: 5
  networks:
    - app-net

修改Spring Boot服务的依赖条件 #

api:
  # ...其他配置
  depends_on:
    psql-db:
      condition: service_healthy

3. 检查环境变量是否正确传递 #

如果直接用docker run启动镜像，务必传递所有数据库相关的环境变量，否则Spring Boot会使用默认配置（比如连接localhost:5432），导致连接失败。

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