跳到主要内容
安装配置教程

Tomcat SSL证书安装实战:用 keytool 导入 PKCS12 并在 server.xml 启用 8443 HTTPS(Tomcat 9.0.x / 10.1.x)

tomcat ssl证书安装 — Tomcat SSL证书安装实战:用 keytool 导入 PKCS12 并在 server.xml 启用 8443 HTTPS(Tomcat 9.0.x / 10.1.x)
核心结论

Tomcat SSL证书安装的核心动作只有三步:把 CA 签发的 fullchain 证书导入 PKCS12 格式的 keystore(keytool -importcert),在 conf/server.xml 的 8443 Connector 里用 SSLHostConfig + Certificate 指向该文件,重启 Tomcat 生效,Tomcat 9.0.x 与 10.1.x 通用。 生成密钥库的命令为 keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -storetype PKCS12 -keystore tomcat.p12 -validity 365,导入成功时 keytool 回显 Certificate reply was installed in keystore。 Tomcat 8.5 之前写 keystoreFile/keystorePass,8.5 及以后写 SSLHostConfig + certificateKeystoreFile + certificateKeystoreType=PKCS12;SSLCertificateFile 属于 APR/tcnative 连接器属性,在 NIO 下不生效。 验证三连:openssl s_client -connect 域名:8443 -servername 域名 -showcerts 看链长是否为 3,curl -I --tlsv1.3 看是否返回 200,nmap --script ssl-enum-ciphers -p 8443 看协议与套件。 Let's Encrypt 证书有效期 90 天,续期后必须重新 keytool -importcert 覆盖别名并重启 Tomcat,JSSE 连接器不支持热加载,这点与 Nginx 的 reload 有本质区别。

为什么 Tomcat SSL证书安装后 8443 端口还是打不开?先定位这 6 个根因

把证书成功导进 keystore,只能算完成了一半。据 Apache Tomcat 9 官方文档,conf/server.xml 中 8443 端口的 Connector 在出厂状态下整段都被注释掉了;而据 Let’s Encrypt 文档,PEM 与 keystore 是两套互不兼容的存储格式。所以“Tomcat SSL证书安装完了却打不开”绝大多数不是证书本身的问题。先做三项事实确认,再对照下面 6 个根因,不要凭猜测修改配置:

# 1) 端口是否真的在监听:无任何输出 = Connector 根本没起来
ss -lntp | grep 8443

# 2) 本机自测,绕开浏览器缓存、CDN 与云安全组
curl -k -v https://127.0.0.1:8443/ 2>&1 | head -20

# 3) 看启动日志里有没有该协议处理器
grep -i "ProtocolHandler" $CATALINA_BASE/logs/catalina.out | tail -5
# 正常应出现:Starting ProtocolHandler ["https-jsse-nio-8443"]

根因 1:Connector 默认被注释,等于没配。Tomcat 9.0.x 的 server.xml 里 8443 那一段包在 <!-- --> 中,装完证书却不取消注释,日志里连 https-jsse-nio-8443 都不会出现。取消注释并补全 certificateKeystoreFile 后才会监听。

根因 2:把 Nginx 的 PEM 直接塞进 keystore 属性。JSSE 连接器只接受 JKS/PKCS12,写 fullchain.pem 会立刻抛 java.io.IOException: Invalid keystore format,这是 Tomcat SSL证书安装最高频的失败原因。正确做法是先合成 PKCS12,并确认链长度:

# -in 用 fullchain(含中间证书),保证中间证书一起进链
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem 
  -name tomcat -out tomcat.p12 -passout pass:ChangeIt123

# 别名与链长度自检:Certificate chain length 应为 2 或 3
keytool -list -v -keystore tomcat.p12 -storepass ChangeIt123 
  | grep -E "Alias name|Certificate chain length"

根因 3:版本写法混用。Tomcat 8.5 起推荐 SSLHostConfig + <Certificate> 嵌套写法;SSLCertificateFile/SSLCertificateKeyFile 属于 APR/tcnative 连接器(依赖 libtcnative-1 与 OpenSSL),写在 Http11NioProtocol 下不生效,也不报错——最难查的一类“静默失效”。Tomcat 10.1.x 已移除旧式顶层 keystoreFile 属性。

写法 适用连接器 / 版本 关键属性 典型现象
顶层 keystoreFile / keystorePass Tomcat 8.0 及更早;10.1.x 已移除 keystoreFile 10.1 启动报属性无法识别
SSLHostConfig + <Certificate> Http11NioProtocol,8.5+ 推荐 certificateKeystoreFile / certificateKeystoreType 未取消注释则无监听
SSLCertificateFile / SSLCertificateKeyFile APR/tcnative(需 OpenSSL) SSLCertificateKeyFile NIO 下写了也不生效
<!-- Tomcat 9.0.x / 10.1.x 通用:conf/server.xml -->
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
            maxThreads="150" SSLEnabled="true">
    <SSLHostConfig>
        <Certificate certificateKeystoreFile="/opt/tomcat/conf/tomcat.p12"
                     certificateKeystorePassword="ChangeIt123"
                     certificateKeystoreType="PKCS12"
                     type="RSA" />
    </SSLHostConfig>
