跳到主要内容
安装配置教程

证书链不完整怎么配置?Nginx、Apache、Tomcat 补全中间证书的实操步骤

证书链不完整怎么配置 — 证书链不完整怎么配置?Nginx、Apache、Tomcat 补全中间证书的实操步骤
核心结论

证书链不完整的标准解法是:把「服务器证书 + 中间证书」按 leaf 在前、中间 CA 在后的顺序拼成一个 fullchain.pem,再让 Web 服务器只指向这一个文件——Nginx 改 ssl_certificate、Apache 2.4.8+ 改 SSLCertificateFile、HAProxy 合并进 crt 文件,改完 reload 即生效。 30 秒判定命令:openssl s_client -connect 域名:443 -servername 域名 -showcerts /dev/null | grep -c 'BEGIN CERTIFICATE',返回 1 就是缺链,正常应为 2 或 3。 浏览器能打开不代表链完整:Chrome/Edge 会通过 AIA 扩展(RFC 5280 §4.2.2.1)在线抓取中间证书,而 Java 8 的 com.sun.security.enableAIAcaIssuers 默认 false、Android 7.0 以前不抓 AIA,所以故障只在 App 和后端调用中暴露。 根证书不要放进服务器证书文件:SSL Labs 会报 Chain issues: Contains anchor,且每次握手多传约 1.5 KB,对握手首包(TCP 初始拥塞窗口约 14.6 KB)是净负担。 验证标准:openssl s_client 加 -verify_return_error 后输出 Verify return code: 0 (ok),且 testssl.sh 3.2 的 --chain 检查显示 Chain of trust - ok。

问题背景与根本原因:为什么浏览器能打开,App 却报证书错误?

很多人的第一反应是「浏览器能打开,说明证书没问题」,这恰恰是排查方向跑偏的起点。据 RFC 8446 §4.4.2 的定义,TLS 1.3 握手中的 Certificate 消息本身允许服务器一次下发多张证书(leaf 在前、中间 CA 依次在后),协议层面完全支持完整链。问题在于:Nginx、Apache、HAProxy 都不会自动从系统信任库「补齐」中间 CA,它们只把配置文件里指定的内容原样发出去。所以证书链不完整怎么配置,本质是「你喂给服务器什么,客户端就收到什么」,而不是让服务器自己去拼。

那为什么 Chrome、Edge 看起来一切正常?因为它们会读取 leaf 证书里的 AIA 扩展(RFC 5280 §4.2.2.1 定义的 caIssuers 字段),按 URL 在线把中间证书抓下来补上。这个「善意」的兜底把服务端配置缺陷一路掩盖到上线之后——直到不做 AIA 抓取的客户端出现:Java 8 的系统属性 com.sun.security.enableAIAcaIssuers 默认值为 false;Android 7.0(API 24)以前的系统版本不抓 AIA;OpenSSL 1.0.2 / 1.1.1 的 s_client 和 curl 同样不抓。于是就有了经典的「浏览器正常、App 报错」。

客户端 / 运行时 是否按 AIA 在线补链 缺链时的真实表现
Chrome / Edge / Safari 桌面版 是 正常,掩盖问题
Windows Schannel / CryptoAPI 是 正常
Java 8 JSSE(默认 false) 否 PKIX path building failed
Android < 7.0(API 24) 否 SSLHandshakeException
curl / openssl s_client 否 verify error:num=21: unable to verify the first certificate
Go crypto/tls 否 x509: certificate signed by unknown authority

先用一条命令确认,别猜:

# 统计服务端在 TLS 握手中实际下发的证书张数
# 返回 1 = 只发了 leaf,链不完整;返回 2 或 3 才正常
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null 
  | grep -c 'BEGIN CERTIFICATE'

# 反向验证:显式提供中间证书后能否校验通过
# 通过说明证书本身没问题,缺的只是“服务端没发中间证书”
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt 
  -untrusted intermediate.crt leaf.crt
# 期望输出:leaf.crt: OK

四类高频漏配场景,覆盖了绝大多数线上事故:Nginx 的 ssl_certificate 只指向 domain.crt 单证书;Apache 2.4.8 之前未配置 SSLCertificateChainFile;Tomcat 的 JKS 里只导入了 leaf;Kubernetes Ingress 的 Secret 中 tls.crt 只含一张证书。影响面也远不止 HTTPS 站点:mTLS 双向认证、gRPC、Android/iOS App、Java 后端互调、IoT 固件里的精简 TLS 栈,只要客户端信任库更新不及时,缺链就是硬故障,而不是「偶发问题」——据 Let’s Encrypt 文档的统计口径,链配置错误长期位居证书部署问题前列。

证书链不完整怎么配置?6 步完整实操流程(含命令)

