解决PhpStorm连接Docker中PostgreSQL的密码验证失败问题

问题分析 #

你遇到的FATAL: password authentication failed for user "app"错误，大概率是两个原因导致：

1. Docker容器的PostgreSQL端口未正确映射到主机，PhpStorm使用了错误的端口连接
2. PostgreSQL的认证配置（pg_hba.conf）未允许外部连接使用密码认证

解决方案 #

1. 确认并修正端口映射 #

你的docker-compose.yml中ports: - '5432'是随机端口映射，容器的5432端口会被映射到主机的一个随机端口（比如32768），而非默认的5432。

• 查看当前容器的端口映射：

  docker ps
  

  输出中会有类似0.0.0.0:32768->5432/tcp的内容，32768就是主机侧的端口，PhpStorm连接时要填这个端口。

• 更稳妥的方式是固定端口映射，修改docker-compose.yml的ports配置：

  ports:
    - '5432:5432'
  

  这样主机的5432端口直接映射到容器的5432端口，PhpStorm可以用默认端口连接。

2. 调整PostgreSQL认证配置 #

官方PostgreSQL镜像默认的pg_hba.conf对于外部连接（比如主机的PhpStorm）可能使用ident认证，而非密码认证，需要修改配置：

步骤1：创建自定义pg_hba.conf

在项目根目录下新建conf文件夹，里面创建pg_hba.conf文件，内容如下：

# 本地Unix socket连接（容器内部）用peer认证
local   all             all                                     peer
# 允许来自主机的IPv4连接使用密码认证
host    all             all             127.0.0.1/32            scram-sha-256
# 允许所有IPv4地址连接（如果需要远程访问或容器在自定义网络）
host    all             all             0.0.0.0/0               scram-sha-256
# IPv6本地连接
host    all             all             ::1/128                 scram-sha-256

步骤2：修改docker-compose.yml映射配置文件

更新database服务的volumes，添加自定义配置文件的映射：

services:
  database:
    image: postgres:${POSTGRES_VERSION}-alpine
    container_name: database
    env_file:
      - .env
    volumes:
      - db-data:/var/lib/postgresql/data:rw
      - ./conf/pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf:ro
    ports:
      - '5432:5432' # 这里用固定端口，或者保留随机端口但记住映射值

步骤3：重建容器

删除旧卷和容器，重新启动：

docker-compose down -v && docker-compose up -d

3. 确认PhpStorm连接配置 #

在PhpStorm的数据库连接窗口中，确保：

• 主机：localhost（如果用端口映射到主机）
• 端口：对应主机侧的端口（固定的5432或随机映射的端口）
• 数据库：app
• 用户：app
• 密码：password

完成以上配置后，重新测试连接即可正常访问。

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