</Connector>

根因 4:只导入 leaf 证书,证书链不全。Java 客户端会抛 sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target;而 PC 浏览器会自行下载中间证书,显示正常,于是被误判成“已经装好了”。用上面的 keytool -list -v 看链长度即可分辨。

根因 5:别名或密码不一致。别名写错报 java.security.KeyStoreException: Cannot find key of alias tomcat9,密码写错报 java.security.UnrecoverableKeyException: Cannot recover key。以 keytool -list 输出的别名为准,配置项名是 certificateKeyAlias。

根因 6:网络层未放行。firewalld、iptables 与云厂商安全组默认都不放行 8443:

firewall-cmd --add-port=8443/tcp --permanent && firewall-cmd --reload
firewall-cmd --list-ports            # 确认输出含 8443/tcp
iptables -I INPUT -p tcp --dport 8443 -j ACCEPT   # iptables 场景
# 云主机还需在控制台安全组入方向放行 8443/TCP

排查顺序固定为:先本机 curl -k https://127.0.0.1:8443 证明 Tomcat 自身可用,再逐层向外验证防火墙与安全组。如果本机不通,问题必然在根因 1–5 之中,无需再动网络配置。

Tomcat SSL证书安装的完整步骤:从 keytool 生成 CSR 到 8443 生效的 7 步

下面按 7 步走完,Tomcat SSL证书安装 从密钥库生成到 8443 端口真正监听,每步都有可复制命令和判断成功的回显。环境基准:Tomcat 9.0.x / 10.1.x,JDK 8 及以上(Tomcat 10.1 要求 JDK 11+),keytool 随 JDK 分发,默认 -storetype 在 JDK 9+ 为 PKCS12。

第 1 步:生成 PKCS12 密钥库。CN 必须与要签发的域名完全一致,否则 CA 校验或浏览器比对会失败。-validity 365 只对自签阶段有效,CA 签发后以证书自身的 notAfter 为准。

# -dname 中的 CN 必须等于要签发的主域名;PKCS12 是 JDK 9+ 默认库格式
keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 
  -sigalg SHA256withRSA -storetype PKCS12 
  -keystore /opt/tomcat/conf/tomcat.p12 -validity 365 
  -dname "CN=www.example.com,OU=Ops,O=Example,L=Beijing,ST=Beijing,C=CN"
# 回显关键行:Generating 2,048 bit RSA key pair and self-signed certificate (SHA256withRSA)

第 2 步:导出 CSR。把 CSR 交给商业 CA,或用 Let’s Encrypt 的 --csr 模式(certbot 会跳过私钥生成,直接使用你的密钥):

keytool -certreq -alias tomcat -keystore /opt/tomcat/conf/tomcat.p12 
  -storetype PKCS12 -file tomcat.csr

# Let's Encrypt 路线,产物为 0000_chain.pem(中间 CA)与 0001_cert.pem(叶子证书)
certbot certonly --csr tomcat.csr --webroot -w /var/www/html -d www.example.com

第 3 步:核对证书。据 Let’s Encrypt 文档,签发后必须确认 SAN 覆盖全部域名(泛域名需 *.example.com),否则 HTTPS 握手会报 NET::ERR_CERT_COMMON_NAME_INVALID。

openssl x509 -in 0001_cert.pem -noout -subject -issuer -dates
# 关注:subject=CN = www.example.com;X509v3 Subject Alternative Name 含全部域名;notAfter

第 4 步:合并证书链。顺序必须是叶子在前、中间 CA 在后,反了会导致链验证失败(浏览器报 unable to get local issuer certificate)。

cat 0001_cert.pem 0000_chain.pem > fullchain.pem
openssl verify -CAfile 0000_chain.pem fullchain.pem   # 期望输出:fullchain.pem: OK

第 5 步:导入 keystore。先导入链,再导入 fullchain 覆盖自签的 alias。导入单张叶子而非 fullchain,是移动端与 Java 客户端握手失败的最常见原因。

# 若根/中间 CA 已在 JDK 的 cacerts 中,可跳过第一条
keytool -importcert -alias root -file 0000_chain.pem 
  -keystore tomcat.p12 -storetype PKCS12
keytool -importcert -alias tomcat -file fullchain.pem 
  -keystore tomcat.p12 -storetype PKCS12
# 成功回显:Certificate reply was installed in keystore

第 6 步:放置并授权。属主必须是运行 Tomcat 的用户,否则启动直接抛 java.io.FileNotFoundException: /opt/tomcat/conf/tomcat.p12 (Permission denied)。

