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

SSL 证书安装教程 best practices:跨 Nginx、Apache、HAProxy 与 Tomcat 的一致安装与验收

ssl证书 安装教程 best practices — SSL 证书安装教程 best practices:跨 Nginx、Apache、HAProxy 与 Tomcat 的一致安装与验收
核心结论

SSL 证书安装的最佳实践是先做材料校验(证书与私钥 modulus 一致、fullchain 顺序为 leaf→intermediate、私钥权限 600),再按 Nginx 1.26/Apache 2.4.62/HAProxy 3.0/Tomcat 10.1 的格式落地,最后用 openssl s_client 确认 Verify return code: 0 (ok)。 Nginx 与 Apache 直接用 PEM fullchain;Tomcat 10.1 优先 PKCS#12,老 Java 8 再用 keytool -importkeystore 转 JKS。 HAProxy 3.0 的 crt 文件必须把证书、私钥、中间链合并,私钥不能加密,权限 600。 验证至少跑三组命令:openssl s_client -showcerts、curl --tlsv1.3 -vI、nmap --script ssl-enum-ciphers,目标 SSL Labs A/A+,扫描 2-5 分钟。

一、为什么同一张证书在 Nginx 能跑、到 Tomcat 就报错?

这是运维群里最高频的提问之一:同一份 fullchain.pem + privkey.pem,在 Nginx 上 nginx -t 一路绿灯,搬到 Tomcat 却抛 java.io.IOException: keystore password was incorrect 或 CertificateException: No certificate found。根因不在证书本身,而在证书材料的格式与每个服务端各自的信任模型不匹配。下面按四个根因逐一拆解,这也是本 ssl证书安装教程 best practices 的基线。

根因一:PEM 是文本,Java 默认不吃文本。据 OpenSSL 3.2 文档,PEM 只是把 DER 做 Base64 再套上 -----BEGIN CERTIFICATE----- 头尾,换行位置与链顺序都会影响解析。Nginx/Apache/HAProxy 直接读 PEM,而 Tomcat 走密钥库。JDK 9 起 keystore.type 默认已改为 pkcs12,JKS 属于遗留格式,因此 Tomcat 8.5+ 首选 PKCS#12:

# 把 PEM 链 + 私钥打包成 PKCS#12;-certfile 只放中间 CA,绝不要放根证书
openssl pkcs12 -export 
  -in fullchain.pem -inkey privkey.pem 
  -certfile intermediate.crt 
  -name tomcat -out keystore.p12 
  -passout pass:Changeit123
# -name 必须与 server.xml 中 keystoreAlias 一致,别名不匹配是 Tomcat 启动失败的常见原因
# 仅 Tomcat 7 及更早需要再转 JKS:
keytool -importkeystore -srckeystore keystore.p12 -srcstoretype PKCS12 
  -destkeystore keystore.jks -deststoretype JKS -deststorepass Changeit123

根因二:中间链缺失或顺序颠倒。服务端只应发送「叶子证书 + 中间 CA」,根证书由客户端本地信任库提供。RFC 8446 第 4.4.2 节要求 Certificate 消息按 leaf→intermediate 顺序排列,顺序反了部分客户端直接报 curl: (60) unable to get local issuer certificate。拼接后务必自检:

# 正确顺序:叶子在前,中间 CA 在后
cat server.crt intermediate.crt > fullchain.pem
# 打印链上每张证书的 subject/issuer,确认逐级衔接
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
服务端 证书材料格式 链如何提供 典型坑
Nginx 1.20+ PEM 单文件 ssl_certificate 指向 fullchain.pem 只配叶子证书,链缺失
Apache httpd 2.4 PEM 2.4.8 起 SSLCertificateChainFile 已废弃,链并入 SSLCertificateFile 仍在用旧指令导致链未下发
HAProxy 2.x PEM 单文件 crt 文件内 leaf→intermediate 顺序拼接 顺序错、文件含多余空行
Tomcat 8.5+ PKCS#12 密钥库内自带链 JKS 遗留格式、别名不匹配