“证书链不完整怎么配置”这个问题,本质是服务器只发送了站点证书(leaf),没把签发它的中间 CA 一起发出去。据 RFC 8446 §4.4.2,服务端证书列表必须“发送者证书在前、每张后续证书直接签发前一张”,根证书可以省略——但中间证书不能省。典型症状是浏览器正常、Java 客户端和 curl/openssl 报 unable to get local issuer certificate。下面 6 步可直接照抄执行。

  1. 步骤 1:诊断现状,找出断在哪一级。用 s_client 导出服务端实际发出的整条链,再用 crl2pkcs7 逐张打印 subject/issuer:

    # 导出服务端真实发出的证书(-servername 保证 SNI 正确,避免拿到默认站点证书)
    openssl s_client -connect sslgood.com:443 -servername sslgood.com -showcerts </dev/null 2>/dev/null > chain.txt
    
    # 逐张打印 subject 与 issuer,判断缺哪一级
    openssl crl2pkcs7 -nocrl -certfile chain.txt | openssl pkcs7 -print_certs -noout
    

    判据:如果只输出 1 张、且 issuer 指向某个中间 CA(如 Let's Encrypt R10、DigiCert Global G2),而列表里没有该 CA 自己的证书,就是链断了。

  2. 步骤 2:取得中间证书。优先用签发渠道自带的产物,不要网上随手下载:

    签发渠道 中间证书文件位置 说明
    Let’s Encrypt + certbot /etc/letsencrypt/live/example.com/fullchain.pem certbot 1.0 起默认生成 fullchain(leaf+中间),chain.pem 为纯中间证书
    acme.sh 签发时加 --fullchain-file /etc/nginx/ssl/fullchain.pem 不加该参数只输出 --cert-file 的单张 leaf,链必断
    商业 CA 控制台/签发邮件中的 ca-bundle.crt 或 intermediate.crt DigiCert、Sectigo 均提供单独的 intermediate 包
  3. 步骤 3:按正确顺序拼接。leaf 必须在最前,多级中间证书“下级在前、上级在后”,根证书不放入(放了只会让握手多传 1–2 KB):

    # 正确顺序:站点证书 + 中间证书(可多个,从下到上)
    cat domain.crt intermediate.crt > fullchain.pem
    
    # 确认第一张是站点证书
    openssl x509 -in fullchain.pem -noout -subject
    
  4. 步骤 4:校验私钥匹配。顺序拼错或拿错私钥,reload 时才报错,不如提前验证:

    # RSA 证书:比对 modulus 的 MD5,两行必须完全一致
    openssl x509 -noout -modulus -in fullchain.pem | openssl md5
    openssl rsa  -noout -modulus -in privkey.pem   | openssl md5
    
    # ECDSA 证书没有 modulus,改用公钥比对
    openssl x509 -noout -pubkey -in fullchain.pem | openssl md5
    openssl pkey -in privkey.pem -pubout | openssl md5
    

    不一致时 Nginx reload 会直接失败:SSL_CTX_use_PrivateKey_file(...) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)。

  5. 步骤 5:改配置并平滑重载。不同服务对“链文件”的指定位置差异很大:

    服务 指定链的指令 校验 + 重载
    Nginx(1.x 全版本) ssl_certificate 指向 fullchain.pem(无默认值,必须显式配置) nginx -t && systemctl reload nginx
    Apache ≥ 2.4.8 SSLCertificateFile 可直接写全链文件 apachectl configtest && systemctl reload httpd
    Apache < 2.4.8 额外用 SSLCertificateChainFile 指向 intermediate.crt 同上
    HAProxy bind :443 ssl crt /etc/haproxy/site.pem(证书+中间证书+私钥合并为单文件) haproxy -c -f /etc/haproxy/haproxy.cfg 后 reload
    Tomcat 9/10 链必须已在 keystore 内:keytool -importcert -alias intermediate -file intermediate.crt -keystore conf/ssl.jks 需重启,reload 不会重载 keystore
    # Nginx 关键片段
    server {
        listen 443 ssl;
        server_name sslgood.com;
        ssl_certificate     /etc/nginx/ssl/fullchain.pem;  # 必须是含中间证书的链文件
        ssl_certificate_key /etc/nginx/ssl/privkey.pem;
        ssl_protocols       TLSv1.2 TLSv1.3;               # nginx ≥1.23.4 的默认值
    }
    
    # HAProxy 合并单文件(顺序:证书 → 中间证书 → 私钥)
    cat domain.crt intermediate.crt privkey.pem > /etc/haproxy/site.pem
    
  6. 步骤 6:本地 + 外网双向复验。本地用 -untrusted 显式提供中间证书,能区分“链配错”还是“系统根库问题”:

    # 期望输出:domain.crt: OK
    openssl verify -untrusted intermediate.crt 
      -CAfile /etc/ssl/certs/ca-certificates.crt domain.crt
    
    # 外网复验:统计服务端实际发出的证书张数,应为 2 或 3
    openssl s_client -connect sslgood.com:443 -servername sslgood.com -showcerts </dev/null 2>/dev/null 
      | grep -c 'BEGIN CERTIFICATE'
    

    本地仍报 error 20 at 0 depth lookup: unable to get local issuer certificate 说明中间证书拿错了级别;外网计数仍为 1 说明配置文件没生效(检查是否改的是被 include 的那份 vhost)。最后用 SSL Labs 或 Mozilla SSL Configuration Generator 的推荐配置对照一次 ssl_protocols/ssl_ciphers,确认链与协议套件同时达标。

