本地Spring Boot连接Docker容器中PostgreSQL失败求助

1. 确保Docker-Compose端口映射正确 #

你的docker-compose.yaml必须将PostgreSQL容器的5432端口映射到宿主机端口，否则本地Spring Boot应用无法访问容器内的数据库。示例配置：

services:
  postgres:
    image: postgres:15-alpine
    container_name: doc-pgsql-container
    ports:
      - "5432:5432"  # 宿主机端口:容器端口，必须配置这一行
    environment:
      POSTGRES_USER: your_db_user
      POSTGRES_PASSWORD: your_db_password
      POSTGRES_DB: your_db_name
    volumes:
      - postgres_data:/var/lib/postgresql/data  # 可选，持久化数据

volumes:
  postgres_data:

2. 修正Spring Boot的application.properties配置 #

本地应用不在Docker内部网络，不能用Docker服务名称作为数据库主机地址，必须用宿主机的localhost（或127.0.0.1）加上映射的端口：

# 核心配置，替换成你的实际信息
spring.datasource.url=jdbc:postgresql://localhost:5432/your_db_name
spring.datasource.username=your_db_user
spring.datasource.password=your_db_password
spring.datasource.driver-class-name=org.postgresql.Driver

# 可选：开启SQL日志，排查连接问题
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

如果是Windows/macOS的Docker Desktop用户，偶尔localhost会有解析问题，可以尝试用host.docker.internal代替localhost：

spring.datasource.url=jdbc:postgresql://host.docker.internal:5432/your_db_name

3. 验证容器内PostgreSQL的可访问性 #

先在宿主机直接用psql命令测试连接，排除网络或数据库配置问题：

psql -h localhost -p 5432 -U your_db_user -d your_db_name

如果这个命令能成功连接，说明网络和数据库配置没问题，问题出在Spring Boot的配置上；如果连接失败，按以下步骤排查：

• 检查docker-compose.yaml里的POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB是否和命令里的一致
• 查看容器日志，确认PostgreSQL是否正常启动：docker logs doc-pgsql-container，日志里应该有database system is ready to accept connections的提示
• 检查宿主机防火墙是否禁用了5432端口（临时关闭防火墙测试）

4. 排查PostgreSQL的连接权限（极少情况） #

默认postgres镜像允许所有IP连接，但如果你自定义了pg_hba.conf配置，需要确保添加允许外部连接的规则：

# 在pg_hba.conf中添加
host    all             all             0.0.0.0/0               scram-sha-256

如果挂载了自定义配置文件，重启容器生效。

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