---

解決 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 文件（已經包含了站點證書 + 中間證書），避免手動拼接出錯。