配置示例:Nginx 1.26、Apache 2.4.57、HAProxy 2.8、Tomcat 9 分别怎么写

把证书链补全,本质只有一句话:让服务器在 TLS 握手时把 leaf 证书和中间证书一起发给客户端。不同软件的区别只在于”链写在哪”。下面按 Web 服务器逐条给出可直接复制的配置,版本号均已标注。验证命令统一用 openssl s_client -connect example.com:443 -servername example.com -showcerts,输出里应能看到 1 s:/CN=... 与 i:/C=US/O=Let's Encrypt/CN=R3 两条以上证书。

Nginx 1.18 / 1.24 / 1.26 怎么写?

# /etc/nginx/conf.d/example.conf —— 1.18 / 1.24 / 1.26 通用
server {
    listen 443 ssl;
    server_name example.com;

    # 关键行:fullchain.pem = 站点证书在前 + 中间证书在后,顺序颠倒会握手失败
    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    # Mozilla Server Side TLS「intermediate」兼容配置的推荐值
    ssl_protocols             TLSv1.2 TLSv1.3;   # 1.23.4 起这也是默认值
    ssl_prefer_server_ciphers off;               # 1.11.0 起默认即 off
    ssl_session_timeout       1d;
}
# 改完必做:nginx -t && nginx -s reload

注意 ssl_certificate 自 1.11.0 起可以写多次,用于 RSA + ECDSA 双证书(如 fullchain.rsa.pem 与 fullchain.ecdsa.pem);但同一张证书的链必须写在同一个文件里,不能靠写两次来补链——这是”证书链不完整怎么配置”最常见的误操作。

Apache httpd 2.4.57 怎么写?

# /etc/httpd/conf.d/ssl.conf
<VirtualHost *:443>
    ServerName example.com
    SSLEngine on
    SSLCertificateFile    /etc/httpd/ssl/fullchain.pem   # leaf + 中间证书拼在一起
    SSLCertificateKeyFile /etc/httpd/ssl/privkey.pem
    # 仅 2.4.7 及更早版本才需要下面这行;2.4.8 起 SSLCertificateChainFile 已废弃
    # SSLCertificateChainFile /etc/httpd/ssl/chain.pem
</VirtualHost>

Apache 2.4 官方文档明确把 SSLCertificateChainFile 标为 deprecated,因为 SSLCertificateFile 已支持读取文件中的多张证书。若沿用旧写法,2.4.57 启动日志会出现 AH01905: SSLCertificateChainFile is deprecated 类告警。

HAProxy 2.8 怎么写?HAProxy 要求单个 PEM 内顺序为私钥 → leaf 证书 → 中间证书,顺序错了 haproxy -c 会直接拒绝启动。

# 顺序不可调换;intermediate.crt 可包含多张中间证书
cat privkey.pem domain.crt intermediate.crt > /etc/haproxy/certs/example.pem
chmod 600 /etc/haproxy/certs/example.pem

# haproxy.cfg
# frontend https_front
#     bind *:443 ssl crt /etc/haproxy/certs/example.pem alpn h2,http/1.1

haproxy -c -f /etc/haproxy/haproxy.cfg   # 校验通过再 systemctl reload haproxy

Tomcat 9 / 10.1 怎么写?两条路,任选其一:

# 路线 A:把中间证书导入同一个 JKS keystore
keytool -importcert -alias intermediate -file intermediate.crt 
        -keystore keystore.jks -storepass 你的密码 -noprompt

# 路线 B:直接生成带链的 PKCS#12(推荐,省去手工拼链)
openssl pkcs12 -export -inkey privkey.pem -in domain.crt 
        -certfile intermediate.crt -out example.p12 -name tomcat
<!-- conf/server.xml:certificateKeystoreFile 指向上面生成的文件 -->
<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true">
  <SSLHostConfig>
    <Certificate certificateKeystoreFile="conf/example.p12"
                 certificateKeystorePassword="你的密码"
                 certificateKeystoreType="PKCS12" />
  </SSLHostConfig>
</Connector>

Kubernetes Ingress 与 Node.js 的等价写法:ingress-nginx 会把你给 tls.crt 的内容原样下发,只放 leaf 就会把不完整链直接透传给浏览器——kubectl create secret tls example-tls --cert=fullchain.pem --key=privkey.pem,--cert 必须给完整链。Node.js 则是 https.createServer({ key: fs.readFileSync('privkey.pem'), cert: fs.readFileSync('fullchain.pem') });若上游还有一层需要校验的反向代理,Nginx 侧用 proxy_ssl_trusted_certificate /etc/nginx/ssl/upstream-chain.pem; 指定上游链文件,否则会报 upstream SSL certificate verify error: (20:unable to get local issuer certificate)。

