Mac部署Hoppscotch：容器连接PostgreSQL失败的排查与验证

一、容器与PostgreSQL的连通性排查 #

• 确认PostgreSQL监听范围
  Mac默认安装的PostgreSQL通常仅监听127.0.0.1，而Docker容器处于独立网络命名空间，无法通过localhost访问主机服务。打开PostgreSQL配置文件（Homebrew安装路径为/usr/local/var/postgres/postgresql.conf），将listen_addresses设置为'*'或主机的局域网IP，随后重启服务：

  brew services restart postgresql
  

• 容器内直接测试连通性
  启动临时容器验证网络可达性：

  # 用telnet测试端口是否开放
  docker run --rm alpine telnet <你的Mac局域网IP> 5432
  # 用psql直接验证数据库连接
  docker run --rm postgres psql -h <你的Mac局域网IP> -U <数据库用户名> -d <数据库名>
  

  若连接失败，说明网络层面存在阻断；若连接成功，问题则出在Hoppscotch容器的配置上。
• 调整Docker网络访问方式
  Mac环境下，Docker容器可通过host.docker.internal访问主机服务。修改.env文件中的DATABASE_URL，将localhost替换为host.docker.internal：

  DATABASE_URL="postgresql://<用户名>:<密码>@host.docker.internal:5432/<数据库名>?schema=public"
  

  重新启动Hoppscotch后端容器。

二、其他故障排查方向 #

• 校验环境变量配置
  确认.env文件中的DATABASE_URL参数完全正确（用户名、密码、数据库名、端口无遗漏或错误）。可通过以下命令检查容器内加载的环境变量：

  docker run --rm --env-file .env hoppscotch-backend printenv
  

  对比本地Prisma使用的连接字符串，仅需替换主机地址部分。
• 检查PostgreSQL访问控制规则
  编辑/usr/local/var/postgres/pg_hba.conf，添加允许Docker网段访问的规则（Docker默认bridge网段为172.17.0.0/16）：

  host    all             all             172.17.0.0/16            scram-sha-256
  

  保存后重启PostgreSQL服务。
• 重新生成容器内的Prisma客户端
  本地Prisma正常连接不代表容器内的客户端适配当前环境。进入容器执行生成命令：

  # 先获取容器ID
  docker ps -a
  # 进入容器
  docker exec -it <容器ID> sh
  # 重新生成Prisma客户端
  npx prisma generate
  

• 确认PostgreSQL运行状态
  检查5432端口是否被占用：

  lsof -i :5432
  

  若存在其他占用进程，先终止后重启PostgreSQL；同时确认PostgreSQL服务处于运行状态：

  brew services list | grep postgresql
  

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