Docker容器中Django无法连接PostgreSQL数据库问题排查

1. 数据库HOST配置错误 #

从日志信息来看，Django尝试连接本地Unix socket（/var/run/postgresql/.s.PGSQL.5432），说明DB_HOST环境变量未正确设置：

• 在Docker Compose的默认网络中，容器之间通过服务名互相访问，你的PostgreSQL服务名为postgresql，因此DB_HOST应设为postgresql，而非localhost（容器内的localhost指向自身，而非PostgreSQL容器）。
• 你的web服务未在docker-compose.yml中配置对应环境变量，导致Django无法获取正确的HOST值，最终 fallback 到默认的localhost，引发连接错误。

2. 环境变量未传递到web容器 #

Django配置依赖DB_NAME、DB_USER、DB_PASSWORD、DB_HOST、DB_PORT这些环境变量，但docker-compose.yml的web服务中未定义这些变量，导致Django无法读取到正确的数据库连接参数：

• 需要在web服务的environment字段中添加对应变量，示例配置如下：

  environment:
    DB_NAME: pgdb
    DB_USER: postgres
    DB_PASSWORD: admin
    DB_HOST: postgresql
    DB_PORT: 5432
  

3. PostgreSQL未完全就绪时Django发起连接 #

depends_on仅保证PostgreSQL容器优先启动，但不等待PostgreSQL服务完全就绪（比如数据库初始化完成、监听端口打开）。Django容器启动后立即执行migrate命令，此时PostgreSQL可能还未准备好接受连接，导致连接失败：

• 可通过添加启动等待脚本解决，示例修改web服务的command字段：

  command: bash -c "until pg_isready -h postgresql -p 5432; do sleep 1; done; python manage.py migrate && python manage.py runserver 0.0.0.0:8000"
  

  注：需确保web容器中已安装postgresql-client工具

4. 环境变量键拼写错误（低概率） #

检查是否存在环境变量键拼写不一致的情况，比如Django中使用DB_HOST，但docker-compose中误写为其他名称，导致无法读取正确值。

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