软件 链写在哪 关键指令 / 参数 常见错误
Nginx 1.18+ 与 leaf 同一文件 ssl_certificate fullchain.pem 只写 leaf,或拆成两个 ssl_certificate
Apache 2.4.8+ 与 leaf 同一文件 SSLCertificateFile fullchain.pem 仍在用已废弃的 SSLCertificateChainFile
HAProxy 2.8 单 PEM:key→cert→chain bind *:443 ssl crt example.pem 顺序错,haproxy -c 报错
Tomcat 9 / 10.1 keystore 或 PKCS#12 内 certificateKeystoreFile 只导入 leaf,未 importcert 中间证书
ingress-nginx Secret 的 tls.crt kubectl create secret tls tls.crt 只含 leaf

方案选型对比:fullchain 单文件、独立 chain 文件、keystore 导入怎么选?

选型的核心只有一句话:让服务端在握手时把 leaf 证书和中间证书一起发出去,而不要把根证书发出去。围绕这一目标,不同服务端的实现方式差别很大——这也是“证书链不完整怎么配置”在不同软件上答案完全不同的原因。先看对比表:

服务端 / 版本 关键配置项 是否需独立 chain 文件 推荐做法
Nginx 1.26 ssl_certificate 指向 fullchain.pem 否 单文件
Apache 2.4.57 SSLCertificateFile 指向 fullchain.pem 否 单文件
Apache 2.4.7 及更早 SSLCertificateFile + SSLCertificateChainFile 是 双文件
HAProxy 2.8 bind :443 ssl crt merged.pem(cert+key+chain 三合一) 否 三合一
Tomcat 9 keystore 导入中间证书,或 PKCS#12 导入时带 -certfile 视方式 PKCS#12
IIS 10 中间证书先导入“中间证书颁发机构”存储 是 图形界面补导入
K8s Ingress Secret 的 tls.crt 否 fullchain 写入 tls.crt

为什么优先 fullchain 单文件?配置项从 2 个降为 1 个,续期脚本只需覆盖一个文件,漏配概率最低;更关键的是避免“新 leaf 配旧链”——当 CA 从中间证书 A 切换到 B 时,双文件方案极易只更新了 cert 而忘了 chain,浏览器立刻报 NET::ERR_CERT_AUTHORITY_INVALID。据 Let’s Encrypt 文档,其签发的 fullchain.pem 已按 leaf→intermediate 顺序拼好,可直接使用。

根证书一律不要放进服务器证书文件。SSL Labs 会报 Chain issues: Contains anchor;且单张证书约 1.5 KB,多传一张会撑大 ServerHello 之后的 Certificate 消息,容易撞上 TCP 初始拥塞窗口(约 10 个 MSS ≈ 14.6 KB)限制,弱网下平白多一个 RTT。上线前用两条命令自检:

# 1) 数量应为 2(leaf + intermediate),出现 3 说明混进了根证书
grep -c "BEGIN CERTIFICATE" /etc/nginx/ssl/example.com.fullchain.pem

# 2) 打印每张证书的 subject/issuer,确认顺序是 leaf -> intermediate
openssl crl2pkcs7 -nocrl -certfile /etc/nginx/ssl/example.com.fullchain.pem 
  | openssl pkcs7 -print_certs -noout

# 3) 独立验证链是否闭合(chain.pem 只放中间证书)
openssl verify -untrusted chain.pem cert.pem
# 期望输出:cert.pem: OK

RSA + ECDSA 双证书场景(Nginx 1.11.0+):两张 leaf 各自需要一个带链的文件,写成两条 ssl_certificate,Nginx 会按客户端支持的签名算法自动择优,不要试图把两张 leaf 拼进同一个文件。

# /etc/nginx/conf.d/example.conf
ssl_certificate     /etc/nginx/ssl/example.com.rsa.fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/example.com.rsa.key;
ssl_certificate     /etc/nginx/ssl/example.com.ecdsa.fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/example.com.ecdsa.key;

私有 CA / 内网同样不能省。客户端信任库只装根证书时,服务端仍必须下发中间证书,“内网信任”不是豁免理由;建议内网也统一走 fullchain 流程,避免测试与生产配置分叉。Tomcat 侧若走 PKCS#12,导入时用 -certfile 把链带进去:

openssl pkcs12 -export 
  -in fullchain.pem -inkey privkey.pem 
  -certfile chain.pem 
  -name tomcat -out keystore.p12
# Tomcat 9 server.xml 中配套:keystoreType="PKCS12"

成本参考:中间证书由 CA 免费提供,不额外收费;DV 证书约 0–300 元/年(Let’s Encrypt 为 0 元、90 天有效期),OV 约 800–3000 元/年,通配符与多域名按 SAN 数量加价。选型时把“是否提供 ca-bundle 下载”列入评估项,能省掉大量手工拼链的麻烦。

常见错误与排查:6 条真实报错信息对应 6 种病因

证书链问题最难的地方不是修,而是先判断故障在哪一端。下面 6 条报错都是真实日志原文,按“报错 → 病因 → 一条定位命令”对齐;先跑命令确认,再改配置,能避免把客户端问题当成服务端问题来折腾。

