Mage无法连接Docker部署的PostgreSQL：求根因分析与解决方法

根本原因 #

1. 缺失指定的数据库Schema：配置中指定了POSTGRES_SCHEMA=magic，但PostgreSQL初始化后仅默认创建public schema，未自动生成magic schema，导致Mage连接时找不到目标Schema。
2. PostgreSQL监听限制：postgres:14镜像默认仅监听localhost地址，Docker内部网络中的Mage容器无法发起连接请求。

解决方案 #

步骤1：创建缺失的magic Schema #

进入PostgreSQL容器，执行Schema创建命令：

# 进入PostgreSQL容器
docker exec -it magic-zoomcamp-postgres psql -U postgres

# 在psql交互界面中执行创建命令
CREATE SCHEMA magic;

执行完成后输入\q退出psql。

步骤2：修改PostgreSQL监听配置 #

更新docker-compose.yml中的postgres服务配置，添加命令参数允许监听所有地址：

postgres:
  image: postgres:14
  restart: on-failure
  container_name: ${PROJECT_NAME}-postgres
  env_file:
    - .env
  environment:
    POSTGRES_DB: ${POSTGRES_DBNAME}
    POSTGRES_USER: ${POSTGRES_USER}
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  ports:
    - "${POSTGRES_PORT}:5432"
  # 添加以下command配置
  command: postgres -c listen_addresses='*' -c pg_hba.conf='host all all 0.0.0.0/0 md5'

步骤3：重启相关容器 #

# 重启postgres容器
docker-compose restart postgres

# 重启Mage容器确保配置生效
docker-compose restart magic

步骤4：验证连接 #

在Mage的连接配置界面使用以下参数测试：

• 主机：postgres（Docker Compose服务名，容器间网络可直接解析）
• 端口：5432（PostgreSQL容器内部端口）
• 数据库名：postgres
• 用户名：postgres
• 密码：postgres
• Schema：magic

额外排查点 #

• 确认所有容器正常运行：执行docker-compose ps，检查postgres和magic容器状态为Up
• 查看Mage容器日志验证环境变量加载：docker-compose logs magic，搜索POSTGRES_开头的变量，确认配置值正确
• 用pgadmin连接PostgreSQL，确认magic schema已存在且可访问

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