证书链不完整(Incomplete Chain)检测与修复:从 curl 报错到 fullchain 正确部署
问题背景与根因:为什么浏览器打得开,程序却报错
TLS 握手时,服务器必须在 Certificate 消息里一次性下发整条证书链:叶子证书(站点证书)→ 签发它的中间证书(可能有多级)。根证书不发送,因为它必须已经存在于客户端信任库中。RFC 8446 明确要求证书按「叶子 → 中间」的顺序排列。
线上绝大多数「证书链不完整」事故,根因只有一个:运维只把 your_domain.crt 配到了服务器,压缩包里那个 ca_bundle.crt(中间证书)被忽略了。
为什么桌面浏览器看起来正常?因为 Chrome / Firefox / Edge 在验证失败时,会读取叶子证书里的 AIA(Authority Information Access)扩展,主动去 HTTP 下载缺失的中间证书并缓存。于是同一台服务器出现「浏览器能开、程序报错」的经典现象:
| 客户端 | 是否自动补链(AIA) | 典型表现 |
|---|---|---|
| Chrome / Firefox / Edge | 是,且本地缓存 | 正常打开,甚至不显示警告 |
| curl / OpenSSL | 否 | curl: (60) unable to get local issuer certificate |
| Java(HttpClient / OkHttp) | 否(默认关闭) | PKIX path building failed |
| Node.js(https / axios) | 否 | UNABLE_TO_VERIFY_LEAF_SIGNATURE |
| Android 原生 TLS | 否 | Trust anchor for certification path not found |
| 微信小程序 / 公众号 | 否 | request:fail ssl handshake error |
顺便修正两个被旧文章写错的时效事实:自 2020-09-01 起,公开信任 CA 签发的 TLS 证书最长有效期 398 天(Apple / Chrome 强制执行),Let’s Encrypt 仍为 90 天;按 CA/B Forum SC-081 时间表,2026-03-15 起上限降至 200 天,2027-03-15 降至 100 天,2029-03-15 降至 47 天。续期越频繁,「新证书忘了带中间证书」暴露的概率越高,链检测必须自动化。
第二个常见根因是顺序错误或混入根证书:顺序写反(中间在前、叶子在后)会报 error 2 at 1 depth lookup;把根证书一起打包会让握手包多出 1~2 KB,个别老客户端报 self-signed certificate in certificate chain。
第一步:用 openssl 一分钟判定证书链是否完整
-servername 必须带上,否则多站点共用 IP 时会命中默认 vhost 的证书,导致误判。
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| grep -E 'depth=|verify error|Verify return code'
判定标准:
Verify return code: 0 (ok)且出现 depth=0/1(多级中间证书还有 depth=2)→ 链完整。Verify return code: 21 (unable to verify the first certificate)→ 只下发了叶子证书,缺中间证书,最典型。Verify return code: 20 (unable to get local issuer certificate)→ 链断裂或本机缺对应根证书。Verify return code: 10 (certificate has expired)→ 中间证书过期,叶子证书却可能没过期。
统计服务端实际下发的证书张数,返回 1 就是故障:
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| grep -c 'BEGIN CERTIFICATE'
离线校验本地文件(适合放进 CI 或续期钩子):
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted chain.pem leaf.pem
# leaf.pem: OK
# 失败示例:error 2 at 1 depth lookup: unable to get issuer certificate
-untrusted 就是中间证书文件,-CAfile 是根证书。再看叶子证书的 AIA,它会告诉你该去哪里下载中间证书:
openssl x509 -in leaf.pem -noout -text | grep -A4 'Authority Information Access'
# CA Issuers - URI:http://cacerts.example-ca.com/xxxx.crt
批量巡检脚本,可直接放进定时任务:
for d in a.example.com b.example.com; do
printf '%s: ' "$d"
openssl s_client -connect $d:443 -servername $d -verify_return_error </dev/null 2>&1
| grep -q 'Verify return code: 0' && echo OK || echo FAIL
done
第二步:从 CA 拿对文件,正确组装 fullchain
CA 下载页通常一次给四五个文件,命名各家不同,先认清它们:
| 文件名(示例) | 内容 | 是否部署 |
|---|---|---|
| your_domain.crt / certificate.crt | 叶子证书 | 需要,但单发它一定报错 |
| ca_bundle.crt / intermediate.crt / chain.crt | 中间证书 1~2 张 | 需要,必须拼在叶子后面 |
| fullchain.crt / fullchain.pem | 叶子 + 全部中间 | 直接用,最省事 |
| root.crt / ca.crt | 根证书 | 不要部署 |
手动拼接并校验(顺序不能反):
cat your_domain.crt intermediate.crt > fullchain.pem
grep -c 'BEGIN CERTIFICATE' fullchain.pem # 应为 2 或 3
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
正常输出应能看到「叶子 subject = example.com,issuer = 中间 CA」以及「中间 CA 的 subject / issuer」。若中间证书本身有交叉签名(例如同一张中间证书同时由新根与旧根签发),只保留一条路径上的中间证书,不要两条都塞进去,否则部分客户端会走错路径。
Let’s Encrypt / certbot 用户不用自己拼,/etc/letsencrypt/live/example.com/ 下已经有现成文件:fullchain.pem(叶子 + 中间)、chain.pem(仅中间)、cert.pem(仅叶子)、privkey.pem(私钥)。Nginx 和 Apache 2.4.8+ 都指向 fullchain.pem。注意续期后文件会更新,必须 reload 服务。
三个易踩的坑:通配符证书的 fullchain 里只有一张叶子,不能和单域名证书混拼;证书有效期上限 398 天(Let’s Encrypt 90 天),中间证书的 notAfter 可能早于叶子证书,续期时要整体替换;从 CDN / WAF 控制台下载的包通常已是 fullchain,但仍要用上面的 grep 数一遍确认。
第三步:Nginx / Apache / Tomcat / Node.js 部署 fullchain
Nginx:ssl_certificate 指向 fullchain,而不是 leaf。
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 叶子+中间,顺序固定
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem; # 仅供 OCSP stapling 校验
ssl_stapling on;
ssl_stapling_verify on;
ssl_protocols TLSv1.2 TLSv1.3;
}
# nginx -t && systemctl reload nginx
Apache:2.4.8 及以上直接把 fullchain 写进 SSLCertificateFile;2.4.8 之前(如 CentOS 7 自带的 httpd 2.4.6)必须额外指定 SSLCertificateChainFile。
SSLCertificateFile /etc/httpd/ssl/fullchain.crt
SSLCertificateKeyFile /etc/httpd/ssl/privkey.key
# httpd < 2.4.8 才需要下面这行,2.4.8+ 加了会导致中间证书重复下发
# SSLCertificateChainFile /etc/httpd/ssl/chain.crt
# httpd -t && systemctl reload httpd
Tomcat / Java:必须把链打进 PKCS12,只导叶子证书照样握手失败。
openssl pkcs12 -export -inkey privkey.pem -in fullchain.pem
-certfile chain.pem -name tomcat -out keystore.p12 -passout pass:changeit
keytool -list -v -keystore keystore.p12 -storepass changeit | grep -E 'Alias|Certificate[|Owner|Issuer'
<Connector port='443' protocol='org.apache.coyote.http11.Http11NioProtocol' SSLEnabled='true'>
<SSLHostConfig>
<Certificate certificateKeystoreFile='/opt/tomcat/conf/keystore.p12'
certificateKeystorePassword='changeit'
certificateKeystoreType='PKCS12' />
</SSLHostConfig>
</Connector>
Node.js:cert 字段必须是 fullchain;HAProxy:bind *:443 ssl crt /etc/haproxy/site.pem,其中 site.pem 的拼接顺序是私钥 → 叶子 → 中间。改完务必用第二步的命令复测,不要凭重启成功就认为配置正确。
第四步:服务器与客户端配置对照表
下表把常见服务的「正确写法」和「高频错法」放一起对照,排障时可以直接按行核对。
| 服务 | 关键配置项 | 文件内容要求 | 典型错误 |
|---|---|---|---|
| Nginx | ssl_certificate | 叶子 + 中间 | 只配 leaf,curl 报 60 |
| Apache ≥ 2.4.8 | SSLCertificateFile | 叶子 + 中间 | 又配 ChainFile,中间证书重复 |
| Apache < 2.4.8 | SSLCertificateFile + SSLCertificateChainFile | 两个文件分开 | 漏配 ChainFile |
| Tomcat | certificateKeystoreFile | PKCS12 内含完整链 | keytool 只导入叶子 |
| Node.js | cert | 叶子 + 中间 | 只给 leaf.pem |
| HAProxy | crt | 私钥 + 叶子 + 中间 | 拼接顺序错 |
| IIS | 服务器证书 | .pfx 含链 | 用 .cer 导入 |
客户端侧同样需要一张对照表,用来解释「为什么同一个域名在不同程序里表现不同」:
| 客户端 | 信任库位置 | 是否 AIA 补链 |
|---|---|---|
| curl / OpenSSL | Debian/Ubuntu: /etc/ssl/certs/ca-certificates.crt;RHEL: /etc/pki/tls/certs/ca-bundle.crt | 否 |
| Java | $JAVA_HOME/lib/security/cacerts | 否 |
| Node.js | 内置 Mozilla CA(可用 NODE_EXTRA_CA_CERTS 追加) | 否 |
| Android | /system/etc/security/cacerts | 否 |
| Chrome / Firefox | 系统或内置 CA | 是 |
结论很直接:浏览器能打开不能作为验收标准。验收必须用 openssl s_client、curl 或 SSL Labs 这类不做 AIA 补链的路径。另外,Java 客户端如果连的是内网自签 CA,正确做法是把根证书 keytool -importcert -alias corp-root -file root.crt -keystore $JAVA_HOME/lib/security/cacerts 导入 cacerts,而不是在代码里 trustAll。
第五步:常见错误与真实报错对照排查
下面是线上最常抓到的原始报错,可以直接对照定位:
# curl
curl: (60) SSL certificate problem: unable to get local issuer certificate
# Java
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
# Node.js
Error: unable to verify the first certificate
code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'
# Python requests
SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
unable to get local issuer certificate (_ssl.c:1007)'))
# Android
javax.net.ssl.SSLHandshakeException: java.security.cert.CertPathValidatorException:
Trust anchor for certification path not found.
# 微信小程序
request:fail ssl handshake error
这六条报错指向同一个根因:服务端没下发中间证书。用 curl --cacert 或代码里加 trustAll 都是掩盖问题,必须修服务端。
openssl verify 的错误码能进一步区分细节:
| 报错 | 含义 | 修复动作 |
|---|---|---|
| error 20 at 0 depth lookup: unable to get local issuer certificate | 只发了叶子 | 配置 fullchain |
| error 2 at 1 depth lookup: unable to get issuer certificate | 链中缺一级中间证书 | 补全 ca_bundle |
| error 10 at 1 depth lookup: certificate has expired | 中间证书过期 | 整体替换 fullchain |
| error 19 at 0 depth lookup: self-signed certificate in certificate chain | 把根证书塞进了 fullchain | 移除根证书 |
| error 62 at 0 depth lookup: hostname mismatch | 证书 SAN 不含该域名 | 换证书或改 server_name |
还有一种「配置看起来对但依然报错」的情况:多 vhost 共用 443,server_name 写错导致 SNI 命中默认站点证书;或者 CDN 回源时只配了源站证书、边缘节点证书链没更新。排查时先在源站直连测一遍,再经 CDN 测一遍,对比 openssl s_client 输出的 subject 是否一致,就能定位是哪一段断链。
第六步:修复后的验证清单
改完配置后逐条执行,全部通过才能上线:
# 1. 严格校验(最关键的一条)
openssl s_client -connect example.com:443 -servername example.com
-verify_return_error -verify_hostname example.com </dev/null
# 期望最后一行:Verify return code: 0 (ok)
# 2. 下发证书数量,应 ≥ 2
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| grep -c 'BEGIN CERTIFICATE'
# 3. curl 视角,期望输出 200 0
curl -sSI https://example.com -o /dev/null -w '%{http_code} %{ssl_verify_result}n'
# 4. Java 视角,应列出叶子与中间两张的 Owner / Issuer
keytool -printcert -sslserver example.com:443 | grep -E 'Owner|Issuer'
# 5. Node.js 视角
node -e "require('tls').connect({host:'example.com',port:443,servername:'example.com',rejectUnauthorized:true},()=>{console.log('TLS OK');process.exit(0)}).on('error',e=>{console.error(e.code);process.exit(1)})"
最后用 SSL Labs 复核,页面上的 Chain issues 一栏应为 none,评级 A 或 A+:
curl -s 'https://api.ssllabs.com/api/v3/analyze?host=example.com&all=ready&fromCache=on'
| jq '.endpoints[0].details.cert.chain'
把检测固化成日常监控,避免下次续期再翻车:
# 每日巡检
0 3 * * * /usr/bin/openssl s_client -connect example.com:443 -servername example.com -verify_return_error </dev/null 2>&1 | grep -q 'Verify return code: 0' || echo 'chain broken' | mail -s alert ops@example.com
# certbot 续期后自动 reload
# /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
#!/bin/sh
nginx -t && systemctl reload nginx
注意:-verify_return_error 会让 openssl 在验证失败时以非零状态退出,这正是监控脚本需要的信号;不加这个参数,即使链不完整 openssl 也可能正常打印完握手信息并返回 0。
常见问题
不是。Chrome、Firefox 会读取证书里的 AIA 扩展,自动下载缺失的中间证书并缓存,把问题掩盖掉。curl、Java、Node.js、Android、微信小程序都不做 AIA 补链,会直接握手失败。验收必须用 openssl s_client 或 SSL Labs,而不是看浏览器地址栏。
不需要。服务器只需下发叶子证书和全部中间证书,根证书客户端信任库里本来就有。把根证书塞进 fullchain 会让握手包多出 1~2 KB,个别客户端还会报 self-signed certificate in certificate chain(openssl error 19)。
在 /etc/letsencrypt/live/你的域名/ 目录下:fullchain.pem 是叶子加中间证书,chain.pem 只有中间证书,cert.pem 只有叶子证书,privkey.pem 是私钥。Nginx 的 ssl_certificate 指向 fullchain.pem,ssl_certificate_key 指向 privkey.pem。
不需要。2.4.8 起 SSLCertificateFile 可以直接读取叶子加中间证书的合并文件;此时再配 SSLCertificateChainFile 会导致中间证书重复下发。CentOS 7 自带的 httpd 2.4.6 低于该版本,仍必须单独配置 ChainFile。
会,一样失败,报 certificate has expired(openssl error 10)。中间证书的有效期可能早于叶子证书,续期时必须整体替换 fullchain,并用 openssl crl2pkcs7 逐张打印 notAfter 确认没有过期的那一张。
自 2020-09-01 起,公开信任 CA 签发的 TLS 证书最长 398 天,Let’s Encrypt 仍为 90 天。按 CA/B Forum SC-081 时间表,2026-03-15 起降至 200 天,2027-03-15 降至 100 天,2029-03-15 降至 47 天,续期会更频繁。