GitHub Actions中Docker Compose部署PostgreSQL无法连接问题

核心排查方向及解决方案 #

1. 等待数据库完全初始化再执行迁移 #

GitHub Actions的容器启动节奏比本地慢，docker-compose up返回成功不代表PostgreSQL已经完成就绪。

• 在执行npx prisma migrate dev前，加入等待数据库可用的脚本：

  until pg_isready -h db -p 5432 -U your_db_user; do
    echo "等待数据库就绪..."
    sleep 2
  done
  

  或者在docker-compose.yml中给服务添加健康检查依赖，确保Web应用只在数据库完全就绪后启动：

  services:
    db:
      image: postgres:15
      healthcheck:
        test: ["CMD-SHELL", "pg_isready -U your_db_user"]
        interval: 5s
        timeout: 5s
        retries: 5
    web:
      build: .
      depends_on:
        db:
          condition: service_healthy
  

2. 验证网络与数据库URL配置 #

• GitHub Actions中Docker Compose默认使用桥接网络，Prisma的数据库URL必须使用容器服务名db作为主机，不能用localhost：

  DATABASE_URL="postgresql://your_db_user:your_db_password@db:5432/your_db_name?schema=public"
  

• 检查docker-compose.yml中数据库的环境变量是否配置正确，避免用户名/密码错误导致连接失败：

  db:
    image: postgres:15
    environment:
      POSTGRES_USER: your_db_user
      POSTGRES_PASSWORD: your_db_password
      POSTGRES_DB: your_db_name
  

3. 查看数据库容器日志定位问题 #

在GitHub Actions步骤中添加日志查看命令，确认数据库启动状态：

docker-compose logs db

如果日志显示初始化错误（比如权限不足、数据目录问题），需要调整容器的挂载配置或用户权限。

4. 确认Prisma命令的执行上下文 #

• 如果Web应用运行在容器内，必须进入容器执行迁移命令，而非在GitHub Actions主机环境执行：

  docker-compose exec web npx prisma migrate dev
  

• 若要在主机环境执行迁移，需在docker-compose.yml中映射数据库端口：

  db:
    image: postgres:15
    ports:
      - "5432:5432"
  

  此时数据库URL可临时改为postgresql://your_db_user:your_db_password@localhost:5432/your_db_name?schema=public，迁移完成后再切换回容器服务名db。

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