install -m 640 -o tomcat -g tomcat tomcat.p12 /opt/tomcat/conf/

第 7 步:改 server.xml 并重启。Tomcat 9 与 10.1 的 Connector 写法一致,8443 为默认 HTTPS 端口:

<!-- conf/server.xml,放在 <Service> 内 -->
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true">
  <SSLHostConfig>
    <Certificate certificateKeystoreFile="conf/tomcat.p12"
                 certificateKeystorePassword="你的密码"
                 certificateKeystoreType="PKCS12" type="RSA"/>
  </SSLHostConfig>
</Connector>
systemctl restart tomcat
tail -f logs/catalina.out   # 出现 Starting ProtocolHandler ["https-jsse-nio-8443"] 即配置层通过
curl -I https://www.example.com:8443/   # 应返回 HTTP/1.1 200 或 302

若启动报 java.io.IOException: keystore password was incorrect,多为 PKCS12 库密码与 key 密码不一致;PKCS12 不支持 key 密码与库密码分离,需用同一口令重新生成。

环节 常见错误做法 正确做法 失败表现
链顺序 中间 CA 在前 leaf → 中间 CA unable to get local issuer certificate
导入内容 只导入叶子证书 导入 fullchain.pem Android/Java 客户端握手失败
文件属主 root:root tomcat:tomcat 640 FileNotFoundException (Permission denied)
密钥库格式 JKS 混用 PKCS12(JDK 9+ 默认) keystore password was incorrect

Tomcat SSL证书安装时 server.xml 怎么写?Tomcat 9.0.x 与 10.1.x 可直接复制的配置

直接回答:Tomcat 9.0.x 和 10.1.x 的正确写法是把证书信息放进嵌套的 <SSLHostConfig> 与 <Certificate>,而不是把 keystoreFile / keystorePass 写在 <Connector> 上。后者是 Tomcat 8.5 及更早时代的属性,在 9.0.x 上仍能启动但已被 Apache Tomcat 官方配置文档标注为 deprecated,在 10.1.x 上继续照抄 2015 年前后的教程是 tomcat ssl证书安装 失败率最高的原因。另外注意 JVM 门槛:9.0.x 要求 Java 8+,10.1.x 要求 Java 11+(这也是 TLS 1.3 能真正生效的前提,Java 8 的 JSSE 不支持 TLS 1.3)。

把下面这段放进 conf/server.xml 的 <Service name=”Catalina”> 内部,与 8080 的 Connector 并列:

<!-- conf/server.xml:Tomcat 9.0.x / 10.1.x 推荐写法 -->
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200" acceptCount="100" connectionTimeout="20000"
           SSLEnabled="true" server=" ">
  <!-- sslEnabledProtocols:只留 TLS1.2/1.3;Java 8 环境请删掉 TLSv1.3 -->
  <SSLHostConfig sslProtocol="TLS"
                  sslEnabledProtocols="TLSv1.2,TLSv1.3"
                  ciphers="TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,ECDHE-RSA-AES128-GCM-SHA256">
    <!-- ${catalina.base} 指向 CATALINA_BASE,systemd 部署时与 CATALINA_HOME 常不同 -->
    <Certificate certificateKeystoreFile="${catalina.base}/conf/tomcat.p12"
                 certificateKeystoreType="PKCS12"
                 certificateKeystorePassword="你的密码"
                 type="RSA" />
  </SSLHostConfig>
</Connector>

为什么必须用嵌套结构?因为 <SSLHostConfig> 是 SNI 的载体:一个 Connector 下可以挂多个 SSLHostConfig(每个带自己的 hostName 与 Certificate),实现同一 8443 端口多域名多证书;旧式 Connector 属性只能绑定单张证书。同时 ciphers 支持 JSSE 与 OpenSSL 两种语法,Tomcat 会自动转换,所以 ECDHE-RSA-AES128-GCM-SHA256 这种 OpenSSL 写法可以直接用(据 Apache Tomcat HTTP Connector 配置参考)。

配置项 9.0.x / 10.1.x 推荐(嵌套元素) 8.5 及更早旧写法
keystore 路径 certificateKeystoreFile keystoreFile
类型 certificateKeystoreType=”PKCS12″ keystoreType=”JKS”
密码 certificateKeystorePassword keystorePass
别名 certificateKeyAlias keyAlias
协议 / 套件 SSLHostConfig 的 sslEnabledProtocols、ciphers Connector 同名属性
SNI 多证书 支持(多个 SSLHostConfig) 不支持

强制 HTTP 跳 8443 不需要 RewriteValve:在 conf/web.xml 的 </web-app> 之前插入 security-constraint 即可,Tomcat 会返回 302。

