Tomcat 配置 SSL 证书实战:从 keystore 转换到 8443 端口 HTTPS 生效
Tomcat 配置 SSL 证书的核心做法是:把站点证书与私钥合成 PKCS12 或 JKS 密钥库,在 conf/server.xml 的 8443 Connector 中用 SSLHostConfig 指定 certificateKeystoreFile、certificateKeystorePassword、certificateKeystoreType 三个参数,重启后 https://域名:8443 生效。 转换命令:openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out tomcat.p12 -name tomcat -passout pass:ChangeIt123,其中 -name 的别名必须与 certificateKeyAlias(默认 tomcat)一致。 Tomcat 8.5.0 及以上支持直接读取 PEM:使用 certificateFile 加 certificateKeyFile,可省掉格式转换这一步,适合复用 Let's Encrypt 的 live 目录。 密钥库必须包含完整证书链(keytool -list -v 显示 Certificate chain length: 3),否则 Android 7 以下与 Java 客户端会报 PKIX path building failed。 验证命令:openssl s_client -connect www.example.com:8443 -servername www.example.com -showcerts 应返回 Verify return code: 0 (ok) 且证书链不少于 2 张。
一、Tomcat 配了证书为什么还是打不开?先看 5 个根本原因
问:证书买了、也导入了,为什么浏览器访问 https://IP:8443 还是打不开?先别怀疑证书本身。绝大多数“tomcat 配置ssl证书后不生效”的案例,根因都落在下面 5 个环节,且全部与证书签发质量无关。
原因一:8443 端口的 Connector 出厂就是注释掉的。Tomcat 9.0.x 与 10.1.x 的 conf/server.xml 默认只启用 port="8080",那段 8443 的 SSL Connector 被整块 <!-- --> 包住(两个版本出厂配置一致)。不取消注释,访问 8443 得到的是 TCP 层 Connection refused,浏览器连 TLS ClientHello 都发不出去。
<!-- conf/server.xml 出厂状态:整段被注释 -->
<!--
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true">
<SSLHostConfig>
<Certificate certificateKeystoreFile="conf/localhost-rsa.jks" type="RSA" />
</SSLHostConfig>
</Connector>
-->
<!-- 启用后的最小可用写法(Tomcat 8.5+ / 9 / 10.1 通用) -->
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true" scheme="https" secure="true">
<SSLHostConfig protocols="TLSv1.2+TLSv1.3">
<Certificate certificateKeystoreFile="conf/tomcat.p12"
certificateKeystorePassword="changeit"
certificateKeystoreType="PKCS12" type="RSA" />
</SSLHostConfig>
</Connector>
原因二:Tomcat 的 TLS 由 JVM 的 JSSE 实现,不是 OpenSSL。它不认 Nginx 那套“ssl_certificate 指证书文件 + ssl_certificate_key 指私钥文件”的路径,默认只从 KeyStore(JKS/PKCS12)取材料。据 Apache Tomcat 8.5 SSL 配置文档,8.5.0 之前必须用 KeyStore,8.5.0 起才新增直接读取 PEM 的能力:
<!-- Tomcat 8.5.0+:跳过 keytool 转换,直接读 PEM -->
<Certificate certificateFile="conf/fullchain.pem"
certificateKeyFile="conf/privkey.pem" type="RSA" />
原因三:证书链不完整,这是最高频故障。只导入域名证书、漏掉中间 CA,Chrome 会靠 AIA 自动补链而显示正常,但 Android 7 以下、Java HttpClient、部分小程序 WebView 会直接报 unable to get local issuer certificate。数一下服务端返回几张证书即可确认:
openssl s_client -connect example.com:8443 -showcerts </dev/null 2>/dev/null
| grep -c "BEGIN CERTIFICATE"
# 输出 1 → 只有叶子证书,链断了;正常应为 2(叶子 + 中间 CA)
原因四:为了 URL 干净改成 443,却撞上端口权限。8443 属非特权端口,任何用户可绑定;而 Linux 下非 root 进程绑定 <1024 端口会抛 java.net.BindException: Permission denied。两条出路:
# 方案 A:给 java 可执行文件授予绑定特权端口的能力
sudo setcap 'cap_net_bind_service=+ep' /usr/lib/jvm/java-17-openjdk-amd64/bin/java
getcap /usr/lib/jvm/java-17-openjdk-amd64/bin/java
# 输出 .../bin/java cap_net_bind_service=ep
# 方案 B:保留 8443,用 iptables 把外部 443 重定向过来(仅对外部流量生效)
sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 8443
原因五:JDK 版本决定了协议上限。在 Connector 里写 protocols="TLSv1.2+TLSv1.3" 只是“声明意图”,JSSE 不支持时该协议会被静默忽略,不会报错:
| JDK 版本 | TLS 1.3 可用 | 说明 |
|---|---|---|
| 8u151 及更早 | 否 | 写了 TLSv1.3 也不生效,握手仍停在 1.2 |
| 8u261+ | 是 | 需显式声明;8u291 起默认禁用 TLS 1.0/1.1 |
| 11.0.3+ | 是 | TLSv1.2/1.3 默认启用,Tomcat 10.1 最低要求 JDK 11 |
| 17 / 21 LTS | 是 | 推荐组合,JSSE 默认策略最严格 |
按“端口是否监听 → 认证材料类型 → 链是否完整 → 端口权限 → JDK 能力”的顺序逐项核对,基本能在几分钟内把“tomcat 配置ssl证书不生效”压缩到某一条具体原因上;后续小节会分别展开 keytool/PKCS12 转换与 8443 Connector 的完整落地步骤。
二、Tomcat 配置 SSL 证书的完整实操步骤(8 步)
下面这 8 步是一条可以完整走通的路径:每一步都给出可直接粘贴的命令,以及”怎么判断这一步真的成功了”。很多人 tomcat 配置ssl证书 失败,并非卡在证书本身,而是卡在第 5 步的证书链长度或第 7 步的别名不一致上——这两处出错时日志给的提示都极其含糊。
-
环境确认:JDK 与 Tomcat 版本必须先对上。先记录 JDK 版本,再确认 Tomcat 版本,两者不匹配时启动会直接抛
UnsupportedClassVersionError,根本走不到 SSL 初始化。# 记录 JDK 版本,建议 11.0.21 或 17.0.x LTS java -version # 例:openjdk version "17.0.9" 2023-10-17 # 确认 Tomcat 版本,输出应为 Server version: Apache Tomcat/9.0.85 $CATALINA_HOME/bin/version.shTomcat 版本 最低 JDK 建议 JDK 说明 9.0.x Java 8 11 / 17 当前维护主力,Servlet 4.0 10.1.x Java 11 17 Jakarta EE 10,包名 javax → jakarta 11.0.x Java 17 17 / 21 Jakarta EE 11,不再支持 Java 11 据 Apache Tomcat 官方文档,10.1.x 要求 Java 11 及以上,11.0.x 要求 Java 17 及以上,用 JDK 8 跑 10.1 会在
catalina.out第一屏就报错退出。 -
生成私钥与 CSR。把私钥和密钥库放在同一文件里,后续所有步骤都以它为准:
keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -keystore tomcat.jks -storetype PKCS12 -validity 365 -dname "CN=www.example.com,OU=Ops,O=Example,L=Hangzhou,ST=Zhejiang,C=CN" # 导出证书签名请求 keytool -certreq -alias tomcat -keystore tomcat.jks -file tomcat.csr文件名叫
.jks只是历史习惯,-storetype PKCS12实际生成的是 PKCS12 容器(JDK 9 起 keystore 默认类型已改为 PKCS12)。RSA 2048 + SHA256withRSA 是当前主流 CA 的准入底线,2048 以下会被直接拒签。 -
提交 CSR 并取回证书,先本地验一遍链。CA 会返回域名证书
domain.crt和中间证书chain.crt,务必拼成完整链再导入:# 叶子证书在前、中间证书在后,顺序不可颠倒 cat domain.crt chain.crt > fullchain.pem # 必须输出 "fullchain.pem: OK" openssl verify -CAfile chain.pem fullchain.pem有效期方面,据 Let’s Encrypt 文档,其证书固定为 90 天并推荐自动化续期;商业 DV 证书常见 1 年(CA/Browser Forum 规定公开信任证书上限 398 天)。
-
合成 PKCS12 密钥库。Tomcat 不直接读 PEM,需要把 fullchain 与私钥打包:
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out tomcat.p12 -name tomcat -passout pass:ChangeIt123 # -name 的值必须与 server.xml 中 certificateKeyAlias 完全一致别名不一致是最常见的翻车点,Tomcat 启动时会抛
java.io.IOException: Alias name [tomcat] does not identify a key entry。 -
校验密钥库内容。这条命令的输出要逐行看:
keytool -list -v -keystore tomcat.p12 -storetype PKCS12 -storepass ChangeIt123Alias name: tomcat Entry type: PrivateKeyEntry <-- 必须是 PrivateKeyEntry Certificate chain length: 3 <-- 小于 2 说明中间证书没导进来 Certificate[1]: Owner: CN=www.example.com Valid from: ... until: ... <-- 核对有效期是否覆盖当前时间链长度只有 1 意味着只导入了叶子证书,Android 和部分 Java 客户端会报
unable to find valid certification path to requested target。 -
放置文件并收紧权限。密钥库等价于私钥,同机其他用户不应可读:
install -m 640 -o tomcat -g tomcat tomcat.p12 /opt/tomcat/conf/ssl/ # 校验:应为 -rw-r----- 1 tomcat tomcat ls -l /opt/tomcat/conf/ssl/tomcat.p12用 644 会让任何本地账户都能拷走私钥并离线解密流量,这是审计中最常见的扣分项。
-
备份并修改 server.xml。先备份再动手,改坏了能 30 秒回滚:
cp conf/server.xml conf/server.xml.bak.$(date +%F) # 然后编辑 8443 端口 Connector,关键属性如下: # SSLEnabled="true" 启用 TLS 握手 # scheme="https" 影响 sendRedirect 生成的绝对 URL # secure="true" 让 request.isSecure() 返回 true # keystoreType="PKCS12" 与第 4 步的容器格式一致 # certificateKeyAlias="tomcat" 与 openssl pkcs12 -name 一致这三个属性缺一不可:只写
SSLEnabled而漏掉scheme时,应用里response.sendRedirect()生成的地址仍会是http://,前端跳转后立刻掉回明文。完整的 Connector 片段见下一节。 -
重启并确认日志关键字。这一步是 tomcat 配置ssl证书 是否真正生效的唯一判据:
systemctl restart tomcat # 或 $CATALINA_HOME/bin/shutdown.sh && $CATALINA_HOME/bin/startup.sh # 出现该行且上下文无 SEVERE 才算成功 grep -n 'https-jsse-nio-8443' $CATALINA_HOME/logs/catalina.out # 期望:INFO [main] org.apache.catalina.core.StandardService.startInternal # Starting ProtocolHandler ["https-jsse-nio-8443"]单实例重启通常 5–15 秒。若日志里只有
http-nio-8080而没有https-jsse-nio-8443,说明 Connector 被注释掉或port属性写错;若出现SEVERE: Failed to initialize end point,则多半是密钥库路径或口令问题。
三、server.xml 与 keytool 命令示例:可直接复制的配置片段
把证书文件准备好只是第一步,真正让 8443 端口吐出 HTTPS 的是 conf/server.xml 里那个 Connector。下面给出的片段可直接粘贴,替换路径与密码即可运行在 Tomcat 9.0.x + Java 11 环境。
问:Tomcat 9.0.x 用 PKCS12 密钥库,8443 Connector 该怎么写?
<!-- conf/server.xml:把默认被注释的 8443 Connector 整段替换为下面内容 -->
<Connector port="8443"
protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="200"
SSLEnabled="true"
scheme="https"
secure="true">
<SSLHostConfig protocols="TLSv1.2+TLSv1.3" honorCipherOrder="true">
<!-- 密钥库由 keytool 或 openssl pkcs12 生成,别名必须与 certificateKeyAlias 一致 -->
<Certificate certificateKeystoreFile="/opt/tomcat/conf/ssl/tomcat.p12"
certificateKeystoreType="PKCS12"
certificateKeystorePassword="ChangeIt123"
certificateKeyAlias="tomcat"
type="RSA" />
</SSLHostConfig>
</Connector>
| 属性 | 默认值 | 说明与取值 |
|---|---|---|
port |
8080(HTTP 示例) | 8443 是 HTTPS 惯例端口;<1024 需 root 或 setcap 授权 |
protocol |
Http11NioProtocol |
Tomcat 9 默认 NIO;高并发可换 Http11Nio2Protocol |
maxThreads |
200 | 取值 1–20000 量级,实际按 CPU 核数×并发系数评估 |
SSLEnabled |
false | 必须显式 true,否则 8443 仍是明文 |
scheme / secure |
http / false | 置为 https/true 后 request.isSecure() 才返回 true,重定向逻辑依赖它 |
protocols |
由 JVM 决定 | 多个协议用 + 连接;Java 11 默认已含 TLSv1.3 |
honorCipherOrder |
false | true 表示由服务端决定套件顺序,配合 Mozilla 推荐的套件列表更安全 |
如果手上是 JKS,用 keytool 转 PKCS12(JDK 9 起 PKCS12 已是默认格式):
keytool -importkeystore -srckeystore tomcat.jks -srcstoretype JKS
-destkeystore tomcat.p12 -deststoretype PKCS12
-srcalias tomcat -destalias tomcat -deststorepass 'ChangeIt123'
# 若已有 PEM 证书链,也可直接生成:
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem
-out tomcat.p12 -name tomcat -passout pass:'ChangeIt123'
问:能跳过格式转换吗?可以。据 Tomcat 8.5 起的官方文档,<Certificate> 支持直接读取 PEM,把上面那行换成:
<Certificate certificateFile="/etc/letsencrypt/live/www.example.com/fullchain.pem"
certificateKeyFile="/etc/letsencrypt/live/www.example.com/privkey.pem"
type="RSA" />
<!-- 注意:certificateFile 必须是 fullchain(站点证书+中间证书),
只放 cert.pem 会导致部分客户端报 unable to get local issuer certificate -->
问:如何强制 8080 跳 8443?在 conf/web.xml 的 </web-app> 之前加入安全约束,Tomcat 会自动返回 302:
<security-constraint>
<web-resource-collection>
<web-resource-name>HTTPSOnly</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
问:HSTS 怎么开?conf/web.xml 里默认注释掉的 HttpHeaderSecurityFilter 需解注释,并补两个初始化参数:hstsEnabled=true(默认 false)、hstsMaxAgeSeconds=31536000(默认 0,即不下发)。全站 HTTPS 未落实前不要开,浏览器缓存一年内无法回退。
问:密码不想进 Git?server.xml 写 certificateKeystorePassword="${TOMCAT_KS_PASS}",在 bin/setenv.sh 中 export TOMCAT_KS_PASS='ChangeIt123',Tomcat 启动时会做系统属性与同名环境变量替换。
问:一定要 8443 吗?想用 443 就改 port="443" 并授权:
sudo setcap 'cap_net_bind_service=+ep' /usr/lib/jvm/java-11-openjdk-amd64/bin/java
# 升级 JDK 后 capability 会丢失,需重新执行;容器里则直接 -p 443:8443 映射,无需改端口
启动失败时先看这三条典型报错:java.io.IOException: Keystore was tampered with, or password was incorrect(密码或别名不符)、java.net.BindException: Address already in use(端口被占)、SSLHostConfig[certificateKeystoreFile] ... was not found(路径相对 $CATALINA_BASE 解析,建议写绝对路径)。
四、方案选型对比:PKCS12 直连、PEM 直读、Nginx 卸载怎么选
先问一句:证书到底该配在 Tomcat 还是 Nginx,差别真有那么大?
差别不小——它决定了你每次续期要动几个文件、要不要重启 JVM、以及应用里 request.getScheme() 拿到的是 http 还是 https。三条主流路径的硬指标对照如下(参数名与默认值以 Tomcat 8.5/9.0/10.1 官方 HTTP Connector 文档为准):
| 对比维度 | PKCS12 密钥库直连 8443 | PEM 直读 8443 | Nginx 卸载 TLS + 反代 8080 |
|---|---|---|---|
| 证书格式 | 单文件 .p12(含私钥+证书链) |
fullchain.pem + privkey.pem |
仅 Nginx 侧 PEM,Tomcat 无证书 |
| 最低版本 | Tomcat 全版本(6/7/8.5/9/10 均可) | Tomcat 8.5.0 及以上 | 任意版本,Connector 保持 HTTP |
| 关键参数 | certificateKeystoreFile、certificateKeystoreType(默认 JKS)、certificateKeystorePassword |
certificateFile、certificateKeyFile |
RemoteIpValve 的 protocolHeader、remoteIpHeader、internalProxies |
| 适用场景 | 单实例、无前置代理的中小站点 | certbot 已托管证书,续期后只重启不改文件 | 多实例、需要统一限流/WAF/灰度 |
| 额外成本 | 每次续期重新导出 p12 并重启 | 私钥落在 Tomcat 运行用户可读路径 | 多一层运维对象与排障链路 |
PKCS12 直连:从旧 JKS 迁过来要跑哪条命令?
据 Oracle JEP 229,JDK 9 起 keytool 的默认密钥库类型已由 JKS 改为 PKCS12,所以新导出的 p12 不用再显式指定 -deststoretype;JDK 8 则必须写。
# 在 JDK 8 / 11 / 17 下均可执行:JKS 转 PKCS12
keytool -importkeystore
-srckeystore conf/tomcat.jks -srcstoretype JKS -srcstorepass changeit
-destkeystore conf/tomcat.p12 -deststoretype PKCS12 -deststorepass changeit
-noprompt
# 校验结果:Alias name 应显示 tomcat,Entry type 为 PrivateKeyEntry
keytool -list -v -keystore conf/tomcat.p12 -storetype PKCS12 -storepass changeit
若 certificateKeystoreType 与实际文件不符,Tomcat 启动即抛 java.io.IOException: Invalid keystore format,这是最常见的踩坑点。
PEM 直读怎么写 server.xml?
<!-- conf/server.xml,Tomcat 8.5.0+;certificateKeystoreFile 与 certificateFile 不可同时配置 -->
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true">
<SSLHostConfig>
<Certificate certificateFile="/etc/letsencrypt/live/example.com/fullchain.pem"
certificateKeyFile="/etc/letsencrypt/live/example.com/privkey.pem" />
</SSLHostConfig>
</Connector>
Let’s Encrypt 文档明确 live/ 下是软链接、真实文件在 archive/,因此 Tomcat 运行用户需对两级目录都有读权限,否则报 FileNotFoundException ... Permission denied。续期钩子只需 certbot renew --deploy-hook "systemctl restart tomcat"。
Nginx 卸载 TLS 后,为什么登录后会无限重定向?
因为 Tomcat 只看到明文 8080,request.getScheme() 恒为 http,Spring Security 之类的 requiresChannel().requiresSecure() 会不停 302 到 https,浏览器报 ERR_TOO_MANY_REDIRECTS。解法是让 Tomcat 信任代理头:
# Nginx 侧必须透传这两个头,缺一不可
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
<!-- Tomcat conf/server.xml,放在 <Host> 内;internalProxies 默认只信任 10/172.16-31/192.168/127/::1 网段 -->
<Valve className="org.apache.catalina.valves.RemoteIpValve"
remoteIpHeader="X-Forwarded-For"
protocolHeader="X-Forwarded-Proto"
protocolHeaderHttpsValue="https" />
注意 internalProxies 默认值不含公网地址:若 Nginx 与 Tomcat 跨公网部署,必须显式改写该正则,否则 Valve 静默不生效。
JKS 还要不要留?
两者在 server.xml 里只差 certificateKeystoreType 一个值(JKS / PKCS12)。新项目统一 PKCS12 即可;只有当老监控探针或老中间件只认 JKS 时才保留 JKS。顺带一提,TLS 1.3 需要 Java 11+ 的 JSSE 实现,sslProtocol 保持默认 TLS 就能自动协商到最高版本,无需手写 TLSv1.3。
- Wildcard 通配符 SSL 证书安装部署续费申请
- SSL证书申请 · SSL证书购买 · SSL证书安装配置
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
五、常见错误与排查:6 条真实报错对照处理
这 6 条报错里,4 条出在 keystore 打包环节(密码、别名、证书链、SAN),2 条出在运行时(端口、协议)。排查顺序建议先看 Tomcat 的 logs/catalina.out 首个异常,再按下面命令验证;据 Tomcat 9 配置文档,certificateKeystoreType 的默认值是 JKS,这正是第 1 条报错最常见的来源。
-
java.io.IOException: Keystore was tampered with, or password was incorrect —— 密码错还是 storeType 错?
九成是密码打错,或拿 PKCS12 文件却写了
certificateKeystoreType="JKS"。先脱离 Tomcat 单独验证(JDK 8 的keytool默认 storetype 是 JKS,JDK 9 起才默认 PKCS12):# 显式指定 PKCS12;能列出别名说明密码正确,问题在 server.xml 的 type keytool -list -storetype PKCS12 -keystore /opt/tomcat/conf/tomcat.p12 -v<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"> <SSLHostConfig> <Certificate certificateKeystoreFile="conf/tomcat.p12" certificateKeystoreType="PKCS12" <!-- 默认 JKS,必须显式改 --> certificateKeystorePassword="changeit" /> </SSLHostConfig> </Connector> -
java.security.UnrecoverableKeyException: Cannot recover key —— 别名密码和库密码不一致
PKCS12 只有一套密码:
openssl pkcs12 -export的-passout同时决定库密码和密钥密码,必须与certificateKeystorePassword逐字符相同;-name决定别名,必须与certificateKeyAlias一致。JKS 才允许-keypass与-storepass不同。openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -name tomcat -out /opt/tomcat/conf/tomcat.p12 -passout pass:changeit keytool -list -v -storetype PKCS12 -keystore /opt/tomcat/conf/tomcat.p12 | grep -i alias -
浏览器 NET::ERR_CERT_AUTHORITY_INVALID 或 Java 客户端 PKIX path building failed —— 只装了叶子证书
# 正常应为 2(叶子+中间)或 3;返回 1 就是缺中间证书 openssl s_client -connect www.example.com:8443 -showcerts </dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE" cat cert.pem chain.pem > fullchain.pem # Let's Encrypt 官方做法,不含根证书 -
javax.net.ssl.SSLHandshakeException: no cipher suites in common —— 协议对不上
典型是服务端只剩 TLSv1.2/TLSv1.3(OpenJDK 11 的
jdk.tls.disabledAlgorithms默认已禁用 TLSv1/1.1),客户端还在 TLSv1.0:openssl s_client -tls1 -connect www.example.com:8443 # 失败即确认版本不交集 openssl s_client -tls1_2 -connect www.example.com:8443 # 成功则只是版本问题不建议为兼容老客户端放开 TLSv1.0;确需放行要同时改
sslEnabledProtocols与 JVM 的java.security。 -
java.net.BindException: Address already in use —— 8443 被占用
ss -lntp | grep 8443 # 定位 PID kill -15 <PID> # 先 SIGTERM,走完 shutdown hook sleep 10 && ss -lntp | grep 8443 # 端口释放后再 startup.sh -
CertificateException: No subject alternative names present / 未过期却报 expired
前者是证书只有 CN 没有 SAN,Chrome 58(2017 年)起直接拒绝:
openssl x509 -in cert.pem -noout -text | grep -A1 "Subject Alternative Name" # 无输出即无 SAN,需重签并在扩展中写 subjectAltName=DNS:www.example.com,DNS:example.com后者多半是系统时间漂移,用
timedatectl看System clock synchronized: yes,或chronyc tracking看偏移量。
| 报错关键字 | 根因 | 验证命令 | 修复动作 |
| Keystore was tampered with | 密码错 / storeType 不符 | keytool -list -storetype PKCS12 -keystore tomcat.p12 |
显式设 certificateKeystoreType="PKCS12" |
| Cannot recover key | 别名或密码未对齐 | keytool -list -v | grep -i alias |
-name/-passout 与 server.xml 一致 |
| ERR_CERT_AUTHORITY_INVALID / PKIX | 缺中间证书 | openssl s_client -showcerts | grep -c |
用 fullchain.pem 重导 p12 |
| no cipher suites in common | 协议/套件无交集 | openssl s_client -tls1 |
统一协议版本,勿开 TLSv1.0 |
| BindException | 8443 被占用 | ss -lntp | grep 8443 |
kill -15 后重启 |
| No subject alternative names | 证书缺 SAN | openssl x509 -text | grep SAN |
重签并加 subjectAltName |
六、如何验证 Tomcat SSL 配置真的生效
浏览器地址栏出现小锁只能说明”握手成功了”,不能说明证书链完整、协议版本达标、老套件已关闭。真正可靠的验证要分三层:握手层、证书层、配置层。下面这套命令序列建议按顺序跑一遍,全部通过才算 tomcat 配置ssl证书真正生效。
第一步:强制 TLS 1.3 握手,确认协议版本与信任链
# -servername 必须写,否则多域名/多 vhost 场景下 JSSE 会回退到默认证书
openssl s_client -connect www.example.com:8443 -servername www.example.com -tls1_3 </dev/null
# 输出中必须同时出现这两行:
# Protocol : TLSv1.3
# Verify return code: 0 (ok)
据 RFC 6066,SNI(Server Name Indication)是客户端在 ClientHello 中声明目标主机名的扩展;Tomcat 的 <SSLHostConfig hostName="..."> 正是靠它选择证书,省掉 -servername 就会拿到第一个(默认)SSLHostConfig 的证书。返回码非 0 时按数字定位:20 通常是中间证书缺失(把 fullchain 一起导入 keystore),21 是本机 CA 库不信任该根,10 是证书已过期。若返回 Protocol : TLSv1.2,说明 Connector 上仍写了 sslProtocol="TLSv1.2" 或 JDK 低于 8u261 一类不支持 1.3 的版本——Tomcat 9.0.x 在未显式配置 protocols 时继承 JVM 的 jdk.tls.server.protocols,JDK 11+ 默认同时启用 TLSv1.2 与 TLSv1.3。
第二步:核对真正下发的那张证书
# 取出服务端实际发送的证书链第一张,检查 CN / 有效期 / SAN
openssl s_client -connect www.example.com:8443 -showcerts </dev/null 2>/dev/null
| openssl x509 -noout -subject -dates -ext subjectAltName
# 示例输出:
# subject=CN = www.example.com
# notBefore=Mar 1 00:00:00 2025 GMT
# notAfter=May 30 23:59:59 2026 GMT
# X509v3 Subject Alternative Name: DNS:www.example.com, DNS:example.com
SAN 列表必须与申请时一致。据 Let’s Encrypt 文档,其签发的证书自 2018 年起 CN 已非必填,客户端一律以 SAN 为准;因此即使 CN 正确,SAN 漏了裸域 example.com,访问裸域照样报 NET::ERR_CERT_COMMON_NAME_INVALID。
第三步:HTTP 层确认协议协商
curl -vI https://www.example.com:8443 2>&1 | grep -E "SSL connection|TLSv1.3|HTTP/1.1 200"
# * SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
# < HTTP/1.1 200
第四步:枚举套件,看有没有残留的老算法
nmap --script ssl-enum-ciphers -p 8443 www.example.com
# 输出按 TLSv1.2 / TLSv1.3 分段列出套件,末尾给出强度评级
# 目标:两个版本均为 A,且不出现 RC4、3DES、*_CBC_* 套件
| 验证手段 | 覆盖层面 | 通过标准 | 耗时 | 常见误判 |
|---|---|---|---|---|
| openssl s_client | 握手协议 + 信任链 | TLSv1.3 且 Verify return code: 0 | <1s | 漏写 -servername,误判为证书错误 |
| s_client -showcerts + x509 | 证书内容 | CN/SAN/有效期与申请一致 | <1s | 只看 CN 不看 SAN |
| curl -vI | HTTP 层 | SSL connection using TLSv1.3 + 200 | <1s | 忽略 301/403 也是握手成功 |
| nmap ssl-enum-ciphers | 套件强度 | TLS1.2/1.3 均 A,无 CBC/3DES | 10–60s | 只测到 TLS1.2 段就下结论 |
| SSL Labs / myssl | 全链路 + 前向保密 + HSTS | 评分 A 及以上 | 1–3min | CDN 回源未改,扫到的是边缘节点 |
第五步:日志侧兜底
# Tomcat 9/10 启动成功时必现该行;无 SEVERE 即为正常
grep -E "https-jsse-nio-8443|SEVERE" "$CATALINA_BASE"/logs/catalina.out | tail -n 20
# 用 systemd 托管时更快:
journalctl -u tomcat -n 100 --no-pager
若日志里出现 java.io.IOException: keystore password was incorrect 或 Alias name [tomcat] does not identify a key entry,说明 server.xml 中 keystorePass 与实际 keystore 口令不符,或导入的是受信证书而非私钥条目——这类问题浏览器只会报笼统的 ERR_SSL_PROTOCOL_ERROR,必须回日志定位。
最后用第三方视角复核:Qualys SSL Labs 的 SSL Server Test 输入域名,等 1–3 分钟出分,目标 A 及以上;国内网络可并行跑 myssl.com。两者都会独立检查证书链完整性、HSTS 响应头、协议版本与 ECDHE 前向保密支持,能发现本地命令看不到的链顺序问题(例如只下发了叶证书、漏掉中间 CA)。
七、Tomcat 8.5/9/10/11 版本差异与证书自动续期
Tomcat 各版本在 SSL 配置上的差异,是很多团队从 8.5 升级到 10/11 时最容易遇到问题的地方。下面按“版本选型 → 自动续期 → 不重启的可行性 → 到期监控”四个实际问题依次拆解。
问题一:我的 Tomcat 版本还安全吗?SSL 语法要不要改?
据 Apache Tomcat 官方下载页的生命周期说明,8.5.x 已于 2024-03-31 结束支持(EOL),不再发布安全补丁;9.0.x 的支持期延续到 2027-03-31 左右;10.1.x 要求 JDK 11+;11.0.x 要求 JDK 17+。也就是说,仍在运行 8.5 且已暴露在公网的实例,等于长期没有安全补丁可用,这比“配置麻烦”更值得优先处理。
好消息是:server.xml 里的 <Connector> 与 <SSLHostConfig> 属性名在 9/10/11 之间基本一致,certificateKeystoreFile、certificateKeystorePassword、certificateKeystoreType 均沿用。真正的破坏性变化在包名:Tomcat 10 起 Servlet API 从 javax.servlet.* 迁移到 jakarta.servlet.*,自定义 Valve、Filter、Realm 需重新编译,与 SSL 无关但常被一起升级。
| 版本 | 最低 JDK | Servlet 包名 | 支持状态 | SSL 配置语法 |
|---|---|---|---|---|
| 8.5.x | JDK 7+ | javax.* | 2024-03-31 EOL | SSLHostConfig(8.5 起引入) |
| 9.0.x | JDK 8+ | javax.* | 至 2027-03-31 | 与 8.5 一致 |
| 10.1.x | JDK 11+ | jakarta.* | 维护中 | 属性名不变 |
| 11.0.x | JDK 17+ | jakarta.* | 维护中 | 属性名不变 |
问题二:Let’s Encrypt 90 天到期,怎么让它自动换?
据 Let’s Encrypt 文档,其证书有效期固定 90 天,官方明确建议用 ACME 客户端自动化而非手工续期。certbot 的 --deploy-hook 只在证书真正续期成功后触发,比 --post-hook 更精准(后者每次 renew 都跑)。先在 /etc/letsencrypt/renewal/www.example.com.conf 中固化钩子,再手动验证一次:
# 1) 把部署钩子写入 renewal 配置,后续自动续期都会执行
sudo certbot renew --cert-name www.example.com
--deploy-hook "/opt/tomcat/renew-ssl.sh"
# 2) renew-ssl.sh 内容(务必 chmod 750,属主 root:tomcat)
#!/bin/bash
set -euo pipefail
LIVE=/etc/letsencrypt/live/www.example.com
OUT=/opt/tomcat/conf/ssl/tomcat.p12
# PKCS12 导出:-name 必须与 server.xml 的 certificateKeyAlias 一致
openssl pkcs12 -export
-in "$LIVE/fullchain.pem"
-inkey "$LIVE/privkey.pem"
-out "$OUT"
-name tomcat
-passout pass:ChangeIt123
chown tomcat:tomcat "$OUT" && chmod 640 "$OUT"
# 重启使 Connector 重新加载 keystore
systemctl restart tomcat
# 3) 演练(不真正续期,只跑钩子验证脚本可用)
sudo certbot renew --cert-name www.example.com --dry-run
注意 -name tomcat 与 certificateKeyAlias="tomcat" 必须匹配,否则 Tomcat 启动报 java.io.IOException: Alias name [tomcat] does not identify a key entry。ChangeIt123 仅为示例,生产环境应从受限文件读取,避免密码进入 shell 历史。
问题三:换证书一定要重启吗?中断多久?
Tomcat 没有内置的“证书热加载”开关,PKCS12/JKS keystore 由 Connector 在初始化时读入内存,改文件不会生效,必须重启 Connector。PEM 方式(certificateFile + certificateKeyFile)在部分 9.0.x 小版本中同样需要重启;若追求零重启,可借助 JMX 的 reload() 或外部优雅重启。单实例重启造成的中断通常在 5-15 秒,建议放在业务低峰期,并配合前置负载均衡摘节点。
问题四:怎么在用户投诉前发现证书快过期?
用一个纯 openssl 探针即可,无需装插件:-checkend 2592000 表示检查剩余是否少于 30 天,不足则返回非 0,直接对接 Zabbix system.run 或 Prometheus blackbox_exporter 的 probe_ssl_earliest_cert_expiry 指标:
# 剩余不足 30 天(2592000 秒)时退出码非 0,可作为告警条件
openssl s_client -connect www.example.com:8443 -servername www.example.com
</dev/null 2>/dev/null
| openssl x509 -checkend 2592000 -noout
|| echo "CRITICAL: 证书将在 30 天内过期"
问题五:免费证书够用吗,还是必须买商业证书?
差别主要在组织核验、保险赔付与人工支持,而非加密强度——两者的加密算法相同。内网、测试环境用自签证书即可(浏览器会告警,但可用 keytool -genkeypair 快速生成)。
| 类型 | 参考价格 | 有效期 | 核验方式 | 适用场景 |
|---|---|---|---|---|
| Let’s Encrypt DV | 免费 | 90 天,需自动化 | 域名控制权 | 公网 Web、API |
| 商业 DV | 约 100-600 元/年 | 1 年 | 域名控制权 | 不想维护自动化的站点 |
| 商业 OV | 约 800-3000 元/年 | 1 年 | 组织信息人工核验 | 政企、对外门户 |
| 自签名 | 0 | 自定义 | 无 | 内网、联调测试 |
在规划 tomcat 配置ssl证书的升级路线时,建议把“版本 EOL 日期”和“证书到期日”放进同一张运维日历;证书续期脚本一旦上线,--dry-run 演练与 30 天探针这两道保险能挡掉绝大多数线上事故。
Tomcat 8.5.0 及以上可以。在 SSLHostConfig 的 Certificate 元素里写 certificateFile 指向 fullchain.pem、certificateKeyFile 指向 privkey.pem 即可,不需要转换;8.5 以下版本必须先转成 PKCS12 或 JKS 密钥库,否则启动时会报找不到 keystore。
先按顺序排除三层:catalina.out 里有没有 Starting ProtocolHandler ["https-jsse-nio-8443"](进程层),ss -lntp | grep 8443 能否看到监听(端口层),云服务器安全组和 firewalld 是否放行 8443(网络层)。三层都正常再回头看证书,多数“打不开”其实是安全组没开端口。
单实例、无其他 Web 服务时,Tomcat 直接配 8443 最省事,少一个组件也少一个故障点;多实例、需要统一限流、WAF、灰度或已有 Nginx 集群时,让 Nginx 卸载 TLS 更划算,但要在 Tomcat 端配置 RemoteIpValve,否则应用取到的 scheme 仍是 http,容易触发重定向循环。
使用 PKCS12/JKS 密钥库时必须重启,因为文件是在 Connector 初始化时一次性读入内存的;PEM 直读方式在多数 9.0.x 版本中同样需要重启才生效。把 openssl pkcs12 -export 与 systemctl restart tomcat 写进 certbot 的 –deploy-hook,就能把这一步自动化。
先确认密钥库格式与密码:keytool -list -v -storetype PKCS12 -keystore tomcat.p12 -storepass 你的密码。若这里就报错,说明密码本身不对;若这里正常但 Tomcat 报错,多半是 server.xml 里 certificateKeystoreType 写成了 JKS 而文件其实是 PKCS12,改回 PKCS12 即可。
浏览器有 AIA 自动补链机制,缺中间证书也能蒙混过关,而 Java 默认只信任 keystore 里已有的根证书,不会自动下载中间证书。解决办法是把中间证书拼进 fullchain 后重新导出 PKCS12,确认 keytool -list -v 输出中 Certificate chain length 至少为 2。
SSL 部分几乎没有区别,SSLHostConfig、Certificate、certificateKeystoreFile 这些属性名在 9.0.x、10.1.x、11.0.x 中保持一致。真正的差异在运行环境:10.1.x 要求 JDK 11+,11.0.x 要求 JDK 17+,并且应用代码的包名从 javax.* 换成了 jakarta.*,升级时证书配置可以直接复用。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。