根因三:私钥权限与 SELinux 上下文。Nginx worker 以 nginx 用户读取私钥,644 权限等于把私钥暴露给全机;但在 RHEL/CentOS 上把私钥放 /root 下又会被 SELinux 的 httpd_t 域拒绝(admin_home_t 不可读),正确做法是固定目录 + 属组 + restorecon:

install -d -m 750 -o root -g nginx /etc/nginx/ssl
install -m 640 -o root -g nginx fullchain.pem privkey.pem /etc/nginx/ssl/
restorecon -Rv /etc/nginx/ssl          # 恢复为 etc_t 上下文,解除 SELinux 拒绝
# 若使用自定义路径:semanage fcontext -a -t httpd_sys_content_t "/data/ssl(/.*)?"

根因四:只 reload 不验收。nginx -t 只做语法检查,不校验证书与私钥是否配对、链是否完整、OCSP 是否可达。上线后必须做端到端探测:

# 期望输出 Verify return code: 0 (ok);非 0 即链或信任问题
openssl s_client -connect example.com:443 -servername example.com 
  -showcerts </dev/null 2>/dev/null | grep -E "Verify return code|depth="

时间与成本上,DV 单域名证书约 0–300 元/年、OV 约 500–2000 元/年、EV 约 1500–5000 元/年;四端统一安装的窗口建议留 30–60 分钟,灰度验证再留 10–15 分钟。据 CA/Browser Forum Baseline Requirements,公有证书有效期上限为 398 天且将继续缩短——这意味着手工复制文件的做法注定不可持续,本文后续给出的 ssl证书安装教程 best practices 一律以「可重复、可脚本化」为前提。

二、完整实操步骤:从材料校验到四类服务端落地(分步骤编号)

本节按“先校验、再落盘、后灰度”的顺序给出六个步骤,全部命令可直接复制。核心原则只有一条:证书材料在任何服务端上都是同一套 PEM 内容,差异只出现在加载方式与格式转换上,所以校验环节做扎实,后面四类服务端的配置就只是语法差别。

步骤 1:校验证书与私钥是否匹配。这是最高频的翻车点,配对失败时 Nginx 会直接报 SSL_CTX_use_PrivateKey() failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)。RSA 证书用模数比对,两行 MD5 必须完全一致:

# RSA 证书:两个 MD5 必须一致(OpenSSL 1.1.1 / 3.x 均适用)
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in privkey.pem   | openssl md5

# ECC 证书(ECDSA P-256 等):用公钥 SHA256 比对
openssl pkey -pubout -in privkey.pem          | openssl sha256
openssl x509 -pubkey -noout -in cert.pem      | openssl sha256

步骤 2:校验链顺序与完整性。顺序错了浏览器会报“证书链不完整”,而服务端往往能正常启动,属于最隐蔽的故障:

# 用中间链验证域名证书,期望输出 cert.pem: OK
openssl verify -CAfile chain.pem -untrusted chain.pem cert.pem

# 查看 fullchain.pem 的实际顺序,第一张必须是你的域名证书
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout

据 Let’s Encrypt 文档,fullchain.pem 的约定就是“域名证书在前、中间证书在后”,顺序颠倒会触发 unable to get local issuer certificate。生产环境建议把 -CAfile 换成系统根库(/etc/ssl/certs/ca-certificates.crt),可同时验证是否误带了根证书。

步骤 3:统一命名与权限。四类服务端共用一个目录,便于脚本轮换与审计:

install -d -m 700 -o root -g root /etc/ssl/example.com
install -m 644 fullchain.pem chain.pem /etc/ssl/example.com/
install -m 600 privkey.pem             /etc/ssl/example.com/
# 若 Nginx worker 非 root 运行,可单独放宽属组
chown root:nginx /etc/ssl/example.com/privkey.pem   # 权限保持 600

目录 700、私钥 600、证书 644 是通行默认值;私钥一旦是 644,多数发行版上的 Nginx 仍能启动,但等于把密钥暴露给所有本地用户。

步骤 4:按服务端转换格式。PEM 是通用底座,只有 Tomcat 需要额外转换:

服务端 加载格式 关键配置 语法检查 / 生效
Nginx ≥1.11 PEM ssl_certificate fullchain.pem; ssl_certificate_key privkey.pem; nginx -t → systemctl reload nginx
Apache httpd 2.4 PEM SSLCertificateFile fullchain.pem、SSLCertificateKeyFile privkey.pem apachectl configtest → reload
HAProxy 2.x PEM(证书+私钥合并单文件) bind :443 ssl crt /etc/haproxy/certs/example.com.pem haproxy -c -f cfg → reload
Tomcat 10.1 / 9.x PKCS#12(JKS 亦可) Connector 的 keystoreFile / keystorePass catalina.sh configtest
# HAProxy 需要把 fullchain + 私钥拼成一个文件(顺序:证书→中间→私钥)
cat fullchain.pem privkey.pem > /etc/haproxy/certs/example.com.pem
chmod 600 /etc/haproxy/certs/example.com.pem

# Tomcat 10.1 推荐 PKCS#12(Java 9+ 默认密钥库类型即 PKCS12)
openssl pkcs12 -export -out keystore.p12 -inkey privkey.pem 
  -in fullchain.pem -name tomcat -passout pass:ChangeMe

# Java 8 老环境再转 JKS(keytool 随 JDK 提供)
keytool -importkeystore -srckeystore keystore.p12 -srcstoretype PKCS12 
  -destkeystore keystore.jks -deststoretype JKS

步骤 5:单节点灰度并 reload。永远不要一次推全量,先在一台上验证再滚动:

nginx -t && systemctl reload nginx
apachectl configtest && systemctl reload httpd
haproxy -c -f /etc/haproxy/haproxy.cfg && systemctl reload haproxy
/opt/tomcat/bin/catalina.sh configtest   # Tomcat 无热加载,需 restart

reload 与 restart 的区别在证书轮换时很关键:Nginx、Apache、HAProxy 的 reload 会平滑重读证书,旧连接不受影响;Tomcat 的 Connector 只在启动时读取 keystore,必须重启。

步骤 6:先备份,再记录回滚点。把旧文件与旧配置按日期归档,保留 30 天,reload 前用 diff -u 确认改动范围:

