跳到主要内容

证书链不完整(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 天,续期会更频繁。