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 与重启服务。