连接Docker部署的Postgres容器超时、密码认证失败问题

两个连接报错是完全独立的原因导致的：

• 连接172.17.0.2超时：这个地址是Docker默认bridge网络为容器分配的内网地址，仅能在Docker宿主机本地路由访问。如果你的pgAdmin运行在其他机器上，或者pgAdmin本身跑在未做网络配置的其他Docker容器内，根本无法直达这个内网网段，必然触发连接超时。
• 连接localhost报密码认证失败：从docker ps输出看端口映射0.0.0.0:5432->5432/tcp是正常生效的，这类报错90%以上的原因是PostgreSQL官方镜像的环境变量生效逻辑问题：POSTGRES_USER、POSTGRES_PASSWORD仅在数据目录为空、数据库第一次初始化时才会读取生效。如果你之前启动过同名PostgreSQL容器、或者残留了旧的匿名数据卷，新传入的账号密码环境变量会被直接忽略，数据库仍沿用历史初始化时设置的账号密码。
  剩余少量常见诱因包括：宿主机本地5432端口被原生安装的PostgreSQL服务占用，你实际连的是宿主机本身的数据库而非容器内的；Linux环境下localhost默认解析到IPv6地址::1，但Docker端口映射默认仅绑定IPv4。

• 先确认端口占用情况
  Linux宿主机执行：

  ss -tulpn | grep 5432
  

  Windows宿主机执行：

  netstat -ano | findstr :5432
  

  如果输出里的监听进程不是docker-proxy，说明本地已有PostgreSQL服务占用了5432端口。要么停掉本地PostgreSQL服务，要么修改容器启动的端口映射为-p 5433:5432，后续连接时用localhost:5433即可。
• 清理残留旧数据卷后重建容器（最高优先级修复）
  旧数据卷残留是最常见的诱因，按以下命令彻底清理后重启：

  # 强制删除现有故障容器
  docker rm -f admin-service
  # 列出所有docker数据卷，找到关联PostgreSQL的匿名卷（通常为一长串随机ID命名）
  docker volume ls
  # 删除对应残留的匿名数据卷，把<volume_id>替换成上一步查到的卷ID
  docker volume rm <volume_id>
  # 重新启动容器，建议显式指定命名数据卷，避免后续再出现匿名卷残留问题
  docker run -d -e POSTGRES_USER=user -e POSTGRES_PASSWORD=456789 --name admin-service -p 5432:5432 -v postgres_admin_data:/var/lib/postgresql/data postgres
  

  等待10~15秒让容器完成数据库初始化，再通过pgAdmin连接localhost即可正常认证。
• 特殊场景适配
  • 如果是Linux宿主机，连接时地址填127.0.0.1替代localhost，强制走IPv4连接规避解析问题。
  • 如果需要从其他机器访问这个数据库，不要填容器内网IP172.17.0.2，直接填写Docker宿主机的物理局域网/公网IP，同时放开宿主机防火墙对5432端口的入站规则。
  • 如果pgAdmin本身运行在Docker容器内，优先通过映射到宿主机的端口连接，不要直接用容器内网IP，减少Docker网桥路由、防火墙拦截导致的异常。

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