Let’s Encrypt SSL 证书 Tomcat 部署实战:PKCS12/JKS、续期与报错排查
问题背景与根因:为什么 Tomcat 部署 Let’s Encrypt 总出问题
Let’s Encrypt 是免费 DV 证书,默认有效期 90 天,通过 ACME 自动续期;CA/B Forum 当前规定公开信任 TLS 证书最长 398 天,这个 398 天不是 Let’s Encrypt 的默认周期,不要把续期任务设成一年一次。Tomcat 8.5 以后用 SSLHostConfig/Certificate 配置证书,部署失败通常不是证书本身,而是链、格式、密码、别名、端口和重载。
根因集中在五类:一是只把 cert.pem 导出 PFX,缺中间证书,浏览器能补链但 curl/Java/小程序失败;二是 PFX 密码或别名与 server.xml 不一致;三是旧 JDK 信任库没有 ISRG Root X1;四是续期只更新了 PEM,没有重新导出 PFX 并重启 Tomcat;五是 8443 未放行或 SNI 域名不匹配。
先做两个检查:
openssl x509 -in /etc/letsencrypt/live/example.com/cert.pem -noout -subject -issuer -dates
openssl crl2pkcs7 -nocrl -certfile /etc/letsencrypt/live/example.com/fullchain.pem | openssl pkcs7 -print_certs -noout
第一条看叶子证书域名和到期时间;第二条看 fullchain 是否包含中间证书。正常应看到叶子证书和 R3/R10/R11 等中间证书。若只有一张,后续 Java 客户端大概率报 PKIX。另一个检查是端口:ss -lntp | grep 8443。确认 Tomcat 监听后再谈证书链。把这三步做完,再进入导出和配置,能少走很多弯路。
准备证书文件与生成 PKCS12
推荐从 Let’s Encrypt 的 live 目录直接取 fullchain.pem 和 privkey.pem。certbot 申请:
sudo certbot certonly --webroot -w /var/www/html -d example.com -d www.example.com
sudo certbot certificates
acme.sh 申请:
acme.sh --issue -d example.com -d www.example.com --webroot /var/www/html
acme.sh --list
生成 PKCS12,注意 -in 用 fullchain.pem,不是 cert.pem:
sudo openssl pkcs12 -export -out /opt/ssl/example.com.pfx -inkey /etc/letsencrypt/live/example.com/privkey.pem -in /etc/letsencrypt/live/example.com/fullchain.pem -name tomcat -passout pass:'StrongPass'
sudo chown tomcat:tomcat /opt/ssl/example.com.pfx
sudo chmod 640 /opt/ssl/example.com.pfx
老 Java 8 若报 keystore 解析错误,加兼容参数重新导出:
sudo openssl pkcs12 -export -out /opt/ssl/example.com.pfx -inkey /etc/letsencrypt/live/example.com/privkey.pem -in /etc/letsencrypt/live/example.com/fullchain.pem -name tomcat -passout pass:'StrongPass' -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -macalg sha1
校验:
openssl pkcs12 -in /opt/ssl/example.com.pfx -info -noout -passin pass:'StrongPass'
keytool -list -v -keystore /opt/ssl/example.com.pfx -storetype PKCS12 -storepass 'StrongPass' | grep -E 'Alias|Entry type|Certificate chain length'
应看到别名 tomcat、PrivateKeyEntry、chain length 至少 2。若 chain length 为 1,说明没用 fullchain。密码不要写进 shell 历史,生产环境用受限权限文件或 Tomcat 属性注入。
配置 Tomcat Connector 与 server.xml 示例
Tomcat 8.5/9/10 在 server.xml 的 Service 内配置 8443 Connector。示例:
<Connector port='8443' protocol='org.apache.coyote.http11.Http11NioProtocol'
maxThreads='150' SSLEnabled='true' scheme='https' secure='true'
clientAuth='false' sslEnabledProtocols='TLSv1.2,TLSv1.3'
redirectPort='8443'>
<SSLHostConfig>
<Certificate certificateKeystoreFile='/opt/ssl/example.com.pfx'
certificateKeystorePassword='${ssl.keystore.pass}'
certificateKeystoreType='PKCS12'
certificateKeyAlias='tomcat' />
</SSLHostConfig>
</Connector>
把 80 Connector 的 redirectPort 指向 8443,应用里 <security-constraint> 才会跳转 HTTPS。密码不建议明文:在 bin/setenv.sh 增加 -Dssl.keystore.pass=StrongPass 到 CATALINA_OPTS,并限制 setenv.sh 权限为 640。Tomcat 9/10 默认 keystore 类型已是 PKCS12,但显式写 certificateKeystoreType 更稳。多域名用多个 SSLHostConfig,每个带 hostName 和独立 Certificate;单域名不要乱加 hostName。
改完先校验 XML:xmllint --noout conf/server.xml,再重启:systemctl restart tomcat。看日志 logs/catalina.out 是否出现 Starting ProtocolHandler [https-openssl-nio-8443]。若启动即报 java.io.IOException: keystore password was incorrect,先回到上一节核对密码和别名。Tomcat 8.5 老版本若没有 sslEnabledProtocols 属性,可改用 SSLProtocol=’TLSv1.2,TLSv1.3′ 或升级。TLSv1.3 需要 Java 11+,Java 8 只保留 TLSv1.2。Tomcat 7 的写法是 keystoreFile/keystorePass,不能照抄 SSLHostConfig。
老版本 Tomcat 与 JKS 迁移
Tomcat 7 或必须用 JKS 的环境,用 keytool 从 PFX 导入。命令:
keytool -importkeystore -srckeystore /opt/ssl/example.com.pfx -srcstoretype PKCS12 -srcstorepass 'StrongPass' -srcalias tomcat -destkeystore /opt/ssl/example.com.jks -deststoretype JKS -deststorepass 'StrongPass' -destkeypass 'StrongPass' -alias tomcat
若 PFX 内别名不是 tomcat,先 keytool -list -v -keystore /opt/ssl/example.com.pfx -storetype PKCS12 -storepass 'StrongPass' 查别名,去掉 -srcalias 或改成实际别名。JKS 的 destkeypass 至少 6 位,且要与 deststorepass 一致,否则 Tomcat 可能报 Alias name [tomcat] does not identify a key entry。导入后检查链长度:
keytool -list -v -keystore /opt/ssl/example.com.jks -storepass 'StrongPass' | grep -E 'Alias|Entry type|Certificate chain length'
server.xml 改成 certificateKeystoreFile=’/opt/ssl/example.com.jks’ certificateKeystoreType=’JKS’。JKS 在 Java 9 以后不再是默认格式,且加密强度弱于 PKCS12;新部署不要为了兼容旧文档选 JKS。迁移时保留 PFX 源文件,JKS 只作为过渡。若 keytool 报 java.io.IOException: keystore password was incorrect,不要反复重试,先确认源 PFX 密码和 deststorepass 是否混用。JKS 同样必须包含中间证书,否则客户端仍报 PKIX。
证书格式与客户端兼容性对比
三种格式的取舍如下:
| 格式 | Tomcat 支持 | 优点 | 注意 |
|---|---|---|---|
| PKCS12/PFX | 8.5+ 推荐 | 单文件含私钥和链,跨平台,Java 9+ 默认 | 必须用 fullchain 导出;密码和别名要匹配 |
| JKS | 全版本兼容 | 老 Tomcat 直接可用 | Java 9 后不推荐;keypass 至少 6 位;易漏中间链 |
| PEM 双文件 | 不直接用于 Certificate | Let’s Encrypt 原生,可读性好 | Tomcat 需先转 PKCS12/JKS;不能只给 cert.pem |
| 带链 PFX | 推荐 | curl、Java、小程序兼容性好 | chain length 至少 2;续期后要重新导出 |
选型建议:Tomcat 8.5+ 一律 PKCS12;只有旧系统才 JKS。验证格式不要只看文件大小,执行 keytool -list -v 看 Entry type 是否为 PrivateKeyEntry、Certificate chain length 是否大于等于 2。若为 1,说明只有叶子证书。另一个对比是 ACME 客户端:certbot 适合系统包管理和 systemd timer,acme.sh 适合纯 shell 和无 root 场景;两者都能续期,但都必须把 fullchain 重新导出 PFX 并重启 Tomcat。不要混用两个客户端管理同一域名,避免 live 目录和续期钩子冲突。
常见错误排查与真实报错
报错 1:curl: (60) SSL certificate problem: unable to get local issuer certificate。服务端没发中间证书。检查:
openssl s_client -connect example.com:8443 -servername example.com -showcerts /dev/null | grep -c 'BEGIN CERTIFICATE'
返回 1 就是缺链。用 fullchain.pem 重新导出 PFX,别用 cert.pem。若返回 2 以上仍报错,检查客户端 CA 包。
报错 2:javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target。先确认服务端链完整,再把 ISRG Root X1 导入客户端信任库:
keytool -importcert -alias isrgrootx1 -file isrg-root-x1.pem -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit -noprompt
生产不要改全局 cacerts,优先用 -Djavax.net.trustStore 指定应用信任库。
报错 3:java.security.cert.CertificateException: No subject alternative names present。访问域名不在 SAN。用 openssl x509 -in cert.pem -noout -text | grep -A1 'Subject Alternative Name' 核对,重新签发包含该域名。
报错 4:java.io.IOException: keystore password was incorrect 或 Alias name [tomcat] does not identify a key entry。用 keytool -list -v -keystore /opt/ssl/example.com.pfx -storetype PKCS12 -storepass 'StrongPass' 核对密码、别名、Entry type。Tomcat 的 certificateKeyAlias 必须与 PFX 别名一致。
报错 5:javax.net.ssl.SSLHandshakeException: no cipher suites in common。协议或套件不匹配。用 openssl s_client -connect example.com:8443 -tls1_2 测试,检查 sslEnabledProtocols 是否只开了客户端不支持的版本;Java 8 不要只写 TLSv1.3。
自动续期与 Tomcat 重载
Let’s Encrypt 90 天有效期,续期必须自动化。建议用一个脚本完成导出 PFX 和重启 Tomcat:
#!/bin/bash
set -e
DOMAIN=example.com
LE=/etc/letsencrypt/live/$DOMAIN
PFX=/opt/ssl/$DOMAIN.pfx
openssl pkcs12 -export -out $PFX -inkey $LE/privkey.pem -in $LE/fullchain.pem -name tomcat -passout pass:StrongPass
chown tomcat:tomcat $PFX
chmod 640 $PFX
systemctl restart tomcat
保存为 /usr/local/bin/renew-tomcat-cert.sh,chmod 750。certbot 续期钩子:
sudo certbot renew --deploy-hook /usr/local/bin/renew-tomcat-cert.sh --dry-run
sudo systemctl list-timers | grep certbot
acme.sh 方式:
acme.sh --install-cert -d example.com --key-file /etc/letsencrypt/live/example.com/privkey.pem --fullchain-file /etc/letsencrypt/live/example.com/fullchain.pem --reloadcmd '/usr/local/bin/renew-tomcat-cert.sh'
注意 –reloadcmd 在证书更新后执行,脚本里不要再调用 certbot,避免递归。若 Tomcat 以 tomcat 用户运行,PFX 权限 640 足够;不要 777。验证:certbot renew --dry-run 后看 journalctl -u tomcat -n 50 是否有 8443 启动成功。生产环境把密码放脚本外的 600 权限文件,用 source 读取,别把 StrongPass 提交到 Git。续期后不生效,九成是只更新了 PEM,没有重新导出 PFX 或没有重启。
效果验证
先在本机验证端口和证书:
ss -lntp | grep 8443
openssl s_client -connect example.com:8443 -servername example.com -showcerts /dev/null | openssl x509 -noout -subject -issuer -dates
看 Verify return code: 0 (ok) 和日期。再数证书链:
openssl s_client -connect example.com:8443 -servername example.com -showcerts /dev/null | grep -c 'BEGIN CERTIFICATE'
至少 2 张。curl 验证:
curl -vI https://example.com:8443
curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result}' https://example.com:8443
ssl_verify_result 为 0 表示校验通过。Java 侧:
keytool -printcert -sslserver example.com:8443 | grep -E 'Owner|Issuer|Valid'
java -Djavax.net.debug=ssl:handshake -jar app.jar
浏览器访问 https://example.com:8443,点锁看证书链和 SAN。对外服务可用 testssl.sh:testssl.sh --severity HIGH https://example.com:8443。最后检查 HTTP 跳转:curl -I http://example.com 应返回 301/302 到 https。若 8443 外网不通,检查安全组和 firewalld:firewall-cmd --add-port=8443/tcp --permanent; firewall-cmd --reload。验证通过后,把 8443 换成 443 需改 Connector port 并处理 root 权限或反向代理。
常见问题
Let’s Encrypt 默认签发 90 天证书;398 天是 CA/B Forum 对公开信任 TLS 证书的最长有效期上限,不是 Let’s Encrypt 的默认周期。必须配置自动续期,并在续期后重新导出 PFX、重启 Tomcat,不能按一年一次设置。
Tomcat 8.5+ 优先 PKCS12/PFX,配置 certificateKeystoreType=’PKCS12’;JKS 只用于老版本兼容。PFX 必须由 fullchain 和 privkey 导出,chain length 至少 2;JKS 导入后核对别名和 keypass。新部署不要选 JKS。
先确认服务端返回完整链,用 openssl s_client -showcerts 数证书;再检查客户端 JDK 信任库是否含 ISRG Root X1。优先升级 JDK 或用 -Djavax.net.trustStore 指定信任库,不要只导入叶子证书,也不要把服务端 fullchain 当客户端信任库。
Let’s Encrypt 续期只更新 PEM,Tomcat 用的 PFX 不会自动变化。在 deploy-hook 中执行 openssl pkcs12 重新导出,再 systemctl restart tomcat;用 certbot renew –dry-run 验证钩子。只 reload 不一定重新加载 keystore,重启最稳。
可以,但必须用 DNS-01 验证。certbot 可用 –manual –preferred-challenges dns 或 DNS 插件,acme.sh 可用 –dns dns_cf。通配符 *.example.com 只匹配一级子域,不匹配 a.b.example.com;续期同样要自动化并重启 Tomcat。
如果客户端直接访问 https://example.com:8443,就必须在防火墙和安全组放行 8443/TCP;生产更常见的是用 Nginx/HAProxy 监听 443 反代到 Tomcat 8443,或把 Connector 改为 443。改 443 需处理 root 权限或端口转发,并配置 HTTP 跳转 HTTPS。