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

Tomcat 配置 SSL 证书实战:从 keystore 转换到 8443 端口 HTTPS 生效

tomcat 配置ssl证书 — 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 步的别名不一致上——这两处出错时日志给的提示都极其含糊。

  1. 环境确认: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.sh
    Tomcat 版本 最低 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 第一屏就报错退出。

  2. 生成私钥与 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 以下会被直接拒签。

  3. 提交 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 天)。

  4. 合成 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。

  5. 校验密钥库内容。这条命令的输出要逐行看:

    keytool -list -v -keystore tomcat.p12 -storetype PKCS12 -storepass ChangeIt123
    Alias 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。

  6. 放置文件并收紧权限。密钥库等价于私钥,同机其他用户不应可读:

    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 会让任何本地账户都能拷走私钥并离线解密流量,这是审计中最常见的扣分项。

  7. 备份并修改 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 片段见下一节。

  8. 重启并确认日志关键字。这一步是 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。

五、常见错误与排查:6 条真实报错对照处理

这 6 条报错里,4 条出在 keystore 打包环节(密码、别名、证书链、SAN),2 条出在运行时(端口、协议)。排查顺序建议先看 Tomcat 的 logs/catalina.out 首个异常,再按下面命令验证;据 Tomcat 9 配置文档,certificateKeystoreType 的默认值是 JKS,这正是第 1 条报错最常见的来源。

  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>
    
  2. 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
    
  3. 浏览器 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 官方做法,不含根证书
    
  4. 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。

  5. 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
    
  6. 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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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