Java 第三方 HTTPS 接口 PKIX path building failed 解决方案

在 Java 开发中，通过 RestTemplate 或 HttpClient 调用第三方 HTTPS 接口时，偶尔会碰到如下异常堆栈：

这个报错非常典型，尤其容易出现在对接政务网、专网、企业私有云或自定义 CA 签发证书的场景下。本文梳理一下背后的成因以及生产环境的标准解决方案。

---

一、 报错原因分析

HTTPS 通信建立时，Java 会校验目标服务器返回的 SSL 证书合法性。

Java 运行环境（JRE）内置了一个名为 cacerts 的密钥库，存放了受信任的根证书列表。当目标服务器的证书不是由知名的公共 CA 机构颁发（或者属于私有/自签名证书、中间证书链不完整）时，JVM 在本地的 cacerts 里找不到对应的信任链，就会直接拒绝连接并抛出 PKIX path building failed。

---

二、 解决方案

解决此问题通常有两种途径：运维层面导入证书（推荐） 和 代码层面绕过校验（应急方案）。

方案 1：向 JVM 信任库导入目标证书（首选）

这是最标准、最安全的做法。不需要修改任何业务代码，直接将对方接口的证书导入到运行当前 Java 项目的 JRE cacerts 库中。

第一步：在 Linux 服务器上直接抓取目标证书

无需在本地用浏览器导出再上传服务器，在 Linux 终端通过 openssl 即可一键拉取目标网站的证书：

(将 api.your-domain.com 替换为目标接口域名或 IP)

第二步：使用 keytool 导入 JRE 的 cacerts

确定服务正在使用的 JDK/JRE 路径，执行导入命令：

• 默认密码：JRE cacerts 的默认口令一般为 changeit（输入时屏幕不显示字符，盲打后按回车）。
• 交互确认：当终端提示 Trust this certificate? [no]: 时，输入 y 并回车。

第三步：重启 Java / Tomcat 服务

导入成功后，必须重启应用服务，JVM 重新载入 cacerts 后，HTTPS 请求即可恢复正常。

---

方案 2：代码层重构 RestTemplate 跳过 SSL 校验（应急/测试环境）

如果是在测试环境，或者无法立即获取服务器终端权限，可以通过配置让 RestTemplate 忽略 SSL 证书校验。

跳过 SSL 检查的工具代码实现：

在发起请求的方法中，改用此 Factory 生成的 RestTemplate 即可解决报错。

---

三、 总结

1. 环境与 JRE 路径要对齐：一台服务器上可能安装了多个 JDK 或 JRE。在导入证书前，务必通过 ps -ef | grep java 或查看环境变量，确认运行当前 Tomcat/Jar 包的到底是哪一个 JRE 路径，否则导入错地方依然会报错。
2. 不要盲目修改框架安全策略：线上生产环境建议优先使用方案 1（导入证书）。直接在代码里关闭 SSL 全局校验会带来潜在中间人攻击的安全风险，除非是内部高度信任的闭环专网环境。