Win10 WSL环境Docker部署PostgreSQL连接报getaddrinfo ENOTFOUND错误如何解决

根因说明 #

该报错属于DNS解析失败：发起数据库连接的程序尝试将主机名database解析为IP地址时，找不到对应解析记录，结合给出的配置，问题由配置错误、WSL环境Docker网络适配规则、配置覆盖三类原因共同导致，按以下步骤修复即可。

步骤1：修正docker-compose.yaml配置错误 #

现有配置存在3个直接引发异常的问题，逐一修正：

• 删除错误的容器名配置：当前给PostgreSQL容器设置container_name: localhost会和系统本地环回地址的解析规则冲突，直接删除该配置项，或改为无冲突的名称如rentx-postgres
• 移除互斥配置：network_mode: host和ports端口映射规则互斥，使用host网络模式时容器直接共享宿主机网络栈，端口映射配置不会生效；且WSL2环境下host网络默认仅绑定WSL实例内部，无法直接对Windows宿主机暴露端口，跨环境连通性差，建议直接删除所有服务下的network_mode: host配置，使用compose默认的桥接网络稳定性更高
• 修正数据卷挂载路径：PostgreSQL官方镜像默认数据存储路径为/var/lib/postgresql/data，当前配置挂载到/data/postgres会导致数据库初始化失败、数据无法持久化，必须修正。

修正后的可用配置参考：

version: "3.7"

services:
  database:
    image: postgres
    restart: always
    ports:
      - 5432:5432
    environment:
      - POSTGRES_USER=docker
      - POSTGRES_PASSWORD=ignite
      - POSTGRES_DB=rentx
    volumes:
      - pgdata:/var/lib/postgresql/data
  app:
    build: .
    container_name: rentx
    ports:
      - 3333:3333
    volumes:
      - .:/usr/app
    depends_on:
      - database

volumes:
  pgdata:
    driver: local

步骤2：匹配场景修正数据库连接地址 #

报错提示尝试解析database主机，说明实际运行的连接配置并非贴出的host: localhost，大概率是环境变量、.env文件覆盖了配置文件的参数，根据应用运行场景选择正确的host：

• 若应用跑在docker-compose启动的app容器内部：连接host直接填database即可，compose默认会为同网络下的服务内置DNS解析，服务名可直接作为主机名使用，此时不需要走端口映射，容器内直接通过5432端口连通数据库
• 若应用跑在WSL终端本地/Windows宿主机上：连接host填localhost即可，前提是已经开启Docker Desktop的WSL集成。

步骤3：WSL环境连通性校验 #

改完配置仍报错的话，按顺序排查：

1. 确认容器状态：执行docker ps查看PostgreSQL容器是否处于Up状态，再执行docker logs <PostgreSQL容器ID>查看日志，排查是否有初始化失败、权限不足、端口占用的问题
2. 校验端口连通性：在运行应用的环境内执行telnet <连接用的host> 5432，如果连接失败：
   • WSL内部连不通：检查WSL内的iptables、ufw防火墙规则是否放行5432端口，同时确认5432端口没有被WSL本地安装的其他PostgreSQL实例占用
   • Windows侧连不通：打开Docker Desktop设置 -> Resources -> WSL Integration，确认当前使用的WSL发行版集成开关已开启，重启Docker Desktop后重试
3. 排查配置覆盖：检查项目根目录的.env文件、系统环境变量中是否存在DB_HOST=database类的配置，多数ORM框架会优先读取环境变量，导致配置文件中修改的host参数不生效。

避坑提示 #

• 禁止将容器名设置为localhost、127.0.0.1这类系统保留的主机名/地址，会直接打乱本地解析规则
• WSL2环境下Docker的host网络模式与Windows宿主机网络天然隔离，除非明确需要容器直接操作宿主机网络，否则优先使用默认桥接网络+端口映射的方案，适配成本最低
• 用官方镜像部署有状态服务时，先确认镜像默认的存储、配置路径，不要随意挂载自定义路径，避免出现权限、初始化失败问题

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