跳到主要内容
Tomcat

ZeroSSL 证书部署到 Tomcat 实战:PKCS12 转换、SSLHostConfig 配置与证书链排错

一、问题背景:为什么 ZeroSSL 证书在 Tomcat 上总是“浏览器能开、程序报错”

ZeroSSL 是目前使用较广的免费证书 CA:免费 DV 证书有效期 90 天,既可以通过 ACME 协议自动签发,也可以在网页端手动签发,另外还提供付费 OV/EV。证书本身通常没有问题,问题几乎都出在 Tomcat 加载证书的方式上。

Nginx、Apache 直接读 PEM 文件,ssl_certificate 指向 fullchain 就行;Tomcat 走的是 Java KeyStore(PKCS12 或 JKS),一个条目里必须同时装下私钥和完整证书链。很多教程让人把 ZeroSSL 下载包里的 certificate.crt(叶子证书)单独导入,结果浏览器访问正常,因为 Chrome 会通过 AIA 自动补齐中间证书,而 curl、Java 客户端、微信小程序全部报 PKIX path building failed,因为 Java 不会去 AIA 抓中间证书。

第二个问题出在配置语法。Tomcat 8.5 起引入 SSLHostConfig / Certificate 嵌套结构,旧的 keystoreFile、keystorePass 平铺属性在 8.5 上仍兼容但会打印废弃警告,在 Tomcat 10.1/11 中已被移除;直接照抄多年前的教程,启动后 8443 端口要么不监听,要么抛 Attribute keystoreFile invalid。

第三个问题是 JDK 与密钥算法。OpenSSL 3.x 默认用 AES-256-CBC + SHA256 生成 PKCS12,而 JDK 8u301 之前的版本不支持这套 PBE 算法,启动即报 UnrecoverableKeyException: Cannot recover key。此外还要注意:公开信任的 TLS 证书最长有效期已被限制在 398 天,ZeroSSL 免费证书为 90 天,意味着一年至少续期 4 次,续期后必须让 Tomcat 重新加载 keystore,否则线上仍是旧证书。下面按“准备文件 → 配置 → 验证 → 排错”的顺序给出可直接执行的完整流程。

二、准备证书文件:从 ZeroSSL 下载包到 fullchain 与 PKCS12

ZeroSSL 网页端签发完成后,在证书详情页选择 Tomcat 或 Other 格式下载,得到一个 zip 包,解压后通常包含三个文件:certificate.crt(域名证书、叶子证书)、ca_bundle.crt(中间证书)、private.key(私钥)。如果私钥是本地生成 CSR 时保存的,需要自己准备好。

mkdir -p /opt/ssl/example.com && cd /opt/ssl/example.com
unzip ~/example.com.zip
ls -l
# -rw-r--r-- certificate.crt
# -rw-r--r-- ca_bundle.crt
# -rw------- private.key

第一步先做链校验,确认中间证书和叶子证书能对上:

cat certificate.crt ca_bundle.crt > fullchain.crt
openssl verify -untrusted ca_bundle.crt certificate.crt
# certificate.crt: OK

顺序不能反:叶子证书必须在最前,中间证书在后。顺序颠倒时 openssl verify 会返回 error 20 at 0 depth lookup: unable to get local issuer certificate。

第二步导出 PKCS12,推荐给 Tomcat 8.5 及以上使用。注意 -name 指定的别名后面在 Tomcat 里可以用 certificateKeyAlias 引用,密码建议 12 位以上并含特殊字符:

openssl pkcs12 -export 
  -in fullchain.crt 
  -inkey private.key 
  -name tomcat 
  -out /opt/ssl/example.com.pfx 
  -passout pass:'Z3roSSL@2025' 
  -keypbe AES-256-CBC -certpbe AES-256-CBC -macalg sha256

如果目标服务器是 JDK 8u301 以下的旧环境(CentOS 7 自带 OpenJDK 1.8.0_262 之类),需要降级 PBE 算法,否则 Java 读不了:

openssl pkcs12 -export -in fullchain.crt -inkey private.key -name tomcat 
  -out /opt/ssl/example.com.pfx -passout pass:'Z3roSSL@2025' 
  -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -macalg sha1

