Docker Compose部署Postgres与pgAdmin4无法连接的问题排查

背景 #

尝试从pgAdmin4连接PostgresDB，二者均通过Docker Compose容器化部署，且处于同一postgres-pg-admin-net网络中

启动脚本 #

docker compose --env-file ./.docker/.db.env --env-file ./.docker/.pgadmin.env -f ./.docker/compose.db.yaml up --build --wait

配置文件 #

compose.db-env.yaml #

version: '3.8'

networks:
  postgres-pg-admin-net:
    driver: bridge

volumes:
  db-data:
  pgadmin-data:

compose.db.yaml #

version: "3.8"

include:
  - ./compose.db-env.yaml

services:
  db-prod:
    container_name: backend-db-prod
    deploy:
      resources:
        limits:
          cpus: "1"
          memory: 4G
    env_file: ./.db.env
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-db}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
      POSTGRES_PORT: ${POSTGRES_PORT:-5432}
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    image: postgres:16.1-alpine3.18
    networks:
      - postgres-pg-admin-net
    platform: linux/amd64
    ports:
      - ${POSTGRES_PORT}:5432
    restart: unless-stopped
    volumes:
      - db-data:/var/lib/postgresql/data/
      - ./.postgresql.conf:/etc/postgresql.conf

  pgadmin:
    container_name: pgadmin
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 1G
    depends_on:
      - db-prod
    image: dpage/pgadmin4:7.4
    env_file: ./.pgadmin.env
    environment:
      MASTER_PASSWORD_REQUIRED: ${MASTER_PASSWORD_REQUIRED:-False}
      PGADMIN_CONFIG_SERVER_MODE: ${PGADMIN_CONFIG_SERVER_MODE:-False}
      PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL:-pgadmin4@pgadmin.com}
      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD:-admin}
    volumes:
      - pgadmin-data:/var/lib/pgadmin
      - ./.pgadmin.servers.json:/pgadmin4/servers.json
    platform: linux/amd64
    ports:
      - 5050:80
    restart: unless-stopped
    networks:
      - postgres-pg-admin-net

.db.env #

POSTGRES_CONTAINER_NAME=backend-db-dev
POSTGRES_DB=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_PORT=5432
POSTGRES_USER=postgres

.pgadmin.dev #

MASTER_PASSWORD_REQUIRED=False
PGADMIN_CONFIG_SERVER_MODE=False
PGADMIN_DEFAULT_EMAIL=pgadmin4@pgadmin.com
PGADMIN_DEFAULT_PASSWORD=admin

.pgadmin.servers.json（pgAdmin预配置服务器文件） #

{
  "Servers": {
    "main": {
      "Name": "main",
      "Group": "Servers",
      "Port": 5432,
      "Username": "postgres",
      "Host": "backend-db-dev",
      "SSLMode": "prefer",
      "MaintenanceDB": "postgres"
    }
  }
}

错误现象 #

容器启动后，pgAdmin4连接Postgres时提示无法解析主机地址，连接设置中主机填写的是backend-db-dev，但Docker网络中Postgres容器的别名是db-prod和backend-db-prod。

错误分析与修复步骤 #

1. 主机地址配置错误（核心问题） #

在pgadmin.servers.json中，Host字段填写的是backend-db-dev，但实际Postgres容器的容器名是backend-db-prod，且Docker Compose服务名是db-prod——这两个名称才是同一网络内可解析的主机名。

修复：修改pgadmin.servers.json的Host字段为以下任意一个：

• 服务名db-prod（推荐，因为容器名可能变化，服务名由Compose管理更稳定）
• 容器名backend-db-prod

修改后的pgadmin.servers.json：

{
  "Servers": {
    "main": {
      "Name": "main",
      "Group": "Servers",
      "Port": 5432,
      "Username": "postgres",
      "Host": "db-prod",
      "SSLMode": "prefer",
      "MaintenanceDB": "postgres"
    }
  }
}

2. 环境文件名称不匹配 #

启动脚本中指定的pgAdmin环境文件是./.docker/.pgadmin.env，但你提供的文件名为.pgadmin.dev，会导致环境变量无法正确加载。

修复：

• 要么将.pgadmin.dev重命名为.pgadmin.env
• 要么修改启动脚本中的--env-file参数为./.docker/.pgadmin.dev

3. Postgres配置文件监听地址检查 #

你挂载了自定义的postgresql.conf到容器内，如果该文件中listen_addresses设置为localhost，会导致Postgres只监听容器内部的localhost，其他容器无法连接。

修复：确保postgresql.conf中包含：

listen_addresses = '*'

4. 重启容器生效 #

修改配置后，重启容器使更改生效：

docker compose -f ./.docker/compose.db.yaml down
docker compose --env-file ./.docker/.db.env --env-file ./.docker/.pgadmin.env -f ./.docker/compose.db.yaml up --build --wait

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