报错原文(可搜索片段) 病因 定位命令
curl: (60) SSL certificate problem: unable to get local issuer certificate 服务端未下发中间证书,或客户端 CA 库过旧 curl -vI --cacert /etc/ssl/certs/ca-certificates.crt https://域名
sun.security.validator.ValidatorException: PKIX path building failed: unable to find valid certification path to requested target JDK 的 cacerts 里缺根证书/中间证书 keytool -list -cacerts | grep -i isrg
javax.net.ssl.SSLHandshakeException: ... CertPathValidatorException: Trust anchor for certification path not found Android 7.0(API 24)以前不抓 AIA,服务端必须补链 openssl s_client -showcerts -connect 域名:443
SSL Labs:Chain issues: Incomplete / Contains anchor / Extra download 缺中间证书 / 多发根证书 / 客户端需二次抓取(性能告警) SSL Labs 服务器测试页
error 19 at 0 depth lookup: self-signed certificate in certificate chain 或 error 2 at 1 depth lookup: unable to get issuer certificate 拼接顺序颠倒,或混入无关交叉签名证书 openssl verify -untrusted chain.pem leaf.pem
SSL_CTX_use_certificate_chain_file() failed (SSL: error:0908F066:PEM routines:get_header_and_data:bad end line) CRLF 换行、多余空行、BOM 或权限不可读 file fullchain.pem / dos2unix

第 1 条的关键是排除客户端因素。用系统 CA bundle 显式复测(Debian/Ubuntu 为 /etc/ssl/certs/ca-certificates.crt,RHEL 系为 /etc/pki/tls/certs/ca-bundle.crt):若仍报 60,问题在服务端,因为 --cacert 已绕开客户端信任库差异。据 Let’s Encrypt 文档,Nginx 的 ssl_certificate 必须指向 fullchain.pem(叶证书 + 中间证书),而不是 cert.pem。

# 数一下服务端到底下发了几张证书(OpenSSL 1.0.0+ 均支持 -showcerts)
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null 
  | grep -c 'BEGIN CERTIFICATE'
# 输出 1 = 只发了叶证书,链不完整;2~3 = 正常(根证书不必下发)

# 客户端侧复测:绕开本地信任库差异,判定故障归属
curl -vI --cacert /etc/ssl/certs/ca-certificates.crt https://example.com

# 服务端侧校验拼接顺序:chain.pem 仅含中间证书,leaf.pem 仅含站点证书
openssl verify -untrusted chain.pem leaf.pem
# 期望 "leaf.pem: OK";error 2 / error 19 见上表

第 2 条是 Java 特有坑。JDK 8u301、11.0.12 及以后版本的 cacerts 才内置 ISRG Root X1(Let’s Encrypt 根),更老的 JDK 需要手工导入;注意 JDK 9 起才有 -cacerts 参数,JDK 8 要写完整路径,默认口令为 changeit。

# JDK 9+:查询默认信任库
keytool -list -cacerts -storepass changeit | grep -i "isrg"
# JDK 8:显式指定路径(8u301 之前通常查不到)
keytool -list -keystore "$JAVA_HOME/jre/lib/security/cacerts" -storepass changeit | grep -i "isrg"

# 缺失时导入根证书(PEM 或 DER 均可),别名可自定义
keytool -importcert -trustcacerts -alias isrg-root-x1 -file isrgrootx1.pem 
  -keystore "$JAVA_HOME/jre/lib/security/cacerts" -storepass changeit

第 3 条别想着改 App 代码。Android 7.0 起系统会按证书 AIA 字段自动补抓中间证书,7.0 之前不会,唯一解是在服务端把中间证书拼进链里。同理,SSL Labs 的 Extra download 虽不报错,但意味着每次握手多一次网络往返,移动端弱网下会明显拖慢首包。

第 6 条多半是复制粘贴惹的祸。Windows 编辑器保存的 fullchain.pem 常带 CRLF,OpenSSL 的 PEM 解析器只认 LF:

file fullchain.pem                 # 出现 "CRLF line terminators" 即需转换
dos2unix fullchain.pem             # 同时清掉多余空行;BOM 用 sed -i '1s/^xEFxBBxBF//' 去除
chmod 644 fullchain.pem            # 属主 root、权限 644,确保 nginx 的 worker 用户(nginx/www-data)可读
nginx -t && systemctl reload nginx # 先测配置语法再平滑重载,避免直接 restart 断连

判定边界可以简化成一句话:openssl s_client -showcerts 数出的证书张数决定服务端是否要改配置,curl --cacert 的结果决定客户端信任库是否要更新——两者互不替代。证书路径构建规则见 RFC 5280 第 6 节,公开 TLS 证书的链要求则以 CA/Browser Forum Baseline Requirements 为准。

效果验证:怎么确认证书链配置真的生效了?

改完 Nginx 的 ssl_certificate 或 Apache 的 SSLCertificateChainFile,别靠刷新浏览器判断——HTTP/2 连接复用和系统证书缓存都会给你旧结果。正确顺序是自下而上验四层:先数服务端发了几张证书,再看信任路径能否走通,最后用客户端 SDK 闭环。据 Let’s Encrypt 文档,服务端必须下发 leaf 证书与全部中间证书(根证书可发可不发),这是判断”证书链不完整怎么配置”是否真的收尾的唯一判据。

第一步:服务端到底发了几张证书?

