JoySSL SSL 证书 Tomcat 安装部署实战:PFX/JKS 配置、证书链排查与续期验证
JoySSL 签发证书后,很多运维把 PFX 丢到 Tomcat 的 conf 目录就重启,结果浏览器能打开,但 Java 客户端、curl、小程序却报证书错误。根因通常不在证书本身,而在“链、库、配置、进程”四层。第一,只部署了叶子证书,没有把中间 CA 一并放入 keystore;桌面浏览器会 AIA 补链,Java 默认不会。第二,keystore 类型、密码、别名不一致,Tomcat 启动日志会出现 Keystore was tampered with 或 key alias does not exist。第三,Tomcat 8.5/9/10/11 的 Connector 写法不同,老教程仍在用 SSLCertificateFile 这类 Apache 指令。第四,证书有效期规则已变化:公开信任 TLS 证书单张最长 398 天,Let’s Encrypt 为 90 天,续期后只替换文件不重启 Tomcat 不会生效。第五,8443 未放行、SNI 未带 servername、Java 信任库未预置根证书,都会让握手失败。排查先看三处:Tomcat catalina.out、openssl s_client 输出、keytool -list -v。
openssl x509 -in cert.pem -noout -subject -issuer -dates -ext subjectAltName
keytool -list -v -keystore /opt/ssl/example.com.pfx -storetype PKCS12 -storepass 'PFX密码'
准备 JoySSL 证书文件与 CSR 核对:PFX、JKS、PEM 怎么选
从 JoySSL 控制台下载证书时,优先选择 PFX/PKCS12 单文件,Tomcat 8.5+ 可直接读取;如果控制台只给 PEM,则下载 fullchain.pem 与私钥 key.pem,再用 openssl 打包成 PFX。拿到文件后先核对三件事:证书是否包含完整链、SAN 是否覆盖实际域名、私钥与证书是否匹配。RSA 证书用 modulus 比对,ECC 证书用公钥哈希比对。检查命令如下,输出中的 Issuer 应出现中间 CA 名称,Subject Alternative Name 应包含 example.com 与 www.example.com。
openssl x509 -in cert.pem -noout -subject -issuer -dates -ext subjectAltName
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
openssl x509 -noout -modulus -in cert.pem | openssl md5
openssl rsa -noout -modulus -in key.pem | openssl md5
openssl pkcs12 -in example.com.pfx -info -noout -passin pass:'PFX密码'
如果要把 PFX 转成 JKS,使用 keytool 导入,并显式指定目标别名 tomcat,避免 Tomcat 找不到 key alias。命令中 -destkeypass 必须与 -deststorepass 一致或单独配置,否则会出现 Cannot recover key。转换后再次用 keytool -list -v 确认条目类型为 PrivateKeyEntry,且证书链长度大于 1。
keytool -importkeystore -srckeystore example.com.pfx -srcstoretype PKCS12 -srcstorepass 'PFX密码' -destkeystore example.com.jks -deststoretype JKS -deststorepass 'JKS密码' -destkeypass 'JKS密码' -destalias tomcat
keytool -list -v -keystore example.com.jks -storepass 'JKS密码'
完整实操步骤:上传、权限、JKS 导入与 Tomcat 启动
生产环境不要把证书放在 Tomcat 安装目录内,建议统一放到 /opt/ssl,属主设为运行 Tomcat 的用户,权限 600。步骤一:创建目录并上传 PFX 或 JKS。步骤二:如果使用 JKS,执行上节的 keytool 导入。步骤三:编辑 $CATALINA_HOME/conf/server.xml,加入 8443 Connector。步骤四:放行防火墙端口。步骤五:重启 Tomcat 并观察 catalina.out。步骤六:用 openssl s_client 验证。命令可直接执行,注意把 tomcat 用户替换为实际运行用户。
install -d -m 700 -o tomcat -g tomcat /opt/ssl
cp example.com.pfx /opt/ssl/example.com.pfx
chown tomcat:tomcat /opt/ssl/example.com.pfx
chmod 600 /opt/ssl/example.com.pfx
firewall-cmd --add-port=8443/tcp --permanent
firewall-cmd --reload
systemctl restart tomcat
tail -n 100 -f $CATALINA_HOME/logs/catalina.out
如果系统启用 SELinux,Tomcat 读取 /opt/ssl 可能被拒绝,可执行 chcon -t cert_t /opt/ssl/example.com.pfx,或用 semanage fcontext 添加永久规则。启动日志中看到 Starting ProtocolHandler [https-nio-8443] 才说明 Connector 已加载。若日志出现 Address already in use,先用 ss -lntp | grep 8443 查占用进程;若出现 Keystore was tampered with,优先核对密码和 storeType,而不是反复重签证书。
Tomcat 配置示例:PFX、JKS 与 HTTP 跳转 HTTPS
Tomcat 8.5/9/10/11 的 SSL 配置都使用 SSLHostConfig 与 Certificate,但 8.5 已停止维护,生产建议 9.0 或 10.1/11。下面示例中属性使用单引号,实际 server.xml 可换成双引号。PFX 方式最简洁,certificateKeystoreType 必须写 PKCS12,certificateKeyAlias 建议显式指定。JKS 方式则把类型改为 JKS,并保证别名与 keytool 导入时一致。
<Connector port='8443' protocol='org.apache.coyote.http11.Http11NioProtocol' maxThreads='150' SSLEnabled='true'>
<SSLHostConfig>
<Certificate certificateKeystoreFile='/opt/ssl/example.com.pfx'
certificateKeystorePassword='PFX密码'
certificateKeystoreType='PKCS12'
certificateKeyAlias='tomcat' />
</SSLHostConfig>
</Connector>
JKS 配置只需替换三行:certificateKeystoreFile 指向 example.com.jks,certificateKeystoreType 改为 JKS,certificateKeystorePassword 填 JKS 密码。若使用 PEM,Tomcat 8.5+ 可写 certificateFile=’/opt/ssl/fullchain.pem’ 与 certificateKeyFile=’/opt/ssl/key.pem’,适合 acme.sh 自动续期。HTTP 跳转 HTTPS 时,保留 8080 Connector 并设置 redirectPort=’8443’,再在应用 web.xml 中加入 security-constraint,或使用 RewriteValve 做 301 跳转。
<Connector port='8080' protocol='HTTP/1.1' connectionTimeout='20000' redirectPort='8443' />
PFX、JKS、PEM 三种部署方式对比表格
选择哪种格式,取决于 Tomcat 版本、是否多别名、是否自动化续期。PFX 适合单域名或通配符证书,单文件迁移方便;JKS 适合老版本 Tomcat 或需要固定别名、多个证书条目共存的环境;PEM 适合 acme.sh、certbot 等自动续期工具直接写入文件。无论哪种格式,都要确认 keystore 或 fullchain 中包含中间 CA,否则 Java 客户端仍会报 PKIX path building failed。
| 格式 | Tomcat 关键参数 | 常用检查命令 | 优点 | 注意事项 |
|---|---|---|---|---|
| PFX/PKCS12 | certificateKeystoreFile、certificateKeystorePassword、certificateKeystoreType=’PKCS12′ | openssl pkcs12 -info;keytool -list -v | Tomcat 8.5+ 首选,单文件,含私钥与链 | 别名可能不是 tomcat,需显式 certificateKeyAlias |
| JKS | certificateKeystoreType=’JKS’、certificateKeyAlias=’tomcat’ | keytool -importkeystore;keytool -list -v | 兼容老版本,别名可控 | 需设置 -destkeypass,密码与 storepass 易混 |
| PEM | certificateFile、certificateKeyFile | openssl x509;openssl pkey | 便于自动化续期与版本管理 | 权限 600,fullchain 顺序为叶子证书在前 |
如果 Tomcat 前面还有 Nginx 或负载均衡,证书应部署在入口层,Tomcat 只处理 HTTP;此时不要重复配置 8443,否则容易出现端口冲突和 SNI 混乱。若必须端到端加密,Tomcat 的 keystore 也要放完整链,不能只放叶子证书。
常见错误排查:从真实报错到修复命令
报错一:java.io.IOException: Keystore was tampered with, or password was incorrect。说明 storepass 或 keystore 类型不对,先用 keytool -list -v -storetype PKCS12 验证密码,再检查 server.xml 是否把 PKCS12 写成 JKS。报错二:java.security.UnrecoverableKeyException: Cannot recover key。多为 keypass 与 storepass 不一致,JKS 转换时补 -destkeypass。报错三:javax.net.ssl.SSLHandshakeException: PKIX path building failed。说明链不完整,执行 openssl s_client -showcerts 看是否只有一张证书,应改用 fullchain 或含中间 CA 的 PFX。
openssl s_client -connect example.com:8443 -servername example.com -showcerts </dev/null
curl -vI https://example.com:8443 --resolve example.com:8443:127.0.0.1
报错四:javax.net.ssl.SSLHandshakeException: no cipher suites in common。常见于客户端只支持 TLS 1.2 而 Tomcat 只开 TLS 1.3,或证书算法与 Java 版本不匹配。报错五:java.security.cert.CertificateException: No subject alternative names present。证书 SAN 未覆盖访问域名,需重签或改用正确域名。报错六:Tomcat 日志 The key alias [tomcat] does not exist。用 keytool -list 查看实际别名,改 certificateKeyAlias。报错七:curl: (60) SSL certificate problem: unable to get local issuer certificate。客户端缺中间 CA,不是服务端没配好,可用 -CAfile fullchain.pem 复测。
效果验证:openssl、curl、浏览器与 Java 客户端四层检查
第一层用 openssl 看握手与链,输出中 Verify return code 应为 0,Certificate chain 应至少包含叶子证书和中间 CA。第二层用 curl 模拟真实 HTTPS 请求,–resolve 可绕过 DNS 指向本机。第三层用浏览器检查锁标志、SAN、有效期和协议版本。第四层用 Java 自带工具复测,因为 Java 不一定会自动补链。keytool -printcert -sslserver 可直接打印服务端证书链,适合快速确认。
echo | openssl s_client -connect example.com:8443 -servername example.com 2>/dev/null | openssl x509 -noout -dates -subject -issuer
curl -vI https://example.com:8443 --resolve example.com:8443:127.0.0.1
keytool -printcert -sslserver example.com:8443
java -Djavax.net.debug=ssl:handshake -cp . TestSSL https://example.com:8443
Java 自测时重点看 ServerHello、Certificate chain 和 Finished 三处。如果 -Djavax.net.debug=ssl:handshake 输出中只有一张证书,说明 Tomcat keystore 缺中间 CA;如果出现 unable to find valid certification path,则客户端信任库未预置根证书,可导入根 CA 或使用 -Djavax.net.ssl.trustStore 指定 truststore。最后检查证书有效期,公开信任 TLS 证书最长 398 天,Let’s Encrypt 为 90 天,避免上线当天就临近过期。
续期与自动化:398 天与 90 天证书如何平滑生效
证书续期后,Tomcat 不会自动重新加载 keystore。替换 PFX 或 JKS 后必须重启 Tomcat 进程,执行 systemctl restart tomcat 或 $CATALINA_HOME/bin/shutdown.sh 后 startup.sh。若使用 PEM 方式,也要确认 certificateFile 指向的是新 fullchain.pem。续期后先用 openssl x509 -noout -dates 检查 notBefore 与 notAfter,再重启,最后用 openssl s_client 复测。不要只替换文件就认为完成,进程内旧证书仍会继续服务。
openssl x509 -in /opt/ssl/fullchain.pem -noout -dates -subject
systemctl restart tomcat
openssl s_client -connect example.com:8443 -servername example.com </dev/null | openssl x509 -noout -dates
使用 acme.sh 时,可通过 reloadcmd 在续期成功后自动重启 Tomcat;如果 Tomcat 读取 PFX,可在 hook 中先用 openssl pkcs12 -export 重新打包,再 restart。Let’s Encrypt 证书 90 天到期,建议每天检查一次;JoySSL 付费证书按 398 天上限管理,提前 30 天续期。自动化脚本要记录退出码,失败时告警,避免证书过期后才发现重启命令没有执行。
acme.sh --install-cert -d example.com --ecc --fullchain-file /opt/ssl/fullchain.pem --key-file /opt/ssl/key.pem --reloadcmd 'systemctl restart tomcat'
常见问题
Tomcat 8.5+ 优先用 PFX/PKCS12,单文件包含私钥与证书链,配置 certificateKeystoreType=’PKCS12′ 即可。老版本 Tomcat 或需要固定别名时用 JKS,通过 keytool -importkeystore 导入并设置 certificateKeyAlias=’tomcat’。两种格式都要确认 keystore 内含中间 CA。
这是证书链不完整或客户端信任库缺根证书。先用 openssl s_client -showcerts 检查服务端是否只返回叶子证书,若是,把 fullchain 或含中间 CA 的 PFX 重新部署到 Tomcat;若链完整,再把根 CA 导入 Java truststore,或用 -Djavax.net.ssl.trustStore 指定信任库复测。
Tomcat 在启动时加载 keystore,替换文件不会自动生效。需要重启 Tomcat 进程,执行 systemctl restart tomcat 或 shutdown.sh 后 startup.sh。重启后用 openssl s_client 查看 notAfter 是否为新日期,并确认 server.xml 指向的确实是新文件路径。
先看 $CATALINA_HOME/logs/catalina.out,重点搜 Keystore、alias、Address already in use、SSLHandshakeException。再用 ss -lntp | grep 8443 查端口占用,用 keytool -list -v 核对密码、类型、别名。若是 SELinux 环境,还要检查 /opt/ssl 目录的 cert_t 上下文。
部署步骤基本一致,都是把 PFX/JKS/PEM 配到 Connector。区别主要在验证方式、保障范围和有效期管理:DV 只验证域名,适合测试和个人站点;付费证书通常提供更高保障和商业支持。无论哪种,都要按 398 天上限或 90 天周期提前续期并重启 Tomcat。