证书链不完整怎么解决?Nginx/Apache 补全中间证书实操指南
证书链不完整的解决办法是把「服务器证书 + 中间证书」按 leaf 在前、intermediate 在后的顺序合并为 fullchain.pem,并在 Web 服务器引用该文件(Nginx 用 ssl_certificate fullchain.pem),不要包含根证书;用 openssl s_client -connect 域名:443 -servername 域名 -showcerts 检查,Verify return code 应为 0 (ok)。 Let's Encrypt 用户直接使用 /etc/letsencrypt/live/example.com/fullchain.pem,不要用 cert.pem——后者只含 1 张叶子证书,缺少 R10/R11 中间证书,证书有效期 90 天,续期后依旧会缺链。 手工合并命令为 cat server.crt intermediate.crt > fullchain.pem,合并后用 openssl verify -CAfile root.crt -untrusted intermediate.crt server.crt 验证,返回 OK 才算正确。 curl 报 (60) unable to get local issuer certificate、Java 报 PKIX path building failed,八成是缺中间证书;在 SSL Labs 测试中会显示 Chain issues: Incomplete。 OCSP Stapling 依赖完整链,Nginx 需同时配置 ssl_stapling on、ssl_stapling_verify on 和 ssl_trusted_certificate chain.pem(Nginx 1.3.7+ 支持),否则 stapling 会静默失败。
证书链不完整是怎么引起的?先看清 leaf、中间证书与根证书的关系
“浏览器能打开、脚本却报证书错误”,常见根因不是证书无效,而是证书链没拼完整。按 RFC 5280 第 6 节,认证路径从服务器证书(leaf)出发,经中间证书逐级回溯到信任锚(根证书);RFC 8446 第 4.4.2 节的 certificate_list 只要求服务器发送 leaf 和中间证书,根证书不应随链下发,因为操作系统、浏览器和 JDK 信任库已预置。
| 层级 | 作用与内容 | 谁持有 | 握手是否发送 | Let’s Encrypt 对应文件 |
|---|---|---|---|---|
| leaf(服务器证书) | 域名、公钥、SAN | 你的服务器 | 必须 | cert.pem |
| intermediate(中间证书) | 由根或上级中间证书签发的 CA 证书 | 你的服务器随链下发 | 必须,缺则链断 | chain.pem |
| root(根证书) | 自签名信任锚 | OS、浏览器、JDK 信任库 | 不应发送 | 系统 ca-certificates,不在 live 目录 |
原因一:只部署了叶子证书。Certbot 默认目录中 cert.pem 只有 1 张证书,chain.pem 是中间证书,fullchain.pem 才是 leaf + 中间证书。据 Let’s Encrypt 文档,Nginx 的 ssl_certificate 应指向 fullchain.pem;若指向 cert.pem,即使 90 天自动续期成功,链依旧缺中间证书。先数一数:
# 适用 OpenSSL 1.1.1/3.x;grep -c 统计 PEM 证书块数量
grep -c 'BEGIN CERTIFICATE' /etc/letsencrypt/live/example.com/cert.pem # 通常输出 1:只有 leaf
grep -c 'BEGIN CERTIFICATE' /etc/letsencrypt/live/example.com/fullchain.pem # 通常输出 2:leaf + R10/R11(ECDSA 为 E5/E6)
原因二:合并顺序错或漏拼。正确顺序是 leaf → intermediate(可多张),不要拼 root。把中间证书放在前面,或把根证书一起拼进去,部分客户端会路径构建失败;Java 常见报错是 CertPathValidatorException: PKIX path building failed,早期 Java 8u 与 Android 4.4 对顺序和多余根证书尤其敏感。合并与验证可用:
# 顺序不能反:站点证书在前,中间证书在后;不要 cat 根证书
cat /etc/letsencrypt/live/example.com/cert.pem
/etc/letsencrypt/live/example.com/chain.pem
> /etc/ssl/example.com.fullchain.pem
# -untrusted 提供中间证书;verify 默认使用系统信任库
openssl verify -untrusted /etc/letsencrypt/live/example.com/chain.pem
/etc/letsencrypt/live/example.com/cert.pem
# 期望输出:cert.pem: OK
原因三:中间证书过期或与根不匹配。这里要区分两个日期:DST Root CA X3 本身已于 2021-09-30 过期,而 Let’s Encrypt 用它对 ISRG Root X1 做的交叉签名在 2024-09-30 到期。仍下发旧交叉链的站点,在老设备上会报 unknown issuer;应改用由 ISRG Root X1 签发的 R10/R11 链(ECDSA 为 E5/E6)。
为什么“浏览器能开、程序报错”?Chrome、Firefox 支持 RFC 5280 §4.2.2.1 定义的 AIA(Authority Information Access)扩展,能自动下载缺失的中间证书并缓存;curl、Python requests、Java、Go 默认不抓取 AIA,于是直接失败。用一条命令看服务器实际发了什么:
# OpenSSL 1.1.1/3.x;s_client 默认不主动用 -connect 的主机名做 SNI,需显式加 -servername
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| grep -E '^ *[0-9]+ s:|^ *i:'
# 正常应看到 leaf 的 i: 等于下一张中间证书的 s:,最后一张的 i: 指向 ISRG Root X1 等根
若只看到 0 s:CN = example.com 和 i:... R11,却没有 R11 自身证书,就是典型的链不完整。影响面不止网页:移动端 API、支付回调、Webhook、监控探针、gRPC 都会握手失败,日志常只有一句 SSLHandshakeException,或 curl 报 curl: (60) SSL certificate problem: unable to get local issuer certificate。要解决证书链不完整,最稳妥的是在发布流程中固化检查:部署后用 openssl s_client -showcerts 数证书张数,并用 openssl verify -untrusted 验证路径;容器最小镜像里若缺 ca-certificates,需用 -CAfile 显式指定信任库,否则会误判。
修复证书链不完整的 6 步实操流程(从定位到 reload)
证书链不完整怎么解决?不要靠猜。按下面 6 步走,每一步都有可验证的输出,最后以 reload 结束,全程不重启整机、不断开现有连接。
第 1 步:定位——服务器到底发了几张证书?
# 统计服务器在 TLS 握手中实际下发的证书数量
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 </dev/null 2>/dev/null
| tail -n 5
返回 1 说明服务器只发了叶子证书,中间证书缺失。-servername 必须显式指定,否则 SNI 虚主机场景会连到错误的默认站点,测出的结果是假阴性。输出末尾若出现 Verify return code: 21 (unable to verify the first certificate),即为缺中间证书的典型报错(该错误码定义见 OpenSSL verify 手册的 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY 相关条目)。
第 2 步:取得正确的中间证书
Let’s Encrypt 用户不必外找,/etc/letsencrypt/live/example.com/chain.pem 就是 certbot 落盘的中间证书链。商业 CA(DigiCert、GlobalSign、Sectigo)需从各自的 repository 下载 intermediate 包——注意选对交叉签名版本。拿到后核对签发关系:
openssl x509 -in chain.pem -noout -subject -issuer
# Subject 必须等于你叶子证书的 Issuer,否则拿错了中间证书
第 3 步:按 leaf → intermediate 顺序合并
cat server.crt chain.pem > fullchain.pem
# 列出链中每张证书的 subject/issuer,确认层级方向正确
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
顺序反了(intermediate 在前)在某些客户端上仍可握手成功,但严格的校验器会直接失败,所以务必按”叶子在前”拼接。根证书不要放进 fullchain.pem。
第 4 步:在文件层面验证合并结果
# 用指定根证书 + untrusted 中间链验证叶子证书
openssl verify -CAfile root.crt -untrusted chain.pem server.crt
# 期望输出:server.crt: OK
# 更贴近真实环境:用系统信任库验证,避免只在自签根下"自证清白"
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt fullchain.pem
第 5 步:替换配置并 reload
| Web 服务器 | 配置指令 | 语法检查 | 生效命令 |
|---|---|---|---|
| Nginx 1.19+ | ssl_certificate /path/fullchain.pem; |
nginx -t |
systemctl reload nginx |
| Apache httpd 2.4 | SSLCertificateFile(2.4.8+ 可直接指向 fullchain) |
apachectl configtest |
systemctl reload httpd |
Apache 2.4.8 之前需额外用 SSLCertificateChainFile 指定中间证书;该指令在 2.4.8 起被标记为 deprecated,2.4.8+ 推荐把整链写进 SSLCertificateFile。reload 只重载配置、保留监听套接字,现有连接不受影响。
第 6 步:复检
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null
| grep -c "BEGIN CERTIFICATE" # 期望 ≥ 2
curl -vI https://example.com 2>&1 | grep -i "SSL certificate verify"
链数应 ≥2,Verify return code 变为 0 (ok),curl 输出 SSL certificate verify ok,此时才算真正解决了证书链不完整问题。若仍是 21,优先检查 ssl_certificate 是否被写成了叶子证书而非 fullchain——这是实践中最常见的配置笔误。
Nginx、Apache、HAProxy、Tomcat 的配置片段与命令示例
把证书链补全落到具体服务上,各家要求的文件形态并不一样——有的要你给”叶子+中间”合并文件,有的要私钥也塞进同一个 PEM。下面按 Nginx、Apache、HAProxy、Tomcat 逐一给出可直接复制的片段,最后给一条通用的链路核对命令。
Nginx(1.24,1.11.0+ 支持同一 server 挂多张不同算法证书):ssl_certificate 指向的文件必须是叶子证书在前、中间证书在后的拼接结果,Nginx 会把这个文件里的证书按顺序全部发给客户端。很多人以为 ssl_trusted_certificate 能顺手修好链不完整,其实不行——据 Nginx 官方文档,它只用于 OCSP Stapling 和客户端证书验证,不参与发送给客户端。
server {
listen 443 ssl;
server_name example.com;
# 叶子 + 中间证书,按顺序拼接,Nginx 全量下发
ssl_certificate /etc/nginx/ssl/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
# 仅供 OCSP Stapling / 校验客户端证书,不发给浏览器
ssl_trusted_certificate /etc/nginx/ssl/chain.pem;
ssl_protocols TLSv1.2 TLSv1.3; # 默认值仅 TLSv1.2 TLSv1.3(1.23.4+)
ssl_stapling on;
ssl_stapling_verify on;
resolver 8.8.8.8 valid=300s;
}
# 改完先测语法再平滑重载
nginx -t && nginx -s reload
Apache 2.4.58:只需两个指令,把 fullchain 交给 SSLCertificateFile 即可。但 2.4.8 之前的版本 SSLCertificateFile 只认叶子证书,中间证书必须单独用 SSLCertificateChainFile 指定;该指令在 2.4.8+ 已弃用但仍兼容,混用时启动日志会出现 deprecated 提示。
<VirtualHost *:443>
ServerName example.com
SSLEngine on
# 2.4.8+:叶子+中间合并文件写这里
SSLCertificateFile /etc/httpd/ssl/fullchain.pem
SSLCertificateKeyFile /etc/httpd/ssl/privkey.pem
# 仅 2.4.8 以下需要;2.4.8+ 保留也不报错但已弃用
# SSLCertificateChainFile /etc/httpd/ssl/chain.pem
SSLProtocol -all +TLSv1.2 +TLSv1.3
</VirtualHost>
# 校验配置后优雅重启
apachectl configtest && apachectl graceful
HAProxy 2.8:crt 指向的 PEM 必须把私钥、叶子、中间证书合并进同一个文件,顺序可以是 key→leaf→intermediate 或 leaf→intermediate→key,但私钥不能缺——缺了会直接启动失败并报 unable to load SSL private key。据 HAProxy 配置手册,同一文件内多张证书按首次出现顺序匹配 SNI。
# 合并顺序:私钥 → 叶子 → 中间证书
cat /etc/letsencrypt/live/example.com/privkey.pem
/etc/letsencrypt/live/example.com/cert.pem
/etc/letsencrypt/live/example.com/chain.pem
> /etc/haproxy/certs/example.com.pem
chmod 600 /etc/haproxy/certs/example.com.pem
# haproxy.cfg
# frontend https_in
# bind :443 ssl crt /etc/haproxy/certs/example.com.pem alpn h2,http/1.1
haproxy -c -f /etc/haproxy/haproxy.cfg # 输出 Configuration file is valid
Tomcat 9/10:JKS 方案要把中间证书逐个 -importcert 进同一 keystore;更省事的是直接导出 PKCS12,让 Tomcat 从 SSLHostConfig 读取。
# 方案 A:导入中间证书到已有 keystore
keytool -importcert -alias intermediate -file intermediate.crt
-keystore keystore.jks -storepass changeit -noprompt
# 方案 B:直接用 fullchain 生成 PKCS12
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem
-out example.p12 -name tomcat -passout pass:changeit
# server.xml(Tomcat 8.5+ 的 SSLHostConfig 写法)
# <SSLHostConfig>
# <Certificate certificateKeystoreFile="conf/example.p12"
# certificateKeystorePassword="changeit"
# certificateKeystoreType="PKCS12"
# type="RSA" />
# </SSLHostConfig>
| 服务 | 证书文件要求 | 关键指令 | 版本坑 |
|---|---|---|---|
| Nginx 1.24 | leaf + intermediate 合并;私钥单独 | ssl_certificate |
ssl_trusted_certificate 不下发,勿混用 |
| Apache 2.4.58 | fullchain 单文件即可 | SSLCertificateFile |
<2.4.8 需 SSLCertificateChainFile |
| HAProxy 2.8 | key + leaf + intermediate 同文件 | bind ... ssl crt |
缺私钥直接启动失败 |
| Tomcat 9/10 | JKS 或 PKCS12 内含中间证书 | certificateKeystoreFile |
JKS 需逐个别名导入 |
改完统一用 OpenSSL 复核,不要只信浏览器:
# 用系统根库构建路径,返回 0 (ok) 说明链完整
openssl s_client -connect example.com:443 -servername example.com
-CAfile /etc/ssl/certs/ca-certificates.crt </dev/null | grep "Verify return code"
# 验证失败时立即非 0 退出,适合放进 CI / 监控脚本
openssl s_client -connect example.com:443 -servername example.com
-verify_return_error </dev/null >/dev/null && echo "chain OK"
若输出仍是 verify error:num=21:unable to verify the first certificate,基本可判定服务器少发了中间证书——这正是”证书链不完整怎么解决”最常见的现场:文件本身没坏,只是拼接顺序或文件选错了。按 RFC 8446(TLS 1.3)与 RFC 5246(TLS 1.2)的要求,服务端应发送从叶子到(不含)根证书的完整链,根证书由客户端本地信任库提供;Mozilla SSL Configuration Generator 生成的片段也遵循这一顺序约定。
手工合并、fullchain.pem 与托管证书:方案对比与选型建议
证书链不完整怎么解决,本质上是一道”选源”题:链文件从哪里来、续期后谁负责更新,决定了这个问题是一次性修复还是每 90 天复发一次。核心原则很简单——能直接使用 CA 或 ACME 客户端产出的 fullchain.pem,就不要手工 cat 合并。手工合并的产物不会随续期自动重建,一旦漏更新,链会再次不完整,而且这种故障往往在浏览器端才暴露。
先看对比,再决定你属于哪一行:
| 方案 | 适用场景 | 关键文件与参数 | 维护成本 | 备注 |
|---|---|---|---|---|
| 手工合并 fullchain | Nginx / Apache 通用 | cat leaf.crt intermediate.crt > fullchain.pem;ssl_certificate fullchain.pem; |
中 | 续期后需重新合并,顺序必须叶在前、中间在后 |
| Let’s Encrypt fullchain.pem | Certbot 用户 | /etc/letsencrypt/live/<域名>/fullchain.pem |
低 | 续期自动更新,只需 reload |
| Apache SSLCertificateChainFile | Apache 2.4.8 以下 | chain.pem 单独指定 |
中 | 2.4.8+ 已弃用,改用 fullchain 指向 SSLCertificateFile |
| HAProxy 合并 PEM | 四层 / 七层负载均衡 | key + leaf + intermediate 合并为单文件 | 中 | 必须包含私钥,否则启动报错 |
| Tomcat keytool 导入 | Java 应用 | keystore.jks 或 PKCS12 |
高 | 中间证书需用 -importcert 单独导入,链不全会抛 PKIX 异常 |
| 云厂商证书托管 | 无专职运维 | 控制台上传 fullchain | 低 | 上传时必须选择含中间证书的版本 |
手工合并并非不能用,但要写清命令和顺序。据 OpenSSL 文档,验证时按”叶 → 中间 → 根”自底向上构建链,顺序错乱会导致 unable to get local issuer certificate:
# 顺序不能颠倒:站点证书在前,中间证书在后,根证书不要放(客户端自带)
cat example.com.crt intermediate.crt > fullchain.pem
# 校验合并结果:应输出 2(叶 + 中间),且 verify return code: 0 (ok)
grep -c "BEGIN CERTIFICATE" fullchain.pem
openssl verify -untrusted intermediate.crt example.com.crt
商业 CA 与云托管的坑在于”来源可信”:下载其官方 intermediate 包并核对 SHA-256 指纹,与 CA 官网仓库公布值比对;不要从第三方博客复制中间证书,容易拿到过期或错配的 CA。Let’s Encrypt 免费、90 天有效期;DV 单域名商业证书约 100–600 元/年,OV 约 800–3000 元/年,下单前先确认证书包里是否附带链文件。
容器与 Kubernetes 场景要单独注意:把 fullchain.pem 与 privkey.pem 放进同一个 Secret,键名必须是 tls.crt(内容为完整链)与 tls.key。Ingress-Nginx 直接读取 tls.crt,若只放叶子证书,集群内 Pod 之间的出站 TLS 调用同样会报链不完整。
# tls.crt 必须是 fullchain,tls.key 是私钥
kubectl create secret tls example-tls
--cert=fullchain.pem --key=privkey.pem -n default
选型时按一句话判断:续期流程能否自动产出并加载完整链? 能,就用 Certbot 的 fullchain;不能,才退回手工合并,并把”重新合并 + reload”写进续期脚本的同一个 hook 里,避免下一次又出现证书链不完整。
证书链不完整常见报错与逐条排查
同一张证书,浏览器正常、命令行却报错,八成不是证书本身有问题,而是证书链不完整——服务器只发了叶证书,没发中间证书。RFC 8446 与 Mozilla 服务器端 TLS 指南都建议服务端发送完整链(不含根证书),因为很多客户端并不做 AIA 补链。排查时先按报错分类,再逐条定位。
| 报错原文(截取) | 典型根因 | 一条命令定位 |
|---|---|---|
curl: (60) SSL certificate problem: unable to get local issuer certificate |
服务器少发中间证书,或客户端根库过旧 | openssl s_client -connect host:443 -showcerts 数证书张数 |
PKIX path building failed: unable to find valid certification path |
JDK cacerts 缺中间/根证书 | keytool -list -cacerts |
X509_check_private_key:key values mismatch |
证书与私钥不是一对 | 比对两个 modulus 的 md5 |
PEM_read_bio_X509_AUX() failed ... no start line |
CRLF 换行、缺 BEGIN 行、权限不足 | file + chmod 644 |
Verify return code: 21 (unable to verify the first certificate) |
确认缺中间证书(最直接信号) | 同第一行 |
1)curl (60):先数证书张数。据 curl 文档,7.68 起默认改用系统 CA 包并输出上述文案(更早版本报 unable to get local issuer certificate 但语义相同)。先看服务端到底发了几张:
# 统计服务器实际发送的证书数量(含叶证书),1 = 缺中间证书,2~3 = 正常
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null
| grep -c "BEGIN CERTIFICATE"
# 查看链路深度与最终校验码
openssl s_client -connect example.com:443 -servername example.com -verify 5 &1
| grep -E "depth=|Verify return code"
若结果为 1,直接补中间证书即可。若已是 2 仍报错,则是客户端信任库问题:CentOS 7 的 ca-certificates 在 2021 年之前的版本不含 ISRG Root X1,Let’s Encrypt 文档明确要求执行 yum update ca-certificates(目标版本 ≥ 2021.2.50)后才能校验 Let’s Encrypt 证书链。
2)Java PKIX 报错:补完中间证书后仍失败,说明 JDK 的 cacerts 里没有对应根证书。JDK 9+ 用 -cacerts 参数,JDK 8 需显式指定 $JAVA_HOME/jre/lib/security/cacerts,默认口令为 changeit:
# JDK 9+:检查是否已信任 ISRG Root X1
keytool -list -cacerts -storepass changeit | grep -i isrg
# JDK 8:路径不同,其余参数一致
keytool -list -keystore "$JAVA_HOME/jre/lib/security/cacerts" -storepass changeit | grep -i isrg
3)Nginx 启动失败 key values mismatch:这不是链的问题,而是 ssl_certificate 与 ssl_certificate_key 配错了对。两条命令的 md5 必须完全一致(RSA 证书适用;ECDSA 请把 rsa 换成 ec):
openssl x509 -noout -modulus -in /etc/nginx/ssl/fullchain.pem | openssl md5
openssl rsa -noout -modulus -in /etc/nginx/ssl/privkey.pem | openssl md5
# 输出两行哈希相同才匹配;不同则说明拿错了私钥
4)PEM_read_bio_X509_AUX() failed … no start line:OpenSSL 读不到 -----BEGIN CERTIFICATE-----。常见于 Windows 导出带 CRLF、只贴了正文、或 fullchain.pem 权限为 600 而 worker 用户为 www-data。执行 file /etc/nginx/ssl/fullchain.pem 应输出 PEM certificate 或 ASCII text;用 chmod 644 fullchain.pem 放开读权限,再用 sed -i 's/r$//' fullchain.pem 去掉 CRLF。
5)Verify return code 21 与 20 的区别:21 是 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE,几乎可以断定缺中间证书;20 是 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY,说明客户端信任库里找不到根证书,需检查系统 CA 包是否过期。这两个码出自 OpenSSL 的 verify 手册,可直接作为”证书链不完整怎么解决”的判断依据。
6)浏览器 NET::ERR_CERT_AUTHORITY_INVALID / SEC_ERROR_UNKNOWN_ISSUER:先排除时钟偏差——超过 5 分钟即可能失败,用 date -u 与响应头 Date 对比。其次检查是否误把根证书拼进了 fullchain.pem:部分 Android 4.x 对多余根证书会直接拒绝握手,正确做法是只拼叶证书 + 中间证书,根证书由客户端自备。若上述都对仍报错,按前面步骤确认证书链不完整怎么解决的判定逻辑,再回到服务器配置补链。
怎么确认证书链已经完整?5 种验证方法
把中间证书补进 fullchain.pem 之后,最危险的想法是“浏览器能打开就说明修好了”。浏览器(Chrome/Firefox)实现了 RFC 5280 的 AIA(Authority Information Access)扩展抓取,发现中间证书缺失时会自己下载并缓存,所以人工访问往往看不出问题;而 Java 的 HttpClient、Python requests(certifi 包)、老版本 Android 以及大量 IoT 设备不做 AIA 补链,会直接抛出 unable to get local issuer certificate。因此必须用“不会自动补链”的客户端来验证。以下 5 种方法按成本从低到高排列,建议至少跑前 3 种。
方法一:计数法——最快判断服务器发了几张证书。据 OpenSSL 文档,-showcerts 会把对端发送的全部证书打印出来,-servername 用于触发 SNI(缺了它可能拿到默认站点的证书,测了个寂寞)。
# 统计服务器在 TLS 握手中实际下发的证书张数
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null
| grep -c "BEGIN CERTIFICATE"
# 正常返回 2(leaf + 1 张中间证书)或 3(leaf + 2 张中间证书)
# 返回 1 = 只发了叶子证书,证书链不完整
# 返回 0 = 连接/SNI 失败,先排查端口与域名
方法二:路径验证法——让 OpenSSL 真正构建信任链。计数只数张数,不证明能链到根;-verify_return_error 会让校验失败时以非 0 退出码结束。
# 指定系统信任库,模拟真实客户端的路径构建过程
openssl s_client -connect example.com:443 -servername example.com -verify_return_error
-CAfile /etc/ssl/certs/ca-certificates.crt </dev/null
# 成功:末尾出现 Verify return code: 0 (ok)
# 缺中间证书的典型报错(OpenSSL 1.1.1/3.x 均一致):
# verify error:num=21:unable to verify the first certificate
# Verify return code: 21 (unable to verify the first certificate)
方法三:curl 法——最贴近应用层真实行为。curl 自 7.68 起默认开启严格证书链校验(CURLOPT_SSL_VERIFYPEER 默认为 1),且不做 AIA 补链,比浏览器更容易暴露缺链。
curl -vI https://example.com 2>&1 | grep -i "SSL certificate verify"
# 通过:* SSL certificate verify ok.
# 失败:* SSL certificate problem: unable to get local issuer certificate
# 临时跳过校验仅用于对比定位(切勿用于生产):curl -k -vI https://example.com
方法四:在线工具与离线复核。在 SSL Labs(ssllabs.com/ssltest)输入域名,查看 Certification Paths 是否呈现完整三级,Chain issues 一栏应为 None;若显示 Incomplete 会被直接扣分。内网或未公开站点可用 testssl.sh 5.0 离线复核:
# testssl.sh 5.0+,--chain 检查证书链,--server-defaults 输出协议与套件默认值
./testssl.sh --chain --server-defaults example.com
# 关注 "Chain of trust" 段与 "Chain issues" 行,缺链时输出 Incomplete
方法五:浏览器复核。开发者工具 → Security → View certificate → 证书路径,应看到「你的域名证书 → 中间 CA → 根 CA」三级;若中间一级标注“已下载”或整体缺失,说明服务器未发送,浏览器是临时抓取补上的。
| 方法 | 依赖 | 能否发现缺链 | 关键判定输出 | 局限 |
|---|---|---|---|---|
| 计数法 | OpenSSL 1.1.1+ | 能 | 2 或 3 |
只数张数,不验证能否链到根 |
| 路径验证法 | OpenSSL + 系统 CA | 能 | Verify return code: 0 (ok) |
本地信任库过期会误报 |
| curl -vI | curl 7.68+ | 能 | SSL certificate verify ok. |
同样依赖本机 CA bundle |
| SSL Labs | 公网可达 | 能 | Chain issues: None |
内网站点无法测试 |
| testssl.sh | 5.0+ | 能 | Chain issues: Incomplete |
需自行下载脚本 |
补充两点:一是若站点在 CDN 后面,需分别验证边缘节点与回源;二是根证书不应由服务器下发(据 Let’s Encrypt 文档,
fullchain.pem= 叶子证书 + 中间证书,不含根),多发根证书会增大握手体积并可能触发部分客户端的告警。
证书链与 OCSP Stapling、续期自动化的联动项
证书链配置正确只是起点。真正让运维在凌晨被告警叫醒的,往往是链修好之后没有把 OCSP Stapling、自动续期和监控串成一条闭环——链断一次能修,流程断一次会反复复发。
OCSP Stapling 为什么”链不完整就静默失败”?因为 Nginx 在启动时不会因为 stapling 失败而拒绝启动,它只是把 OCSP 响应缓存留空,握手时不下发 stapled 响应,客户端浏览器仍然自己回源查 OCSP,用户端感知不到,只有抓握手包或跑 openssl s_client 才看得见。Nginx 从 1.3.7 开始支持 ssl_stapling,1.11.0 起重写了 resolver 的解析行为(必须显式配置 resolver 才能解析 OCSP 响应者域名)。
# /etc/nginx/conf.d/example.conf 适用于 Nginx 1.11.0+ 的写法
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 服务器证书 + 中间证书
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_stapling on; # 默认 off,必须显式开启
ssl_stapling_verify on; # 默认 off,校验 OCSP 响应签名
ssl_trusted_certificate /etc/nginx/ssl/chain.pem; # 仅信任链,不下发给客户端
resolver 8.8.8.8 1.1.1.1 valid=300s; # 默认 30s,valid 控制 DNS 缓存时长
resolver_timeout 5s; # 默认 30s
}
验证命令(OpenSSL 1.0.2+ 均支持 -status):
openssl s_client -connect example.com:443 -status -servername example.com </dev/null 2>/dev/null | grep -A1 "OCSP Response Status"
# 期望输出:OCSP Response Status: successful (0x0)
# 若输出 "no response sent" 或整段缺失,说明 stapling 未生效,先检查链是否完整
续期后忘记 reload 是最常见的二次故障。Certbot 的 --deploy-hook 只在证书真正更新时触发,而 --renew-hook(已废弃)语义更宽,容易造成无意义 reload。据 Let’s Encrypt 官方文档,90 天有效期下推荐在剩余 30 天时续期,Certbot 默认对剩余不足 30 天的证书执行续期。
# 写入 /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh 并 chmod +x
certbot renew --deploy-hook "systemctl reload nginx" --quiet
# 演练:模拟完整续期,不消耗速率限制,可提前发现 fullchain.pem 路径被改、权限丢失、webroot 失效
certbot renew --dry-run
| 联动项 | 失败表现 | 检测手段 | 关键默认值/阈值 |
|---|---|---|---|
| OCSP Stapling | 静默失败,无 stapled 响应 | openssl s_client -status |
ssl_stapling 默认 off |
| 续期 reload | 磁盘证书已换,内存仍旧证书 | certbot renew --dry-run |
剩余 30 天触发续期 |
| 到期监控 | 临期才告警,来不及排查链问题 | probe_ssl_earliest_cert_expiry |
建议阈值 21 天(90 天的 3/4) |
| 证书格式 | 旧版 Nginx 解析失败 | openssl x509 -in fullchain.pem -noout |
PEM 文本、LF 换行、末尾单个换行 |
监控层建议双指标并行:probe_ssl_earliest_cert_expiry 盯剩余秒数(阈值 21 天 ≈ 1814400 秒),probe_success 配合自写的 openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted chain.pem fullchain.pem 脚本,覆盖”证书没过期但链断了”的盲区。这正是”证书链不完整怎么解决”在自动化阶段必须回答的第二问:修链是止血,联动才是根治。
格式统一别忽视:私钥用 RSA 2048 或 ECDSA P-256,fullchain.pem 保持 PEM 文本、LF 换行、末尾保留一个换行符;混入 DER 二进制或 CRLF 换行,在 OpenSSL 1.0.2 及部分旧版 Nginx 上会直接报 PEM_read_bio:no start line 或 SSL_CTX_use_certificate_chain_file() failed。可用 file fullchain.pem 与 cat -A fullchain.pem | grep '^M' 快速自检。
长期维护:续期后如何避免证书链再次不完整
续期成功了,为什么客户端还是报证书链不完整? 因为 certbot renew 只覆盖 /etc/letsencrypt/live/<域名>/ 下的四个文件,其中 cert.pem 只有服务器叶子证书,fullchain.pem 才是”叶子 + 中间证书”的完整拼接。如果 Nginx 的 ssl_certificate 指向 cert.pem,续期本身不会报任何错,但链始终缺一级——这正是”证书链不完整怎么解决”最容易被忽略的复发原因:问题不在证书,在配置引用。据 Let’s Encrypt 文档,live/ 目录是符号链接,续期后指向 archive/ 的新文件,配置写错一次就会一直错下去。
怎么从源头堵住? 把所有 Web 服务器的证书入口统一为 fullchain.pem,并把这条规则写进上线检查清单,用 grep 做机器门禁。Apache 2.4.8+ 同样适用:SSLCertificateFile 直接指向 fullchain.pem 即可,SSLCertificateChainFile 自 2.4.8 起已废弃,再写它反而容易造成两处不一致。
# 上线门禁:配置中出现 /cert.pem 即拒绝发布(Nginx + Apache 一起扫)
if grep -rnE 'ssl_certificate[[:space:]]+[^;]*/cert.pem|SSLCertificateFile[[:space:]]+[^ ]*/cert.pem'
/etc/nginx /etc/apache2 /etc/httpd 2>/dev/null; then
echo "拒绝上线:发现 cert.pem 引用,必须改为 fullchain.pem" >&2
exit 1
fi
echo "证书引用检查通过"
变更后如何自动校验,而不是等人肉发现? 把校验放进 certbot 的 deploy hook(/etc/letsencrypt/renewal-hooks/deploy/,certbot 1.x+ 每次续期成功后执行)。顺序很关键:先做文件级校验,再做 reload,最后做端到端 s_client 校验,任一失败即回滚配置。-verify_return_error 必须加——s_client 默认即使验证失败也返回 0,这是很多人误以为”校验通过”的坑。
#!/usr/bin/env bash
# /etc/letsencrypt/renewal-hooks/deploy/10-chain-guard.sh (chmod +x)
set -euo pipefail
DOMAIN="example.com"
LIVE="/etc/letsencrypt/live/${DOMAIN}"
CA="/etc/ssl/certs/ca-certificates.crt" # RHEL 系为 /etc/pki/tls/certs/ca-bundle.crt
# 1) 文件级:chain.pem 是中间证书,用它验证 cert.pem,期望输出 "...cert.pem: OK"
openssl verify -CAfile "$CA" -untrusted "$LIVE/chain.pem" "$LIVE/cert.pem"
# 2) 此时才 reload,证书文件有问题时线上仍跑旧证书,零影响
nginx -t && systemctl reload nginx
# 3) 端到端:缺链时这里会报 "verify error:num=20:unable to get local issuer certificate"
if ! openssl s_client -connect 127.0.0.1:443 -servername "$DOMAIN"
-verify_hostname "$DOMAIN" -verify_return_error -CAfile "$CA" </dev/null >/dev/null 2>&1; then
echo "[FATAL] $DOMAIN 证书链校验失败,回滚配置" >&2
cp -a "/etc/nginx/conf.d/${DOMAIN}.conf.bak" "/etc/nginx/conf.d/${DOMAIN}.conf"
nginx -t && systemctl reload nginx
exit 1
fi
echo "[OK] $DOMAIN 证书链完整"
中间证书轮换要不要跟? 必须跟。CA 的中间证书会轮换,配置里”写死”的旧链或客户端缓存的旧链都会失效。Let’s Encrypt 已于 2024-09-06 起用 R10/R11 取代 R3 签发 RSA 证书,并在 2024-06-06 停止提供 ISRG Root X1 的 DST Root CA X3 交叉签名(依据 Let’s Encrypt 的 “Shortening the Let’s Encrypt Chain of Trust” 公告)。轮换前先在测试环境用 openssl s_client -showcerts 确认服务端实际下发的链,再全量;旧交叉链到期前预留 2 周灰度窗口,优先观察 Android 7.0 以下等老信任库。
| 环节 | 变化 | 你要做的动作 |
|---|---|---|
| RSA 中间证书 | R3 → R10/R11(2024-09-06 起) | 确认 fullchain.pem 已同步更新,无需改配置 |
| 交叉签名 | DST Root CA X3 交叉链 2024-06-06 停止提供 | 评估老 Android 兼容性,必要时保留兼容链 |
| 根证书 | ISRG Root X1 自签有效期至 2035-06-04 | 客户端信任库需包含 X1,否则报 num=20 |
一张证书覆盖多个域名,链文件要准备几份? 一份。fullchain.pem 与域名数量无关,但每个 server 块都要显式引用同一个文件,别指望 ssl_certificate 跨块继承。若同时部署 RSA 与 ECDSA 双证书,Nginx 1.11.0+ 允许写多行 ssl_certificate,各自指向对应的 fullchain.pem:
server {
listen 443 ssl;
http2 on; # Nginx 1.25.1+;更早版本写 listen 443 ssl http2;
server_name example.com www.example.com;
# RSA 链(默认入口,禁止写成 cert.pem)
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# ECDSA 链(Nginx 1.11.0+ 支持多条 ssl_certificate,按客户端算法自动选择)
ssl_certificate /etc/letsencrypt/live/example.com-ecdsa/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com-ecdsa/privkey.pem;
}
故障时怎么 5 分钟内定位是缺链还是过期? 靠 CMDB 里事先记好的字段,而不是临时翻服务器。每条域名记录至少包含:
- 证书来源(Let’s Encrypt / 商业 CA / 自建内部 CA)与签发中间证书的 Subject(如
CN=R10, O=Let's Encrypt, C=US); - 到期日与续期方式(certbot timer / ACME 客户端 / 人工),以及续期后由哪个 deploy hook 触发 reload;
- 责任人,以及该域名是否启用双证书、是否有老客户端兼容要求。
拿到这三项,用 openssl s_client -connect host:443 -servername 域名 -showcerts 对比服务端下发链与记录是否一致,缺链会直接体现在 verify error:num=20/21,过期则表现为 num=10:certificate has expired,两者处置路径完全不同。
过期通常报 certificate has expired 或 Verify return code: 10 (certificate has expired),浏览器会明确提示「证书已过期」;缺链则报 unable to get local issuer certificate、PKIX path building failed 或 Verify return code: 21。用 openssl s_client -showcerts 看发送的证书数量,只有 1 张就是缺链。
Chrome、Firefox 支持 AIA 扩展,会自动向 CA 下载缺失的中间证书并缓存,所以看起来正常;curl、Python requests、Java 默认不抓取 AIA,直接按本地信任库构建路径,缺中间证书就失败。据 RFC 5280,客户端不应依赖 AIA 抓取,正确做法是服务器主动发送中间证书。
不需要,也不建议。根证书已在客户端信任库中,服务器重复发送会增加约 1–2 KB 握手体积;部分 Android 4.x 设备对多余根证书会判定路径异常。正确内容是 leaf + intermediate,最多再加一张交叉签名中间证书。
先确认配置里引用的确实是 fullchain.pem 而不是 cert.pem,再执行 openssl s_client -showcerts 看实际发送了几张证书。若只有 1 张,通常是 Nginx reload 未生效或配置被其他 include 覆盖;另外 CentOS 7 等老系统的 ca-certificates 可能缺少 ISRG Root X1,需 yum update ca-certificates 后重试。
ssl_certificate 指向发送给客户端的证书链(必须是 fullchain.pem),ssl_trusted_certificate 只用于 OCSP Stapling 验证和客户端证书校验,不会发送给客户端,通常指向 chain.pem。两者都配置才能让 stapling 正常工作,Nginx 1.3.7+ 支持这两个指令。
reload 即可,执行 nginx -t 检查语法后 systemctl reload nginx,现有连接不会中断。只有修改了监听端口、worker 进程数等需要重新 bind 的配置才需要 restart;生产环境优先 reload,避免瞬时连接拒绝。
需要确认上传的是否为 fullchain。多数云厂商(阿里云、腾讯云)在控制台上传证书时要求分别填写「证书内容」和「证书链」,只填叶子证书就会复现缺链;部分厂商支持一键部署到 SLB/CDN,但仍建议用 openssl s_client 对线上域名做一次复核。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。