跳到主要内容
Tomcat

DigiCert SSL 证书 Tomcat 部署实战:PKCS12/JKS 配置、验证与排错全流程

问题背景与根因:证书“装好了”为什么还报错

Tomcat 的 SSL 配置在 8.5 版本发生过一次断代式变化:Tomcat 7 时代在 <Connector> 上直接写 keystoreFile / keystorePass,从 8.5 开始改为 <SSLHostConfig> + <Certificate> 嵌套结构。把老教程的配置粘到 Tomcat 9/10 上,轻则证书不生效,重则启动直接抛 java.lang.IllegalArgumentException。同时 Java 9 起 keytool 默认 keystore 类型由 JKS 改为 PKCS12,这也是大量“照抄老步骤”失败的来源。

线上最常见的根因只有三类:

  • 证书链不完整:只部署了叶子证书(example.com.crt),没带中间 CA。浏览器会通过 AIA 自动补链,看起来一切正常;但 curl、Java、微信小程序、Android 原生 OkHttp 不会补链,直接失败。
  • keystore 类型或密码不匹配:把 PEM 文件当 PKCS12 加载;或 OpenSSL 3.x 生成的 PFX 使用 AES-256-CBC + PBKDF2,Java 8 早期版本读不出来。
  • 配置未生效:改了 server.xml 没重启;或续期后新文件落在别的路径,Connector 仍指向旧文件。

还要纠正一个普遍过时的事实:目前公开信任的 SSL/TLS 证书最长有效期 398 天,Let’s Encrypt 仍是 90 天。CA/B 论坛 SC-081 已排定进一步缩短(2026-03-15 起 200 天、2027-03-15 起 100 天、2029-03-15 起 47 天),“一年装一次”的运维习惯必须改成自动续期 + 自动重载。

证书文件准备:PFX/PKCS12、JKS 与 PEM 的取舍

在 DigiCert CertCentral 中进入订单详情页,下载格式选择:

  • Apache/Tomcat:给出 PEM 包,含 example.com.crt(叶子)、DigiCertCA.crt(中间 CA)、DigiCertGlobalRootG2.crt(根,通常无需部署)。
  • PKCS#12 / PFX:直接给 .p12 文件,密码在下载页显示,可被 Tomcat 8.5+ 直接加载。

私钥由你生成 CSR 时产生,CA 不会提供。拿到 PEM 后先合并完整链,再转 PFX:

cat example.com.crt DigiCertCA.crt > fullchain.crt

openssl pkcs12 -export 
  -in fullchain.crt 
  -inkey example.com.key 
  -certfile DigiCertCA.crt 
  -name tomcat 
  -out /opt/ssl/example.com.pfx

若目标服务器是 Java 8u301 以下版本,OpenSSL 3.x 的默认算法会读不出来,需要降级算法:

openssl pkcs12 -export -legacy 
  -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -macalg sha1 
  -in fullchain.crt -inkey example.com.key -certfile DigiCertCA.crt 
  -name tomcat -out /opt/ssl/example.com.pfx

导出后立刻校验内容与数量,并收紧权限(Tomcat 运行用户必须可读):

openssl pkcs12 -in /opt/ssl/example.com.pfx -nokeys -info -passin pass:你的密码
# 输出应包含 MAC verified OK,且至少两个 Certificate bag(叶子 + 中间 CA)

chown tomcat:tomcat /opt/ssl/example.com.pfx
chmod 600 /opt/ssl/example.com.pfx
格式 适用 Tomcat 版本 优点 注意点
PKCS12 / PFX 8.5 及以上(推荐) 单文件含私钥 + 完整链,Java 9+ 默认类型 必须显式写 certificateKeystoreType=”PKCS12″
JKS 全版本兼容 老环境无需改造 已标记 legacy,Java 9+ 需 -deststoretype JKS 显式指定
PEM(crt + key) 需先转 PKCS12 便于 openssl 直接校验 Tomcat 不支持直接加载 PEM

