解决 Apache/WAF SSL 证书链不完整导致的 PKIX path building failed 问题

---

解决 Apache/WAF SSL 证书链不完整导致的 PKIX path building failed 问题

在日常运维或开发中，很多人都会遇到一个棘手的 SSL 错误：

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException:
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target

这种错误通常出现在 Java 客户端（例如 Spring Boot、OkHttp、HttpClient）调用 HTTPS 接口时，而浏览器访问同一个地址却完全正常。这种情况大概率是 证书链不完整 导致的。

---

为什么会出现证书链错误？

SSL/TLS 证书通常并不是直接由操作系统信任的根证书颁发的，而是经过一层或多层 中间证书 (Intermediate CA) 过渡：

站点证书 (Leaf, 例如 *.example.com)↓
中间证书 (Intermediate CA)↓
根证书 (Root CA, 操作系统或 Java 自带)

浏览器一般会自动补全缺失的中间证书，所以肉眼访问是正常的。但 Java 客户端更严格，要求服务端必须下发完整的证书链。如果 WAF/Apache 配置中只返回了站点证书，就会导致 PKIX path building failed 错误。

---

常见场景

直连服务器正常，但经过 WAF 出错

• 直连服务器：服务器证书配置完整，包括站点证书和中间证书，客户端验证成功。
• 经过 WAF：只返回了站点证书，缺少中间证书，导致 Java 客户端报错。

Windows/Linux 下证书文件说明

以常见的证书文件为例：

• example.com.crt → 网站的站点证书 (Leaf)
• example.com.key → 私钥
• bundle.crt → 中间证书集合 (Intermediate Chain)

如果只在 Apache/WAF 配置里加载 example.com.crt，客户端就会缺失中间证书。

引入 WAF 或其他中间层：

有些 WAF 或反向代理只下发了服务器证书，却没有完整传递中间证书链。结果就是直连服务器没问题，但通过 WAF 访问时会提示 x509: certificate signed by unknown authority。

---

解决方法

方法一：单独配置 ChainFile（推荐）

在 Apache 配置中增加：

SSLCertificateFile      /path/to/example.com.crt
SSLCertificateKeyFile   /path/to/example.com.key
SSLCertificateChainFile /path/to/bundle.crt

注意：SSLCertificateChainFile 在 Apache 2.4.8 之后被废弃，但很多 WAF 或旧版本仍然支持。

---

方法二：拼接成 fullchain.crt（通用,博主使用的）

如果 WAF/CDN/SLB 只允许上传一个证书文件，可以把站点证书和中间证书拼接到一起：

cat example.com.crt bundle.crt > fullchain.crt

Windows PowerShell 下：

Get-Content example.com.crt, bundle.crt | Set-Content fullchain.crt

然后配置：

SSLCertificateFile    /path/to/fullchain.crt
SSLCertificateKeyFile /path/to/example.com.key

这样服务端就会完整下发证书链，Java 客户端验证就不会报错。

---

方法三：导入中间证书到 Java（临时方案）

如果短期内不能修改 WAF 配置，也可以在 Java 环境中导入中间证书：

keytool -import -alias intermediate-ca \-keystore $JAVA_HOME/jre/lib/security/cacerts \-file bundle.crt

默认密码是 changeit。

这种方法不推荐长期使用，因为每台客户端都要单独导入。

---

验证配置是否正确

配置完成后，可以用 OpenSSL 验证：

openssl s_client -connect example.com:443 -showcerts

如果能看到：

0 s:/CN=*.example.com
1 i:/CN=Intermediate CA
2 i:/CN=Root CA

说明证书链完整，Java 客户端访问就不会报错了。

---

总结

• PKIX path building failed 错误本质是 缺少中间证书。
• 直连正常、过 WAF 报错，说明 WAF 配置的证书不完整。
• 最推荐的做法是 在 WAF/Apache 上配置完整证书链（ChainFile 或 fullchain.crt）。
• 验证方法：使用 openssl s_client -showcerts 查看完整链。

这样就能避免 Java 调用 HTTPS 接口时遇到 SSLHandshakeException。

---

✅ 小贴士：配置证书时，最好直接使用 CA 提供的 fullchain.crt 文件（已经包含了站点证书 + 中间证书），避免手动拼接出错。