Docker-Compose环境下Django无法解析PostgreSQL主机名'db'问题

问题现象 #

启动Docker Compose时，Django后端的数据迁移步骤失败，报错：

#0 0.697 django.db.utils.OperationalError: could not translate host name "db" to address: Name or service not known

单独启动db服务时一切正常，且Docker网络中能看到db容器。

现有配置 #

docker-compose.yml #

version: '3.8'

services:
  nginx:
    container_name: app_server_conf
    build:
      context: ./
      dockerfile: ./Dockerfile
    ports:
      - "80:80"
    environment:
      - PUBLIC_URL=127.0.0.1
    volumes:
      - staticfiles:/staticfiles
    networks:
      - appNetwork
    depends_on:
      - backend    
  db:
    image: postgres:latest
    container_name: db
    restart: always
    ports:
      - "5432:5432"
    networks:
      - appNetwork
    environment:
      POSTGRES_HOST_AUTH_METHOD: trust
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test
    volumes:
      - postgresql:/var/lib/postgresql/data
    healthcheck:
      test: pg_isready -U postgres

  backend:
    container_name: backend
    ports:
      - "8000:8000"
    build:
      context: backend
      dockerfile: ./Dockerfile
    command: "make run"
    networks:
      - appNetwork
    volumes:
      - staticfiles:/app/static/
    depends_on:
      db:
        condition: service_healthy
    links:
      - db:db

volumes:
  postgresql:
  staticfiles:

networks:
  appNetwork:
    driver: bridge

Django settings.py 数据库配置 #

DATABASES = {
    'default': {
        'HOST':'db',
        "ENGINE": "django.db.backends.postgresql",
        'NAME': 'backend_db',
        'USER': 'test',
        'PASSWORD': 'test',
        'PORT': '5432',
    }
}

问题分析 #

1. 健康检查不匹配：PostgreSQL容器的健康检查使用pg_isready -U postgres，但配置的数据库用户是test，可能导致健康检查失败，后端容器等待service_healthy时出现网络解析异常。
2. 迁移时机错误：如果后端Dockerfile中包含RUN python manage.py migrate命令，镜像构建阶段无法访问Docker Compose网络，自然解析不到db主机。
3. 数据库未预先创建：settings中指定的backend_db数据库未自动创建，后续可能引发新的错误，当前报错的核心是主机解析问题，但此配置缺失需提前修正。

解决方案 #

1. 修正PostgreSQL健康检查命令 #

将db服务的健康检查命令改为匹配配置的用户，并添加超时、重试参数：

healthcheck:
  test: pg_isready -U test
  interval: 5s
  timeout: 5s
  retries: 5

确保健康检查能准确判断数据库是否就绪。

2. 迁移命令移至容器启动阶段 #

检查后端的Dockerfile，删除任何构建阶段执行的迁移命令（如RUN python manage.py migrate）。修改make run的逻辑，在启动服务前执行迁移：
假设Makefile内容如下：

run:
    python manage.py migrate --noinput
    python manage.py runserver 0.0.0.0:8000

这样迁移会在容器启动后执行，此时已加入Docker网络，能正常解析db主机。

3. 自动创建目标数据库 #

在db服务的环境变量中添加POSTGRES_DB，指定要创建的数据库名：

environment:
  POSTGRES_HOST_AUTH_METHOD: trust
  POSTGRES_USER: test
  POSTGRES_PASSWORD: test
  POSTGRES_DB: backend_db

避免Django连接时因数据库不存在报错。

4. 验证网络连通性（排查用） #

如果问题仍存在，进入后端容器测试网络：

docker exec -it backend ping db

若能ping通，说明网络正常，重点检查迁移执行时机；若ping不通，确认容器是否加入同一网络（当前配置已指定appNetwork，一般不会有问题）。

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