Windows环境下通过localhost连接Docker中Postgres服务失败求助

故障原因及排查方案 #

核心高发原因（Windows环境特有） #

• Shell语法不兼容导致环境变量失效
  你当前使用的命令都是Bash语法，在Windows原生的PowerShell/CMD中无法正确解析：
  1. docker run命令中的${DB_USER}这类变量取值语法，在PowerShell中应该写为$env:DB_USER，CMD中应该写为%DB_USER%，语法不对会导致变量取值为空，等于你给Postgres配置的默认用户名是postgres，密码是空值，和你预期的配置不一致
  2. 执行psql命令时前缀PGPASSWORD="${DB_PASSWORD}"的临时变量赋值语法，PowerShell/CMD完全不识别，等于你没有给psql传密码参数，自然触发密码验证失败
• 旧容器数据卷残留导致账号密码不更新
  如果你之前已经用zero2prod作为容器名启动过Postgres，Docker会持久化对应的数据卷，已经初始化过的Postgres账号密码会保存在数据卷中，后续你修改环境变量重新启动同名容器，不会覆盖已有的账号密码配置，导致你本地的DB_PASSWORD和容器内实际的密码不匹配
• 端口映射冲突导致连错服务
  你指定的${DB_PORT}端口如果已经被本地安装的其他Postgres服务占用，你执行psql命令连接的实际是本地原生的Postgres服务，不是Docker容器内的服务，自然账号密码验证失败

排查验证步骤 #

1. 先确认容器运行状态，执行docker ps查看zero2prod容器是否处于正常运行状态
2. 进入容器内部验证账号密码是否正确，执行：

docker exec -it zero2prod psql -U <你实际配置的DB_USER值> -d <你实际配置的DB_NAME值>

如果可以正常登录，说明容器本身配置没有问题，故障出在外部连接的环境变量或者端口问题
3. 检查端口占用，执行netstat -ano | findstr :<你实际配置的DB_PORT值>，查看端口对应的PID是不是Docker的进程

修复方案 #

1. 如果你用PowerShell执行命令，统一修改语法：
   • 启动容器命令改为：

   docker run `
       --name zero2prod `
       -e POSTGRES_USER=$env:DB_USER `
       -e POSTGRES_PASSWORD=$env:DB_PASSWORD `
       -e POSTGRES_DB=$env:DB_NAME `
       -p "$($env:DB_PORT):5432" `
       -d postgres `
       postgres -N 1000
   

   • 连接命令改为：

   $env:PGPASSWORD = $env:DB_PASSWORD
   psql -h "localhost" -U $env:DB_USER -p $env:DB_PORT -d "postgres"
   

2. 如果是旧数据卷残留问题，先删除旧容器和关联数据卷再重新启动：

docker rm -f zero2prod
docker volume rm $(docker volume ls -qf name=zero2prod)

3. 如果是端口冲突，修改docker run命令中的端口映射为其他未被占用的端口即可

内容的提问来源于stack exchange，提问作者T.A