Docker部署Django+PostgreSQL时无法解析主机名db报错如何解决？

错误根因 #

这个报错本质是Docker内部网络的服务名解析失败，web容器无法通过服务名db找到同网络下的数据库容器，和数据库账号密码、镜像版本、鉴权配置无关。

排查&解决方案 #

• 检查服务网络归属
  确认docker-compose.prod.yml中没有显式定义互不连通的自定义networks，如果配置了自定义网络，必须保证web和db服务绑定同一个网络。未显式配置networks时，Docker Compose默认会为同项目所有服务创建统一桥接网络，无需额外配置。
• 确认数据库容器正常运行
  执行命令查看db容器状态：

  docker compose -f docker-compose.prod.yml ps
  

  如果db容器处于退出状态，执行docker logs db查看启动失败原因（常见原因包括宿主机5432端口占用、postgres_data卷权限不足、环境变量配置错误等），只有db容器处于运行状态时，服务名才会被Docker DNS注册。
• 清理Docker残留资源
  旧的容器、网络缓存经常会导致解析异常，执行以下命令重建所有资源（需要保留现有数据库数据的话去掉-v参数）：

  docker compose -f docker-compose.prod.yml down -v
  docker compose -f docker-compose.prod.yml up --build -d
  

• 检查镜像构建阶段是否有数据库操作
  查看你的Dockerfile.prod，确认没有把python manage.py migrate这类需要连接数据库的命令写在RUN指令中：Docker镜像构建阶段不会接入Docker Compose的项目网络，此时连接db必然会解析失败，这类命令需要放到容器启动脚本、command配置或者entrypoint中执行。
• 手动验证网络连通性
  服务启动后进入web容器执行解析测试：

  docker exec -it web ping db
  

  如果无法解析，可以先查询db容器的实际IP：

  docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' db
  

  将.env.prod中的SQL_HOST改为查询到的IP测试连接，能连通则可确认是Docker内部DNS异常，可尝试重启Docker daemon解决。

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