<!-- conf/web.xml 末尾,</web-app> 之前 -->
<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,默认值是 443 而不是 8443 -->
<!-- <Connector port="8080" protocol="HTTP/1.1" redirectPort="8443" /> -->

性能参数别照抄默认值:connectionTimeout 默认 60000 ms(示例 20000 更适合公网短连接)、maxThreads 默认 200、acceptCount 默认 100。开启 compression=”on” 并把 compressibleMimeType 覆盖 text/html,text/xml,text/css,application/json,通常能把首屏传输量压掉 30%–60%,比换硬件便宜得多。

HSTS 不是 Tomcat 的内置能力(RFC 6797 定义的是响应头 Strict-Transport-Security: max-age=31536000; includeSubDomains),要么在应用过滤器里加,要么在前置 Nginx 统一加;同时用 server=” ” 抹掉 Server 响应头里的版本号,减少指纹暴露。做完 tomcat ssl证书安装 后按下面三条验证:

# 1) 确认 Connector 已启动(Tomcat 9.0.x 日志)
grep -i "Starting ProtocolHandler" logs/catalina.out
# 2) 只走 TLS1.3 握手,看协商结果
openssl s_client -connect 127.0.0.1:8443 -servername example.com -tls1_3 </dev/null | grep -E "Protocol|Cipher"
# 3) 确认 8080 被 302 到 8443
curl -sI http://127.0.0.1:8080/ | head -3

两个高频报错:java.io.IOException: Keystore was tampered with, or password was incorrect —— certificateKeystorePassword 与 keytool 生成时的 -storepass 不一致;java.lang.IllegalArgumentException: …/conf/tomcat.p12 (No such file or directory) —— ${catalina.base} 解析到了 CATALINA_BASE,而你把 p12 放在了 CATALINA_HOME 下。配置套件时可对照 Mozilla Server Side TLS 的 intermediate 建议,证书链则按 Let’s Encrypt 文档要求把中间证书一并导入 PKCS12。

Tomcat SSL证书安装方案对比:JSSE、APR/tcnative 与 Nginx 前置怎么选

在动手改 server.xml 之前,先要确定用哪种方式终止 TLS。Tomcat 9.0.x 与 10.1.x(Apache Tomcat 官方在 2024 年仍在维护这两个分支,10.1.x 要求 Java 11+)支持三条主流路线:JSSE(JDK 自带实现,配合 keytool 与 PKCS12)、APR/tcnative(调用 OpenSSL 的本地库)、以及 Nginx 反向代理前置终止。三者的差异不只在于配置文件怎么写,还决定了后续续期、OCSP、TLS 1.3 的可用性。

对比项 JSSE(keytool + PKCS12) APR/tcnative(OpenSSL) Nginx 反向代理
证书文件格式 .p12 / .jks .pem + .key .pem + .key
配置位置 server.xml 的 SSLHostConfig / Certificate server.xml 的 SSLCertificateFile 等属性 nginx.conf 的 ssl_certificate
是否需装额外库 不需要,JDK 自带 需 libtcnative-1 与 OpenSSL 1.1.1+ 不需要
TLS 1.3 支持 JDK 11+ 默认支持 取决于 tcnative 版本(1.2.x 起) OpenSSL 1.1.1+ 支持
OCSP Stapling 不支持 支持 SSLUseStapling 支持 ssl_stapling
证书续期方式 重新导入并重启 Tomcat 重启 Tomcat nginx -s reload 即可
典型场景 单机中小站点、内网应用 高并发、需要 OCSP 多实例、统一证书入口

选型建议一:单台 Tomcat、日 PV 在 10 万以内,直接用 JSSE + PKCS12。 零额外依赖,升级 JDK 也不会破坏 OpenSSL 链接。据 Apache Tomcat 9 配置文档,protocol="org.apache.coyote.http11.Http11NioProtocol" 下只要在 SSLHostConfig 里给出 certificateKeystoreFile、certificateKeystorePassword、certificateKeystoreType="PKCS12" 即可,SSLEnabled 默认 false,必须显式写成 true。这是 Tomcat SSL证书安装最省事的路径,也是本系列后续实操章节采用的方式。

<!-- Tomcat 9.0.x / 10.1.x:JSSE + PKCS12,端口 8443 -->
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200" SSLEnabled="true">   <!-- SSLEnabled 默认 false,必须显式开启 -->
  <SSLHostConfig>
    <Certificate certificateKeystoreFile="conf/domain.p12"
                 certificateKeystoreType="PKCS12"          <!-- 默认 JKS,PKCS12 需显式声明 -->
                 certificateKeystorePassword="changeit" />
  </SSLHostConfig>
</Connector>

