Java 请求 HTTPS 报 PKIX path building failed：从证书链到 truststore 的完整排查

先看懂：这个错误到底在说什么

Java 服务调用 HTTPS 接口时，如果日志里出现 javax.net.ssl.SSLHandshakeException，并且原因链里有 SunCertPathBuilderException: unable to find valid certification path to requested target，通常不是"网络不通"，而是客户端无法从服务器发来的证书链走到自己信任的根证书。

这里的关键字是 truststore。JSSE 会通过 trust manager 做对端身份校验；服务器证书能在浏览器里打开，不代表运行该 Java 进程的 JDK 也信任它。浏览器、操作系统和 JVM，可能各自拿着不同的"通讯录"。

第一步：确认服务端发了什么证书

先在能访问目标域名的机器上执行，-servername 不要省略。多域名共用 IP 时，SNI 不同，服务端可能返回不同证书。

复制代码

openssl s_client -connect api.example.com:443 \
  -servername api.example.com -showcerts < /dev/null

重点看三件事：服务器证书的 SAN 是否包含请求主机名；中间证书是否由服务端一起发送；输出末尾的 Verify return code 是否异常。-showcerts 展示的是服务端发送的列表，不等于 OpenSSL 已经替你完成完整信任验证，所以还要结合客户端 truststore 判断。

第二步：确认 Java 用的是哪一个 JDK

很多"明明导入过证书"的问题，最后都落在导入了 A JDK，服务却跑在 B JDK。不要只看当前 Shell 的 java -version，要看启动脚本、systemd 的 ExecStart、容器镜像和进程实际路径。

复制代码

java -version
readlink -f "$(command -v java)"
ps -ef | grep '[j]ava'

# 查看某个 JDK 的默认信任库位置
JAVA_HOME=/opt/jdk-17
"$JAVA_HOME/bin/keytool" -list -cacerts -storepass changeit | head

如果应用显式设置了 -Djavax.net.ssl.trustStore=/path/custom.p12，默认的 cacerts 可能根本不会参与本次连接。JVM 参数、环境变量和容器启动参数要一起查，不能凭目录名猜。

第三步：判断是缺根证书、缺中间证书，还是导入错文件

现象	优先怀疑	验证方法
只有某个老 JDK 失败	根证书库过旧	对比实际 JDK 与 cacerts 内容
浏览器正常，Java 失败	Java truststore 不含对应信任链	读取 JVM 的 trustStore 参数
换了服务器证书后失败	服务端漏发中间证书	用 s_client 查看发送列表
导入后仍失败	导入了叶子证书、别名错误或改错 JDK	keytool -list 与进程参数交叉核对

不要看到 PKIX 就直接把服务器证书导入信任库。若服务端本应发送完整链，正确修复通常是补齐服务端链；客户端盲目导入叶子证书会增加维护成本，证书一换又要重新处理。

第四步：优先使用独立 truststore，别直接改全局 cacerts

对单个应用，建议创建专用 truststore，并在启动参数中显式指定。这样影响范围小，也方便回滚。下面示例使用 PKCS12；密码通过部署系统的安全方式注入，示例中的值不是生产凭据。

复制代码

keytool -importcert -noprompt \
  -alias partner-ca \
  -file partner-ca.crt \
  -keystore /etc/myapp/truststore.p12 \
  -storetype PKCS12 \
  -storepass '示例密码请替换'

java -Djavax.net.ssl.trustStore=/etc/myapp/truststore.p12 \
     -Djavax.net.ssl.trustStoreType=PKCS12 \
     -jar app.jar

导入前先核对指纹和证书用途，来源不明的证书不要因为"能通"就信任。Oracle 的 keytool 支持导入 X.509 证书或证书链；别名只是管理标识，真正的信任判断仍取决于证书链和 trust manager 的校验。

第五步：用 keytool 做可重复的验收

复制代码

keytool -list -v \
  -keystore /etc/myapp/truststore.p12 \
  -storetype PKCS12 \
  -storepass '示例密码请替换' \
  -alias partner-ca

验收时记录 Subject、Issuer、Validity、SAN（如果是服务端证书）和 SHA-256 指纹。不要只看"Entry type: trustedCertEntry"，因为别名存在不等于导入了正确证书。随后用与生产完全相同的启动参数发起一次真实 HTTPS 请求，再观察应用是否仍然抛出 PKIX 异常。

第六步：打开 JSSE 调试，但只在短时间内使用

如果前面仍无法定位，可临时增加 -Djavax.net.debug=ssl,handshake,trustmanager。Oracle 文档说明 JSSE 提供这一调试能力。日志通常会暴露正在加载的 truststore、收到的证书链以及信任判断过程。

复制代码

java -Djavax.net.debug=ssl,handshake,trustmanager \
     -Djavax.net.ssl.trustStore=/etc/myapp/truststore.p12 \
     -jar app.jar 2> /tmp/jsse-debug.log

# 只在本机分析，避免把调试日志直接上传到公共平台
awk '/trustStore|trustmanager|certificate chain|PKIX|handshake_failure/' \
    /tmp/jsse-debug.log | head -80

调试日志可能包含主机名、证书主题和连接细节，不要原样贴到工单或文章评论区。定位完成后移除调试参数，避免日志膨胀。

常见错误修法：为什么看似有效却不稳

**关闭校验：**自定义 TrustManager 信任全部证书，只是绕过问题，不是修复，生产环境不要这样做。
**只导入叶子证书：**短期可能恢复，续期或换 CA 后又会断；先修服务端证书链或导入明确的企业根 CA。
**改系统 cacerts：**会影响同一 JDK 上的其他应用，升级 JDK 还可能丢失变更；单应用优先独立 truststore。
**只重启应用：**如果启动参数仍指向旧路径，重启只是把错误再播放一遍。

最后用一张清单收口

用带 SNI 的 openssl s_client 读取服务端证书列表。
确认生产进程的 Java 路径、JVM 参数和实际 trustStore。
区分服务端缺中间证书与客户端缺受信根证书。
优先使用最小范围的独立 PKCS12 truststore，保存指纹和变更记录。
用 keytool 读回别名、Issuer、有效期和 SHA-256 指纹。
用真实 HTTPS 请求验收，再关闭 JSSE debug。

证书问题最怕"浏览器能开，所以 Java 也该能开"这句经验主义。把服务端发送链、JVM 启动参数和 truststore 内容三者放到同一张排障表里，PKIX 通常就不再神秘了。

参考资料

Oracle JSSE Reference Guide；Oracle keytool 文档；OpenSSL s_client 文档。