跳到主要内容
Tomcat

Let’s Encrypt 证书部署到 Tomcat 实战:PKCS12 配置、证书链修复与自动续期

问题背景与根因:为什么 Tomcat 装 Let’s Encrypt 证书总踩坑

在 Nginx 上部署 Let’s Encrypt 只需要两行 ssl_certificate 指令,搬到 Tomcat 却经常出现「浏览器能打开、Java 客户端握手失败」的情况。根因集中在三点。

其一,格式不匹配。ACME 客户端签发的产物固定是 PEM:cert.pem(叶子证书)、chain.pem(中间证书)、fullchain.pem(叶子加中间)、privkey.pem(私钥)。Tomcat 8.5 之前只认 JKS,8.5 之后主推 PKCS12,两者都需要额外转换一步。

其二,证书链缺失。Let’s Encrypt 当前的默认链是「叶子 ← R10/R11(RSA)或 E5/E6(ECDSA)← ISRG Root X1」,2025 年起新申请默认签发 ECDSA P-256 证书。很多人图省事把 cert.pem 导入 keystore,服务端只发送叶子证书。桌面浏览器会通过 AIA 扩展自动补齐中间证书,看起来一切正常;但 curl、Java、微信小程序、老版本 Android 不会补链,直接报 PKIX 错误。

其三,有效期短且持续缩短。Let’s Encrypt 证书有效期 90 天,官方建议剩余 30 天时续期。同时 CA/Browser Forum 已通过 SC-081 提案,公开 CA 证书最长有效期从现在的 398 天,在 2026-03-15 缩短到 200 天,2027-03-15 缩短到 100 天,2029-03-15 缩短到 47 天;Let’s Encrypt 也已提供 6 天短期证书选项。任何「到期前手动换一次」的流程都不可持续,必须把「续期 → 转换 PKCS12 → 重启 Tomcat」写成 deploy hook。

动手前先确认版本,不同大版本的配置语法完全不同:

catalina.sh version | grep 'Server version'
# 或
java -cp /opt/tomcat/lib/catalina.jar org.apache.catalina.util.ServerInfo

输出形如 Apache Tomcat/9.0.98。Tomcat 7 使用 keystoreFile / keystorePass 老属性;Tomcat 8.5 及以上改用 <SSLHostConfig> 嵌套 <Certificate>;Tomcat 8.5.2 起 JSSE 实现可以直接读取 PEM,不再强制要求 keystore。选错语法会得到 java.lang.IllegalArgumentException 或 Connector 静默不启动。

第一步:申请证书并让 Tomcat 用户能读到私钥

推荐用 certbot 的 webroot 模式,不停机、不需要 80 端口独占。假设站点根目录是 /var/www/html:

certbot certonly --webroot -w /var/www/html -d example.com -d www.example.com --deploy-hook '/usr/local/bin/tomcat-reload.sh'

签发完成后产物在 /etc/letsencrypt/live/example.com/。acme.sh 用户则用下面这条命令把文件「落地」到指定目录,并顺带注册续期后的回调:

acme.sh --install-cert -d example.com --ecc --key-file /opt/ssl/example.com.privkey.pem --fullchain-file /opt/ssl/example.com.fullchain.pem --reloadcmd '/usr/local/bin/tomcat-reload.sh'

这里有一个必踩的坑:/etc/letsencrypt/live 与 archive 目录默认权限是 0700、属主 root,Tomcat 以 tomcat 用户运行时读不到 privkey.pem,启动日志里是:

java.io.FileNotFoundException: /etc/letsencrypt/live/example.com/privkey.pem (Permission denied)

正确做法是把文件复制到独立目录并改属主,不要直接 chmod 777 源目录,那等于把私钥公开:

install -d -o tomcat -g tomcat -m 750 /opt/ssl
install -o tomcat -g tomcat -m 640 /etc/letsencrypt/live/example.com/fullchain.pem /opt/ssl/example.com.fullchain.pem
install -o tomcat -g tomcat -m 640 /etc/letsencrypt/live/example.com/privkey.pem /opt/ssl/example.com.privkey.pem

同时确认私钥是 ECDSA 还是 RSA,后面配置里的 type 属性必须对应:

openssl pkey -in /opt/ssl/example.com.privkey.pem -noout -text | head -1
openssl x509 -in /opt/ssl/example.com.fullchain.pem -noout -subject -issuer -dates

