如何将pgAdmin Docker容器连接到Debian宿主机本地的PostgreSQL数据库

核心原因 #

1. 容器内的localhost指向容器自身的环回地址，而非宿主机
2. host.docker.internal是Docker Desktop for Windows/Mac的专属特性，原生Linux Docker默认没有该解析规则

可行解决方法 #

• 方法1：使用Docker网关地址连接
  1. 执行命令查询Docker默认网桥的网关地址：

     docker network inspect bridge | grep Gateway
     

     绝大多数场景下返回值为172.17.0.1
  2. 修改宿主机PostgreSQL配置：
     • 编辑postgresql.conf（通常路径为/etc/postgresql/[版本号]/main/postgresql.conf），将listen_addresses修改为'*'或者包含Docker网段的地址
     • 编辑pg_hba.conf（同目录下），添加Docker网段访问规则：

       host  all  all  172.17.0.0/16  scram-sha-256
       

     • 执行sudo systemctl restart postgresql重启PostgreSQL服务
  3. pgAdmin连接配置中，地址填上述查询到的网关地址，其他参数保持正常配置即可
• 方法2：启动容器时手动添加宿主机解析
  启动容器时新增--add-host参数手动映射宿主机地址，修改后的启动命令如下：

  docker run -p 8000:80 --env-file ./pgadmin_docker_env.list --add-host=host.docker.internal:host-gateway -d dpage/pgadmin4
  

  注意：官方dpage/pgadmin4镜像默认监听容器内的80端口，你原命令中的端口映射8000:8000以及访问localhost:8080均为错误配置，按照上述命令映射后访问localhost:8000即可进入pgAdmin
  启动完成后，pgAdmin中连接地址填host.docker.internal即可正常访问宿主机PostgreSQL
• 方法3：使用host网络模式启动
  不需要网络隔离的场景下可以直接用宿主机网络启动容器，启动命令如下：

  docker run --net=host --env-file ./pgadmin_docker_env.list -d dpage/pgadmin4
  

  该模式下容器直接共享宿主机网络栈，pgAdmin中填localhost即可连接到宿主机PostgreSQL，无需修改PostgreSQL配置

额外排查项 #

如果按照上述方法仍连接失败，可逐一排查：

• 执行ss -tulpn | grep 5432确认PostgreSQL确实在监听5432端口
• 确认宿主机防火墙没有拦截Docker网段的5432端口请求，Debian默认ufw防火墙可执行以下命令放通：

  ufw allow in from 172.17.0.0/16 to any port 5432
  

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