# -servername 必带,否则 SNI 站点会拿到默认证书;</dev/null 防止 s_client 卡在交互等待
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null 
  | grep -c 'BEGIN CERTIFICATE'
# 期望:2(leaf + 1 张中间证书)或 3(leaf + 2 张,常见于交叉签名链)
# 输出 1 = 只发了 leaf,中间证书缺失;输出远大于 3 = 误把根证书或无关证书塞进了链文件

第二步:信任路径能不能走到根?

# -CAfile 用本地信任库:Debian/Ubuntu 为 /etc/ssl/certs/ca-certificates.crt,RHEL 系为 /etc/pki/tls/certs/ca-bundle.crt
# -verify_return_error 让验证失败时进程返回非零,便于写进 CI 脚本
openssl s_client -connect example.com:443 -servername example.com 
  -verify_return_error -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null 2>&1 | tail -3
# 通过:Verify return code: 0 (ok)
# 失败:Verify return code: 21 (unable to verify the first certificate)
#       verify error:num=20:unable to get local issuer certificate

这两条报错是 OpenSSL 依据 RFC 5280 §6 路径验证算法给出的,含义完全不同:20 表示本地信任库里找不到签发者(多为中间证书没发),21 表示链在第一张就断了。区分它们才能定位是配置问题还是证书本身选错。

第三步:应用层真的通了吗?

# --tlsv1.2 强制走 TLS 1.2,排除 TLS 1.3 下个别老客户端的差异
curl -sSI --tlsv1.2 https://example.com -o /dev/null -w '%{http_code}n'   # 期望 200
curl -vI https://example.com 2>&1 | grep -E 'SSL certificate verify|issuer:'
# 期望:* SSL certificate verify ok.
# 失败:curl: (60) SSL certificate problem: unable to get local issuer certificate
验证层级 关键命令/参数 通过判据 失败典型输出
证书数量 -showcerts | grep -c 2 或 3 1
信任路径 -verify_return_error -CAfile Verify return code: 0 (ok) 21 (unable to verify the first certificate)
HTTP 层 curl -sSI -w '%{http_code}' 200 + SSL certificate verify ok. curl: (60) ... unable to get local issuer certificate
第三方扫描 testssl.sh Chain of trust 该段落为 ok,逐张列出中间证书 Chain of trust: failed / chain incomplete
SSL Labs analyze.html?d=example.com Certification Paths 完整,Chain issues 为空 Chain issues: Incomplete

第四步:第三方工具复核

git clone --depth 1 https://github.com/drwetter/testssl.sh.git && cd testssl.sh
./testssl.sh --severity LOW --chain example.com | grep -A4 'Chain of trust'
# 期望 Chain of trust 段为 ok 并列出 Certificate #1/#2 的 issuer 与有效期
# 3.2 之前无 --chain 开关会提示 unknown option,去掉该参数同样会打印此段落

nmap --script ssl-cert -p 443 example.com | grep -c 'Subject:'   # 与第一步数量应一致

第五步:客户端侧闭环

keytool -printcert -sslserver example.com:443 | grep -E '^Certificate[|Issuer:'
# 期望打印 Certificate[1]、Certificate[2](必要时 [3]);只有 [1] 说明链不完整

openssl verify -untrusted intermediate.crt -CAfile /etc/ssl/certs/ca-certificates.crt domain.crt
# 期望:domain.crt: OK(-untrusted 传入中间证书,模拟服务端补全后的完整链)

为什么 s_client 返回 0 (ok),浏览器里还是报证书错误?因为 Chrome/Firefox 会通过证书里的 AIA 扩展(Authority Information Access)自动下载缺失的中间证书并缓存,而 curl、Java、Python requests 等不会。所以”浏览器正常”不能作为链配置生效的证据——按 Let’s Encrypt 与 Mozilla Server Side TLS 的建议,服务端必须自包含完整链,验证时以 openssl s_client 和 openssl verify 的结果为准。

续期与自动化:certbot、acme.sh 续期后证书链为什么又丢了?

续期之后证书链”又丢了”,绝大多数情况不是 CA 少发了中间证书,而是配置指向了错误的文件:续期只是重新写了一遍 /etc/letsencrypt/live/<domain>/ 下的几个文件,如果你引用的本来就是只含 leaf 的 cert.pem,那么每 60 天续期一次,就等于每 60 天重新确认一次”缺链”状态。据 Let’s Encrypt 文档,certbot 1.x 及以上在该目录下固定生成四类文件:cert.pem(仅服务器证书)、chain.pem(仅中间证书)、fullchain.pem(leaf + 中间证书)、privkey.pem(私钥)。Nginx 的 ssl_certificate、Apache 的 SSLCertificateFile 都应当指向 fullchain.pem。

# 1) 先确认当前 fullchain 里到底有几张证书(期望 >= 2)
openssl crl2pkcs7 -nocrl -certfile /etc/letsencrypt/live/example.com/fullchain.pem 
  | openssl pkcs7 -print_certs -noout

# 2) Nginx:把 ssl_certificate 改成 fullchain
#    ssl_trusted_certificate 只用于 OCSP stapling,填 chain.pem 即可
ssl_certificate         /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key     /etc/letsencrypt/live/example.com/privkey.pem;
ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;

