ZeroSSL SSL 证书 Tomcat 安装部署教程(PKCS12/JKS 实战与排错)
问题背景与根因:为什么 ZeroSSL 证书在 Tomcat 上容易部署失败
ZeroSSL 提供 90 天免费 DV 证书(支持 ACME 或网页申请)以及付费 OV/EV 证书。按 CA/B Forum 规则,当前公开可信证书最长有效期不超过 398 天,Let’s Encrypt 与 ZeroSSL 免费 DV 均为 90 天,旧文中“多年有效期”的说法已经过时。Tomcat 8.5+ 推荐直接使用 PFX/PKCS12,也可继续使用 JKS;但实际部署失败通常不是证书本身,而是 Java SSL 栈对 keystore 的要求更严格。
常见根因有六类:第一,ZeroSSL 下载包中 certificate.crt 只有叶子证书,ca_bundle.crt 才是中间证书,导出 PFX 时未加 -certfile 会导致链不完整;第二,Tomcat 8.5 之前用 keystoreFile,8.5+ 用 SSLHostConfig/Certificate,新旧属性混写会不生效;第三,PFX 密码、JKS 密码、key 密码不一致,报 keystore password was incorrect;第四,alias 不匹配,报 Alias name tomcat does not identify a key entry;第五,续期后只覆盖文件未重启 Tomcat,浏览器仍显示旧证书;第六,云安全组或防火墙未放行 8443,客户端报连接失败。
排查时先看服务端链是否完整:openssl s_client -connect example.com:8443 -servername example.com -showcerts </dev/null。输出中应能看到叶子证书和至少一张中间证书,最后出现 Verify return code: 0 (ok)。如果只有一张证书,即使浏览器能打开,Java、curl、小程序也可能报 PKIX 错误。
准备证书文件与 CSR:从 ZeroSSL 下载包到可用的 PFX
建议在服务器上固定目录操作,例如 /opt/ssl。如果使用网页申请,先在服务器生成私钥和 CSR,把 CSR 内容粘贴到 ZeroSSL 申请页;如果使用 ACME,可直接得到私钥和证书文件。生成 CSR 的命令如下,域名和路径按实际替换:
mkdir -p /opt/ssl && cd /opt/ssl
openssl req -new -newkey rsa:2048 -nodes -keyout example.com.key -out example.com.csr -subj '/CN=example.com'
cat example.com.csr
ZeroSSL 签发后通常下载到 certificate.crt、ca_bundle.crt 和 private.key。其中 certificate.crt 是域名证书,ca_bundle.crt 是中间证书链。先合并 fullchain,再导出 PKCS12。注意 -name 就是 alias,后面 Tomcat 配置 JKS 时会用到:
cd /opt/ssl
cat certificate.crt ca_bundle.crt > fullchain.crt
openssl pkcs12 -export -in fullchain.crt -inkey example.com.key -out example.com.pfx -name tomcat -passout pass:'StrongPass123'
openssl pkcs12 -info -in example.com.pfx -passin pass:'StrongPass123' -noout
keytool -list -v -keystore example.com.pfx -storetype PKCS12 -storepass 'StrongPass123'
如果下载包已经提供 fullchain 文件,可直接作为 -in;如果只有叶子证书,则必须写成 -in certificate.crt -certfile ca_bundle.crt,否则 PFX 内没有中间证书。PFX 密码不要为空,Tomcat 的 certificateKeystorePassword 需要与导出口令完全一致。文件权限建议 chmod 600 example.com.pfx,属主改为运行 Tomcat 的用户,避免启动时读不到文件。
Tomcat 8.5+ 配置 PKCS12:server.xml 完整示例
Tomcat 8.5、9、10 均支持在 Connector 内使用 SSLHostConfig 配置 PKCS12。把 PFX 放到 Tomcat 可读目录,例如 /opt/tomcat/conf/ssl/example.com.pfx,并设置权限:
sudo mkdir -p /opt/tomcat/conf/ssl
sudo cp /opt/ssl/example.com.pfx /opt/tomcat/conf/ssl/example.com.pfx
sudo chown tomcat:tomcat /opt/tomcat/conf/ssl/example.com.pfx
sudo chmod 600 /opt/tomcat/conf/ssl/example.com.pfx
编辑 conf/server.xml,在 Service 内增加或替换 8443 Connector。下面配置使用单引号属性,实际 XML 中也合法;scheme 和 secure 用于让应用识别 HTTPS:
<Connector port='8443' protocol='org.apache.coyote.http11.Http11NioProtocol' maxThreads='150' SSLEnabled='true' scheme='https' secure='true'>
<SSLHostConfig>
<Certificate certificateKeystoreFile='/opt/tomcat/conf/ssl/example.com.pfx'
certificateKeystorePassword='StrongPass123'
certificateKeystoreType='PKCS12' />
</SSLHostConfig>
</Connector>
如果使用 JKS,则把 certificateKeystoreType 改为 JKS,并增加 certificateKeyAlias='tomcat'。注意 certificateKeystorePassword 是 keystore 口令,JKS 中 key 口令若不同,还需要 certificateKeyPassword。配置完成后不要只 reload Web 应用,应重启 Tomcat 进程:sudo systemctl restart tomcat。生产环境建议把 server.xml 权限限制为 Tomcat 用户可读,因为密码以明文存在配置中;也可通过环境变量或外部化配置降低泄露风险。
旧版 Tomcat 与 JKS 迁移:keytool 导入命令
Tomcat 8.5 之前不支持 SSLHostConfig,需要使用 Connector 的 keystoreFile、keystorePass、keystoreType 属性。若手上只有 ZeroSSL 的 PFX,可先用 keytool 转为 JKS。注意 -destkeypass 与 -deststorepass 可以相同,也可不同;如果 alias 已存在,keytool 会提示覆盖,生产环境先备份旧 JKS。
keytool -importkeystore -srckeystore example.com.pfx -srcstoretype PKCS12 -srcstorepass 'StrongPass123' -destkeystore example.com.jks -deststoretype JKS -deststorepass 'JksPass123' -destkeypass 'JksPass123' -alias tomcat
keytool -list -v -keystore example.com.jks -storetype JKS -storepass 'JksPass123'
老版本 Connector 示例:
<Connector port='8443' protocol='org.apache.coyote.http11.Http11NioProtocol' SSLEnabled='true' keystoreFile='/opt/ssl/example.com.jks' keystorePass='JksPass123' keystoreType='JKS' />
迁移后重点检查三件事:keytool -list -v 输出中 alias 必须是 tomcat 且条目类型为 PrivateKeyEntry;证书链中应包含中间证书;Connector 的 keystorePass 必须与 JKS storepass 一致。Java 9 之后默认 keystore 类型已偏向 PKCS12,新部署优先 PKCS12,JKS 仅用于兼容旧 Tomcat 或旧应用。若从 JKS 迁回 PKCS12,可用 keytool -importkeystore -srckeystore example.com.jks -srcstoretype JKS -destkeystore example.com.pfx -deststoretype PKCS12。
证书链、私钥匹配与密码校验:部署前必须做的检查
部署前先验证证书主题、有效期和链。下面命令分别检查叶子证书、用中间证书验证叶子、以及私钥与证书模数是否一致。模数 MD5 一致才说明私钥匹配:
openssl x509 -in certificate.crt -noout -subject -issuer -dates
openssl verify -CAfile ca_bundle.crt certificate.crt
openssl x509 -noout -modulus -in certificate.crt | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5
如果检查对象是 PFX,则从 PFX 中分别取证书和私钥再比对:
openssl pkcs12 -in example.com.pfx -clcerts -nokeys -passin pass:'StrongPass123' | openssl x509 -noout -modulus | openssl md5
openssl pkcs12 -in example.com.pfx -nocerts -nodes -passin pass:'StrongPass123' | openssl rsa -noout -modulus | openssl md5
链完整性用 openssl s_client 检查最直接:openssl s_client -connect example.com:8443 -servername example.com -showcerts </dev/null。输出中 Certificate chain 应至少有两段,Verify return code 为 0。若为 unable to get local issuer certificate,说明中间证书缺失;若为 certificate has expired,检查 notAfter 并确认续期文件已替换。密码校验可用 keytool -list -v -keystore example.com.pfx -storetype PKCS12 -storepass 'StrongPass123',能列出 PrivateKeyEntry 才说明密码和 alias 正确。
部署验证与效果确认:重启、端口、curl 与 Java 调试
配置完成后重启 Tomcat,并确认 8443 已监听。若使用 systemd,服务名可能是 tomcat 或 tomcat9,按实际替换:
sudo systemctl restart tomcat
sudo systemctl status tomcat --no-pager
sudo ss -lntp | grep 8443
本机验证 TLS 握手和证书链,再用 curl 检查 HTTP 响应:
openssl s_client -connect 127.0.0.1:8443 -servername example.com -CAfile /opt/ssl/ca_bundle.crt </dev/null
curl -vI https://example.com:8443
keytool -printcert -sslserver example.com:8443
浏览器访问 https://example.com:8443,确认锁标志、证书颁发者为 ZeroSSL、有效期正确。Java 应用自测可加 -Djavax.net.debug=ssl:handshake 观察握手日志:java -Djavax.net.debug=ssl:handshake -jar app.jar。日志中应出现 Found trusted certificate 或握手完成;若出现 PKIX path building failed,回到链完整性检查。最后检查云安全组和主机防火墙是否放行 8443,例如 sudo firewall-cmd --add-port=8443/tcp --permanent 后重载。验证通过后再切换 DNS 或负载均衡后端,避免新旧证书混用。
常见错误排查:真实报错与处理命令
1. curl: (60) SSL certificate problem: unable to get local issuer certificate 或 Java 报 PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target。根因是 PFX 只含叶子证书。重新导出:openssl pkcs12 -export -in certificate.crt -inkey example.com.key -certfile ca_bundle.crt -out example.com.pfx -name tomcat -passout pass:'StrongPass123',重启 Tomcat。
2. java.io.IOException: keystore password was incorrect。说明 server.xml 中 certificateKeystorePassword 与 PFX 导出口令不一致。用 keytool -list -v -keystore example.com.pfx -storetype PKCS12 -storepass 'StrongPass123' 验证;若密码含特殊字符,注意 XML 转义和 shell 引号。
3. java.io.IOException: Alias name tomcat does not identify a key entry。说明 JKS 中 alias 不是 tomcat 或条目不是私钥。执行 keytool -list -v -keystore example.com.jks -storepass 'JksPass123' 查看 alias,并在 Connector 中设置 certificateKeyAlias 或老版本 keyAlias。
4. curl: (7) Failed to connect to example.com port 8443。Connector 未监听或防火墙未放行。检查 sudo ss -lntp | grep 8443、sudo tail -n 100 /opt/tomcat/logs/catalina.out,并确认云安全组入方向允许 8443。
5. 浏览器报 NET::ERR_CERT_DATE_INVALID 或仍显示旧证书。续期后未重启 Tomcat。执行 openssl s_client -connect example.com:8443 -servername example.com </dev/null | openssl x509 -noout -dates 查看 notAfter,确认配置路径指向新文件后 sudo systemctl restart tomcat。若报 no cipher suites in common,检查 Java 版本、SSLProtocol 与客户端 TLS 版本是否匹配。
方案对比:PKCS12、JKS 与 PEM 怎么选
Tomcat 8.5+ 支持 PKCS12、JKS,也可用 PEM 文件直接配置。选择时重点看 Tomcat 版本、Java 版本和运维习惯。下表给出对比:
| 格式 | 适用版本 | 关键配置 | 优点 | 缺点 | 推荐场景 |
|---|---|---|---|---|---|
| PFX/PKCS12 | Tomcat 8.5+,Java 8/9+ | certificateKeystoreFile、certificateKeystoreType=’PKCS12′ | 单文件含私钥和链,跨平台通用,Java 9+ 默认格式 | 密码明文写在 server.xml,需保护文件权限 | 新部署首选 |
| JKS | 老版本 Tomcat 及兼容场景 | keystoreFile、keystorePass、keystoreType=’JKS’ | 旧环境兼容性好,keytool 管理成熟 | 格式较旧,alias 和 key 密码易配错 | Tomcat 8.5 之前或旧应用 |
| PEM | Tomcat 8.5+ | certificateFile、certificateKeyFile、certificateChainFile | 无需转换,便于证书文件直接挂载 | 链文件路径和权限要求高,配置项较多 | 容器化、证书由外部挂载 |
如果使用 ACME 自动续期,建议让脚本输出 PFX 并固定路径,deploy-hook 中执行 systemctl restart tomcat。ZeroSSL 免费 DV 为 90 天,付费 OV/EV 最长 398 天,续期频率不同,但验证方法一致:看 openssl s_client 的链和 notAfter。不要同时保留旧 PFX 和新 PFX 在同一 alias 下,避免加载到错误证书。
常见问题
ZeroSSL 免费 DV 证书有效期为 90 天,支持 ACME 自动续期;付费 OV/EV 证书按 CA/B Forum 规则最长 398 天。部署到 Tomcat 后建议用 ACME 客户端续期,并在 deploy-hook 中重启 Tomcat,避免证书过期。
必须重启 Tomcat 进程。Tomcat 在启动时加载 keystore,替换 PFX 或 JKS 后仅 reload Web 应用不会重新加载 Connector 的 SSL 配置。执行 systemctl restart tomcat 后,用 openssl s_client 查看 notAfter 是否已更新。
不建议为空。Tomcat 的 certificateKeystorePassword 需要与 PFX 导出口令一致,空密码在不同 Java 版本和 keytool 中兼容性差。建议用 -passout pass:’StrongPass123′ 设置强密码,并将 PFX 权限设为 600。
浏览器会自动补全中间证书,Java 不会。若 PFX 只含叶子证书,Java 客户端会报 PKIX path building failed。导出 PFX 时加 -certfile ca_bundle.crt,或直接使用 fullchain.crt,并用 openssl s_client -showcerts 确认链完整。
老版本用 JKS 和 Connector 的 keystoreFile、keystorePass、keystoreType 属性,不支持 SSLHostConfig。先用 keytool -importkeystore 把 PFX 转成 JKS,再在 server.xml 配置,最后用 keytool -list -v 验证 alias 和证书链。