Tomcat 8.5+ 配置实操:server.xml 完整示例

编辑 $CATALINA_HOME/conf/server.xml,把默认被注释掉的 8443 Connector 替换为下面这段(是嵌套结构,不是老式属性堆叠):

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200" SSLEnabled="true" scheme="https" secure="true">
  <SSLHostConfig protocols="TLSv1.2,TLSv1.3"
                 honorCipherOrder="true"
                 ciphers="TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,
                          ECDHE-RSA-AES128-GCM-SHA256,ECDHE-RSA-AES256-GCM-SHA384">
    <Certificate certificateKeystoreFile="/opt/ssl/example.com.pfx"
                 certificateKeystorePassword="PFX导出密码"
                 certificateKeystoreType="PKCS12"
                 type="RSA" />
  </SSLHostConfig>
</Connector>

关键参数说明:

  • certificateKeystoreFile 必须是绝对路径,相对路径以 $CATALINA_HOME 为基准,极易踩坑。
  • certificateKeystoreType 缺省时按 Java 默认类型推断,Java 8 上会当成 JKS,导致 PFX 加载失败。
  • protocols 只保留 TLSv1.2 与 TLSv1.3,TLSv1.0/1.1 已被主流客户端淘汰。
  • 同一 IP 部署多域名时,用 <SSLHostConfig hostName="a.example.com"> 区分,并以 defaultSSLHostConfigName 指定默认主机。

密码不要明文写在 server.xml。在 conf/catalina.properties 末尾追加 keystore.pass=xxxx,再写 certificateKeystorePassword="${keystore.pass}",并把该文件 chmod 600、属主改为 Tomcat 运行用户。

把 8080 强制跳转到 8443,无需引入 rewrite 模块,在 Connector 内嵌安全约束即可:

<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000">
  <SecurityConstraint>
    <WebResourceCollection><UrlPattern>/*</UrlPattern></WebResourceCollection>
    <UserDataConstraint><TransportGuarantee>CONFIDENTIAL</TransportGuarantee></UserDataConstraint>
  </SecurityConstraint>
</Connector>

改完必须重启进程:systemctl restart tomcat,或 $CATALINA_HOME/bin/shutdown.sh && $CATALINA_HOME/bin/startup.sh。Tomcat 热加载不会重新读取 keystore。

老版本 Tomcat 7/8.0:JKS 导入与旧式 Connector

Tomcat 8.5 以下只能加载 JKS。用 keytool 从 PFX 一步转换,注意 storepass 与 keypass 必须一致,否则会抛 UnrecoverableKeyException:

keytool -importkeystore 
  -srckeystore /opt/ssl/example.com.pfx -srcstoretype PKCS12 -srcstorepass 'PFX密码' 
  -destkeystore /opt/ssl/example.com.jks -deststoretype JKS 
  -deststorepass 'JKS密码' -destkeypass 'JKS密码' -noprompt

转换结果必须验证链长度,为 2(叶子 + 中间)或 3(含根)才算正确:

keytool -list -v -keystore /opt/ssl/example.com.jks -storepass 'JKS密码' 
  | grep -E "Alias name|Certificate chain length|Valid from"
# Certificate chain length: 3

旧式 Connector 写法(Tomcat 7/8.0 专用,切勿混用到 8.5+):

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true" maxThreads="150" scheme="https" secure="true"
           keystoreFile="/opt/ssl/example.com.jks" keystorePass="JKS密码"
           keystoreType="JKS" clientAuth="false" sslProtocol="TLS" />

两个高频坑:一是 protocol="HTTP/1.1" 在 Tomcat 7 后期已被废弃,建议显式写 Http11NioProtocol 全限定类名;二是 PFX 中存在多个 alias(例如曾导入过测试证书)时必须补 keystoreAlias="tomcat",否则 Tomcat 取到第一个 alias,会出现“证书域名对不上”的诡异现象。

JKS 在 Java 9 之后已被标记为 legacy 格式,keytool 会打印警告但可继续使用。新项目建议直接升级到 Tomcat 9/10 并使用 PKCS12,避免格式转换过程中的链丢失风险。

证书链与私钥匹配的本地校验

部署前先在本地验完三件事,能省掉 80% 的线上排查时间。

1)私钥与证书是否配对:分别取模数做 MD5 比对,两行输出必须完全一致。

openssl x509 -in example.com.crt -noout -modulus | openssl md5
openssl rsa  -in example.com.key -noout -modulus | openssl md5
# 两条命令输出相同即匹配

2)证书链是否完整可验证:

openssl verify -CAfile DigiCertGlobalRootG2.crt 
  -untrusted DigiCertCA.crt example.com.crt
# example.com.crt: OK

若返回 unable to get local issuer certificate,说明中间 CA 缺失或拼接顺序错误,需按“叶子 → 中间”顺序重新合并。

3)PFX 内是否包含完整链:

openssl pkcs12 -in /opt/ssl/example.com.pfx -nokeys -passin pass:密码 
  | grep -c "BEGIN CERTIFICATE"
# 结果应 >= 2

同时确认 SAN 覆盖全部域名、有效期符合 398 天上限:

openssl x509 -in example.com.crt -noout -subject -issuer -dates 
  -ext subjectAltName

注意 SAN 才是现代客户端的校验依据,CN 早已被忽略。若网站同时有 www 与裸域,或存在 API 子域,务必确认 SAN 列表全部包含,否则会触发 ERR_CERT_COMMON_NAME_INVALID。

部署验证:openssl、curl、Java 三路复核

重启后先确认端口在监听,再做 TLS 层验证:

systemctl restart tomcat
ss -lntp | grep 8443
openssl s_client -connect 127.0.0.1:8443 -servername example.com </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates

外网验证链是否被公共信任库接受,重点看 Verify return code:

openssl s_client -connect example.com:8443 -servername example.com 
  -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null 2>&1 
  | grep -E "Verify return code|Protocol|Cipher"
# Verify return code: 0 (ok)
# Protocol: TLSv1.3  Cipher: TLS_AES_256_GCM_SHA384

curl 复核(DNS 未切换时用 --resolve 直连):

curl -vI https://example.com:8443 --resolve example.com:8443:127.0.0.1

Java 客户端复核,这是小程序、Android、Spring 微服务最容易踩的一环:

keytool -printcert -sslserver example.com:8443 | head -20
java -Djavax.net.debug=ssl:handshake -cp . TestSSL https://example.com:8443

在调试输出中检索 Found trusted certificate 与 Certificate chain length;若出现 sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target,几乎可以断定服务端下发的链不完整。

最后用浏览器确认锁标志,点开证书查看颁发者是否为 DigiCert,并完整走一遍 8080 → 8443 的跳转是否生效。

常见错误与真实报错排查

真实报错 根因 处理方式
java.io.IOException: Keystore was tampered with, or password was incorrect certificateKeystorePassword 与实际 PFX 密码不一致,或密码含特殊字符未转义 用 openssl pkcs12 -info -passin 验证密码;含 & # 等字符改用 ${} 属性注入
java.security.UnrecoverableKeyException: Cannot recover key key 密码与 store 密码不同(JKS 转换常见) -destkeypass 与 -deststorepass 设为一致后重新导入
java.lang.IllegalArgumentException: alias [null] does not exist keystore 中 alias 与配置不符,或 PFX 内无条目 keytool -list 查看 alias,补 certificateKeyAlias
curl: (60) SSL certificate problem: unable to get local issuer certificate 只部署叶子证书,链不完整 用 fullchain.crt 重新导出 PFX 并重启
ERR_SSL_VERSION_OR_CIPHER_MISMATCH protocols/ciphers 过窄,客户端不支持 protocols 同时保留 TLSv1.2 与 TLSv1.3
ERR_CERT_COMMON_NAME_INVALID SAN 未包含访问域名 重新签发含该域名的证书
java.lang.IllegalArgumentException: keystore type 相关异常 缺 certificateKeystoreType,Java 8 按 JKS 解析 PFX 显式写 certificateKeystoreType=”PKCS12″

排查顺序建议固定为三步:第一步看 keystore 内部,keytool -list -v -keystore /opt/ssl/example.com.pfx -storetype PKCS12,确认 alias 与 chain length;第二步看服务端实际下发,openssl s_client -showcerts 输出应能看到至少两张证书;第三步看客户端,用 -Djavax.net.debug=ssl:handshake 定位是链问题还是协议问题。

另外注意 Tomcat 启动日志中的 Server startup in [xxxx] milliseconds:若日志里没有 Initializing ProtocolHandler [https-openssl-nio-8443],说明 Connector 根本没被加载,通常是 XML 语法错误或端口被注释块包裹。

上线检查清单与续期自动化

交付前逐项核对:

  • 证书有效期 ≤ 398 天,SAN 覆盖全部业务域名(含 www、API 子域)
  • PFX/JKS 内至少包含 1 张中间 CA,openssl verify 返回 OK
  • server.xml 使用 SSLHostConfig 嵌套结构,certificateKeystoreType 显式声明
  • keystore 密码外置到 catalina.properties,文件权限 600、属主为 Tomcat 用户
  • 8080 已强制跳转 8443
  • openssl s_client 输出 Verify return code: 0 (ok)
  • Java / 小程序 / Android 端到端连通

续期脚本示例(以 ACME 为例,每次续期后自动重建 PFX 并重启 Tomcat):

#!/bin/bash
# /usr/local/bin/reload-tomcat.sh
set -e
openssl pkcs12 -export 
  -in /etc/letsencrypt/live/example.com/fullchain.pem 
  -inkey /etc/letsencrypt/live/example.com/privkey.pem 
  -name tomcat -out /opt/ssl/example.com.pfx -passout pass:"$PFX_PASS"
chown tomcat:tomcat /opt/ssl/example.com.pfx
chmod 600 /opt/ssl/example.com.pfx
systemctl restart tomcat

挂到续期流程:certbot renew --deploy-hook /usr/local/bin/reload-tomcat.sh。商业证书(DigiCert 等)虽为 398 天,同样建议把到期告警做成监控项:

echo | openssl s_client -connect example.com:8443 -servername example.com 2>/dev/null 
  | openssl x509 -noout -enddate

注意:只替换 .pfx 文件而不重启 Tomcat 是无效的,keystore 在 Connector 初始化时一次性加载,这也是“续期后浏览器仍显示旧证书”的头号原因。

常见问题

Tomcat 8.5 及以上优先用 PKCS12/PFX,单文件即含私钥与完整证书链,且是 Java 9+ 的默认 keystore 类型;Tomcat 8.5 以下只能用 JKS,需用 keytool -importkeystore 转换,注意 destkeypass 与 deststorepass 保持一致。

这是证书链不完整的典型症状,浏览器会通过 AIA 自动补链,其他客户端不会。把叶子证书与中间 CA 按顺序合并成 fullchain.crt,重新导出 PFX,确认包内至少两个 Certificate bag 后重启 Tomcat 即可。

必须重启。keystore 在 Connector 初始化阶段一次性加载进内存,热加载不会重新读取文件;仅执行 reload 往往仍使用旧证书。生产环境建议 shutdown.sh + startup.sh 或 systemctl restart tomcat,并预留 10 秒以上等待端口重新监听。

用 openssl 分别提取模数并做 MD5:openssl x509 -in cert.crt -noout -modulus | openssl md5 与 openssl rsa -in key.key -noout -modulus | openssl md5,两条输出完全一致即匹配,不一致说明私钥与证书不是同一对。

目前公开信任的 SSL/TLS 证书最长 398 天,Let’s Encrypt 为 90 天;CA/B 论坛已排定 2026 年起逐步缩短至 200 天、100 天、47 天。建议到期前 30 天完成续期,并用 deploy-hook 自动重建 PFX 与重启服务。

内容审核

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