# 3) Apache 2.4.8+:SSLCertificateFile 指向 fullchain 后,
#    SSLCertificateChainFile 已废弃,不要再单独写中间证书
SSLCertificateFile    /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem

第二个高频坑是”续期成功了但服务没重载”。certbot 的 certbot renew 默认只更新磁盘文件,不会 reload 服务,必须显式挂 deploy hook(写进 /etc/letsencrypt/renewal-hooks/deploy/ 或 --deploy-hook);acme.sh 则用 --install-cert 一次性把文件路径和重载命令绑进续期任务,路径写死、钩子写死,避免人工遗漏:

# acme.sh:安装证书时同时注册续期钩子(60 天自动续期)
acme.sh --install-cert -d example.com 
  --key-file       /etc/nginx/ssl/privkey.pem 
  --fullchain-file /etc/nginx/ssl/fullchain.pem 
  --reloadcmd      'systemctl reload nginx'   # 续期成功后自动执行

# certbot:新增 deploy hook,之后每次 renew 成功都会执行
certbot renew --deploy-hook 'systemctl reload nginx'

第三个坑出现在商业证书上:续期时 CA 可能更换中间 CA(例如从旧的交叉签名链切到新根),如果你沿用上一周期的 intermediate.crt,浏览器会报 unable to get local issuer certificate。续期流程里必须同步替换链文件并重新拼接,而不是只替换 leaf。

项目 certbot(1.x+) acme.sh
leaf 证书 live/<domain>/cert.pem ~/.acme.sh/<domain>/<domain>.cer
含链文件 live/<domain>/fullchain.pem --fullchain-file 指定的路径
续期后重载 需 --deploy-hook 或 renewal-hooks/deploy/ --reloadcmd 写入续期任务
默认续期节奏 剩余 30 天内触发(systemd timer/cron) 每 60 天(--days 可调)

告警节奏要跟着有效期走:Let’s Encrypt 证书有效期 90 天,建议在到期前 30 天告警。据 CA/Browser Forum SC-081 决议,公有 TLS 证书最长有效期将分阶段缩短,到 2029 年降至 47 天,人工续期窗口会被压缩到几乎不可操作,链文件与重载的自动化程度直接决定站点可用性。监控侧可用 Prometheus blackbox_exporter 的 probe_ssl_earliest_cert_expiry 指标(配合 expr: probe_ssl_earliest_cert_expiry - time() < 86400 * 30),或在 Zabbix 中执行 ssl-cert-check -a -f /etc/ssl/certs/ca-certificates.crt -s example.com:443 -x 30 做主动探测。

最后把回归检查固化进流水线,每次续期或换 CA 后固定跑一遍,两条断言即可:证书数量 ≥ 2、握手在严格校验下不报错。

# 期望输出 2 或更多;只输出 1 说明链又丢了
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null 
  | grep -c 'BEGIN CERTIFICATE'

# 严格校验(OpenSSL 1.1.1+),失败时返回非零,可直接让 CI 红掉
openssl s_client -connect example.com:443 -servername example.com -verify_return_error </dev/null

证书链之外的关联配置:OCSP Stapling、HSTS 与客户端信任库

为什么 ssl_stapling on 写了却没生效?因为 OCSP Stapling 不是独立功能,它必须能自己拼出”leaf → 中间证书 → 根”的完整链去验证 OCSP 响应。据 Nginx 官方文档,ssl_stapling 默认 off,ssl_stapling_verify 也默认 off;而 ssl_trusted_certificate 指向的文件里只应放中间证书,不要放站点自己的 leaf,否则 Nginx 找不到签发者,stapling 会静默失败——页面照常打开,只是响应里没有 OCSP 字段。这正是”证书链不完整怎么配置”里最容易被漏掉的一环:ssl_certificate 用的是 fullchain.pem,但 stapling 走的是另一个文件。

# Nginx 1.19.0+ 通用写法,放入 server{} 或 http{}
ssl_stapling on;                 # 默认 off
ssl_stapling_verify on;          # 默认 off,开启后需 resolver 或可信证书
ssl_trusted_certificate /etc/nginx/ssl/chain.pem;  # 仅中间证书,不含 leaf
resolver 223.5.5.5 8.8.8.8 valid=300s;             # 缺此行 stapling 必然失败
resolver_timeout 5s;
# 验证:返回 successful 才算真正生效
echo | openssl s_client -connect example.com:443 -servername example.com 
  -status 2>/dev/null | grep -A1 "OCSP Response Status"
# 期望输出:OCSP Response Status: successful (0x0)
# 若为 "no response sent",先查 chain.pem 是否含中间证书、resolver 是否可达

HSTS 要不要和链配置一起上?两者技术上互不影响,但发布节奏必须绑在一起:链不完整时浏览器会先弹证书错误,用户点了”继续访问”也拿不到 HSTS 头;反过来,一旦 HSTS 生效且 includeSubDomains 覆盖了某个仍用自签名的子域,该子域会直接不可访问且无法回退。建议首次上线先给 300 秒观察:

# 灰度期(Nginx 1.7.5+ 才支持 always 参数)
add_header Strict-Transport-Security "max-age=300" always;
# 确认链、跳转、子域全部正常后,再拉长到一年
# add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

服务端补全了链,客户端为什么还报 unknown CA?因为信任库是三条独立的链,必须分别确认。CentOS 7 自带的 ca-certificates 包停留在较旧版本(且 CentOS 7 已于 2024-06-30 EOL),可能不含新根;JDK 更是完全不读系统库,只认自己的 cacerts。

环境 更新命令 生效文件 关键注意
Debian / Ubuntu update-ca-certificates /etc/ssl/certs/ca-certificates.crt 证书放 /usr/local/share/ca-certificates/,后缀须为 .crt
RHEL / CentOS / Rocky update-ca-trust extract /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem 源文件放 /etc/pki/ca-trust/source/anchors/
JDK 8u/11/17/21 keytool -importcert $JAVA_HOME/lib/security/cacerts 默认口令 changeit,与系统库完全隔离
keytool -importcert -noprompt -trustcacerts -alias my-root 
  -file my-root.crt -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit

交叉签名证书该留还是该删?部分 CA(如 Let’s Encrypt 在 DST Root CA X3 到期前后的过渡方案)会同时提供由旧根和新根签发的两张中间证书。交叉签名能让 Android 7.0 以下等老客户端走通,代价是链长度 +1、握手包变大。据 Let’s Encrypt 官方说明,过渡期结束后应切换为单链,长期携带冗余证书只会拖慢握手并让审计变复杂。

私有 CA 和双向认证呢?服务端除了下发自己的中间证书,还要用 ssl_client_certificate 指定客户端证书的 CA 链,该指令同样要求完整链文件(不含 leaf),否则握手阶段会直接失败,日志里常见 400 Bad Request / No required SSL certificate was sent 或验证错误:

ssl_client_certificate /etc/nginx/ssl/client-ca-chain.pem;  # 客户端 CA 完整链
ssl_verify_client on;
ssl_verify_depth 2;   # 默认 1,链深一级就要加一

怎么避免下次再漏?把 fullchain 的生成、校验、reload 做成幂等脚本,纳入 Ansible / SaltStack,与 TLS 版本、加密套件、HSTS 一起作为 HTTPS 基线统一审计。这样”证书链不完整怎么配置”就从一次性排查变成可回归的检查项:

#!/usr/bin/env bash
set -euo pipefail
cat /etc/nginx/ssl/leaf.crt /etc/nginx/ssl/chain.pem > /etc/nginx/ssl/fullchain.pem
openssl verify -untrusted /etc/nginx/ssl/chain.pem /etc/nginx/ssl/leaf.crt  # 期望 leaf.crt: OK
nginx -t && systemctl reload nginx

典型报错有三类:curl 报 curl: (60) SSL certificate problem: unable to get local issuer certificate;Java 报 PKIX path building failed: unable to find valid certification path to requested target;Android 报 Trust anchor for certification path not found。桌面浏览器因为会通过 AIA 扩展自动抓取中间证书,通常不会报错,这也是问题最容易被忽略的原因。

只配中间证书,不要配根证书。服务器证书文件应为 leaf + 中间证书(fullchain.pem),根证书已经内置在客户端和操作系统的信任库中,再下发一遍会被 SSL Labs 标记为 Chain issues: Contains anchor,并让每次握手多传约 1.5 KB。只有当客户端信任库确实缺少某个新根时,才考虑用交叉签名证书过渡,而不是直接下发根证书。

配置方法完全一致,区别在文件来源:Let's Encrypt 用 certbot 生成的 fullchain.pem 即为完整链,acme.sh 需显式加 –fullchain-file;商业证书(DigiCert、Sectigo 等)通常在签发邮件或控制台提供 ca-bundle.crt,需要自己 cat 拼接。另一点差异是商业证书续期时中间 CA 可能变更,需要同步替换链文件,而 Let's Encrypt 的中间证书相对稳定。

先确认服务端真的发出了多张证书:openssl s_client -showcerts 输出的 BEGIN CERTIFICATE 数量是否为 2 或 3,若仍为 1,说明配置没生效或 reload 失败,检查 nginx -t 输出与进程是否真正重载。若服务端数量正常,问题在客户端:老版本 curl/OpenSSL 的 CA 包过旧,执行 update-ca-certificates(Debian/Ubuntu)或 update-ca-trust extract(RHEL 系)更新信任库后再测。

不是一回事。ssl_certificate 从 Nginx 1.11.0 起可以写多次,用途是同时部署 RSA 和 ECDSA 两张不同的服务器证书,让 Nginx 按客户端能力自动选择。而证书链必须写在同一个文件里,即一张 leaf 后面紧跟它的中间证书。把两张 leaf 拼进一个文件、或把不同算法的链混在一起,都会导致握手失败。

用 openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout -text | grep -A2 'Not After' 可以列出链上每张证书的到期时间。中间证书有效期通常比 leaf 长,但并非绝对,尤其在使用交叉签名证书时;建议把链文件也纳入到期监控,与 leaf 一起在到期前 30 天告警。


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。