Docker化Django+PostgreSQL项目时容器无法连接本地数据库如何解决

报错核心原因：Docker容器的网络命名空间独立，容器内的localhost指向容器自身，而非宿主机，因此无法访问宿主机上部署的PostgreSQL服务，可选择以下两种方案解决：

方案1：继续使用宿主机部署的PostgreSQL #

• 调整Django数据库配置：
  替换settings.py中数据库的HOST值：
  • Windows/macOS Docker Desktop环境：填写host.docker.internal（Docker预留的宿主机映射域名）
  • Linux Docker环境：填写172.17.0.1（Docker默认网桥的网关地址，即宿主机在Docker网桥中的IP）
• 调整宿主机PostgreSQL访问权限：
  1. 打开PostgreSQL配置文件postgresql.conf，修改listen_addresses = '*'，允许监听所有网卡的请求
  2. 打开PostgreSQL客户端认证配置文件pg_hba.conf，添加规则允许Docker网段访问：

  host    all             all             172.17.0.0/16            scram-sha-256
  

  3. 重启宿主机PostgreSQL服务使配置生效

方案2（推荐）：将PostgreSQL纳入Docker Compose编排，实现全栈容器化 #

该方案无需依赖宿主机环境，整套服务可一键启动，适配所有部署环境。

步骤1：修改docker-compose.yml，添加PostgreSQL服务 #

version: '3'
services:
  db:
    image: postgres:14-alpine
    # 数据卷持久化数据库数据，避免容器重启丢失数据
    volumes:
      - postgres_data:/var/lib/postgresql/data/
    environment:
      - POSTGRES_DB=mydb
      - POSTGRES_USER=myuser
      - POSTGRES_PASSWORD=mypass
    restart: always

  web:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    ports:
      - "8000:8000"
    # 声明依赖，确保db容器先于web容器启动
    depends_on:
      - db
    # 传入数据库配置环境变量，避免硬编码
    environment:
      - DB_HOST=db
      - DB_NAME=mydb
      - DB_USER=myuser
      - DB_PASSWORD=mypass
    restart: always

# 声明全局数据卷
volumes:
  postgres_data:

步骤2：修改settings.py数据库配置，适配容器网络 #

import os

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': os.getenv('DB_NAME', 'mydb'),
        'USER': os.getenv('DB_USER', 'myuser'),
        'PASSWORD': os.getenv('DB_PASSWORD', 'mypass'),
        # Docker Compose会自动将服务名`db`解析为PostgreSQL容器的内网IP
        'HOST': os.getenv('DB_HOST', 'localhost'),
        'PORT': '5432',
    }
}

步骤3：重新启动服务 #

1. 清理旧容器：docker-compose down
2. 重新构建镜像：docker-compose build
3. 启动所有服务：docker-compose up -d
4. 首次启动执行数据库迁移：docker-compose exec web python manage.py migrate

注意：depends_on仅保证容器启动顺序，不会等待PostgreSQL服务完全初始化完成，若首次启动仍报连接错误，等待数秒后重启web容器即可。

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