跳到主要内容
Tomcat

SSL.com 证书 Tomcat 部署实战:PFX/JKS 配置、真实报错排查与验证

一、问题背景与根因:为什么 Tomcat 部署证书比 Nginx 更容易失败

Nginx、Apache 直接读取 PEM 文本文件,而 Tomcat 是 Java 进程,证书必须交给 JVM 的 KeyStore(PKCS12 或 JKS)管理,再通过 Connector 暴露 8443 端口。这条链路上任何一环出错,表现出来的现象都是“浏览器打不开”或者“部分客户端握手失败”,因此先定位根因,比急着改配置更有效。

生产环境最常见的四类根因:

  • 证书链不完整。SSL.com 的下载包里通常有三样东西:叶子证书 example.com.crt、中间链 ca-bundle.crt、以及打包好的 PFX。只把叶子证书导入 KeyStore,浏览器可能靠 AIA 自动补链而显示正常,但 curl、Java、微信小程序、老版本 Android 不会补链,直接报 PKIX path building failed。
  • 载体与 Tomcat 版本不匹配。Tomcat 8.5+ 原生支持 PKCS12,8.0 及更早只认 JKS;把 PFX 路径直接写进老版本 server.xml 会抛 Invalid keystore format。
  • 续期后没换文件。SSL.com 证书单张有效期上限为 398 天(Let’s Encrypt 等 ACME 证书为 90 天)。续期后新文件路径或密码变了,server.xml 仍指向旧文件,浏览器就报证书过期。
  • JDK 与协议不匹配。JDK 11+ 默认禁用 TLSv1/TLSv1.1,若 ciphers 只配了 TLS 1.3 套件,只支持 TLS 1.2 的老客户端会报 ERR_SSL_VERSION_OR_CIPHER_MISMATCH。

下文以 Tomcat 9.0.x / 10.1.x + JDK 11/17 + SSL.com DV/OV/EV 证书为环境,所有命令可直接复制执行。

二、完整实操第一步:准备证书文件并做三项校验

先把 SSL.com 下载包里的 example.com.crt、ca-bundle.crt、example.com.pfx 上传到服务器 /opt/ssl/,并收紧权限(私钥文件绝不可 644)。

mkdir -p /opt/ssl && cd /opt/ssl
chmod 600 *.pfx *.key
chown -R tomcat:tomcat /opt/ssl
# 查看 PFX 结构:条目数、加密算法、是否含中间链
openssl pkcs12 -info -in example.com.pfx -noout
# 拆分叶子证书与中间链
openssl pkcs12 -in example.com.pfx -nokeys -clcerts -out leaf.crt
openssl pkcs12 -in example.com.pfx -nokeys -cacerts -out chain.crt
cat leaf.crt chain.crt > fullchain.crt

三项必查,任何一项不过都不要往下走:

# 1) 有效期与 SAN,确认域名没写错
openssl x509 -in fullchain.crt -noout -subject -issuer -dates -ext subjectAltName
# 2) 链完整性,返回 OK 才算完整
openssl verify -CAfile chain.crt -untrusted chain.crt leaf.crt
# 3) 私钥与证书是否配对,两个 md5 必须一致
openssl x509 -in leaf.crt -noout -modulus | openssl md5
openssl pkcs12 -in example.com.pfx -nocerts -nodes | openssl rsa -noout -modulus | openssl md5

如果 SSL.com 只交付了 PEM 而没有 PFX,用一条命令自行打包,中间链必须一起打进 -in 参数,否则后面所有排查都是白费:

openssl pkcs12 -export -in fullchain.crt -inkey example.com.key 
  -name tomcat -out example.com.pfx -passout pass:'YourStrongPass'

注意 -name 指定的别名(这里是 tomcat)后面转 JKS 时会用到,建议统一命名,避免出现 alias 1 这种难维护的值。

三、配置示例:Tomcat 9/10 用 PFX 直连(推荐方案)

编辑 $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 sslProtocol="TLSv1.2+TLSv1.3"
                 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="YourStrongPass"
                 certificateKeystoreType="PKCS12"
                 type="RSA" />
  </SSLHostConfig>
</Connector>

若手上只有 PEM(fullchain + key),Tomcat 8.5+ 可直接引用,无需转 KeyStore,方便与 Nginx 共用同一套证书:

<Certificate certificateFile="/opt/ssl/fullchain.crt"
             certificateKeyFile="/opt/ssl/example.com.key"
             certificateChainFile="/opt/ssl/chain.crt"
             type="RSA" />

