Docker部署Django+PostgreSQL连接失败：连接拒绝问题排查

你通过Docker部署Django与PostgreSQL容器组合时，PostgreSQL日志显示已正常启动监听5432端口，但Django侧出现连接拒绝错误：

django.db.utils.OperationalError: connection to server at "127.0.0.1", port 5432 failed: Connection refused
        Is the server running on that host and accepting TCP/IP connections?

核心错误原因 #

在Docker Compose的默认网络环境中，每个容器都是独立的网络节点。127.0.0.1在web容器内指向容器自身，而非db容器，这是导致连接被拒绝的根本原因。

具体修复步骤 #

1. 修正.env文件的数据库主机配置 #

将.env文件中的POSTGRES_HOST=127.0.0.1修改为POSTGRES_HOST=db——Docker Compose会自动为每个service分配对应的主机名，db服务的主机名就是db。

修正后的.env文件：

POSTGRES_DB=my_db
POSTGRES_USER=my_admin
POSTGRES_PASSWORD=my_api
POSTGRES_HOST=db
POSTGRES_PORT=5432

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

确保Django项目settings.py中的数据库配置正确读取环境变量，示例配置如下：

import os

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.getenv('POSTGRES_DB'),
        'USER': os.getenv('POSTGRES_USER'),
        'PASSWORD': os.getenv('POSTGRES_PASSWORD'),
        'HOST': os.getenv('POSTGRES_HOST'),
        'PORT': os.getenv('POSTGRES_PORT'),
    }
}

3. 补充说明：depends_on的局限性 #

虽然你配置了depends_on: - db，但该选项仅保证web容器在db容器之后启动，不确保PostgreSQL服务已完全就绪。如果遇到db服务未初始化完成web就尝试连接的情况，可以添加健康检查或使用wait-for-it脚本辅助，但修改主机名已能解决当前的连接拒绝问题。

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