第一行输出 Private-Key: (256 bit) 且带 ASN1 OID: prime256v1 即为 ECDSA;输出 (2048 bit) 为 RSA。第二行确认 issuer 是 R10/R11/E5/E6 之一,notAfter 距今 90 天左右。若证书是 RSA 而私钥是 EC(或反之),后面的握手一定失败,所以这一步不能跳过。

第二步:用 openssl 生成 PKCS12 并校验私钥匹配

一条命令即可,关键是 -in 必须用 fullchain.pem(含中间证书),不要用 cert.pem,也不要额外加 -certfile chain.pem,否则链会重复写入:

openssl pkcs12 -export -name tomcat -inkey /opt/ssl/example.com.privkey.pem -in /opt/ssl/example.com.fullchain.pem -out /opt/ssl/example.com.p12 -passout pass:'Str0ngP@ss-2025'

OpenSSL 3.x 默认使用 AES-256-CBC + PBKDF2(PBES2)加密 PKCS12,而 JDK 8u301 之前的版本不支持 PBES2,Tomcat 启动会抛:

java.io.IOException: Integrity check failed: java.security.NoSuchAlgorithmException: Algorithm HmacPBESHA256 not available

遇到这个报错有两条路:升级到 JDK 8u301+/11/17,或者在导出时降级加密算法(OpenSSL 3 加 -legacy,或显式指定 -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -macalg sha1)。降级后兼容老 JDK,但私钥保护强度随之下降,优先选升级。

导出后必须验证三件事,缺一不可:

# 1. p12 能打开且别名正确
openssl pkcs12 -in /opt/ssl/example.com.p12 -passin pass:'Str0ngP@ss-2025' -noout -info
# 2. 证书与私钥公钥指纹一致
openssl x509 -in /opt/ssl/example.com.fullchain.pem -noout -pubkey | openssl md5
openssl pkey -in /opt/ssl/example.com.privkey.pem -pubout | openssl md5
# 3. p12 内的证书数量(应为 2 或 3)
openssl pkcs12 -in /opt/ssl/example.com.p12 -passin pass:'Str0ngP@ss-2025' -nokeys -clcerts -nomacver 2>/dev/null | grep -c 'BEGIN CERTIFICATE'

两条 md5 必须完全一致,否则就是「证书与私钥不匹配」,Tomcat 会拒绝启动。第 3 条统计的是 p12 中携带的证书数量,等于 1 说明链没打进去,回到上一步检查是否误用了 cert.pem。最后设置权限:

chown tomcat:tomcat /opt/ssl/example.com.p12
chmod 640 /opt/ssl/example.com.p12

PKCS12 把私钥和证书放在同一个文件里,密码就是唯一的防线,务必使用 16 位以上随机密码并写入受控的配置文件,不要提交到 Git。

第三步:Tomcat 8.5/9/10 的 server.xml 完整配置示例

编辑 $CATALINA_BASE/conf/server.xml,把默认被注释掉的 8443 Connector 替换为下面的写法。注意属性名是 certificateKeystoreFile,不是老版本的 keystoreFile:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200" SSLEnabled="true" scheme="https" secure="true"
           compression="on" redirectPort="8443">
  <SSLHostConfig protocols="TLSv1.2,TLSv1.3"
                 honorCipherOrder="true"
                 ciphers="TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256">
    <Certificate certificateKeystoreFile="/opt/ssl/example.com.p12"
                 certificateKeystorePassword="Str0ngP@ss-2025"
                 certificateKeystoreType="PKCS12"
                 certificateKeyAlias="tomcat"
                 type="EC" />
  </SSLHostConfig>
</Connector>

type 必须是 EC(ECDSA 证书)或 RSA,写错会导致握手阶段报 no cipher suites in common。如果你拿到的是 RSA 证书,把 type 改成 RSA,并把 ciphers 里的 ECDSA 套件换成 ECDHE-RSA-AES256-GCM-SHA384 等。

Tomcat 8.5.2 及以上也可以完全跳过 PKCS12,直接读 PEM,续期时少一步转换,出错面更小:

<Certificate certificateFile="/opt/ssl/example.com.fullchain.pem"
             certificateKeyFile="/opt/ssl/example.com.privkey.pem"
             type="EC" />

