跳到主要内容

证书链不完整(Incomplete Chain)检测与修复:fullchain 部署与报错排查

问题背景:浏览器能打开,为什么 curl、Java、小程序却报错

证书链不完整(Incomplete Chain)最典型的症状是:桌面浏览器打开正常,curl、Java、Node.js、Android、微信小程序却握手失败。原因不是证书本身无效,而是服务器只下发了站点叶子证书,没有下发中间证书。桌面浏览器可能缓存过该中间证书,或通过证书 AIA 地址补链;命令行与移动端通常只依赖服务端实际发送的链和本地信任库,缺一环就报错。常见报错包括 curl: (60) SSL certificate problem: unable to get local issuer certificate、Java 的 PKIX path building failed、Node 的 UNABLE_TO_VERIFY_LEAF_SIGNATURE,以及小程序 request:fail ssl hand shake error。另一个高发场景是续期:公开信任 TLS 证书最长有效期为 398 天,Let’s Encrypt 证书默认 90 天,续期脚本若把 cert.pem 而不是 fullchain.pem 写进配置,就会出现“刚续期就报错”。因此排查时先看服务端证书链,再看客户端信任库,不要用 -k 或关闭校验掩盖问题。

根因拆解:叶子证书、中间证书与信任锚的关系

一条完整的 TLS 证书链由叶子证书、中间证书和根证书组成。叶子证书绑定域名,签发者是中间证书;中间证书的签发者是根证书;根证书预置在操作系统或运行时的信任库中。服务端应发送叶子证书和全部中间证书,根证书通常不需要发送,因为客户端本地已有。判断是否缺链,不要只看浏览器地址栏,要看服务端实际下发的证书数量与顺序。常见错误有:Nginx 的 ssl_certificate 指向 cert.pem 而非 fullchain.pem;Apache 2.4.7 及更早版本漏配 SSLCertificateChainFile;Tomcat 导入 JKS/PKCS12 时只导入叶子证书;Node.js 的 cert 选项只读入站点证书;手动 cat 时把中间证书放在叶子证书前面。正确顺序是叶子证书在前,中间证书在后,可包含交叉签名证书,但不要依赖客户端去 AIA 拉取。中间证书本身也会过期,续期或更换 CA 后要重新核对链。排查时可用 openssl x509 -in fullchain.pem -noout -subject -issuer -dates 逐张查看,或 openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout 列出链中每张证书的 subject 和 issuer。若 issuer 与上一张 subject 对不上,说明顺序或文件错误。

检测步骤:三条命令判断是否缺中间证书

先设置域名变量,避免手误。执行:

DOMAIN=example.com
openssl s_client -connect ${DOMAIN}:443 -servername ${DOMAIN} -showcerts </dev/null 2>/dev/null | grep -E 'depth=|verify error|Verify return code'

若输出 Verify return code: 0 (ok),说明本机信任库能验证通过;若出现 verify error:num=20:unable to get local issuer certificate 或 21 (unable to verify the first certificate),高度怀疑缺中间证书。必须带 -servername,否则多域名服务器可能返回默认站点证书。继续统计服务端下发证书数量:

openssl s_client -connect ${DOMAIN}:443 -servername ${DOMAIN} -showcerts </dev/null 2>/dev/null | awk '/BEGIN CERTIFICATE/{n++} END{print n}'

正常应大于等于 2,即叶子证书加至少一张中间证书;只有 1 张通常就是不完整链。再用 curl 复现:

curl -vI https://${DOMAIN}

若报 curl: (60) SSL certificate problem: unable to get local issuer certificate,与 openssl 结果相互印证。注意不要在客户端用 –insecure 或 -k 作为修复。

修复实操:获取 fullchain 并替换部署文件

Let’s Encrypt/Certbot 用户先确认文件:

sudo certbot certificates
sudo ls -l /etc/letsencrypt/live/example.com/
sudo grep -c 'BEGIN CERTIFICATE' /etc/letsencrypt/live/example.com/fullchain.pem

fullchain.pem 是叶子加中间证书,cert.pem 只有叶子证书,生产配置应使用 fullchain.pem。手动证书用户从 CA 下载包含中间证书的压缩包,按叶子在前、中间在后的顺序合并:

cat example.com.crt intermediate.crt > fullchain.pem
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted intermediate.crt example.com.crt

最后一行期望输出 example.com.crt: OK。若失败,先检查 intermediate.crt 是否与叶子证书的签发者匹配,再检查系统 CA 包路径。替换配置后先做语法检查再平滑重载:

sudo nginx -t && sudo systemctl reload nginx
sudo apachectl configtest && sudo systemctl reload httpd

Certbot 自动续期默认使用 fullchain.pem,但自定义 deploy hook 要确认 reload 的是新文件。公开证书最长 398 天、Let’s Encrypt 90 天,续期后必须复测链,不能只看到期时间。

配置示例:Nginx、Apache、Tomcat 与 Node.js

Nginx 推荐直接指向 fullchain.pem,并保留 chain.pem 给 OCSP stapling 使用:

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;
    ssl_protocols TLSv1.2 TLSv1.3;
}

Apache 2.4.8 及以上把叶子与中间证书合并到 SSLCertificateFile:

SSLCertificateFile /etc/httpd/ssl/fullchain.pem
SSLCertificateKeyFile /etc/httpd/ssl/privkey.pem
# Apache 2.4.8+ 不再需要 SSLCertificateChainFile

Tomcat 用 PKCS12 导入完整链:

