NestJS Boilerplate 项目 Docker 部署中 PostgreSQL 连接问题解析

在使用 NestJS Boilerplate 项目进行 Docker 部署时，开发者可能会遇到服务器无法连接 PostgreSQL 数据库的问题。本文将深入分析这一常见问题的原因，并提供完整的解决方案。

问题现象

当开发者尝试通过 docker compose up -d 命令启动项目时，服务器容器无法正常启动，而数据库容器却运行良好。错误日志显示服务器无法连接到 PostgreSQL 数据库，报错信息为 ECONNREFUSED。

根本原因分析

这个问题源于 Docker 容器网络环境与本地开发环境的差异：

1. 主机名解析差异：在 Docker 容器网络中，服务间通信需要使用服务名称而非 localhost
2. 环境变量配置：项目默认的 .env 文件中 DATABASE_HOST 设置为 localhost，这在容器环境中不适用
3. 构建顺序问题：直接使用 docker compose up -d 可能导致镜像未正确重建

完整解决方案

1. 修改数据库连接配置

在 .env 文件中，将数据库主机名从 localhost 改为 Postgres 服务名：

DATABASE_HOST=postgres

2. 正确的 Docker 启动方式

建议使用以下命令确保镜像正确构建：

docker-compose up --build

3. 验证步骤

1. 检查容器是否全部运行：docker ps -a
2. 查看服务器容器日志：docker logs <container_name>
3. 通过 Adminer 或 TablePlus 验证数据库连接

技术原理

在 Docker Compose 环境中，每个服务都运行在独立的容器中，这些容器通过 Docker 创建的网络进行通信。当使用 localhost 作为主机名时，容器会尝试连接自身的网络接口，而不是目标服务容器。

正确的做法是使用 Docker Compose 文件中定义的服务名称作为主机名。在本例中，数据库服务在 docker-compose.yml 中定义为 "postgres"，因此应用容器需要通过 "postgres" 这个主机名来访问数据库服务。

最佳实践建议

1. 环境分离：为开发、测试和生产环境准备不同的 .env 文件
2. 健康检查：在 docker-compose.yml 中添加健康检查确保依赖服务就绪
3. 日志监控：配置集中式日志收集以便问题排查
4. 网络配置：了解 Docker 网络模式，根据需求选择合适的网络配置

通过以上解决方案，开发者可以顺利解决 NestJS Boilerplate 项目在 Docker 环境中的数据库连接问题，确保应用正常启动和运行。