第三步自检,输出里应该能看到 1 个私钥条目和至少 2 张证书(叶子 + 中间,部分 CA 有 2 张中间证书则更多):

openssl pkcs12 -info -in /opt/ssl/example.com.pfx -passin pass:'Z3roSSL@2025' -nokeys 2>/dev/null | grep -E "subject=|issuer="
chown tomcat:tomcat /opt/ssl/example.com.pfx
chmod 600 /opt/ssl/example.com.pfx

权限务必收紧:keystore 里存的就是受口令保护的私钥,chmod 644 会让同机任意用户可读。

三、Tomcat 8.5 / 9 / 10 配置:SSLHostConfig 完整写法

编辑 $CATALINA_HOME/conf/server.xml,找到被注释掉的 8443 Connector,替换为下面的写法(Tomcat 8.5、9.0、10.0、10.1、11 通用):

<Connector port="8443"
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200"
           SSLEnabled="true"
           scheme="https"
           secure="true"
           compression="on"
           URIEncoding="UTF-8">
  <SSLHostConfig protocols="TLSv1.2,TLSv1.3"
                 honorCipherOrder="true"
                 sslProtocol="TLS"
                 sessionCacheSize="20000"
                 sessionTimeout="86400"
                 ciphers="TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,ECDHE-RSA-AES256-GCM-SHA384,ECDHE-RSA-AES128-GCM-SHA256">
    <Certificate certificateKeystoreFile="/opt/ssl/example.com.pfx"
                 certificateKeystorePassword="Z3roSSL@2025"
                 certificateKeystoreType="PKCS12"
                 certificateKeyAlias="tomcat"
                 type="RSA" />
  </SSLHostConfig>
</Connector>

参数要点:protocol 建议显式写 Http11NioProtocol 或 Http11Nio2Protocol;certificateKeystoreType 不写时 Tomcat 会按文件后缀猜测,.pfx 能猜到 PKCS12,但显式声明可避免歧义;protocols 只保留 TLSv1.2 与 TLSv1.3,TLSv1.0/1.1 已在 RFC 8996 中被正式废弃;ciphers 里的 TLS 1.3 套件名只在 JDK 11+ 生效,JDK 8 会忽略,JDK 8 请确保 ECDHE-RSA-AES128-GCM-SHA256 这类套件在列。

同一台 Tomcat 跑多个域名(SNI)时,在同一个 Connector 内并列多个 SSLHostConfig,用 hostName 区分,默认那个保持 _default_:

<SSLHostConfig hostName="api.example.com">
  <Certificate certificateKeystoreFile="/opt/ssl/api.example.com.pfx"
               certificateKeystorePassword="Passw0rd@api"
               certificateKeystoreType="PKCS12" />
</SSLHostConfig>

改完 server.xml 必须重启,server.xml 不支持热加载:

/opt/tomcat/bin/shutdown.sh
sleep 5
/opt/tomcat/bin/startup.sh
tail -n 200 /opt/tomcat/logs/catalina.out | grep -iE "ssl|keystore|connector"

端口与权限:如果直接用 443,Linux 下非 root 进程无法绑定 1024 以下端口,可给 java 授予能力或做端口转发:

setcap 'cap_net_bind_service=+ep' /usr/lib/jvm/java-17-openjdk-amd64/bin/java
# 或使用 firewalld 放行 8443
firewall-cmd --permanent --add-port=8443/tcp && firewall-cmd --reload

四、老版本 Tomcat(7 / 8.0)与 JKS:keytool 导入与兼容写法

如果服务器上跑的是 Tomcat 7 或 8.0,没有 SSLHostConfig,只能使用平铺属性的 Connector,keystore 建议转成 JKS。用 JDK 自带的 keytool 一条命令完成转换:

keytool -importkeystore 
  -srckeystore /opt/ssl/example.com.pfx 
  -srcstoretype PKCS12 
  -srcstorepass 'Z3roSSL@2025' 
  -destkeystore /opt/tomcat/conf/example.com.jks 
  -deststoretype JKS 
  -deststorepass 'ChangeIt@2025' 
  -destkeypass 'ChangeIt@2025' 
  -noprompt