openssl pkcs12 -export -inkey privkey.pem -in fullchain.pem -name tomcat -out keystore.p12

在 server.xml 的 SSLHostConfig 中指定:

<SSLHostConfig certificateKeystoreFile='/opt/tomcat/conf/keystore.p12' certificateKeystorePassword='changeit' certificateKeystoreType='PKCS12' />

Node.js 的 cert 必须读 fullchain.pem:

const https = require('https');
https.createServer({key: fs.readFileSync('privkey.pem'), cert: fs.readFileSync('fullchain.pem')}, app).listen(443);

配置完成后先 reload,再执行 openssl 检测,不要只重启进程不验证。

方案对比:仅叶子证书、fullchain 与手动合并

不同部署方式对客户端兼容性差异很大,选型时可参考下表:

方案 文件内容 兼容性 结论
仅 cert.pem 叶子证书 浏览器可能靠缓存或 AIA 通过,curl/Java/Node 易失败 不推荐
fullchain.pem 叶子加全部中间证书 桌面、移动端、命令行均稳定 推荐
手动 cat 合并 叶子加中间证书 顺序正确时同 fullchain 可用,需 verify
包含根证书 叶子加中间加根 多数客户端忽略根,包体增大 通常不需要
Apache ChainFile 独立中间证书文件 仅旧版本需要 2.4.8+ 用 fullchain

选择时抓住两点:服务端必须把中间证书随叶子证书一起发送;客户端信任库只负责根证书。fullchain.pem 不是“把根也塞进去”,而是保证叶子到根的路径在服务端侧完整。若使用 CDN 或负载均衡,源站配置正确不代表边缘节点正确,要在 CDN 控制台上传完整链或开启对应选项。证书有效期方面,公开信任 TLS 证书最长 398 天,Let’s Encrypt 为 90 天,续期后同样要检查链文件是否被覆盖。

常见错误排查:真实报错与处理

按真实报错定位,处理顺序是“先修服务端链,再查客户端信任库”:

  • curl: (60) SSL certificate problem: unable to get local issuer certificate:服务端缺中间证书。部署 fullchain.pem,执行 nginx -t 后 reload,不要用 -k。
  • Java:javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target:先确认服务端发送链数量≥2;若为私有 CA,把根证书导入 cacerts,命令为 keytool -importcert -alias private-root -file root.crt -keystore $JAVA_HOME/lib/security/cacerts。
  • Node.js:UNABLE_TO_VERIFY_LEAF_SIGNATURE 或 unable to get local issuer certificate:cert 选项只读了叶子证书,改成 fullchain.pem。
  • Android/微信小程序:request:fail ssl hand shake error:常见于缺中间证书、SNI 未命中、域名不匹配。用 SSL Labs 和 openssl -servername 复测。
  • openssl 报 verify error:num=20 或 21:检查是否带 -servername、链顺序是否叶子在前、中间证书是否过期。

若修复后仍失败,用 openssl s_client -showcerts 保存服务端实际链,再与本地 fullchain.pem 逐张比对 subject 和 issuer。不要通过关闭证书校验、把叶子证书当根证书导入来绕过,这会在续期后再次失效。

效果验证:SSL Labs、openssl 与多客户端复测

修复后做三层验证。第一层看 openssl 是否验证通过:

openssl s_client -connect example.com:443 -servername example.com -verify_hostname example.com -verify_return_error </dev/null

期望看到 Verify return code: 0 (ok)。若仍报 20/21,回到服务端链继续排查。第二层看链数量与有效期:

openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'
openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -subject -issuer -dates
openssl x509 -in fullchain.pem -noout -subject -issuer -dates

证书数量应≥2,notAfter 应在有效期内,且公开证书剩余有效期不超过 398 天。第三层做客户端复测:curl -vI https://example.com 不再报 60;Java 发起 HTTPS 请求不再 PKIX;Node 用 https.get 测试;Android 与微信小程序真机打开。最后用 SSL Labs 扫描,Chain issues 应为 none,Certificate is not trusted 不应出现。若有 CDN,清缓存或刷新证书后等待边缘节点生效,再复测。

常见问题

浏览器可能缓存了中间证书或通过 AIA 补链,curl 主要依赖服务端实际发送的链和本地信任库。缺中间证书时就会报错。部署 fullchain.pem 后重载服务,不要用 -k 关闭校验。


cert.pem 通常只有站点叶子证书,fullchain.pem 包含叶子证书和全部中间证书。Nginx、Apache、Tomcat、Node.js 生产配置应使用 fullchain.pem;Let’s Encrypt 续期后也要确认配置仍指向 fullchain.pem。


通常不需要。服务端发送叶子证书和中间证书即可,根证书应预置在客户端信任库。把根证书一起下发不会提升兼容性,反而增大握手包,部分客户端还会忽略。关键是叶子到根的中间环节不能缺。


先确认服务端实际发送证书数量≥2且叶子在前,再查客户端信任库是否缺根证书、中间证书是否过期。私有 CA 需把根证书导入 Java cacerts。不要只改客户端,先修服务端链。


执行 openssl s_client 带 -servername 和 -verify_return_error,看到 Verify return code: 0 (ok);统计证书数量≥2;curl 不再报 60;SSL Labs 的 Chain issues 为 none;再用 Java、Node、小程序复测。


公开信任 TLS 证书最长 398 天,Let’s Encrypt 默认 90 天。续期后必须重新加载服务并确认仍使用 fullchain.pem,同时复测链数量与 Verify return code,避免续期脚本把配置改回仅叶子证书。