Docker Compose部署下Django应用无法连接PostgreSQL问题排查

核心排查点与修复步骤 #

1. 确认Django配置正确读取环境变量 #

检查项目settings.py中的数据库配置，必须完全从环境变量取值，不能硬编码：

import os

DATABASES = {
    'default': {
        'ENGINE': os.environ.get('APP_DB_ENGINE'),
        'NAME': os.environ.get('APP_DB_NAME'),
        'USER': os.environ.get('APP_DB_USER'),
        'PASSWORD': os.environ.get('APP_DB_PASSWORD'),
        'HOST': os.environ.get('APP_DB_HOST'),
        'PORT': os.environ.get('APP_DB_PORT'),
    }
}

若存在HOST: 'localhost'这类硬编码值，会导致容器内无法访问DB服务。

2. 验证Web容器环境变量加载 #

进入Web容器，检查环境变量是否正确加载：

docker exec -it immohub-web-1 printenv | grep APP_DB_

需确保APP_DB_HOST=db、APP_DB_PORT=5432，其余参数与.env一致。

3. 测试容器间网络连通性 #

进入Web容器，测试能否访问DB服务的5432端口：

# 安装telnet（Debian/Ubuntu镜像）
apt update && apt install -y telnet
telnet db 5432

若连接被拒绝：

• 确认Docker Compose默认网络未被修改，Web与DB服务需在同一网络。
• 检查主机防火墙是否拦截容器间的5432端口通信。

4. 修复PostgreSQL远程连接权限 #

由于DB数据目录已通过Volume持久化，初始化阶段的pg_hba.conf不会自动更新，需手动允许Docker网段连接：

1. 进入DB容器：

docker exec -it immohub-db-1 bash

2. 编辑pg_hba.conf：

vi /var/lib/postgresql/data/pg_hba.conf

3. 添加以下规则：

host    all             all             172.17.0.0/16            scram-sha-256
host    all             all             192.168.0.0/16           scram-sha-256

4. 重启PostgreSQL：

pg_ctl restart -D /var/lib/postgresql/data/

或直接在docker-compose.yml的db服务中添加启动参数：

db:
  image: postgres
  command: postgres -c 'host all all 0.0.0.0/0 scram-sha-256'
  # 保留原有其他配置

5. 修正初始化脚本挂载方式 #

当前db服务中初始化脚本挂载为目录，若init.sql是单个文件，需修改为文件挂载：

volumes:
  - ./db/data/:/var/lib/postgresql/data/
  - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql

否则挂载失效，可能导致用户/数据库未正确创建。

6. 排查健康检查环境变量解析问题 #

日志中出现FATAL: role "root" does not exist，可能是健康检查的环境变量未正确替换，修改为硬编码参数：

healthcheck:
  test: ["CMD-SHELL", "pg_isready -d immohub -U immohub"]
  interval: 10s
  timeout: 10s
  retries: 5
  start_period: 5s

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