BK=/etc/ssl/backup/$(date +%F); mkdir -p "$BK" && chmod 700 "$BK"
cp -a /etc/ssl/example.com/* "$BK"/
cp -a /etc/nginx/conf.d/example.com.conf "$BK"/
diff -u "$BK"/example.com.conf /etc/nginx/conf.d/example.com.conf

# 回滚
cp -a "$BK"/fullchain.pem "$BK"/privkey.pem /etc/ssl/example.com/
systemctl reload nginx

以上六步构成一套可复用的 ssl 证书 安装教程 best practices 骨架:校验决定“能不能用”,命名与权限决定“安不安全”,灰度与备份决定“出事能不能退”。把这套流程脚本化后,四类服务端的差异就只剩步骤 4 的一条转换命令和步骤 5 的一个 reload 命令。

四个组件装同一张证书,差异到底在哪?不在证书本身,而在证书链的拼接形态和重载前的语法校验命令。据 Let’s Encrypt 文档,fullchain.pem(叶证书+中间证书)与 privkey.pem 是通用输入;但 HAProxy 要求二者物理合并为单文件,Tomcat 则更倾向 PKCS12 密钥库。下面给出四份可直接复制的配置。

Nginx 1.26.2 怎么写?在 server { listen 443 ssl; } 块中配置。ssl_protocols 自 1.23.4 起默认值已改为 TLSv1.2 TLSv1.3,显式声明可避免旧版行为差异(据 nginx 官方 changelog 与 Mozilla SSL Configuration Generator):

server {
    listen 443 ssl;
    http2 on;                                   # 1.25.1+ 用独立指令,替代 listen ... http2
    server_name example.com;

    ssl_certificate           /etc/ssl/example.com/fullchain.pem;  # 叶+中间,必须全链
    ssl_certificate_key       /etc/ssl/example.com/privkey.pem;    # 私钥,权限 600
    ssl_trusted_certificate   /etc/ssl/example.com/chain.pem;      # 仅用于 OCSP stapling 校验
    ssl_protocols             TLSv1.2 TLSv1.3;                     # 禁用 TLS1.0/1.1(RFC 8996)
    ssl_session_cache         shared:SSL:10m;
    ssl_stapling              on;
    ssl_stapling_verify       on;
}
# 校验后重载:先测语法,再平滑重载,不断连接
nginx -t && systemctl reload nginx
# 成功输出:
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

Apache 2.4.62 怎么写?注意 SSLCertificateChainFile 自 2.4.8 起已废弃,官方推荐把 leaf+intermediate 直接合并进 SSLCertificateFile,写错会出现浏览器报”证书链不完整”而 curl 却通过的情况:

<VirtualHost *:443>
    ServerName example.com
    SSLEngine on
    SSLCertificateFile      /etc/ssl/example.com/fullchain.pem   # 2.4.8+ 含中间证书
    SSLCertificateKeyFile   /etc/ssl/example.com/privkey.pem
    SSLProtocol             -all +TLSv1.2 +TLSv1.3
    SSLOptions              +StrictRequire
</VirtualHost>
apachectl configtest        # 期望输出 Syntax OK
systemctl reload httpd      # Debian/Ubuntu 为 apache2

HAProxy 3.0 怎么写?crt 参数只接受”单文件”,私钥不得加密(不能带 passphrase),否则启动即失败:

# 合并顺序:证书 → 私钥 → 中间链,顺序错误会导致握手失败
cat cert.pem privkey.pem chain.pem > /etc/haproxy/certs/example.com.pem
chmod 600 /etc/haproxy/certs/example.com.pem

frontend fe_https
    bind :443 ssl crt /etc/haproxy/certs/example.com.pem alpn h2,http/1.1
    ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets   # 3.0 默认仍允许 TLS1.2 起

haproxy -c -f /etc/haproxy/haproxy.cfg   # Configuration file is valid
systemctl reload haproxy

Tomcat 10.1 怎么写?server.xml 的 <SSLHostConfig> 支持 PEM 直读(Tomcat 8.5+)或 PKCS12,二选一:

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true">
  <SSLHostConfig>
    <Certificate certificateFile="/etc/ssl/example.com/fullchain.pem"
                 certificateKeyFile="/etc/ssl/example.com/privkey.pem"
                 certificateChainFile="/etc/ssl/example.com/chain.pem"
                 type="RSA" />
    <!-- 或:keystoreFile="/etc/ssl/example.com/keystore.p12"
             keystorePass="***" keystoreType="PKCS12" -->
  </SSLHostConfig>
</Connector>
组件 证书文件形态 关键指令 校验命令
Nginx 1.26.2 fullchain + privkey 分离 ssl_certificate nginx -t
Apache 2.4.62 fullchain 合并 SSLCertificateFile apachectl configtest
HAProxy 3.0 三合一单文件 bind ... ssl crt haproxy -c -f
Tomcat 10.1 PEM 或 PKCS12 certificateFile 启动日志 + s_client

如何验收?任何一份 ssl证书 安装教程 best practices 都必须落到外部验证,而不是只看配置语法通过。用 OpenSSL 3.2 强制 TLS 1.3 抓取证书链:

openssl s_client -connect example.com:443 -servername example.com 
  -showcerts -tls1_3 </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates
# subject=CN = example.com
# issuer=C = US, O = Let's Encrypt, CN = R11
# notAfter=...

curl -vI https://example.com --tlsv1.3 --tls-max 1.3 2>&1 | grep -E "SSL certificate verify|TLSv1.3"
# * SSL certificate verify ok.

权限与 SELinux 踩坑怎么办?RHEL/CentOS 上把证书放到 /etc/nginx/ssl 常被 SELinux 拒绝,表现为 403 或 cannot load certificate。先确认模式,再打标签:

getenforce                                  # Enforcing / Permissive / Disabled
ausearch -m avc -ts recent | grep nginx     # 有 AVC denied 即为策略拦截
# 持久化上下文规则(-a 追加,重启不失效)
semanage fcontext -a -t httpd_sys_content_t '/etc/nginx/ssl(/.*)?'
restorecon -Rv /etc/nginx/ssl
chmod 600 /etc/ssl/example.com/privkey.pem && chown root:root /etc/ssl/example.com/privkey.pem

私钥权限建议 600、属主 root;若 Web 进程非 root(如 www-data),用组读 640 并加入 ssl-cert 组,比直接 chmod 644 安全得多——后者会让同机任意用户读到私钥,是审计中的高频高危项。

四、参数对比与方案选型:PEM、PKCS#12、JKS 怎么选

问:同一张证书,为什么 Nginx 直接读 PEM,Tomcat 却非要 PKCS#12 或 JKS?因为三者不是”格式版本”关系,而是三种不同的容器契约:PEM 按 RFC 7468 用 -----BEGIN CERTIFICATE----- 文本块逐段存放,可被 OpenSSL、Nginx、HAProxy 直接解析;PKCS#12(RFC 7292)是加密二进制容器,把私钥、站点证书、中间链打进一个文件;JKS 是 Sun 的私有 keystore 格式,且自 JDK 9 起 keytool 默认生成的是 PKCS#12 而非 JKS——这一点常被老教程忽略,导致”按教程生成 JKS 却拿到 p12″的困惑。据 Tomcat 10.1 官方文档,<Certificate> 元素的 certificateKeystoreType 未显式声明时会依扩展名推断,写错就会在启动时抛 java.io.IOException: Keystore was tampered with, or password was incorrect。

服务端/运行时 推荐格式 证书文件关键参数 私钥权限 重载/重启命令 适用场景
Nginx 1.26 PEM(fullchain + privkey 分离) ssl_certificate、ssl_certificate_key、ssl_trusted_certificate(默认均为空,必须显式配置) 600 root:root nginx -t && systemctl reload nginx 高并发反向代理、静态站点
Apache 2.4.62 PEM(fullchain 合并为单文件) SSLCertificateFile、SSLCertificateKeyFile;2.4.8 起无需再写 SSLCertificateChainFile 600 root:root apachectl configtest && systemctl reload httpd 传统 LAMP、.htaccess 业务
HAProxy 3.0 PEM 合并(cert + key + chain 同文件) bind :443 ssl crt /etc/haproxy/certs/site.pem,可选 ca-file 校验客户端证书 600 haproxy:haproxy haproxy -c -f /etc/haproxy/haproxy.cfg && systemctl reload haproxy 四层/七层负载均衡入口
Tomcat 10.1 PKCS#12 优先,JKS 仅兼容老 Java certificateKeystoreFile、certificateKeystoreType、certificateKeystorePassword 600 tomcat:tomcat systemctl restart tomcat(Connector 不支持热重载) Java 应用、Spring Boot 外置 Tomcat

落地时最常见的动作是”一次签发、两种落盘”。用 OpenSSL 3.x 从 PEM 转 PKCS#12,再用 keytool 按需降级为 JKS:

# 1) 收紧私钥权限(Nginx/Apache 场景,600 是必须项而非建议)
install -m 600 -o root -g root fullchain.pem privkey.pem /etc/nginx/ssl/

# 2) PEM → PKCS#12,供 Tomcat 10.1;-name 对应 server.xml 里的 keystoreAlias
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem 
  -certfile chain.pem -name tomcat -out tomcat.p12 -passout pass:ChangeMe123

# 3) PKCS#12 → JKS,仅在 Java 8 且工具链只认 JKS 时执行
#    JDK 9+ 的 keytool 默认 -deststoretype 为 PKCS12,必须显式写 JKS
keytool -importkeystore -srckeystore tomcat.p12 -srcstoretype PKCS12 
  -destkeystore tomcat.jks -deststoretype JKS -deststorepass ChangeMe123

验收阶段有两条真实报错值得记住:Nginx 若报 SSL_CTX_use_PrivateKey(...) failed (SSL: error:0B080074:X509_check_private_key:key values mismatch),说明私钥与证书不配对,通常是续期后只换了证书没换私钥;Apache 报 AH02217: ssl_stapling_init_cert: can't retrieve issuer certificate,则是 fullchain 里缺中间证书——这两类问题在跨四种服务端批量部署时占比最高,建议把 openssl verify -CAfile chain.pem fullchain.pem 写进发布流水线。

选型结论可以简化成一句:新项目统一产出 PEM + PKCS#12 双份,PEM 喂 Nginx/Apache/HAProxy,PKCS#12 喂 Tomcat;只有当运行时是 Java 8 且既有工具链只认 JKS 时才额外转一份,避免三份文件漂移。预算上,DV 证书 0–300 元/年适合测试与个人站,OV 500–2000 元/年适合企业对外业务,EV 1500–5000 元/年用于高信任场景;把安装窗口预留 30–60 分钟、灰度观察 10–15 分钟,是这份 ssl证书 安装教程 best practices 里成本最低却最常被跳过的一步。

五、常见错误与排查:这些真实报错分别怎么处理

为什么建议先看服务端、再看客户端?因为六类报错里只有两类(curl 的 unable to get local issuer certificate、Java 的 PKIX)可能出在客户端信任库,其余四类都在服务端。先用一条命令从外部复现,就能把排查范围砍掉一半:

# 从任意一台机器看服务端到底发了什么链(-servername 必须带,否则可能拿到默认站点的证书)
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null 
  | grep -c "BEGIN CERTIFICATE"
# 期望输出 2(leaf + intermediate);1 = 漏发中间链;3 = 把根证书也发了
# 依据 RFC 8446 与 CA/B Forum 实践,服务端应发送除根外的完整链,根由客户端自带

Nginx 报 SSL_CTX_use_PrivateKey: key values mismatch 怎么办?这是 ssl_certificate 与 ssl_certificate_key 不配对,最常见的场景是续期脚本只覆盖了证书、没换私钥。按密钥类型选一条命令比对:

# RSA:两行 md5 必须完全一致
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in privkey.pem  | openssl md5

# ECC(ECDSA):改比公钥摘要
openssl x509 -noout -pubkey -in fullchain.pem | openssl sha256
openssl pkey -in privkey.pem -pubout      | openssl sha256

Nginx 1.11.0 起 ssl_certificate 可在同一 server 块内重复书写以同时下发 RSA 与 ECC 双证书,顺序即优先级;若两个文件都写了但只有一个 key,同样会报此错。

Apache 报 AH02217: ssl_stapling_init_cert: can’t retrieve issuer certificate?OCSP stapling 需要从 SSLCertificateFile 里推导出签发者,文件里只有 leaf 就推不出来。Apache 2.4.8 起 SSLCertificateChainFile 被标记为废弃,2.4.62 的推荐做法是把 leaf 与中间证书合并进同一个文件:

cat cert.pem chain.pem > fullchain.pem   # leaf 在前,中间证书在后,顺序不能反

# httpd-ssl.conf(Apache 2.4.62)
SSLCertificateFile     /etc/httpd/ssl/fullchain.pem   # 含 leaf + intermediate
SSLCertificateKeyFile  /etc/httpd/ssl/privkey.pem
SSLUseStapling         on
SSLStaplingCache       "shmcb:logs/ssl_stapling(32768)"

# 验证链是否自洽:chain.pem 中须含签发该 leaf 的中间证书
openssl verify -CAfile chain.pem -untrusted chain.pem cert.pem   # 期望 cert.pem: OK

HAProxy 报 unable to load SSL private key from PEM file?HAProxy 的 crt 是自拼装文件,顺序错或私钥带口令都会失败——HAProxy 3.0 不支持交互式输入口令,必须用未加密私钥:

# 3.0 推荐顺序:leaf → key → chain
cat cert.pem privkey.pem chain.pem > /etc/haproxy/certs/example.com.pem
chmod 600 /etc/haproxy/certs/example.com.pem

openssl rsa -in privkey.pem -check -noout   # 输出 "RSA key ok";若提示 Enter pass phrase 说明有口令
openssl pkey -in privkey.pem -out privkey.plain.pem   # 交互输入口令,导出无口令私钥
# haproxy.cfg
bind *:443 ssl crt /etc/haproxy/certs/   # 目录模式,文件名即 SNI 主机名

Tomcat 报 CertificateException: No subject alternative names present?JSSE 按主机名校验 SAN,而 CN 自 2017 年起已被主流客户端忽略(见 RFC 6125 与 CA/B Forum Baseline Requirements)。先确认 SAN:

openssl x509 -noout -ext subjectAltName -in cert.pem
# X509v3 Subject Alternative Name:
#     DNS:example.com, DNS:www.example.com

重签时把主域名与 www 一起写入 SAN,例如 Let’s Encrypt 的 certbot -d example.com -d www.example.com。生产环境不要靠关闭主机名校验绕过。

curl 报 unable to get local issuer certificate?九成是服务端只发了 leaf,客户端找不到中间证书。用上面的 s_client | grep -c 计数即可定位;正常为 2 张,不是 3 张(含根只会增大握手体积,且部分老客户端会因链歧义报错)。修复方式是改用 Let’s Encrypt 产出的 fullchain.pem(leaf + intermediate),而不是 cert.pem。

Java 报 PKIX path building failed?先分清是信任库缺 CA 还是链缺失:

# JDK 默认信任库 $JAVA_HOME/lib/security/cacerts,默认口令 changeit
keytool -list -cacerts -storepass changeit | grep -i "ISRG Root"

# 仅私有 CA 场景才导入;公有 CA 应优先修服务端链
keytool -importcert -alias myca -file ca.crt -cacerts -storepass changeit -noprompt

把中间证书塞进 cacerts 只是掩盖问题,JDK 每次升级都可能被覆盖,且对非 Java 客户端无效。

报错关键字 出问题的层 先看什么
key values mismatch 密钥对 证书与私钥的 modulus/公钥摘要是否一致
AH02217 链文件 SSLCertificateFile 是否含中间证书
unable to load SSL private key 文件拼装 crt 顺序、私钥是否加密
No subject alternative names 证书内容 SAN 是否覆盖实际访问域名
unable to get local issuer certificate 服务端链 s_client 返回 1 张还是 2 张
PKIX path building failed 客户端信任库 cacerts 是否含该 CA 根

六、效果验证方法:如何确认安装真的生效

链验证:看到 “Verify return code: 0” 就代表证书链没问题吗?

不一定。要同时看两处:-showcerts 是否吐出完整中间证书,以及最后的 Verify return code。注意必须带 -servername(SNI),否则多域名服务器可能返回默认站点证书,验证结果完全对不上。OpenSSL 1.1.1 及以上版本支持该组合(据 OpenSSL 官方文档,-servername 自 1.1.1 起用于 SNI)。

# 一次性取回证书链并打印主体/签发者/有效期
openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null 
  | openssl x509 -noout -subject -issuer -dates
# 通过判据:末尾出现 Verify return code: 0 (ok)
# 若为 20 (unable to get local issuer certificate) → 中间证书缺失
# 若为 10 (certificate has expired) → 证书过期,立即检查 NotAfter

协议版本与套件:怎么证明旧协议真的被关掉了?

只测 TLS 1.3 成功是不够的,还要测它“该失败”的版本。按 RFC 8446,TLS 1.3 已废弃 RSA 密钥交换与 CBC 套件,因此 1.3 握手成功不代表 1.2 的配置也干净。

# 应成功
openssl s_client -connect example.com:443 -servername example.com -tls1_3 </dev/null
# 应失败(若已在 nginx/apache 中禁用 TLS 1.1)
openssl s_client -connect example.com:443 -servername example.com -tls1_1 </dev/null
# 期望报错:sslv3 alert handshake failure / no protocols available

# 枚举实际协商套件(nmap 需安装 ssl-enum-ciphers 脚本)
nmap --script ssl-enum-ciphers -p 443 example.com

参照 Mozilla SSL Configuration Generator 的 “Intermediate” 配置,TLS 1.2 应只剩 ECDHE + AES-GCM/CHACHA20,TLS 1.3 为 TLS_AES_256_GCM_SHA384 等三条。

HTTP 层怎么验?用 curl 8.x(--tls-max 需 7.54+,--tlsv1.3 需 7.61+)锁定协议版本,一次看清证书校验、协议与 HTTP/2:

curl -vI https://example.com --tlsv1.3 --tls-max 1.3 2>&1 | grep -Ei 'SSL certificate verify|TLSv1.3|HTTP/2'
# 期望:SSL certificate verify ok. / TLSv1.3 (OUT) / HTTP/2 200
# 再确认 HSTS 头(Nginx: add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;)
curl -sI https://example.com | grep -i strict-transport-security

常见验证项与失败原因对照

验证项 命令要点 通过判据 常见失败原因
证书链 s_client -showcerts Verify return code: 0 (ok) 漏配 ssl_certificate 中的中间证书
协议 -tls1_3 / -tls1_1 1.3 通、1.1 断 仍保留 TLSv1/1.1 于 ssl_protocols
HSTS curl -sI 存在 max-age≥31536000 always 缺失,4xx 无头
OCSP s_client -status successful (0x0) 未配 resolver 或 stapling off

OCSP Stapling 返回 “not enabled” 怎么办?按 RFC 6960,装订需服务器主动获取响应,所以先确认已开启并配置 DNS 解析器(Nginx 需 ssl_stapling on; ssl_stapling_verify on; resolver 8.8.8.8 valid=300s;):

openssl s_client -connect example.com:443 -servername example.com -status /dev/null 
  | grep -A2 'OCSP Response Status'
# 期望:OCSP Response Status: successful (0x0)
# 若显示 "OCSP response: no response sent" → 检查 ssl_stapling 与 resolver

为什么要多客户端抽检?因为 openssl s_client 不读系统 truststore。Java 环境必须单独验证,否则 Tomcat 上“openssl 正常、应用报 PKIX path building failed”的经典故障无法复现:

curl -I https://example.com                 # curl 8.x
keytool -printcert -sslserver example.com:443  # JDK 8+,核对 Java truststore 是否信任该链
# Android 10+ / iOS 16+ 各真机访问一次,验证根证书兼容性

如何留痕并闭环?用 Qualys SSL Labs 扫描(约 2–5 分钟)目标 A/A+,把扫描日期、证书序列号(openssl x509 -noout -serial)、NotAfter 写入 CMDB。据 Let’s Encrypt 文档,DV 证书有效期 90 天,建议到期前 30 天告警、提前 20 天续期,避免续期失败演变成线上事故。

Nginx/Apache/HAProxy 用 PEM 最直接,Tomcat/Java 优先 PKCS#12。同一张证书可同时保留两份:PEM 给反向代理,PKCS#12 用 openssl pkcs12 -export 生成给 Java;Java 10+ 默认支持 PKCS#12,老 Java 8 再转 JKS。

安装命令基本相同,区别在信任链层数和审核。DV 约 0-300 元/年,OV 约 500-2000 元/年,EV 约 1500-5000 元/年;OV/EV 中间链可能多一层,安装前要用 openssl verify 确认 fullchain 顺序为 leaf→intermediate。

分别计算证书和私钥 modulus 的 MD5,不一致就是配错文件;RSA 用 openssl x509 -noout -modulus 与 openssl rsa -noout -modulus,ECC 用 openssl pkey -pubout 对比公钥。定位后替换为同一批签发的 fullchain.pem 和 privkey.pem。

不强制。Tomcat 10.1 + Java 17 可直接用 PKCS#12,配置 keystoreType='PKCS12';只有老 Java 8 环境或周边工具只认 JKS 时,才用 keytool -importkeystore 转 JKS。

不要。服务端发送 leaf + intermediate 即可,根证书由客户端信任库自带;放根证书会增加握手字节,部分客户端还会报链过长。用 openssl s_client -showcerts 确认只返回 2 张证书即可。

用 openssl s_client -tls1_3 看协议协商,用 -status 看 OCSP Response Status: successful。Nginx 需配置 ssl_stapling on 和 resolver 8.8.8.8,Apache 2.4.62 需 SSLUseStapling on,并确认 fullchain 含中间链。

不影响证书链验证,但部分老客户端会按 SAN 第一项做匹配提示。建议把主域名放 SAN 第一位,并在 Nginx server_name 中显式列出所有域名,避免默认站点串证书。


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

内容审核

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