SpringBoot使用SSL连接Postgres无法创建连接异常排查

问题表现 #

SpringBoot项目配置SSL方式连接PostgreSQL数据库时，数据库连接创建失败，异常触发于SSL初始握手阶段，核心异常信息如下：

Caused by: javax.net.ssl.SSLException: Received fatal alert: unexpected_message
异常栈追踪：
at sun.security.ssl.Alerts.getSSLException(Alerts.java:208)
at sun.security.ssl.Alerts.getSSLException(Alerts.java:154)
at sun.security.ssl.SSLSocketImpl.recvAlert(SSLSocketImpl.java:2020)
at sun.security.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:1127)
at sun.security.ssl.SSLSocketImpl.performInitialHandshake(SSLSocketImpl.java:1367)
at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1395)
at sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1379)
at org.postgresql.ssl.MakeSSL.convert(MakeSSL.java:41)
... 省略57个公共栈帧

触发原因 #

• 服务端未开启SSL支持：客户端强制发起SSL握手请求时，服务端返回普通非SSL协议响应，报文格式不匹配直接触发异常。这是该报错最高频的触发场景。
• 连接配置错误：误将非SSL端口作为SSL端口填写，或者JDBC连接参数中SSL模式配置与服务端要求不匹配（比如服务端要求双向证书认证，客户端未配置客户端证书）。
• 协议版本不兼容：服务端仅支持TLS 1.2及以上版本，客户端JDK默认启用了已废弃的SSLv3、TLS 1.0/1.1协议，握手阶段协议版本协商失败。
• 证书配置问题：服务端使用自签名证书但未在客户端配置信任规则，或者服务端证书链不完整、证书域名与连接地址不匹配，导致握手阶段证书校验失败。
• 驱动版本bug：低版本PostgreSQL JDBC驱动存在SSL握手逻辑兼容问题，与高版本PostgreSQL服务端交互时会触发报文解析错误。

修复方案 #

1. 校验服务端SSL配置
   登录PostgreSQL服务端，检查数据目录下postgresql.conf配置，确认ssl = on，且ssl_cert_file、ssl_key_file指向的服务端证书、私钥文件存在，Postgres进程对文件有读取权限；再检查pg_hba.conf中对应客户端来源的准入规则，对应条目需配置为hostssl类型，配置修改完成后重启PostgreSQL服务生效。如果服务端无SSL连接需求，直接删除客户端连接串中ssl=true相关配置，使用非SSL方式连接即可。
2. 核对客户端连接参数
   SpringBoot配置文件中数据库连接地址、端口、SSL参数需与服务端配置对齐，标准SSL连接配置参考：

   spring:
     datasource:
       url: jdbc:postgresql://数据库地址:SSL服务端口/数据库名?ssl=true&sslmode=require
       driver-class-name: org.postgresql.Driver
   

   测试环境可临时将sslmode设为require跳过证书校验快速定位问题，生产环境建议设置为verify-ca或verify-full，同时通过sslrootcert参数指定服务端根证书路径，强制校验证书合法性。
3. 处理版本兼容问题
   将PostgreSQL JDBC驱动升级到42.2.x及以上稳定版本，同时确认应用运行的JDK版本支持的TLS版本与服务端开放版本匹配。如果服务端仅支持TLS 1.2+，可在应用启动参数中添加如下配置，强制客户端使用对应TLS版本：

   -Djdk.tls.client.protocols=TLSv1.2,TLSv1.3
   

4. 配置证书信任规则
   如果服务端使用自签名SSL证书，可将服务端根证书导入JDK默认信任库cacerts，或者直接在JDBC连接串中通过sslrootcert参数指定根证书本地路径，避免证书校验拦截握手流程。

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