Django 项目中 PostgreSQL 数据库连接失败的根源与修复方案-Python教程-PHP中文网

Django 项目中 PostgreSQL 数据库连接失败的根源与修复方案

本文详解 Docker 环境下 Django 应用因环境变量命名不一致导致的 PostgreSQL 认证失败问题，重点指出 DB_PASSWORD 未被正确设置的根本原因，并提供完整、可落地的配置修正与最佳实践建议。

本文详解 docker 环境下 django 应用因环境变量命名不一致导致的 postgresql 认证失败问题，重点指出 `db_password` 未被正确设置的根本原因，并提供完整、可落地的配置修正与最佳实践建议。

在使用 Docker Compose 编排 Django + Nginx + PostgreSQL 的生产级部署时，一个常见但极易被忽略的故障是：应用能正常启动、Nginx 反向代理畅通，却在访问 Admin 或执行数据库操作时抛出 fe_sendauth: no password supplied 错误。该错误并非网络不通或端口未暴露所致——正如日志明确提示：“连接成功，但未提供密码”。这意味着 Django 已成功解析 HOST 并发起连接请求，却因认证凭据缺失被 PostgreSQL 拒绝。

问题核心在于 环境变量映射错位。观察你的 docker-compose.yml：

django:
  environment:
    - DB_HOST=database
    - POSTGRES_DB=movies_database
    - POSTGRES_USER=app
    - POSTGRES_PASSWORD=123qwe  # ← 此变量名为 POSTGRES_PASSWORD

而 components/database.py 中却尝试读取：

'PASSWORD': os.environ.get('DB_PASSWORD'),  # ← 期望的是 DB_PASSWORD，但实际未设置！

由于 os.environ.get('DB_PASSWORD') 返回 None，Django 最终以空密码尝试连接 PostgreSQL，触发认证失败。Nginx 在此过程中完全不参与数据库连接——它仅负责 HTTP 请求转发（proxy_pass http://django:8000），数据库连接由 Django 进程在容器内直连 database 容器完成，与 Nginx 配置无关。因此修改 nginx.conf 无法解决该问题。

✅ 正确修复方案如下：

Django

避免常见的 Django 错误——QuerySet 评估、N+1 查询、迁移冲突和 ORM 陷阱。

下载

1. 统一环境变量命名（推荐）
修改 components/database.py，使其与 docker-compose.yml 中定义的变量名严格一致：

import os

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('POSTGRES_DB', 'movies_database'),
        'USER': os.environ.get('POSTGRES_USER', 'app'),
        'PASSWORD': os.environ.get('POSTGRES_PASSWORD', '123qwe'),  # ✅ 改为 POSTGRES_PASSWORD
        'HOST': os.environ.get('DB_HOST', 'database'),
        'PORT': os.environ.get('DB_PORT', '5432'),
        'OPTIONS': {
            'options': '-c search_path=public,content'
        }
    }
}

2. （备选）在 docker-compose.yml 中补充缺失变量
若需保持代码不变，可在 django 服务中显式映射：

django:
  environment:
    - DB_HOST=database
    - DB_NAME=${POSTGRES_DB:-movies_database}
    - DB_USER=${POSTGRES_USER:-app}
    - DB_PASSWORD=${POSTGRES_PASSWORD:-123qwe}  # ✅ 显式传递 DB_PASSWORD
    - POSTGRES_DB=movies_database
    - POSTGRES_USER=app
    - POSTGRES_PASSWORD=123qwe

3. 验证与加固建议

启动前执行 docker-compose config 检查变量是否生效；
在 Django 容器内运行 printenv | grep -i postgres 确认环境变量已注入；
生产环境中务必移除硬编码密码（如 '123qwe'），改用 .env 文件或 Docker secrets；
DATABASES 配置中建议添加 CONN_MAX_AGE 和连接池参数（如 dj-database-url 库）提升稳定性。

⚠️ 注意：nginx.conf 中无需为数据库连接做任何配置——Nginx 不处理数据库通信。其唯一职责是将客户端 HTTP 请求反向代理至 Django/uWSGI 服务（proxy_pass http://django:8000）。数据库连接完全由 Django 的 Python 进程通过 libpq 驱动完成，依赖 HOST（容器名）、PORT 和认证信息三要素。

完成上述修正后，重建并重启服务：

docker-compose down -v && docker-compose up --build -d

此时 Django 将携带正确密码连接 PostgreSQL，Admin 登录及所有 ORM 操作即可恢复正常。这再次印证：容器编排中的“解耦”优势，也要求开发者清晰理解各组件职责边界——Nginx 是 Web 代理，不是数据库网关。