选型建议二:需要 OCSP Stapling 或已有 OpenSSL 证书流水线(certbot 直接产出 pem)。 可安装 tomcat-native 走 APR 连接器,但必须确认 tcnative 版本与 OpenSSL 大版本匹配,否则启动即报 java.lang.UnsatisfiedLinkError: org.apache.tomcat.jni.SSLContext.make。可用下面两条命令自检,据 Tomcat 官方 Native 文档,1.2.x 及以上才带 TLS 1.3:

# 1) 查看 JDK 能否加载 tcnative(版本号会直接打印)
java -cp $CATALINA_HOME/bin/tomcat-juli.jar:$CATALINA_HOME/lib/* 
     org.apache.tomcat.jni.Version   # 无输出或报 UnsatisfiedLinkError 即为未装好

# 2) 核对 OpenSSL 大版本与 libtcnative 是否同一来源
openssl version -a | head -1   # 期望 OpenSSL 1.1.1 或 3.x
ldd $CATALINA_HOME/lib/libtcnative-1.so | grep -i ssl

选型建议三:多台 Tomcat 或多应用共用一张证书,优先 Nginx 前置终止 TLS。 Tomcat 只监听 127.0.0.1:8080,证书续期只改一处、nginx -s reload 秒级生效,避免每台机器重复做一次 Tomcat SSL证书安装。配置 proxy_pass http://127.0.0.1:8080; 时别忘了 proxy_set_header X-Forwarded-Proto https;,否则 Tomcat 里的 request.isSecure() 会返回 false,重定向逻辑容易出错。

成本参考:商业 DV 单域名证书约 100–500 元/年,OV 约 800–3000 元/年,通配符 DV 约 800–2000 元/年;Let’s Encrypt 免费但证书有效期 90 天(据 Let’s Encrypt 官方文档),需评估 certbot 自动化与 reload 钩子的运维成本,这部分开销往往比证书本身更值得算清楚。

Tomcat SSL证书安装常见报错:6 条真实异常信息与对应处理

下面这 6 条异常全部来自 Tomcat 9.0.x / 10.1.x 的 logs/catalina.out 与浏览器控制台。先给一张速查表,再逐条给出可直接复制的验证命令——把“定位”和“修复”分开,能避免改配置靠猜。

报错关键词 根因 一条定位命令
Invalid keystore format 文件不是 keystore,或 storetype 与文件不符 file tomcat.p12
Cannot recover key storepass 与 keypass 不一致 keytool -list -keystore tomcat.p12
No subject alternative names 证书缺 SAN 扩展 openssl x509 -noout -text
PKIX path building failed 服务端证书链不全 keytool -list -v 看链长
Address already in use 8443/8005 被占用 ss -lntp | grep 8443
ERR_SSL_VERSION_OR_CIPHER_MISMATCH 协议或套件与客户端无交集 nmap --script ssl-enum-ciphers

1. java.io.IOException: Invalid keystore format,是不是证书文件坏了?

不是坏,是“认错对象”。Tomcat 的 certificateKeystoreType 默认值是 JKS(见 Tomcat 9 官方 SSL How-To),而你放进 conf/ 的往往是 PKCS12;PEM 文本证书更是根本不能被当成 keystore 打开。

# 期望输出 "data"(二进制 keystore);若输出 "ASCII text" 说明拿到的是 PEM
file /opt/tomcat/conf/tomcat.p12

# 只有 PEM(fullchain.pem + privkey.pem)时,先合成 PKCS12 并自检
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem 
  -name tomcat -out /opt/tomcat/conf/tomcat.p12 -passout pass:ChangeIt
keytool -list -keystore /opt/tomcat/conf/tomcat.p12 -storepass ChangeIt

对应的 server.xml 片段(Tomcat 9.0.x 与 10.1.x 通用,9.0 起推荐 <SSLHostConfig> 嵌套写法):

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true" maxThreads="150" scheme="https" secure="true">
  <SSLHostConfig certificateVerification="none">
    <Certificate certificateKeystoreFile="conf/tomcat.p12"
                 certificateKeystoreType="PKCS12"      <!-- 关键:默认是 JKS -->
                 certificateKeystorePassword="ChangeIt"
                 type="RSA" />
  </SSLHostConfig>
</Connector>

2. UnrecoverableKeyException: Cannot recover key 怎么排查?

密码对不上,而且是两层:certificateKeystorePassword 与文件真实 storepass 不符;或 PKCS12 内部的 keypass ≠ storepass。SunJSSE 实现要求 PKCS12 的这两个密码一致,历史上不一致就会抛这条异常。用 keytool -importkeystore 把两者强行归一:

keytool -importkeystore 
  -srckeystore old.p12 -srcstoretype PKCS12 -srcstorepass 旧密码 
  -destkeystore tomcat.p12 -deststoretype PKCS12 
  -deststorepass ChangeIt -destkeypass ChangeIt   # 两者必须相同

3. java.security.cert.CertificateException: No subject alternative names present

证书只有 CN 没有 SAN。据 RFC 6125 与 CA/Browser Forum Baseline Requirements,CN 已不再作为身份回退;Java 8u181+ 同样取消了回退。用 certbot 重签时把所有域名一次传全:

openssl x509 -in fullchain.pem -noout -text | grep -A1 "Subject Alternative Name"
certbot certonly --webroot -w /var/www/html 
  -d example.com -d www.example.com          # 泛域名 * 不覆盖裸域,需分别列出

4. javax.net.ssl.SSLHandshakeException: PKIX path building failed

典型是只装了 cert.pem 没装 fullchain.pem,中间 CA 缺失。链长应为 3(叶证书 + 中间 CA + 根):

keytool -list -v -keystore conf/tomcat.p12 -storepass ChangeIt | grep "Certificate chain length"
openssl s_client -connect example.com:8443 -servername example.com -showcerts </dev/null | grep -c "BEGIN CERTIFICATE"

若链在服务端完整而仍报错,则是客户端信任库缺根 CA,用 keytool -importcert -alias myca -file ca.crt -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit 补入。

5. java.net.BindException: Address already in use

ss -lntp | grep -E '8443|8005'          # Linux
netstat -ano | findstr :8443            # Windows

除 8443 本身冲突外,<Server port="8005"> 的 shutdown 端口被占同样会让整个实例起不来,报错行却出现在 Connector 之后,容易误判。改端口时记得同步安全组与反代 proxy_pass。

6. 浏览器报 ERR_SSL_VERSION_OR_CIPHER_MISMATCH

服务端协议集与客户端无交集。显式收敛协议并复核:

<SSLHostConfig protocols="TLSv1.2,TLSv1.3">   <!-- 删掉 TLSv1/TLSv1.1 -->
  <Certificate ... />
</SSLHostConfig>

nmap --script ssl-enum-ciphers -p 8443 example.com

套件清单建议直接取 Mozilla SSL Configuration Generator 的 “Intermediate” 档,删除 3DES、RC4、CBC 系列。TLSv1.3 需 Java 11+,故 Tomcat 9.0.x 跑在 Java 8 上只能到 TLSv1.2;Tomcat 10.1.x 要求 Java 11+,天然支持。改完 server.xml 必须重启(Connector 不支持热加载),并在 catalina.out 中确认出现 Initializing ProtocolHandler ["https-openssl-nio-8443"] 与 Server startup in ... ms。

怎么确认 Tomcat SSL证书安装成功?5 条命令逐项验证

重启 Tomcat 后 catalina.out 打出 Server startup in xxx ms 并不等于 HTTPS 真的可用——端口监听成功、keystore 加载成功、证书链完整是三件独立的事。下面 5 条命令按「证书链 → HTTP 行为 → keystore 内容 → 协议套件 → 应用层」逐层验证,任何一条失败都能定位到具体环节。验证前请确保 Connector port=”8443″ protocol=”org.apache.coyote.http11.Http11NioProtocol” SSLEnabled=”true” 已配置并重启过 Tomcat 9.0.x / 10.1.x。

第 1 条:证书链与有效期。这是最能暴露问题的一条,注意必须带 -servername 触发 SNI,否则多域名场景下会拿到默认证书(据 OpenSSL 文档,s_client 在不传该参数时不会发送 SNI 扩展):

# 取出服务端实际下发的叶子证书,打印主体/签发者/有效期
openssl s_client -connect www.example.com:8443 
  -servername www.example.com -showcerts /dev/null 
  | openssl x509 -noout -subject -issuer -dates

# 期望输出(Let's Encrypt 示例)
# subject=CN = www.example.com
# issuer=C = US, O = Let's Encrypt, CN = R3
# notBefore=Mar  1 00:00:00 2025 GMT
# notAfter=May 30 23:59:59 2025 GMT

subject 必须是你签发的域名而非 localhost,notAfter 必须与证书文件一致;若 issuer 显示为自签的 CN=Tomcat,说明 Connector 加载的还是默认自签 keystore。

第 2 条:HTTP 行为与协商协议。curl 7.52+ 支持 –tlsv1.3(即最低版本强制 1.3):

# -I 只取响应头;-v 观察握手细节;-m 10 防止卡死
curl -I https://www.example.com:8443 --tlsv1.3 -m 10
curl -v https://www.example.com:8443 -m 10 2>&1 | grep -E "SSL connection|subject:"

# 期望:HTTP/1.1 200 或 302
# 期望:SSL connection using TLSv1.3 / TLS_AES_128_GCM_SHA256

返回 curl: (35) error:0A000410:SSL routines::sslv3 alert handshake failure 通常意味着 Connector 的 sslEnabledProtocols 未包含 TLSv1.3,或 JSSE 未启用。

第 3 条:keystore 内容自检。直接在服务器上读 PKCS12 文件,确认别名与链长度:

# -v 输出完整证书链;PKCS12 需显式指定 -storetype
keytool -list -v -keystore /opt/tomcat/conf/tomcat.p12 -storetype PKCS12

# 关键字段
# Alias name: tomcat
# Certificate chain length: 3
# Owner: CN=www.example.com
# SubjectAlternativeName: DNS:www.example.com, DNS:example.com

据 Oracle keytool 文档,chain length 为 1 表示只导入了叶子证书、缺中间 CA,浏览器和 curl 都会报 unable to get local issuer certificate;SAN 未覆盖的域名即使能打开也会报 No name matching。

第 4 条:协议与套件枚举。从外部视角扫描,比本机 curl 更接近真实用户:

# nmap 7.x + ssl-enum-ciphers 脚本
nmap --script ssl-enum-ciphers -p 8443 www.example.com

# 输出中应同时存在 TLSv1.2 与 TLSv1.3 两段,
# 且 TLSv1.2 段落里不应出现 TLS_RSA_WITH_3DES_EDE_CBC_SHA(3DES 已被 RFC 8422 列为不建议)

若出现 3DES/RC4 套件,说明未在 Connector 上用 ciphers 属性收窄;Tomcat 9.0.x 与 10.1.x 的 sslEnabledProtocols 默认值均为 TLSv1.2,TLSv1.3,不需要再手工加 TLSv1.0。

第 5 条:应用层与日志。浏览器访问 https://域名:8443/,确认页面资源无混合内容(F12 → Console 无 Mixed Content 警告),F12 → Security → View certificate 的证书路径为三级(叶子 → 中间 → 根)。同时看日志:

# 确认协议处理器已启动,且无握手异常堆积
grep -i -E "ssl|https-jsse" /opt/tomcat/logs/catalina.out | tail -20

# 正常:Starting ProtocolHandler ["https-jsse-nio-8443"]
# 异常:javax.net.ssl.SSLHandshakeException: PKIX path building failed
现象 根因 处置
s_client 的 subject 为 localhost 未传 -servername 或 keystore 未替换 补 SNI 参数重测 / 重做导入
Certificate chain length: 1 只导入叶子证书 用 fullchain 重新生成 PKCS12
curl 报 unable to get local issuer 中间 CA 缺失 同上,链必须补齐
日志刷 PKIX path building failed 客户端信任库缺根证书(非服务端问题) 客户端导入 ISRG Root X1

五条全绿后再跑一次 Qualys SSL Labs,目标 B 级以上;低于 B 通常是套件过弱或未启用 TLSv1.3。把这五条写成一个 shell 脚本挂到监控里,证书到期前 30 天即可自动告警。

Tomcat SSL证书安装后怎么续期?90 天免费证书的自动化与注意事项

90 天一到,8443 端口上的证书过期,用户会看到 NET::ERR_CERT_DATE_INVALID。这一节把”续期”这条链路拆成可复制的命令,并说明哪些文件必须留着、哪些绝不能重建。

为什么不能重新生成密钥库?据 Let’s Encrypt 官方文档《Challenge Types》与《Renewing certificates》,续期只更换证书链,私钥保持不变是设计前提。Tomcat 的 tomcat.p12 里同时装着私钥和证书,如果你在续期时用 keytool -genkeypair 重建密钥库,SPKI 指纹变化,所有做过证书固定的客户端(移动 App、部分 MQTT 网关)会直接握手失败。因此正确做法是:首次生成的 tomcat.p12 和原始 tomcat.key 永久保留,续期只用 -importcert 替换别名下的证书链。

为什么 certbot renew 不管你的证书?certbot 默认只扫描 /etc/letsencrypt/live/ 与 /etc/letsencrypt/renewal/ 下的 lineage(来源:certbot 官方文档《Renewing certificates》)。用 --csr 方式签发时,certbot 不写 renewal 配置,所以 certbot renew 会输出 No renewals were attempted.,必须自己写脚本。

下面是可整段复制的续期脚本,适配 Tomcat 9.0.x / 10.1.x,全程约 20–40 秒:

#!/usr/bin/env bash
# /usr/local/bin/tomcat-renew.sh  chmod 700
set -euo pipefail          # 任一命令失败立即退出,避免半成品状态

DOMAIN="www.example.com"
CSR="/opt/certs/tomcat.csr"          # 首次用 keytool -certreq 生成,保留不动
KEYSTORE="/opt/tomcat/conf/tomcat.p12"
PASS="changeit"                      # 与 server.xml 中 keystorePass 一致

# 1) 用原 CSR 重新签发(--csr 模式不会写 renewal 配置,故不用 certbot renew)
certbot certonly --csr "$CSR" --webroot -w /var/www/html 
  -d "$DOMAIN" --cert-path /opt/certs/cert.pem 
  --chain-path /opt/certs/chain.pem --fullchain-path /opt/certs/fullchain.pem 
  --non-interactive --agree-tos

# 2) 只替换证书链,不碰私钥
keytool -importcert -alias tomcat -file /opt/certs/fullchain.pem 
  -keystore "$KEYSTORE" -storetype PKCS12 -storepass "$PASS" -noprompt

# 3) 重启生效
systemctl restart tomcat

定时执行建议放在凌晨低峰,并让失败可见:

# crontab -e
20 3 * * * /usr/local/bin/tomcat-renew.sh >> /var/log/tomcat-renew.log 2>&1 || 
  echo "tomcat renew failed" | mail -s "SSL ALERT" ops@example.com

监控侧不要只看脚本退出码,要读真实有效期。OpenSSL 1.1.1 及以上可这样取值:

echo | openssl s_client -connect www.example.com:8443 -servername www.example.com 2>/dev/null 
  | openssl x509 -noout -enddate
# 输出示例:notAfter=Jun 18 03:20:00 2025 GMT

剩余天数小于 15 天即触发人工介入,这个阈值比 Let’s Encrypt 建议的”剩余 30 天续期”更靠后,留出了排查 DNS、80 端口 webroot 可达性的缓冲。

不想承担重启风险怎么办?多实例环境下更常见的做法是 Nginx 前置终止 TLS,Tomcat 只跑 HTTP 8080,续期后仅 nginx -s reload,Tomcat 进程完全不动。两种方案对比:

方案 续期动作 服务中断 适用场景
Tomcat 直接开 8443 keytool 导入 + restart tomcat 5–20 秒,会话丢失 单实例、内网小站
Nginx 前置 + Tomcat 8080 nginx -s reload 无(平滑重载) 多实例、需要会话保持
Tomcat 开 8443 但用 JKS 热替换 不重启,靠 reloadable 配置 不可靠,不推荐 —

如果坚持让 Tomcat 自己终止 TLS,注意 server.xml 里的 keystoreFile 必须指向同一个 tomcat.p12,keystoreType="PKCS12" 在 Tomcat 9.0.x 与 10.1.x 中均为默认支持(10.1.x 要求 Java 11+)。证书链不全时浏览器会报 unable to get local issuer certificate,务必导入 fullchain.pem 而非 cert.pem——这一点与 Let’s Encrypt 文档中”fullchain 包含中间证书”的说明一致。至此,tomcat ssl证书安装 的运维闭环才算完整:签发、导入、续期、监控四步缺一不可。

必须重启。JSSE 连接器在启动时把 keystore 读入内存并初始化 SSLContext,运行期没有 reload 接口,改完 server.xml 或替换 tomcat.p12 后都要 systemctl restart tomcat。若业务不能中断,可先做 Nginx 前置终止 TLS,Tomcat 只监听 127.0.0.1:8080,续期时只需 nginx -s reload。

不能直接通用。Nginx 用的是 PEM 文本格式的 fullchain.pem + privkey.pem;Tomcat 的 JSSE 连接器需要 JKS 或 PKCS12 二进制 keystore,必须先用 keytool -importcert 把证书链导入。同一张 CA 签发的证书可以同时用于两者,只是需要准备两份不同格式的文件。

说明 certificateKeystoreFile 指向的文件不是合法 keystore。先用 file tomcat.p12 确认类型,再检查是否漏写 certificateKeystoreType="PKCS12",Tomcat 默认按 JKS 解析。如果手上只有 pem,用 keytool -importcert -alias tomcat -file fullchain.pem -keystore tomcat.p12 -storetype PKCS12 导入后再指向新文件。

keystoreFile / keystorePass 是 Tomcat 8.5 之前的顶层属性,Tomcat 10.1 已改为 SSLHostConfig 嵌套 Certificate 的写法,旧属性被忽略且不报错,表现为端口起来了但握手失败。应改用 certificateKeystoreFile、certificateKeystorePassword、certificateKeystoreType 三个属性。

可以。把同一个 tomcat.p12 复制到各节点的 conf 目录,保证别名(alias)与密码一致,server.xml 配置相同即可。注意单域名证书只覆盖该域名,多域名需用 SAN 证书或通配符证书,且私钥分发要走加密通道并限制文件权限为 640。

对大多数站点够用,Let's Encrypt 签发的是 DV 证书,浏览器兼容性与商业 DV 一致,有效期 90 天。代价是必须做自动化续期:用 certbot –csr 签发后 keytool 重新导入并重启 Tomcat,若没有自动化能力,建议选 1 年期的商业 DV 证书降低运维频率。

大概率是网络层未放行。依次检查云安全组入方向是否开放 8443/tcp、firewall-cmd –list-ports 是否包含 8443/tcp、iptables -L -n 是否有 DROP 规则。另外确认 Connector 的 address 属性没有写成 127.0.0.1,否则只监听回环地址,外部自然连不上。


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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