若你的 Tomcat 版本较老、不支持 certificateFile 携带整条链,则把 certificateFile 指向 cert.pem,另加 certificateChainFile="/opt/ssl/example.com.chain.pem"。

最后让 8080 自动跳转:确保 8080 Connector 带 redirectPort="8443",并在 conf/web.xml 的 </web-app> 之前加入安全约束:

<security-constraint>
  <web-resource-collection><web-resource-name>all</web-resource-name><url-pattern>/*</url-pattern></web-resource-collection>
  <user-data-constraint><transport-guarantee>CONFIDENTIAL</transport-guarantee></user-data-constraint>
</security-constraint>

改完必须重启,Tomcat 不会热加载 server.xml。

第四步:老版本 Tomcat 的 JKS 方案与 keytool 导入

Tomcat 7 或仍在使用 keystoreFile 的项目需要 JKS。注意 JDK 9 之后 keytool 的默认目标格式已经变成 PKCS12,必须显式写 -deststoretype JKS,否则你得到的还是一个 p12:

keytool -importkeystore -srckeystore /opt/ssl/example.com.p12 -srcstoretype PKCS12 -srcstorepass 'Str0ngP@ss-2025' -destkeystore /opt/ssl/example.com.jks -deststoretype JKS -deststorepass 'Str0ngP@ss-2025' -destkeypass 'Str0ngP@ss-2025'

三个密码必须完全一致。JKS 允许私钥密码(keypass)与库密码(storepass)不同,但 Tomcat 读取时只用 keystorePass 一个值,两者不一致就会抛 java.security.UnrecoverableKeyException: Cannot recover key。导入后用下面的命令确认别名和链长度:

keytool -list -v -keystore /opt/ssl/example.com.jks -storepass 'Str0ngP@ss-2025' | grep -E 'Alias name|Certificate chain length'

正常输出 Alias name: tomcat 与 Certificate chain length: 2(或 3)。如果 chain length 是 1,说明源 p12 本身就是单证书,需要回到第二步用 fullchain.pem 重新导出。对应的 Connector 老写法:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true"
           keystoreFile="/opt/ssl/example.com.jks" keystorePass="Str0ngP@ss-2025"
           keyAlias="tomcat" clientAuth="false" sslProtocol="TLS" />

顺带提醒:JKS 对私钥使用的是 PBEWithMD5AndTripleDES,安全性弱于 PKCS12 的 AES-256,仅作为兼容手段。JDK 17 起 JKS 仍可用但已被标记为遗留格式,能升级就升级。

第五步:三条命令验证部署是否真正生效

重启后先确认端口在监听,再用 openssl 模拟客户端握手。注意必须带 -servername,否则不会发送 SNI,多域名场景下会拿到错误证书:

systemctl restart tomcat && ss -lntp | grep 8443
openssl s_client -connect 127.0.0.1:8443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'
openssl s_client -connect 127.0.0.1:8443 -servername example.com -verify_return_error -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null

第一条应看到 LISTEN 0 100 *:8443。第二条输出应大于等于 2(叶子加至少一张中间证书),输出 1 就是链缺失。第三条的关键行是 Verify return code: 0 (ok),若为 21 (unable to verify the first certificate) 说明服务端没发中间证书,若为 10 (certificate has expired) 说明读到的还是旧文件。

再用 curl 走完整 HTTP 请求,用 --resolve 绕过 DNS 直接打本机:

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

成功时能看到 SSL certificate verify ok. 和 TLSv1.3 (IN), TLS handshake。Java 应用侧的自测最容易被忽略,用 JDK 自带的调试开关可以看清握手细节:

java -Djavax.net.debug=ssl:handshake -cp . HttpsTest https://example.com:8443 2>&1 | grep -E 'Found trusted certificate|chain|Exception'

不写代码也可以直接查服务端证书链:

keytool -printcert -sslserver example.com:8443 | grep -E 'Owner|Issuer|Valid'

另外建议做一次外部评级扫描,确认协议版本、密钥交换、HSTS 都达标;如果评级里出现 Chain issues: Incomplete,回到第二步用 fullchain.pem 重新导出即可。

常见错误排查:真实报错对照表

下面这些报错在 Tomcat 加 Let’s Encrypt 场景里出现频率最高,可以直接按表定位。

报错信息 根因 修复
curl: (60) SSL certificate problem: unable to get local issuer certificate 服务端只发叶子证书 用 fullchain.pem 重新导出 p12,或配置 certificateChainFile
javax.net.ssl.SSLHandshakeException: PKIX path building failed … unable to find valid certification path to requested target 同上,客户端不会 AIA 补链 同上;客户端可用 keytool -importcert 导入 ISRG Root X1
java.io.IOException: Keystore was tampered with, or password was incorrect 密码错,或 p12 用 PBES2 而 JDK 过旧 核对密码;JDK 8u301+ 或 -legacy 导出
java.security.UnrecoverableKeyException: Cannot recover key JKS 中 keypass 与 storepass 不同 用相同密码重新 importkeystore
java.io.FileNotFoundException: /etc/letsencrypt/live/… (Permission denied) Tomcat 用户无读权限 install -o tomcat -m 640 复制到 /opt/ssl
java.lang.IllegalArgumentException: certificateKeystoreFile does not exist 路径写错或用了相对路径 使用绝对路径并 ls -l 确认
SSL_ERROR_NO_CYPHER_OVERLAP / no cipher suites in common type 与证书算法不匹配(EC 写成 RSA) 改 type=’EC’ 并同步 ciphers
续期后浏览器仍显示旧证书 Tomcat 未重启,keystore 已在内存中 重启进程,见下一节 hook

关于「浏览器正常但 Java/小程序报错」:这是最典型的症状。桌面 Chrome 会解析叶子证书里的 AIA 字段自动下载中间证书,所以看不出问题;Java 的 PKIX 校验和小程序的网络库都不会补链。判断方法就是前面的 grep -c 'BEGIN CERTIFICATE',结果为 1 即确诊。

关于「续期后不生效」:很多人以为把新文件覆盖到原路径就行,但 Tomcat 在 Connector 初始化时就把 keystore 读进内存了,之后不会重新读文件。必须重启 JVM 进程(systemctl restart tomcat),或者用双节点加负载均衡做滚动重启。

关于 OpenSSL 3 读取报错:用 OpenSSL 3.x 读旧脚本生成的 p12 可能报 error:0308010C:digital envelope routines::unsupported,加 -legacy 参数或启用 legacy provider 即可,不影响 Tomcat 实际使用。

第六步:把续期、转换、重启写成一个 deploy hook

手工续期在 90 天周期下迟早出事,尤其是有效期正在向 47 天缩短。创建脚本 /usr/local/bin/tomcat-reload.sh:

#!/bin/bash
set -euo pipefail
DOMAIN=example.com
LE=/etc/letsencrypt/live/$DOMAIN
DST=/opt/ssl
PASS='Str0ngP@ss-2025'

install -o tomcat -g tomcat -m 640 $LE/fullchain.pem $DST/$DOMAIN.fullchain.pem
install -o tomcat -g tomcat -m 640 $LE/privkey.pem   $DST/$DOMAIN.privkey.pem
openssl pkcs12 -export -name tomcat -inkey $DST/$DOMAIN.privkey.pem -in $DST/$DOMAIN.fullchain.pem -out $DST/$DOMAIN.p12 -passout pass:$PASS
chown tomcat:tomcat $DST/$DOMAIN.p12
chmod 640 $DST/$DOMAIN.p12
systemctl restart tomcat

赋予执行权限并放进 certbot 的 deploy 钩子目录,这样每次 certbot renew 成功后都会自动执行:

chmod 750 /usr/local/bin/tomcat-reload.sh
mkdir -p /etc/letsencrypt/renewal-hooks/deploy
ln -sf /usr/local/bin/tomcat-reload.sh /etc/letsencrypt/renewal-hooks/deploy/tomcat-reload.sh
certbot renew --dry-run

--dry-run 会走一遍完整流程但不写真实证书,能验证 hook 是否报错。确认系统定时器存在:

systemctl list-timers | grep certbot

acme.sh 用户则直接在 --install-cert 时用 --reloadcmd '/usr/local/bin/tomcat-reload.sh' 注册,acme.sh 自带 cron 每天检查。

关于重启方式:systemctl reload tomcat 只有在 unit 文件里定义了 ExecReload 时才有效,多数发行版默认没有。若不想整机重启,可以把 Tomcat 部署成双实例,前面挂 Nginx 或 HAProxy,hook 里依次重启;或者干脆把 Connector 改为直读 PEM(certificateFile),此时只需替换文件再重启,转换步骤消失,出错面更小。

最后加一条监控:对 8443 做证书到期检查,剩余天数小于 21 天就告警,避免 hook 静默失败。

echo | openssl s_client -connect example.com:8443 -servername example.com 2>/dev/null | openssl x509 -noout -checkend 1814400 || echo 'CERT EXPIRING'

三种部署方式与客户端工具对比

选哪种格式,取决于你的 Tomcat 版本和自动化程度:

项目 PKCS12(.p12) JKS(.jks) PEM 直读
最低版本 Tomcat 8.5+ 全版本 Tomcat 8.5.2+
私钥加密 AES-256 + PBKDF2 PBEWithMD5AndTripleDES 无,靠文件权限
转换步骤 openssl 一步 openssl 加 keytool 两步 无需转换
续期复杂度 中 高 低
推荐场景 通用部署 老系统兼容 自动化优先

签发工具的差异同样影响后续维护成本:

项目 certbot acme.sh
运行依赖 Python 环境 纯 shell,无外部依赖
默认密钥 RSA 2048,可 –key-type ecdsa RSA 2048,可 –keylength ec-256
续期调度 systemd timer 或 cron 自带 cron,每日检查
续期钩子 –deploy-hook / renewal-hooks 目录 –reloadcmd
适用环境 主流 Linux 发行版 容器、精简系统、群晖等

Tomcat 版本与配置属性的对应关系也需要记牢,写错属性名是新手最常见的失败原因:

Tomcat 版本 Connector 写法 关键属性
7.x 扁平老属性 keystoreFile / keystorePass / keyAlias
8.5.x SSLHostConfig 嵌套 certificateKeystoreFile / certificateKeystoreType
9.0 / 10.1 SSLHostConfig 嵌套 同上,推荐 certificateFile 读 PEM

综合建议:新项目直接用 Tomcat 9.0 或 10.1 加 PEM 直读,配合 acme.sh 的 --reloadcmd,整条链路只有「续期、重启」两个动作;存量 Tomcat 8.5 用 PKCS12 最稳;Tomcat 7 只能在 JKS 上维持,并尽快规划升级。

常见问题

Tomcat 8.5.2 及以上可以,在 SSLHostConfig 的 Certificate 中用 certificateFile 指向 fullchain.pem、certificateKeyFile 指向 privkey.pem,并设置正确的 type。8.5.2 以下必须先用 openssl 转成 PKCS12,或用 keytool 转成 JKS,不能直接读 PEM。

说明服务端只发送了叶子证书,没有携带中间证书。浏览器会通过 AIA 自动补链所以看不出问题,Java 不会。用 openssl s_client -showcerts 统计证书数量,若为 1 就用 fullchain.pem 重新导出 p12,或在配置里补上 certificateChainFile。

目前有效期 90 天,官方建议剩余 30 天时续期,certbot 和 acme.sh 默认都按这个节奏自动执行。由于公开 CA 证书最长有效期将在 2026 年起逐步缩短到 200 天、100 天乃至 47 天,务必用 deploy hook 把续期和 Tomcat 重启串起来。

必须。Tomcat 在 Connector 初始化时就把 keystore 载入内存,之后不会重新读取文件,替换文件本身不生效。可在 deploy hook 中执行 systemctl restart tomcat;若 unit 未定义 ExecReload,reload 无效,只能 restart,建议用双节点滚动重启降低影响。

转换成 JKS 时,目标库密码和私钥密码必须设成同一个值,因为 Tomcat 只用 keystorePass 一个参数去解密私钥,不一致会抛 UnrecoverableKeyException: Cannot recover key。PKCS12 本身只有一个密码,不存在这个问题。

Tomcat 9.0.x 与 10.1.x 在 JDK 11 及以上会自动启用 TLS 1.3,无需额外组件;Tomcat 8.5 需要较新的 8.5.x 版本配合 JDK 11+。在 SSLHostConfig 的 protocols 中显式写 TLSv1.2,TLSv1.3 即可,注意同时配置对应的 TLS 1.3 密码套件。

内容审核

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