四个高频易错点:① 密码含 &、<、> 时在 XML 中必须转义为 &amp;、&lt;、&gt;,否则密码被截断;② 一台机器部署多张证书时,每个 SSLHostConfig 必须写 hostName 属性,否则只生效第一个;③ 改完必须整进程重启(systemctl restart tomcat),仅 reload webapp 不生效;④ certificateKeystoreFile 用绝对路径,不要用相对 $CATALINA_BASE 的写法,避免多实例部署时互相覆盖。若需 8080 强制跳 8443,在 conf/web.xml 的 <web-app> 内加 security-constraint(CONFIDENTIAL)并给 Connector 配 redirectPort="8443"。

四、老版本 Tomcat 与 JKS:keytool 转换全流程

Tomcat 8.0 及更早版本,或运维规范强制要求 JKS 时,用 keytool 转换。关键点:JDK 9 起 keytool 默认生成 PKCS12,转 JKS 必须显式加 -deststoretype JKS,否则你以为转成了 JKS,实际还是 PKCS12,老 Tomcat 照样报 Invalid keystore format。

# 1) 先确认 PFX 内部的别名(常见为 1、tomcat 或域名)
keytool -list -v -storetype PKCS12 -keystore example.com.pfx -storepass 'YourStrongPass' | grep Alias
# 2) 转换并指定目标别名
keytool -importkeystore -srckeystore example.com.pfx -srcstoretype PKCS12 
  -srcstorepass 'YourStrongPass' -srcalias 1 
  -destkeystore /opt/ssl/example.jks -deststoretype JKS 
  -deststorepass 'ChangeIt2024' -destalias tomcat
# 3) 确认条目类型是 PrivateKeyEntry,而不是 trustedCertEntry
keytool -list -v -keystore /opt/ssl/example.jks -storepass 'ChangeIt2024' | grep -E 'Alias|Entry type'

如果第 3 步显示 trustedCertEntry,说明只导入了证书、没有导入私钥,必须回到第 2 步用 -importkeystore 而非 -importcert。如果链不完整,补导中间证书:

keytool -importcert -alias intermediate -file chain.crt 
  -keystore /opt/ssl/example.jks -storepass 'ChangeIt2024' -noprompt

server.xml 对应改为 certificateKeystoreType="JKS"、certificateKeystoreFile 指向 .jks、密码换成 deststorepass 的值。JKS 的完整性校验较弱,建议密码不少于 12 位并单独保管,不要与 PFX 密码复用;文件权限设为 600 且属主为运行 Tomcat 的用户。

五、对比表格:PKCS12 / JKS / PEM 三种载体怎么选

对比项 PKCS12(.pfx/.p12) JKS(.jks) PEM(.crt + .key)
Tomcat 支持版本 8.5+ 原生支持 全版本支持 8.5+ 原生支持
是否含私钥 是,密码加密 是,密码加密 私钥独立文件,明文
是否含中间链 取决于打包,需 openssl 校验 需显式 keytool 导入 由 certificateChainFile 指定
JDK 默认格式 JDK 9+ keytool 默认 JDK 8 及以前默认 不涉及
跨平台通用性 好,OpenSSL 通用 差,Java 专有 最好
续期操作成本 替换文件 + 重启 重新 import 或补导 替换文件 + 重启
推荐场景 Tomcat 8.5+ 首选 老系统兼容过渡 与 Nginx 共用同一套证书

版本属性差异同样要纳入考虑:Tomcat 8.5 / 9.0 使用 certificateKeystoreFile + certificateKeystorePassword + certificateKeystoreType 嵌套在 SSLHostConfig 内;Tomcat 10.1 属性名一致,但要求 JDK 11+,且默认 KeyStore 类型为 PKCS12;Tomcat 7 只支持把 keystoreFile / keystorePass 直接写在 Connector 属性上,不支持 SSLHostConfig 嵌套。

有效期维度也要一起评估:SSL.com 的 DV/OV/EV 证书单张最长 398 天,适合一年一换的手工运维;Let’s Encrypt 等 ACME 证书 90 天,必须做自动化续期,且续期后同样要重启 Tomcat 才生效。选型时把“谁能保证在到期前完成替换”想清楚,比纠结格式更重要。

六、常见错误排查:真实报错与对应处置

以下报错均来自实际工单,按“报错原文 → 根因 → 处置”给出。

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,数一下返回几段 BEGIN CERTIFICATE,正常应 ≥ 2 段;不足则把 chain.crt 打进 PFX 重新导出,或 keytool 补导中间证书。

2) javax.net.ssl.SSLHandshakeException: PKIX path building failed
客户端侧报错,同样指向链不完整或客户端信任库过旧。用 keytool -printcert -sslserver example.com:8443 查看服务端实际下发的链。

