CapRover 中 Maven 应用连接 PostgreSQL 数据库的常见问题排查指南

问题背景

在使用 CapRover 部署 Maven 应用时，开发者可能会遇到无法连接 PostgreSQL 数据库的问题。这种情况通常表现为应用启动正常，但在尝试连接数据库时失败，而通过其他方式却能成功连接。

典型错误表现

1. 应用日志显示数据库连接失败
2. 使用 JDBC URL jdbc:postgresql://srv-captain--[app-name]-db:5432/postgres 无法建立连接
3. 通过命令行工具（如 curl）测试连接时能解析到正确 IP 但应用仍无法连接

根本原因分析

经过排查，这类问题通常由以下几个原因导致：

1. Dockerfile 构建顺序问题：在 Dockerfile 中同时执行 mvn install 和 mvn spring-boot:run 会导致应用在构建阶段就尝试启动，而此时环境可能尚未完全配置好。

2. 环境变量覆盖：Spring Boot 应用可能在其他位置（如 application.properties）覆盖了数据库连接配置。

3. 网络连接验证不足：虽然能解析到数据库服务 IP，但应用层连接参数可能有误。

解决方案

1. 修正 Dockerfile 结构

将构建和运行阶段分离，避免在构建阶段启动应用：

FROM maven AS build
WORKDIR /workspace/app
COPY pom.xml .
COPY src src
RUN mvn install -DskipTests

FROM openjdk:11-jre-slim
WORKDIR /app
COPY --from=build /workspace/app/target/*.jar app.jar
EXPOSE 8080
CMD ["java", "-jar", "app.jar"]

2. 验证环境变量

在应用启动前添加环境变量检查：

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        System.out.println("DB URL: " + System.getenv("POSTGRES_URL"));
        SpringApplication.run(Application.class, args);
    }
}

3. 完整的连接测试方法

在容器内执行全面的连接测试：

1. 解析检查：nslookup srv-captain--[app-name]-db
2. 端口连通性检查：telnet srv-captain--[app-name]-db 5432
3. 使用 psql 客户端直接测试：psql -h srv-captain--[app-name]-db -U postgres

最佳实践建议

1. 使用服务发现名称：始终使用 CapRover 提供的服务名称（如 srv-captain--[app-name]-db）而非硬编码 IP 地址。

2. 分离构建和运行环境：使用多阶段构建减少镜像大小并避免构建时运行应用。

3. 连接池配置：在 Spring Boot 中配置合理的连接池参数：

spring.datasource.hikari.connection-timeout=30000
spring.datasource.hikari.maximum-pool-size=10

4. 健康检查：实现数据库连接健康检查端点，便于监控。

总结

在 CapRover 环境中部署 Maven 应用连接 PostgreSQL 数据库时，确保 Dockerfile 结构合理、环境变量正确传递以及进行全面的连接测试是关键。通过采用多阶段构建、验证环境配置和实施完善的连接检查机制，可以有效避免这类连接问题。