# Warning: JKS keystore uses a proprietary format...

转换完必须确认链长度大于 1,否则说明当初导出的 PFX 里只有叶子证书:

keytool -list -v -keystore /opt/tomcat/conf/example.com.jks -storepass 'ChangeIt@2025' 
  | grep -E "Alias name|Certificate chain length|Owner|Issuer"
# Alias name: tomcat
# Certificate chain length: 3

对应 Connector 写法:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true" scheme="https" secure="true"
           keystoreFile="/opt/tomcat/conf/example.com.jks"
           keystorePass="ChangeIt@2025"
           keystoreType="JKS"
           clientAuth="false"
           sslEnabledProtocols="TLSv1.2,TLSv1.3"
           ciphers="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" />

注意 sslEnabledProtocols 与 ciphers 用的是 OpenSSL 风格套件名(TLS_ECDHE_RSA_WITH_...),和 SSLHostConfig 里的写法不同,混用会报 IllegalArgumentException: Unsupported ciphersuite。另外 JKS 使用专有的 SHA1 摘要保护口令,安全强度和跨语言兼容性都不如 PKCS12,keytool 自身也会提示 proprietary format,升级到 Tomcat 8.5+ 后应尽快切回 PKCS12。

还有一种“半新不旧”的情况:Tomcat 8.5 上仍写老属性。此时 Tomcat 能启动,但 catalina.out 会打印 The keystoreFile attribute is deprecated, use the SSLHostConfig/Certificate element instead。这类警告在升级到 10.1 后会直接变成启动失败,建议一次性改到位。

五、强制 HTTPS 与安全加固:web.xml + HSTS

证书配好只是第一步,还要把 HTTP 流量引导到 HTTPS,并加上 HSTS,避免首次访问被劫持。在 $CATALINA_HOME/conf/web.xml 的 </web-app> 之前加入,顺序有 DTD 约束,必须放在 <welcome-file-list> 之后:

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

同时确认 8080 Connector 上写了 redirectPort="8443"(Tomcat 默认已有),这样 transport-guarantee 才能把请求 302 到 8443。

HSTS 用 Tomcat 自带的 HttpHeaderSecurityFilter,在应用的 WEB-INF/web.xml 里加:

<filter>
  <filter-name>httpHeaderSecurity</filter-name>
  <filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
  <init-param><param-name>hstsEnabled</param-name><param-value>true</param-value></init-param>
  <init-param><param-name>hstsMaxAgeSeconds</param-name><param-value>31536000</param-value></init-param>
  <init-param><param-name>hstsIncludeSubDomains</param-name><param-value>true</param-value></init-param>
  <init-param><param-name>antiClickJackingEnabled</param-name><param-value>true</param-value></init-param>
  <init-param><param-name>antiClickJackingOption</param-name><param-value>SAMEORIGIN</param-value></init-param>
</filter>
<filter-mapping>
  <filter-name>httpHeaderSecurity</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

注意 HSTS 一旦下发 max-age=31536000,浏览器会在一年内强制走 HTTPS,若站点还有未改造的 HTTP 子域,先别加 hstsIncludeSubDomains。此外 HttpHeaderSecurityFilter 只在 Tomcat 8.0+ 存在,Tomcat 7 需要自己在 Nginx 或自定义 Filter 里写响应头。

若前置了 Nginx,让 Nginx 卸载 TLS、Tomcat 只跑 8080 也是常见架构,此时在 Nginx 的 location 里加 proxy_set_header X-Forwarded-Proto https;,并在 Tomcat 的 <Host> 内启用 RemoteIpValve(protocolHeader="X-Forwarded-Proto"),否则应用里的 request.isSecure() 会一直是 false,导致重定向死循环。

六、效果验证:openssl、curl、Java 客户端三重校验

第一层,看 Tomcat 有没有把完整链返回给客户端。-showcerts 会打印服务端发送的全部证书,正常情况下应该能看到 2 张以上:

openssl s_client -connect 127.0.0.1:8443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -E "^ *[0-9] s:|Verify return code"
#  0 s:CN = example.com
#  1 s:C = US, O = ZeroSSL, CN = ZeroSSL RSA Domain Secure Site CA
# Verify return code: 0 (ok)

Verify return code 不是 0 就说明链有问题,常见值是 21 (unable to verify the first certificate)(缺中间证书)和 10 (certificate has expired)(证书过期)。

第二层,看证书主体与有效期是否正确,特别留意续期后是否真的换了新证书:

echo | openssl s_client -connect example.com:8443 -servername example.com 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
# subject=CN = example.com
# issuer=C = US, O = ZeroSSL, CN = ZeroSSL RSA Domain Secure Site CA
# notBefore=Jan  5 00:00:00 2025 GMT
# notAfter=Apr  5 23:59:59 2025 GMT

第三层,用 curl 模拟真实客户端。注意不要用 -k,-k 会跳过校验,掩盖所有问题:

curl -vI https://example.com:8443 --resolve example.com:8443:203.0.113.10
# * Server certificate:
# *  subject: CN=example.com
# *  expire date: Apr  5 23:59:59 2025 GMT
# *  SSL certificate verify ok.
# < HTTP/1.1 200

第四层,用 Java 客户端验证,这是最容易暴露“链不完整”的环节。可以下载一个几十行的 SSLPoke.jar,或者直接用 JDK 自带的调试开关:

java -Djavax.net.debug=ssl:handshake -jar SSLPoke.jar example.com 8443
# Successfully connected
# 失败时输出:javax.net.ssl.SSLHandshakeException: PKIX path building failed

最后在浏览器或在线工具(SSL Labs、ZeroSSL 自带的 SSL 检测)复核一遍,重点看三项:证书链是否完整、是否支持 TLS 1.3、是否还有 TLS 1.0/1.1。三项全绿即部署完成。

七、常见错误排查:真实报错与对应根因

下面这些是 Tomcat 部署 ZeroSSL 证书时出现频率最高的报错,按“报错原文 → 根因 → 处理”对照即可。

报错原文 根因 处理
PKIX path building failed: unable to find valid certification path to requested target keystore 里只有叶子证书,缺中间证书 用 fullchain.crt 重新导出 PFX
curl: (60) SSL certificate problem: unable to get local issuer certificate 同上,链不完整 同上
java.security.UnrecoverableKeyException: Cannot recover key 口令错,或 JDK 8u301- 不认 AES-256-CBC 改用 -keypbe PBE-SHA1-3DES 重新导出
java.io.IOException: keystore password was incorrect server.xml 里口令与导出时不一致 用 openssl pkcs12 -info 复核口令
DerInputStream.getLength(): lengthTag=109, too big 把 PEM 文本文件直接改后缀成 .pfx 用 openssl pkcs12 -export 真正转换
Alias name [tomcat] does not identify a key entry 别名指向受信任证书条目而非私钥条目 用 keytool -list 确认真实别名
浏览器 ERR_SSL_VERSION_OR_CIPHER_MISMATCH 协议或套件不匹配,或 8443 被其他进程占用 ss -lntp | grep 8443 排查
续期后仍是旧证书 只替换文件未重启,或配置指向旧路径 重启 Tomcat 并核对 notAfter

场景一:怀疑证书与私钥不匹配。用公钥摘要比对,比模数比对更通用,因为 ECDSA 证书没有 modulus:

openssl x509 -in certificate.crt -noout -pubkey | openssl md5
openssl pkey -in private.key -pubout | openssl md5
# 两个 md5 必须一致

场景二:Tomcat 起来了但 8443 连不上。先看端口占用,再看日志:

ss -lntp | grep 8443
grep -iE "SEVERE|Exception|SSL" /opt/tomcat/logs/catalina.out | tail -n 30

场景三:续期后不生效。ZeroSSL 免费证书 90 天到期,ACME 客户端续期后要把新的 fullchain 和 key 重新导出成 PFX 并重启 Tomcat,只替换 certificate.crt 是不会生效的,因为 Tomcat 读的是 keystore 而不是 PEM。可以用 acme.sh 的 reloadcmd 固化这个动作:

acme.sh --install-cert -d example.com 
  --key-file       /opt/ssl/example.com/private.key 
  --fullchain-file /opt/ssl/example.com/fullchain.crt 
  --reloadcmd      "openssl pkcs12 -export -in /opt/ssl/example.com/fullchain.crt -inkey /opt/ssl/example.com/private.key -name tomcat -out /opt/ssl/example.com.pfx -passout pass:'Z3roSSL@2025' && /opt/tomcat/bin/shutdown.sh && sleep 5 && /opt/tomcat/bin/startup.sh"

八、方案对比:keystore 格式、Tomcat 版本与 CA 选择

选型上最容易被问到的三个问题:keystore 用哪种格式、当前 Tomcat 版本支持什么写法、免费 CA 和付费证书怎么取舍。下面三张表可以直接作为决策依据。

对比项 PKCS12(.pfx/.p12) JKS PEM(fullchain + key)
Tomcat 支持 8.5+ 原生支持 全版本支持 不能直接用,需转换
是否可含完整链 是,导出时打包 是 需手工拼接
默认保护算法 AES-256-CBC + SHA256 Java 专有 SHA1 无
跨工具兼容 好(OpenSSL、Java、.NET 通用) 仅 Java 生态 最好
推荐场景 Tomcat 8.5+、Spring Boot 仅 Tomcat 7/8.0 遗留系统 Nginx、Apache
Tomcat 版本 配置结构 关键属性 备注
7.0 / 8.0 Connector 平铺属性 keystoreFile、keystorePass、sslEnabledProtocols 无 SSLHostConfig
8.5 SSLHostConfig(推荐) certificateKeystoreFile、certificateKeystoreType 老属性仍兼容但打印废弃警告
9.0 SSLHostConfig 同上 需要 Java 8+
10.0 / 10.1 SSLHostConfig 同上 老属性移除,10.1 需 Java 11+
11.0 SSLHostConfig 同上 需 Java 17+
对比项 ZeroSSL 免费 DV Let’s Encrypt 付费 OV
单张有效期 90 天 90 天 最长 398 天(CA/B 上限)
签发方式 ACME 或网页手动 仅 ACME 人工审核
根信任 Sectigo / UserTrust 体系,主流系统内置 ISRG Root,主流系统内置 同左
适合场景 中小站点、需要网页可视化操作 全自动化流水线 需要展示单位信息

需要特别提醒的是有效期趋势:CA/Browser Forum 已通过将公开 TLS 证书有效期从 398 天逐步缩短至 47 天的计划,2026 年起分阶段生效。这意味着无论选哪家 CA,把续期和部署做成自动化脚本都是必选项,手工换证书的运维方式会越来越难以为继。

常见问题

免费 DV 证书有效期 90 天。推荐用 acme.sh 或 certbot 走 ACME 自动续期,续期后必须重新导出 PKCS12 并重启 Tomcat,因为 Tomcat 读取的是 keystore 文件而不是 PEM 证书。


不需要。Tomcat 8.5 及以上推荐 PKCS12(.pfx),用 openssl pkcs12 -export 生成,配置 certificateKeystoreType 为 PKCS12 即可。JKS 是 Java 专有格式,只在 Tomcat 7、8.0 等老环境使用。


keystore 里只导入了叶子证书,缺少中间证书。浏览器会通过 AIA 自动补链,Java 不会。用 cat certificate.crt ca_bundle.crt > fullchain.crt 拼出完整链后重新导出 PFX 即可解决。


需要。keystore 在 Connector 初始化时加载,直接替换 .pfx 文件不会生效,server.xml 改动同样只支持重启。修改后执行 shutdown.sh 再 startup.sh,并用 openssl s_client 核对 notAfter。


443 是标准 HTTPS 端口,但 Linux 下非 root 进程无法绑定 1024 以下端口,需要 setcap 授权或做端口转发。测试环境用 8443 更简单,生产环境建议用 443,避免客户端 URL 拼接和回调白名单问题。

内容审核

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