悠悠楠杉
网站页面
Docker化Django项目PostgreSQL连接失败：深入解析与解决方案
12/01
在现代Web开发中，将Django项目容器化已成为标准实践。通过Docker与Docker Compose，开发者可以快速搭建本地开发环境或部署生产服务。然而，一个常见且令人困扰的问题是：Django应用启动后无法连接到PostgreSQL数据库，报错如could not connect to server: Connection refused或FATAL: database "mydb" does not exist。这类问题往往不是代码本身的问题，而是容器间通信或配置不一致导致的系统性故障。
首先需要明确的是，Docker容器之间默认是隔离的。即使你在docker-compose.yml中定义了Django和PostgreSQL两个服务，若未正确配置网络或依赖关系，Django容器可能在PostgreSQL尚未完全启动时就尝试建立连接，从而导致失败。一个典型的错误配置是直接在Django的settings.py中写死数据库主机为localhost。但在容器环境中，PostgreSQL运行在另一个独立的容器中，其网络地址并非宿主机的localhost，而应是服务名称（如db）。
正确的做法是在Django的数据库配置中使用服务名作为HOST。例如：
python
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': os.environ.get('POSTGRES_DB'),
'USER': os.environ.get('POSTGRES_USER'),
'PASSWORD': os.environ.get('POSTGRES_PASSWORD'),
'HOST': os.environ.get('DB_HOST', 'db'), # 对应docker-compose中的service name
'PORT': '5432',
}
}
同时，在.env文件或docker-compose.yml中设置对应的环境变量：
yaml
version: '3.8'
services:
db:
image: postgres:15
environment:
POSTGRESDB: myproject
POSTGRESUSER: myuser
POSTGRESPASSWORD: mypassword
volumes:
- postgresdata:/var/lib/postgresql/data/
restart: always
web:
build: .
command: python manage.py runserver 0.0.0.0:8000
volumes:
- .:/code
ports:
- "8000:8000"
environment:
- DBHOST=db
- POSTGRESDB=myproject
- POSTGRESUSER=myuser
- POSTGRESPASSWORD=mypassword
dependson:
- db
stdinopen: true
tty: true
volumes:
postgres_data:
这里的关键点有三个：一是depends_on仅确保容器启动顺序，但不等待PostgreSQL服务真正就绪；二是DB_HOST=db让Django通过Docker内部DNS解析到数据库容器；三是数据卷postgres_data确保数据持久化。
即便如此，仍可能出现连接失败。原因在于depends_on并不能判断PostgreSQL进程是否已准备好接受连接。解决此问题的常用方法是引入“等待脚本”。可以在Django容器启动前执行一段检查脚本，持续探测数据库端口是否开放。例如创建wait-for-db.sh：
bash
!/bin/sh
until pgisready -h "$DBHOST" -p 5432; do
echo "Waiting for PostgreSQL at $DB_HOST:5432..."
sleep 2
done
echo "PostgreSQL is available"
然后在Dockerfile中将其复制并修改启动命令：
dockerfile
COPY wait-for-db.sh /wait-for-db.sh
RUN chmod +x /wait-for-db.sh
CMD ["/wait-for-db.sh", "&&", "python", "manage.py", "runserver", "0.0.0.0:8000"]
此外，还需注意PostgreSQL镜像的初始化机制。首次启动时，它会根据POSTGRES_DB等环境变量自动创建数据库和用户。但如果数据卷已存在旧数据，这些变量将被忽略，可能导致数据库名或密码不匹配。因此，在调试阶段建议清理数据卷：docker-compose down -v，以排除残留数据干扰。
综上所述，Docker化Django项目连接PostgreSQL失败，本质上是容器编排与服务依赖管理的问题。通过合理配置服务名称、环境变量、启动依赖及健康检查机制，绝大多数连接问题都能迎刃而解。关键在于理解容器网络模型，并用工程化手段确保服务间的有序协作。
