如何从宿主机连接docker-compose启动的容器内的Postgres数据库

1. 端口映射与占用检查 #

• 运行docker ps确认端口映射生效：查看目标容器的PORTS列，需存在0.0.0.0:5432->5432/tcp或:::5432->5432/tcp的映射记录，若不存在检查docker-compose配置的端口映射是否配置在Postgres服务下（不要错误配置到Web服务的配置块中），以及容器启动时是否有端口冲突报错。
• 检查宿主机端口占用：Windows执行netstat -ano | findstr "5432"，macOS/Linux执行lsof -i :5432，如果有其他进程占用5432端口，可停掉占用进程，或修改端口映射为5433:5432后通过5433端口连接。

2. 网络与防火墙拦截检查 #

• 临时关闭宿主机防火墙（Windows Defender防火墙、macOS系统防火墙、Linux的ufw/iptables）测试连通性，若关闭后可正常连接，将5432端口加入防火墙白名单即可。
• 若使用WSL2运行Docker，需额外检查WSL2端口转发是否正常，可执行wsl --shutdown重启WSL后重试，或手动配置WSL到宿主机的端口转发规则。
• 若使用Docker Desktop for Mac/Windows，不要直接用容器IP连接，此类环境下Docker网桥运行在虚拟机内，宿主机无法直接访问容器IP，仅可通过localhost+映射端口的方式连接。

3. 基础连通性测试 #

• 优先用宿主机命令行客户端测试，排除GUI客户端配置问题：执行psql -h localhost -p 5432 -U 你的数据库用户名测试，若连接失败再尝试进入Postgres容器内部执行psql -h localhost -p 5432 -U 你的数据库用户名，确认容器内部可正常连接。
• 若容器内部可连接、宿主机命令行仍超时，进入容器执行iptables -L检查容器内部是否有拦截5432端口的规则，关闭容器内部防火墙后重试。

4. Postgres配置有效性检查 #

• 不要仅验证配置文件内容，进入Postgres容器执行psql -U postgres -c 'show listen_addresses'，确认输出为*，若不匹配说明配置修改后未重启Postgres服务，配置未生效。
• 执行psql -U postgres -c 'show hba_file'确认pg_hba.conf的加载路径，检查你修改的配置文件是否为该路径的文件，修改配置后需执行pg_ctl reload或重启Postgres服务让配置生效。

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