Docker部署PostgreSQL数据库连接失败问题求助

问题描述 #

我正在跟随Fernando Herrera的Udemy课程开发NestJS + GraphQL项目，对应仓库的fin-seccion-5分支。按步骤操作后，Docker中的PostgreSQL容器日志显示database system is ready to accept connections，但使用Table Plus、PGadmin、Dbeaver等客户端连接时，持续报错：

connection to server at "localhost" (::1), port 5432 failed: FATAL: password authentication failed for user "postgres"

已尝试的排查操作：

• 修改客户端连接host为postgres或127.0.0.1
• 更换Docker及PostgreSQL镜像版本（14.4、15.2、15.2-alpine）
• 用/不用-d参数启动容器
• 在docker-compose.yml中明确写入数据库密码和名称
• 关闭Windows Defender及杀毒防火墙

问题仍未解决，但项目在Mac上克隆后可正常运行。

针对性解决方案 #

1. 验证端口映射与占用情况 #

确保docker-compose.yml中PostgreSQL服务的端口映射为5432:5432，且本地5432端口未被其他进程占用。用以下命令检查端口占用：

netstat -ano | findstr :5432

若存在占用进程，可杀掉进程或修改容器映射端口（例如5433:5432），同时客户端连接时对应修改端口。

2. 确认环境变量配置与容器重建 #

检查docker-compose.yml中PostgreSQL的环境变量是否正确，无拼写错误：

services:
  postgres:
    image: postgres:15.2-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: your-set-password
      POSTGRES_DB: target-db-name
    ports:
      - "5432:5432"

若之前启动过容器，修改环境变量后需彻底清理旧容器再重建（容器创建时环境变量已固化）：

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

3. 解决WSL2网络适配问题 #

若使用WSL2作为Docker后端：

• 用WSL2的IP替代localhost连接：打开WSL终端，执行hostname -I获取IP，将此IP作为客户端连接的host。
• 开放WSL2侧的5432端口：在WSL终端执行

sudo ufw allow 5432/tcp

4. 清理PostgreSQL数据卷 #

旧数据卷可能残留错误认证信息，彻底清理后重新创建容器：

docker-compose down -v
docker volume prune
docker-compose up -d

5. 核对客户端连接参数 #

确保客户端连接时：

• 用户名与容器配置的POSTGRES_USER完全一致（默认是postgres）
• 密码与POSTGRES_PASSWORD完全匹配（注意大小写、特殊字符）
• 端口与容器映射的端口保持一致

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