3) java.io.IOException: keystore password was incorrect
密码错,或 XML 转义导致密码被截断(含 & 的密码必须写成 &amp;)。先用 openssl pkcs12 -info -in example.com.pfx -noout 确认密码正确。

4) java.security.UnrecoverableKeyException: Cannot recover key
JKS 中该 alias 的私钥口令与 storepass 不一致,转换时补 -srckeypass / -destkeypass 参数。

5) java.io.IOException: Invalid keystore format
文件实际是 PKCS12 但 certificateKeystoreType 写了 JKS,或反之。用 file example.jks 与 keytool -list 交叉确认。

6) IllegalArgumentException: The certificate chain file … does not contain a valid certificate
PEM 模式下 certificateChainFile 指向了空文件或私钥文件,改为指向中间链文件。

7) 浏览器正常,但小程序 / Java 客户端握手失败
约九成是链不完整,一成是 ciphers 只配了 TLS 1.3 套件而客户端只支持 TLS 1.2。用 openssl s_client -tls1_2 -connect example.com:8443 复测即可区分。

8) 8443 端口外部连不上
先 ss -lntp | grep 8443 看是否监听,未监听查 catalina.out;已监听则放行防火墙 firewall-cmd --add-port=8443/tcp --permanent && firewall-cmd --reload,云服务器还要同步放行安全组。

七、效果验证:从命令行到浏览器再到监控

配置改完不要只看浏览器,按下面四步依次验证:

# 1) 握手与证书链,-servername 必带,多证书场景缺它会拿到默认证书
openssl s_client -connect example.com:8443 -servername example.com -showcerts </dev/null
# 2) 严格校验链,出现 Verify return code: 0 (ok) 才算通过
openssl s_client -connect example.com:8443 -servername example.com 
  -CAfile /etc/ssl/certs/ca-certificates.crt -verify_return_error </dev/null
# 3) HTTP 层确认
curl -vI https://example.com:8443
# 4) 剩余有效期,小于 30 天返回非 0,可直接接监控告警
openssl s_client -connect example.com:8443 </dev/null 2>/dev/null | 
  openssl x509 -noout -checkend 2592000 -enddate

Java 应用侧打开握手日志,能看清用了哪个 alias、协商了哪个协议版本:

java -Djavax.net.debug=ssl:handshake -jar app.jar 2>&1 | grep -E "Protocol|CipherSuite|alias"

最后浏览器访问 https://example.com:8443,点锁图标确认“证书有效”、颁发者为 SSL.com 的中间 CA、SAN 包含实际访问域名;再跑 testssl.sh --fast example.com:8443 或 SSL Labs,目标是评级 A 及以上、同时支持 TLS 1.2 与 TLS 1.3、无 SHA-1 与 RC4。全部通过后,把第 4 条 checkend 命令写成每日 cron,才能在 398 天有效期到期前被提醒,而不是等用户投诉。

常见问题

Tomcat 8.5 及以上优先用 PKCS12(.pfx),原生支持、OpenSSL 通用、便于与 Nginx 共用同一份证书;只有 Tomcat 8.0 及更早或既有规范强制时才转 JKS。注意 JDK 9 起 keytool 默认输出 PKCS12,转 JKS 必须显式加 -deststoretype JKS。


九成是证书链不完整。用 openssl s_client -connect 域名:8443 -showcerts 看返回几段证书,正常至少两段(叶子 + 中间 CA)。若只有一段,把 ca-bundle 打进 PFX 重新导出,或在 JKS 中用 keytool -importcert 补导中间证书,然后重启 Tomcat。


替换 /opt/ssl 下的证书文件,确认 server.xml 里的路径与密码指向新文件,然后重启 Tomcat 进程,仅 reload 应用不生效。部分 Tomcat 9 版本能检测 keystore 文件变更自动重载,但生产环境建议显式重启,并用 openssl s_client 复测链是否完整。


XML 中 &、<、> 必须分别转义为 &amp;、&lt;、&gt;,否则会解析失败或密码被截断,表现为 keystore password was incorrect。更稳妥的做法是密码只用字母、数字与 – _ . 这类字符,或改用 PEM 模式,避免在 XML 里写密码。


不必。8443 只是 Tomcat 默认示例端口,可以改成 443,但 Linux 下非 root 进程绑定 1024 以下端口需要 setcap 或 authbind。若前面有 Nginx 反向代理,让 Tomcat 保持 8443 且只监听内网更安全。


SSL.com 证书单张最长 398 天,Let’s Encrypt 为 90 天。建议把 openssl x509 -checkend 2592000 写成每日 cron,剩余不足 30 天即告警;续期后必须重新部署并重启 Tomcat,否则往往到过期当天才被用户发现。

内容审核

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