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

Tomcat HTTPS 配置怎么做?PEM 证书、SSLHostConfig 与反向代理选型(Tomcat 9.0/10.1)

tomcat https 配置 — Tomcat HTTPS 配置怎么做?PEM 证书、SSLHostConfig 与反向代理选型(Tomcat 9.0/10.1)
核心结论

Tomcat HTTPS 配置的核心是把 conf/server.xml 中 8443 Connector 的 SSLEnabled 设为 true,并在 SSLHostConfig 里用 certificateFile 指向 fullchain.pem、certificateKeyFile 指向 privkey.pem;Tomcat 9.0.x 与 10.1.x 均支持,改完重启 15–30 秒生效。 证书链必须用 fullchain.pem(leaf + intermediate),只配 leaf 会让 Java 客户端报 PKIX path building failed;用 openssl s_client -showcerts 应看到至少 2 张证书。 TLS 协议建议只开 TLSv1.3 与 TLSv1.2:protocols='TLSv1.3,TLSv1.2',并用 ciphers 限定 AEAD 套件;TLS 1.3 的套件顺序由客户端决定,honorCipherOrder 对它不生效。 如果前面有 Nginx,建议由 Nginx 终结 TLS、Tomcat 只监听 8080,并在 Tomcat 加 RemoteIpValve 读取 X-Forwarded-Proto,否则应用生成的绝对 URL 仍是 http。 上线验证至少跑三条命令:ss -lntp | grep 8443、openssl s_client -connect ... -servername ... -tls1_3、curl -I --tlsv1.3;DV 证书年费约 0–300 元,OV 约 800–3000 元,部署耗时通常 20–40 分钟。

为什么 Tomcat HTTPS 配置总是不生效?先看 5 个根本原因

很多人的经历是:改完 conf/server.xml、重启 Tomcat,浏览器却依然连不上 8443,或者页面打开了但地址栏没有小锁。Tomcat 的 HTTPS 并不会“自动生效”——它默认只启用 8080 HTTP Connector,server.xml 里那段 8443 的示例自 Tomcat 4 起就一直是注释状态。下面 5 个根因覆盖了绝大多数 tomcat https 配置失败场景,按出现频率排序。

根因 1:8443 Connector 根本没被启用。先确认文件里到底有没有生效的 SSL Connector,而不是看有没有“8443”这几个字:

# 列出所有未被注释的 Connector,以及 8443 相关行
grep -nE '^s*<Connector|SSLEnabled' "$CATALINA_BASE/conf/server.xml"
# 正确输出应包含:<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
#                maxThreads="150" SSLEnabled="true">
# 若 8443 那一行以 <!-- 开头,说明仍是注释示例,等于没配

SSLEnabled="true" 是必须项(默认值 false),且修改后必须重启 JVM;Tomcat 9.0.x / 10.1.x 均不会自动生成自签名证书,也不会自动重定向 HTTP 到 HTTPS。据 Tomcat 官方 SSL How-To,8.5 起推荐用 SSLHostConfig + Certificate 嵌套结构替代旧属性,两者混用时 Tomcat 会在启动阶段报 SEVERE: Failed to initialize end point associated with ProtocolHandler,日志底部常见 java.lang.IllegalArgumentException。

旧教程写法(Connector 属性) Tomcat 9.0 / 10.1 推荐写法(Certificate 属性) 默认值 / 备注
keystoreFile certificateKeystoreFile 无默认值,必填
keystorePass certificateKeystorePassword 无默认值
clientAuth="true" certificateVerification 默认 none,可选 optional/required
sslProtocol="TLSv1.2" protocols(SSLHostConfig 上) 默认由 JSSE 决定,建议显式写 TLSv1.2+TLSv1.3

根因 2:只部署了 leaf 证书。浏览器会自动补链,但 Java 客户端不会。据 RFC 5280 §6,服务器应在握手时发送完整链。缺 intermediate 时客户端抛:

javax.net.ssl.SSLHandshakeException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

验证方法(Let’s Encrypt 的 fullchain.pem 通常含 2–3 张证书):

# 统计服务端实际发送的证书张数,应 ≥ 2
openssl s_client -connect example.com:8443 -servername example.com -showcerts </dev/null 2>/dev/null 
  | grep -c 'BEGIN CERTIFICATE'
# 用 PEM 直接组装 PKCS12,fullchain.pem 是 certificateFile 的正确取值
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem 
  -out tomcat.p12 -name tomcat -CAfile chain.pem -caname root -passout pass:changeit

根因 3:本机监听 ≠ 外网可达。ss -lntp | grep 8443 只能证明 Tomcat 绑上了端口,安全组、firewalld、iptables 任一层丢弃 SYN,外部就是 Connection refused(有 RST)或 timeout(DROP)。CentOS/RHEL 上:

firewall-cmd --add-port=8443/tcp --permanent && firewall-cmd --reload
firewall-cmd --list-ports   # 确认 8443/tcp 已在列表中

根因 4:反代后面丢了 X-Forwarded-Proto。Tomcat 前置 Nginx 时,若未启用 RemoteIpValve,request.getScheme() 始终返回 http,sendRedirect() 生成的绝对地址就是 http://,浏览器报混合内容。在 server.xml 的 <Host> 内加入:

<Valve className="org.apache.catalina.valves.RemoteIpValve"
       protocolHeader="X-Forwarded-Proto"
       remoteIpHeader="X-Forwarded-For"
       internalProxies="10.d{1,3}.d{1,3}.d{1,3}|192.168.d{1,3}.d{1,3}|127.d{1,3}.d{1,3}.d{1,3}" />
<!-- internalProxies 默认覆盖 10/8、172.16/12、192.168/16、127/8 与 ::1;
     若 Nginx 在公网另一台机器,必须显式补上它的出口 IP,否则 Valve 直接忽略该头 -->

根因 5:证书格式与容器不匹配。Tomcat 的 Certificate 支持 JKS/PKCS12 keystore,也支持 PEM(certificateFile + certificateKeyFile,8.5 起)。若同时设置 certificateFile 和 certificateKeystoreFile,Tomcat 会以配置冲突拒绝启动。PEM 路线适合与 Nginx / certbot 共用同一份 Let’s Encrypt 产物,避免每次续期都要重导 keystore。

Tomcat HTTPS 配置前要准备什么?版本、证书格式与端口检查

第一步:确认 Tomcat 与 JVM 版本,否则后面的配置可能根本不生效

在改动任何配置之前,先运行 Tomcat 自带的版本脚本,确认运行时环境。在 Linux 和 macOS 下使用 version.sh,在 Windows 下使用 version.bat:

# 输出三行关键信息,务必与后面的证书/协议方案对齐
$CATALINA_HOME/bin/version.sh

# 典型输出(示例):
# Server version: Apache Tomcat/9.0.104
# Server built:   Dec  5 2024 14:03:00 UTC
# JVM Version:    17.0.12+7-LTS

这里的 JVM Version 决定你能用哪些 TLS 能力:TLS 1.3 由 JSSE 实现,Java 8 的 JSSE 不支持 TLS 1.3,必须使用 Java 11 及以上版本。据 Apache Tomcat 官方 Tomcat Versions 页面,Tomcat 9.0.x 最低要求 Java 8,Tomcat 10.1.x 要求 Java 11,Tomcat 11.0.x 要求 Java 17。

版本 最低 Java 可用 TLS 1.3 Servlet / 命名空间
Tomcat 9.0.x Java 8 需 Java 11+ javax.servlet
Tomcat 10.1.x Java 11 是 jakarta.servlet 6.0
Tomcat 11.0.x Java 17 是 jakarta.servlet 6.1

第二步:证书要准备哪两个文件?

Tomcat 8.5 起,SSLHostConfig 直接支持 PEM,因此不需要再做 PKCS#12 转换:certificateFile 指向 fullchain.pem(叶子证书 + 中间证书,顺序不能颠倒),certificateKeyFile 指向 privkey.pem(RSA 2048 位或 ECDSA P-256)。如果只放入叶子证书,部分 Android 和 Java 客户端会报 PKIX path building failed。

类型 年费区间 有效期 典型场景
DV(Let’s Encrypt) 0 元 90 天,需自动续期 内部系统、个人站点
DV 商业 0–300 元 最长 398 天 通用 HTTPS
OV 800–3000 元 最长 398 天 企业对外服务
EV 3000–10000 元 最长 398 天 金融、强信任场景

第三步:私钥权限怎么验?

最常见的失败原因是 Tomcat 进程读不到私钥。私钥不要放在 /root 下,因为 /root 目录权限为 700,其他用户连遍历都不行,JSSE 抛出的却是 No such file or directory,极易误导排查方向:

# 目录 750、私钥 600,属主为运行 Tomcat 的用户
sudo install -d -o tomcat -g tomcat -m 750 /etc/tomcat/ssl
sudo install -o tomcat -g tomcat -m 600 fullchain.pem privkey.pem /etc/tomcat/ssl/

# 以运行用户身份验证可读性,返回 OK 才算通过
sudo -u tomcat test -r /etc/tomcat/ssl/privkey.pem 
  && echo "OK: 运行用户可读" || echo "FAIL: 检查属主与目录 x 位"

# 真实报错示例:
# java.io.FileNotFoundException: /root/privkey.pem (Permission denied)

第四步:用 8443 还是 443?

8443 是 Tomcat 示例配置中的默认 HTTPS 端口,可直接使用,不需要额外权限。若改用 443,在 Linux 下需要 root 或 CAP_NET_BIND_SERVICE,例如 sudo setcap 'cap_net_bind_service=+ep' $JAVA_HOME/bin/java,但该能力在升级 JDK 后会失效,且对同一 JVM 的所有进程生效;在 Windows 下先用 netstat -ano | findstr :443 排查 IIS、Skype 是否已占用。改端口后要同步放行 firewalld 和云安全组。

第五步:改配置前先备份

# 带日期的原地备份,保留权限与时间戳
cp -a $CATALINA_HOME/conf/server.xml{,.bak-$(date +%F)}

# 出问题时 1 分钟内回滚
cp -a $CATALINA_HOME/conf/server.xml.bak-2025-06-01 $CATALINA_HOME/conf/server.xml

server.xml 里 Connector 的语法错误会直接导致启动失败,catalina.out 只留下一行 LifecycleException,有备份比逐行比对快得多。这也是 tomcat https 配置最常见的“翻车点”:证书没问题,配置语法却写错了。准备工作做完,再进入 SSLHostConfig 的具体写法就顺畅了。

Tomcat HTTPS 配置的完整实操步骤:从上传证书到 8443 监听(8 步)

以下 8 步基于 Tomcat 9.0.x / 10.1.x、以 systemd 服务运行、运行用户为 tomcat、$CATALINA_HOME=/opt/tomcat 的环境。据 Apache Tomcat 官方配置文档,自 8.5 起 JSSE 连接器可直接读取 PEM 格式的证书与私钥,不必再转换成 JKS 或 PKCS12,因此 tomcat https 配置 的步骤比很多人记忆中的 keytool 流程短得多。

步骤 1:目录与权限。私钥必须只对 Tomcat 运行用户可读,否则 JSSE 会抛 java.io.IOException: Keystore was tampered with, or password was incorrect 之类难以定位的异常。

# 创建证书目录,属主 tomcat,权限 750
install -d -o tomcat -g tomcat -m 750 /etc/tomcat/ssl
# 上传 fullchain.pem(服务器证书 + 中间证书,顺序不能颠倒)与 privkey.pem
chown -R tomcat:tomcat /etc/tomcat/ssl
chmod 600 /etc/tomcat/ssl/privkey.pem
chmod 644 /etc/tomcat/ssl/fullchain.pem

步骤 2:校验私钥与证书是否配对。RSA 证书用 modulus 比对,两条命令输出的 MD5 必须逐字符一致:

openssl x509 -noout -modulus -in /etc/tomcat/ssl/fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in /etc/tomcat/ssl/privkey.pem  | openssl md5
# 期望两行都是 (stdin)= 3f:2a:... 完全一致

如果证书是 ECDSA(P-256)签发,-modulus 会报 unable to load certificate,改用公钥比对:

openssl x509 -in fullchain.pem -noout -pubkey | openssl md5
openssl pkey -in privkey.pem -pubout | openssl md5
# 同时确认有效期与 SAN 覆盖域名
openssl x509 -in fullchain.pem -noout -dates -subject -ext subjectAltName

步骤 3–4:改 server.xml。在 <Service> 内新增 8443 Connector(Tomcat 9.0 默认 server.xml 中该 Connector 是注释状态,Tomcat 10.1 模板中的示例已是 SSLHostConfig 写法)。protocol 省略时默认即 NIO,写全是为了避免误落到已废弃的 BIO。

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true" scheme="https" secure="true" maxThreads="200"
           connectionTimeout="20000" redirectPort="8443">
  <SSLHostConfig protocols="TLSv1.3,TLSv1.2">
    <Certificate certificateFile="/etc/tomcat/ssl/fullchain.pem"
                 certificateKeyFile="/etc/tomcat/ssl/privkey.pem"
                 type="RSA"/>
  </SSLHostConfig>
  <!-- 需要 HTTP/2 时再加这一行;不加则只有 HTTP/1.1 -->
  <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol"/>
</Connector>

要点:protocols 在 Tomcat 9.0 中取代了已废弃的 sslProtocol;不写 hostName 时该配置的默认主机名为 _default_,正好对应 openssl s_client 的 -servername 与 SNI。路径写绝对路径最稳妥——相对路径以 $CATALINA_BASE 为基准,容易踩坑。

步骤 5:放行端口。firewalld 与云安全组是两道独立的门,缺一不可。

firewall-cmd --add-port=8443/tcp --permanent && firewall-cmd --reload
# SELinux 系统检查端口标签;RHEL 系 tomcat 包通常已放行 8443
semanage port -l | grep 8443
# 若未列出 http_port_t tcp 8443,才需要手工添加
semanage port -a -t http_port_t -p tcp 8443

步骤 6:重启并确认监听。

systemctl restart tomcat && sleep 20
ss -lntp | grep 8443            # 期望 *:8443 由 java 进程 LISTEN
grep -i 'Starting ProtocolHandler' /opt/tomcat/logs/catalina.out
# 期望:Starting ProtocolHandler ["https-jsse-nio-8443"]

若只看到 http-nio-8080 而没有 https-jsse-nio-8443,说明 Connector 未解析成功,向上翻 SEVERE 行。

步骤 7:本机握手验证。必须带 -servername,否则 SNI 匹配不到对应证书。

openssl s_client -connect 127.0.0.1:8443 -servername app.example.com -tls1_3 </dev/null 
  | grep -E 'Protocol|Cipher|Verify return code'
# 期望 Protocol : TLSv1.3、Verify return code: 0 (ok)
openssl s_client -connect 127.0.0.1:8443 -servername app.example.com -showcerts </dev/null 
  | openssl x509 -noout -subject -ext subjectAltName

步骤 8:外网验证。

curl -I --tlsv1.3 --tls-max 1.3 https://app.example.com:8443/
# 期望 HTTP/2 200 或 HTTP/1.1 200;--tls-max 需 curl 7.61+

返回 curl: (35) error:0A00010B:SSL routines::wrong version number 通常是该端口上跑的是明文 HTTP;返回 403/404 而握手成功则说明 tomcat https 配置 已生效、问题在应用路由层。第 8 步失败时按下一节的报错顺序逐条排查。

Tomcat HTTPS 配置示例:server.xml 的 SSLHostConfig、PEM 与 OpenSSL 命令

一份能直接抄的 server.xml:Connector 里套 SSLHostConfig

Tomcat 9.0.x 与 10.1.x 的 tomcat https 配置结构完全一致:端口、线程参数留在 <Connector>,协议版本与证书全部下沉到 <SSLHostConfig>。最常见的错误是把 TLS 版本写成 Connector 的 sslProtocol——该属性自 Tomcat 8.5 起被 SSLHostConfig 的 protocols 取代,写了既不生效也不报错,只能靠握手结果发现。

<!-- conf/server.xml,Tomcat 9.0.x / 10.1.x 通用 -->
<Connector port="8443"
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200"
           SSLEnabled="true"
           scheme="https"
           secure="true"
           connectionTimeout="20000">
  <!-- TLS 版本写在这里,不是 Connector 的 sslProtocol -->
  <SSLHostConfig protocols="TLSv1.3,TLSv1.2"
                 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"
                 honorCipherOrder="true"
                 sessionTimeout="86400"
                 sessionCacheSize="20480">
    <!-- fullchain.pem 已含中间证书,不要再配 certificateChainFile -->
    <Certificate certificateFile="/etc/tomcat/ssl/fullchain.pem"
                 certificateKeyFile="/etc/tomcat/ssl/privkey.pem"
                 type="RSA" />
  </SSLHostConfig>
  <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
</Connector>

关键默认值(据 Tomcat 9 Configuration Reference):maxThreads 默认 200,connectionTimeout 默认 60000 毫秒,sessionTimeout 默认 86400 秒,sessionCacheSize 默认 0(不限制缓存条目),honorCipherOrder 默认 false——不显式改成 true,服务端就不会按你写的顺序决定套件优先级。据 Let’s Encrypt 文档,fullchain.pem = 叶证书 + 中间证书,privkey.pem 单独保存;把整条链再塞进 certificateChainFile 会让链重复,部分 Android 与 Java 客户端会直接握手失败。

改完配置,用三条 OpenSSL 命令自证

# 1) 证书与私钥是否配对:两行 md5 必须完全一致
openssl x509 -noout -modulus -in /etc/tomcat/ssl/fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in /etc/tomcat/ssl/privkey.pem   | openssl md5

# 2) 确认链顺序:第一张是叶证书,其后是中间证书,不能有重复
openssl crl2pkcs7 -nocrl -certfile /etc/tomcat/ssl/fullchain.pem | openssl pkcs7 -print_certs -noout

# 3) 真实握手:看协商到的协议与套件(-servername 触发 SNI)
openssl s_client -connect app.example.com:8443 -servername app.example.com -tls1_3 </dev/null 2>/dev/null | grep -E "Protocol|Cipher"

多域名共用 8443:多个 SSLHostConfig + SNI

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true" scheme="https" secure="true"
           maxThreads="200" connectionTimeout="20000">
  <!-- 客户端不带 SNI(老 JDK、部分爬虫)时回落到这张证书 -->
  <SSLHostConfig hostName="_default_" protocols="TLSv1.3,TLSv1.2">
    <Certificate certificateFile="/etc/tomcat/ssl/default/fullchain.pem"
                 certificateKeyFile="/etc/tomcat/ssl/default/privkey.pem" type="RSA" />
  </SSLHostConfig>
  <SSLHostConfig hostName="www.example.com" protocols="TLSv1.3,TLSv1.2">
    <Certificate certificateFile="/etc/tomcat/ssl/www/fullchain.pem"
                 certificateKeyFile="/etc/tomcat/ssl/www/privkey.pem" type="RSA" />
  </SSLHostConfig>
  <SSLHostConfig hostName="api.example.com" protocols="TLSv1.3,TLSv1.2">
    <Certificate certificateFile="/etc/tomcat/ssl/api/fullchain.pem"
                 certificateKeyFile="/etc/tomcat/ssl/api/privkey.pem" type="RSA" />
  </SSLHostConfig>
  <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
</Connector>

HTTP/2 依赖 ALPN,只有 Java 11+ 的 JSSE 才提供;Java 8 必须换成 tcnative(OpenSSL 实现)才会真的走 h2。验证只看一行:

curl -I --http2 https://app.example.com:8443/
# 生效:首行 HTTP/2 200;未生效:HTTP/1.1 200 OK(说明 ALPN 没谈成)

换成 Nginx 终止 TLS,Tomcat 只跑 8080

server {
    listen 443 ssl;
    http2 on;                 # Nginx 1.25.1+ 写法;旧版写 listen 443 ssl http2;
    server_name app.example.com;
    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    }
}

此时 Tomcat 侧必须加 Valve,否则 request.getScheme() 仍是 http,重定向会掉回明文、Secure Cookie 也发不出去:

<!-- conf/server.xml 的 <Host> 内 -->
<Valve className="org.apache.catalina.valves.RemoteIpValve"
       remoteIpHeader="x-forwarded-for"
       protocolHeader="x-forwarded-proto"
       protocolHeaderHttpsValue="https" />
方案 证书格式 HTTP/2 开销与适用场景
Tomcat JSSE 直连 8443 PEM / PKCS12 / JKS 需 UpgradeProtocol,且 Java 11+ TLS 在 JVM 内计算,省一层代理;适合单应用、内网服务
Tomcat + tcnative(OpenSSL) PEM(走 OpenSSL 引擎) 支持,ALPN 由 OpenSSL 提供,Java 8 也能 h2 高并发且不想加代理时的折中解,需装 libtcnative
Nginx 反代 443 → 8080 Nginx 侧 PEM Nginx 侧 http2 on,回源 HTTP/1.1 TLS 卸载、限流、静态资源全在 Nginx;多应用、统一证书时首选

证书配错时 Tomcat 的启动日志长这样,先看 Caused by 而不是第一行:

SEVERE [main] org.apache.catalina.core.StandardService.initInternal
  Failed to initialize connector [Connector[HTTP/1.1-8443]]
Caused by: java.io.IOException: ... (私钥与证书不匹配 / 文件不可读 / 别名不存在)

三处细节值得记住:type="RSA" 必须与私钥算法一致,ECC 证书要写 type="EC";ciphers 用冒号分隔的 OpenSSL 风格名称,Tomcat 会映射到 JSSE 套件,改完务必用上面的 s_client 实测;secure="true" 决定 request.isSecure(),反代场景下它由 RemoteIpValve 覆盖,别两处都改。

Tomcat HTTPS 配置方案对比:直接 8443、Nginx 反代与云负载均衡怎么选

做 tomcat https 配置时,第一个要拍板的不是命令怎么写,而是私钥最终落在哪一层:交给 Tomcat 的 Connector(方案 A/B),还是交给前置代理(方案 C/D/E)。这个决定一旦定下,证书格式、HTTP/2 的提供方、客户端真实 IP 的获取方式、续期后的重启动作全部随之确定,后面再改代价很高。五种方案的取舍见下表(Tomcat 9.0 / 10.1 通用,SSLHostConfig 自 8.5 起引入,9.0 起旧的 keystoreFile Connector 属性已废弃)。

方案 证书格式 Tomcat 侧改动 HTTP/2 来源 适用场景 复杂度 证书外成本
A. 直接 8443 + PEM fullchain.pem / privkey.pem SSLHostConfig + Certificate 加 Http2Protocol 小规模、内网、无前置代理 低 0 元
B. 直接 8443 + PKCS12/JKS .p12 / .jks certificateKeystoreFile/Pass 加 Http2Protocol 老 Java 系统、必须单进程 中 0 元
C. Nginx 终结 TLS + 8080 PEM RemoteIpValve Nginx 多站点、静态资源、WAF 中 0 元,Nginx 约 10–30 MB 内存
D. 云负载均衡 + 8080 PEM / PFX 上传 RemoteIpValve 云提供(含 QUIC) 高可用、弹性伸缩 低 约 0.02–0.1 元/小时 + LCU
E. httpd mod_ssl + 8080 PEM RemoteIpValve httpd 已有 Apache 体系 中 0 元

方案 A 是改动最小的路径。Tomcat 9.0 文档明确说明:未指定 certificateChainFile 时,certificateFile 会被当作包含完整链,所以 Let’s Encrypt 的 fullchain.pem 可以直接用,不必拆分。HTTP/2 走 ALPN 协商(RFC 9113),而 JSSE 的 ALPN 支持要到 JDK 8u252 才补齐,低于该版本启动 HTTPS 连接器会因 ALPN 不可用抛 IllegalArgumentException。

<!-- conf/server.xml,Tomcat 9.0/10.1 -->
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true" scheme="https" secure="true" maxThreads="200">
  <SSLHostConfig protocols="TLSv1.2,TLSv1.3">
    <!-- 显式写 type,避免自动推断 RSA/EC 失败 -->
    <Certificate certificateFile="conf/fullchain.pem"
                 certificateKeyFile="conf/privkey.pem"
                 type="RSA" />
  </SSLHostConfig>
  <!-- 不加这行就只协商到 HTTP/1.1 -->
  <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
</Connector>

方案 B 在运维上多一道验证:keytool -list -v 在 Java 8 默认按 JKS 解析,读 PKCS12 必须显式带 -storetype,否则报 java.io.IOException: Keystore was tampered with, or password was incorrect——很多人误以为是密码错了,其实是格式猜错。PEM 方案对应的验证用 openssl x509,两者都能查出有效期与 SAN,但都不支持热加载:证书续期后必须重启 Tomcat,窗口通常 10–30 秒,建议配双实例滚动重启。

# 方案 B:查看别名、有效期、签名算法
keytool -list -v -keystore conf/keystore.p12 -storetype PKCS12
# 方案 A:查看 SAN 与到期时间
openssl x509 -in conf/fullchain.pem -noout -subject -dates -ext subjectAltName
# 校验证书与私钥是否配对(两行输出应一致)
openssl x509 -in conf/fullchain.pem -noout -pubkey | openssl md5
openssl pkey -in conf/privkey.pem -pubout | openssl md5

方案 C/D/E 的共同坑是客户端 IP 和 scheme 丢失。Nginx 或云 LB 回源时只带 X-Forwarded-For,若不同时传 X-Forwarded-Proto,request.getScheme() 仍是 http,Spring Security 的 requiresChannel().requiresSecure() 会陷入重定向循环。更隐蔽的是 internalProxies:它的默认值只覆盖 RFC 1918 私有网段与回环地址,云厂商回源网段(如 100.64.0.0/10)不在其中,此时 getRemoteAddr() 拿到的是 LB 地址而非真实客户端,风控和审计日志全部失真。

<!-- 放在 <Host> 内;C/D/E 方案必配 -->
<Valve className="org.apache.catalina.valves.RemoteIpValve"
       remoteIpHeader="X-Forwarded-For"
       protocolHeader="X-Forwarded-Proto"
       protocolHeaderHttpsValue="https"
       internalProxies="10.d+.d+.d+|100.6[4-9].d+.d+|100.[7-9]d.d+.d+|100.1[0-2]d.d+.d+" />

选型上还有两条经验:一是 ACME 续期脚本要区分方案——A/B 用 certbot renew --deploy-hook "systemctl restart tomcat",C/D/E 则只需 reload Nginx 或把证书重新上传到云 LB,Tomcat 完全不用动;二是方案 D 的 HTTP/2 与 QUIC 由云侧提供,Tomcat 侧连 Http2Protocol 都不用加,但代价是 TLS 参数(密码套件、TLS 版本)只能跟随云厂商策略,无法按 Mozilla SSL Configuration Generator 的 Intermediate 档位逐项微调。

Tomcat HTTPS 配置常见报错:keystore 密码、PKIX、SAN 缺失怎么排

Tomcat 的 HTTPS 报错大多不是”证书坏了”,而是配置、路径、权限、链顺序四类问题。下面按真实报错信息逐条拆解,每条都给出可直接复制的验证命令。

为什么总提示 “Keystore was tampered with, or password was incorrect”?

本质是 keystorePass 与生成 keystore 时输入的密码不一致,而不是文件被篡改。先用 keytool 独立验证密码,把 Tomcat 从怀疑名单里排除:

# 验证 PKCS12 密码是否正确;能列出条目即密码无误
# 适用:Tomcat 9.0.x / 10.1.x 自带 JDK 8+ 的 keytool
keytool -list -keystore /etc/tomcat/ssl/app.p12 -storetype PKCS12

# 若报 "password was incorrect",说明密码错,而非文件损坏
# 从 Tomcat 9 起改用 PEM(server.xml 中 certificateFile + certificateKeyFile)时,
# 必须删除 keystoreFile / keystorePass / keystoreType,两套配置并存会互相覆盖
grep -nE 'keystoreFile|keystorePass|certificateFile' /opt/tomcat/conf/server.xml

Tomcat 9.0 默认 keystoreType 为 JKS,若文件实为 PKCS12 必须显式声明,否则同样报密码错误。

报 “No subject alternative names present” 怎么办?

现代客户端(Chrome 58+、Java 客户端、curl 7.65+)只认 SAN,不再回退到 CN——这是 RFC 6125 第 6.4.4 节的要求。先确认证书里到底有什么:

openssl x509 -text -noout -in /etc/tomcat/ssl/fullchain.pem 
  | grep -A1 'Subject Alternative Name'
# 期望输出包含:DNS:app.example.com, DNS:www.example.com
# 缺少目标域名只能重新签发,改 hosts 或忽略校验都不是修复

“PKIX path building failed” 是证书错了吗?

多数是服务器只发了 leaf 证书、没发中间证书。用 s_client 数一下返回张数:

openssl s_client -connect app.example.com:8443 -showcerts /dev/null 
  | grep -c 'BEGIN CERTIFICATE'
# 返回 1 表示链不完整(缺 intermediate),返回 2 及以上通常正常
# fullchain.pem 顺序必须是:leaf 证书在前,中间证书在后,根证书不要放

据 Let’s Encrypt 文档,其 fullchain.pem 已按此顺序拼接,直接使用即可;若手工 cat 拼接,顺序颠倒会触发同样的 PKIX 报错。

路径与权限类报错如何快速定位?

报 IllegalArgumentException: ... (No such file or directory) 时,八成是 tomcat 用户无读权限,而非路径拼错:

sudo -u tomcat cat /etc/tomcat/ssl/fullchain.pem >/dev/null && echo READ_OK
# 若失败:chown root:tomcat 并 chmod 640,私钥建议 640 而非 644
sudo ausearch -m avc -ts recent | grep tomcat   # SELinux 拒绝会出现在这里
# 或临时验证:setenforce 0 后重启,能起来即证实是 SELinux 标签问题

端口占用与连接被拒怎么区分?

报错 含义 排查命令
Address already in use: bind 8443 已被占用,Connector 起不来 ss -lntp | grep 8443;Windows:netstat -ano | findstr :8443
curl: (7) Connection refused 端口无监听:Connector 未启动或防火墙拦截 先查 logs/catalina.out 是否有 Failed to initialize end point,再查 firewall-cmd --list-ports 与云安全组

注意:Connection refused 是”没人监听”,防火墙丢包通常表现为 curl: (28) timed out,两者排查方向完全不同。改端口时记得同步 port="8444"、防火墙规则与云安全组三处。

Tomcat HTTPS 配置生效怎么验证?6 个检查点与命令输出

配置完 Connector 不等于 HTTPS 已经生效。Tomcat 的端口绑定、JSSE 握手、TLS 版本策略、证书链完整性是四个独立环节,任何一环出问题都可能表现为”页面能开但证书不对”或”外网完全连不上”。下面 6 个检查点按”从内核到应用层”的顺序排列,每一步都给出可直接复制的命令和判读标准,适用 Tomcat 9.0.x / 10.1.x(两者日志与 Connector 命名规则一致,10.1 要求 Java 11+,9.0 支持 Java 8+)。

检查点 1:端口到底监听在哪个地址上?

最常见的”本地能访问、外网访问不了”,根因是 Connector 里写了 address="127.0.0.1",或者 Tomcat 前面有 Apache/Nginx 时故意只监听回环。先看内核视角:

# 查看 8443 的监听地址与持有进程
ss -lntp | grep 8443

# 正确输出(监听所有地址,IPv4+IPv6 通配)
# LISTEN 0 100 *:8443 *:* users:(("java",pid=1234,fd=56))

# 危险输出(仅回环,外网不可达)
# LISTEN 0 100 127.0.0.1:8443 0.0.0.0:* users:(("java",pid=1234,fd=56))

判读要点:*:8443 或 0.0.0.0:8443 表示对外可达;127.0.0.1:8443 只接受本机连接。修正方式是编辑 conf/server.xml 中 <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol">,把 address 属性删除(默认即为所有网卡)或显式写 address="0.0.0.0"。注意 ss 显示的是实际绑定结果,能直接证伪”配置文件改过但没重启”这类问题——Tomcat 的 server.xml 修改必须重启,autoDeploy 只影响 webapp。

检查点 2:证书链和有效期对不对?

这一步绕开浏览器和 DNS,直接在回环上做 TLS 握手,并强制 SNI 与 TLS 1.3,避免拿到默认虚拟主机的证书:

openssl s_client -connect 127.0.0.1:8443 
  -servername app.example.com -tls1_3 -showcerts /dev/null 
  | openssl x509 -noout -subject -issuer -dates

# 期望输出示例
# subject=CN = app.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

三个关键判读:其一,issuer 必须是中间 CA(如 Let’s Encrypt 的 R3/R10、DigiCert 的 Intermediate),如果 issuer 等于 subject,说明你只导入了叶子证书、链不完整,Android 和老版本 Java 客户端会报 unable to find valid certification path;其二,notAfter 必须是未来时间,Let’s Encrypt 证书有效期 90 天(据 Let’s Encrypt 官方文档),过期前 30 天应自动续期;其三,在输出顶部确认 Protocol : TLSv1.3 和 Verify return code: 0 (ok)。Tomcat 的 SSLCertificateChainFile 属性自 8.5 起已废弃,正确做法是把中间证书拼接到 certificateFile 指向的 PEM 文件末尾(叶子在前、中间在后)。

检查点 3:应用层真的返回 200 吗?降级协议是否被拒绝?

# 正常路径:仅允许 TLS 1.3
curl -I --tlsv1.3 --tls-max 1.3 https://app.example.com:8443/
# HTTP/2 200   (需 Connector 配置 SSLEnabled="true" 且 HTTP/2 由默认 UpgradeProtocol 启用)

# 反向验证:TLS 1.1 必须失败
curl -I --tlsv1.1 --tls-max 1.1 https://app.example.com:8443/
# curl: (35) error:0A00042E:SSL routines::tlsv1 alert protocol version

如果第二条命令返回 200,说明 sslProtocol 仍包含 TLSv1/TLSv1.1。Tomcat 9.0/10.1 的默认值随 JVM 而定,sslEnabledProtocols 未显式配置时由 JSSE 决定,而 JDK 8u292+ 与 JDK 11 已默认禁用 TLS 1.0/1.1(参考 Oracle JDK 发布说明与 RFC 8996),但生产环境仍建议在 Connector 内显式写死 sslEnabledProtocols="TLSv1.3,TLSv1.2",不依赖 JVM 默认值。

检查点 4:密码套件里还有没有 RC4、3DES?

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

# 期望结果摘要
# TLSv1.3: TLS_AES_256_GCM_SHA384 / TLS_CHACHA20_POLY1305_SHA256 / TLS_AES_128_GCM_SHA256
# TLSv1.2: ECDHE-RSA-AES256-GCM-SHA384 等,grade: A
# TLSv1.1 / TLSv1.0: 不列出

这张扫描结果是排障时的对照基准,可直接对照 Mozilla Server Side TLS 指南的 Intermediate 配置。若出现 TLS_RSA_WITH_3DES_EDE_CBC_SHA 或 RC4 套件,需在 Connector 中设置 ciphers 属性;Tomcat 9.0 起该属性作用于 TLS 1.2 及以下,TLS 1.3 套件由 JSSE 独立管理,无法通过 ciphers 关闭,只能靠 jdk.tls.disabledAlgorithms 在 java.security 中调整。

检查点 5:浏览器为什么还显示”不安全”?

打开开发者工具 → Security 面板,正常状态显示 Certificate - valid and trusted,且 View certificate 中 SAN 包含实际访问的域名(现代浏览器已不看 CN,只认 SAN,依据 RFC 6125)。若显示 Not secure,按以下顺序排查:页面内仍有 http:// 的图片/脚本(混合内容,Chrome 对混合被动内容也会标记);应用内有 redirectPort 未生效导致 8080 回跳 http;或访问的是 IP 而证书只签了域名。

检查点 6:Tomcat 自己认了吗?

# 确认 HTTPS Connector 已启动,方括号内为 Connector 名称
grep -i 'Starting ProtocolHandler' logs/catalina.out
# 18-Mar-2025 10:12:33.456 INFO [main] org.apache.catalina.startup.Catalina.start
#   Starting ProtocolHandler ["https-jsse-nio-8443"]

# 确认请求确实落在 8443 上
tail -n 20 logs/localhost_access_log.2025-03-18.txt

https-jsse-nio-8443 这个名字由协议实现 + 端口自动生成,若只看到 http-nio-8080,说明 Connector 因证书路径错误或密码错误未能初始化,往上翻日志会看到 java.io.IOException: Keystore was tampered with, or password was incorrect 或 Alias name [tomcat] does not identify a key entry。最后用 Qualys SSL Labs 在线扫描做外部复核,通常 1–3 分钟出结果,理想评级为 A 或 A+(A+ 需启用 HSTS,这属于应用层响应头而非 Tomcat 配置)。

Tomcat HTTPS 配置上线后的运维:TLS 1.3、证书续期与监控

证书明明续期成功了,为什么浏览器还是提示过期?

因为 Tomcat 的 Connector 只在初始化阶段读取 certificateFile / certificateKeyFile,运行期不监听文件变化,也没有 reload 钩子。据 Tomcat 9 官方文档,SSLHostConfig 与 Certificate 的属性仅在 Connector 启动时生效——所以续期只完成了“文件更新”,重启才完成“生效”。这一条是 Tomcat HTTPS 配置里最容易在半年后翻车的坑。

certbot 和 acme.sh 怎么把重启串进续期流程?

# certbot:先空跑验证钩子,不会真的续期
certbot renew --dry-run --deploy-hook 'systemctl restart tomcat'

# 生产写法:写入 /etc/letsencrypt/cli.ini(certbot 2.x 起仍兼容)
# deploy-hook = systemctl restart tomcat
# 注意 --deploy-hook 仅在证书真正续期成功时触发,--post-hook 则每次 renew 都触发

# acme.sh:--install-cert 会把 reloadcmd 持久化到 ~/.acme.sh/app.example.com/app.example.com.conf
acme.sh --install-cert -d app.example.com 
  --key-file       /etc/tomcat/tls/app.key 
  --fullchain-file /etc/tomcat/tls/app.crt 
  --reloadcmd      "systemctl restart tomcat"

Let’s Encrypt 证书有效期 90 天,官方建议每 60 天续期一次(certbot 的 systemd timer 默认每日两次检查,剩余 30 天内才真正续)。重启窗口按 webapp 数量与 JSP 预编译量估算,单实例冷重启通常 10–30 秒,这期间 8443 端口直接拒绝连接;要求零停机就得前置 Nginx/HAProxy 摘节点再重启。

多实例怎么批量重启又不漏验证?

# 1. 串行滚动重启,避免同时摘掉全部节点
ansible tomcat -i inventory.ini -m shell -a "systemctl restart tomcat" --serial 1

# 2. 逐台验证:既看证书有效期,也看应用是否真的起来了
for h in app01 app02; do
  echo | openssl s_client -connect $h:8443 -servername app.example.com 2>/dev/null 
    | openssl x509 -noout -subject -dates
  curl -sS -o /dev/null -w "$h HTTP %{http_code}n" https://$h:8443/
done

怎么在到期前就收到告警?

# 2592000 秒 = 30 天;退出码 0 表示仍在有效期内,1 表示即将到期
echo | openssl s_client -connect app.example.com:8443 -servername app.example.com 2>/dev/null 
  | openssl x509 -noout -checkend 2592000
# 输出 "Certificate will expire" 即 30 天内到期,应立刻介入
方案 采集方式 建议阈值 适用场景
openssl + shell -checkend 2592000 30 天 单机、发布脚本内嵌
Prometheus blackbox_exporter (probe_ssl_earliest_cert_expiry - time())/86400 < 21 21 天 多实例、已有 Prometheus
Zabbix 自定义 item 调 openssl,或 web.page.get 取 8443 30 天 传统运维体系

TLS 1.3 下还要不要设 honorCipherOrder?

据 RFC 8446 与 Mozilla SSL Configuration Generator,TLS 1.3 的套件协商顺序由客户端给出,Tomcat 文档也注明 honorCipherOrder(默认 false)只对 TLS 1.2 及以下生效。真正影响兼容性的是 TLS 1.2 套件列表和证书链是否完整(fullchain 而非 cert)。加固写法:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true">
  <!-- protocols 白名单:不写 TLSv1/TLSv1.1;ciphers 中不列 RC4/3DES 即视为禁用 -->
  <SSLHostConfig protocols="TLSv1.3,TLSv1.2"
                 ciphers="TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384"
                 honorCipherOrder="false">
    <Certificate certificateFile="/etc/tomcat/tls/app.crt"
                 certificateKeyFile="/etc/tomcat/tls/app.key" type="RSA" />
  </SSLHostConfig>
</Connector>

HSTS 放在 Tomcat 侧就启用 HttpHeaderSecurityFilter(conf/web.xml 中默认被注释)。注意 hstsMaxAgeSeconds 默认值是 0,等于不发头,必须显式改成 31536000;hstsIncludeSubDomains 默认 false,只有在确认全部子域都支持 HTTPS 后才打开,否则会把明文子域锁死。用 Nginx 反代时加一行 add_header Strict-Transport-Security "max-age=31536000" always; 更省事。

改 server.xml 前后怎么复核?

cp -a $CATALINA_BASE/conf/server.xml $CATALINA_BASE/conf/server.xml.bak.$(date +%F)
# ...编辑...
diff -u $CATALINA_BASE/conf/server.xml.bak.$(date +%F) $CATALINA_BASE/conf/server.xml

发布 checklist 至少包含三步:diff -u 复核改动、重启后 openssl s_client -connect ... -servername ... 确认协商到 TLSv1.3 且证书为最新序列号、curl -sSI https://app.example.com/ 确认 200 与 HSTS 头存在。只重启不验证,是 Tomcat HTTPS 配置上线后最常见的“以为好了”。

基本一样,都用 SSLHostConfig + Certificate,Connector 类名仍是 org.apache.coyote.http11.Http11NioProtocol。Tomcat 10.1 的包名是 jakarta.*,要求 Java 11+;Tomcat 9 可跑 Java 8,但 TLS 1.3 要 Java 11+。

可以,Tomcat 8.5+ 的 certificateFile/certificateKeyFile 支持 PEM。fullchain.pem 放 certificateFile,privkey.pem 放 certificateKeyFile,权限设 600,续期后重启 Tomcat 即可。

先本机执行 ss -lntp | grep 8443 看监听地址,再 curl -I https://127.0.0.1:8443/ 验证 Connector。若只有 127.0.0.1 监听,改 Connector 的 address 或删掉 address;若本机通外网不通,查 firewalld、iptables 与云安全组。

用 openssl s_client -connect app.example.com:8443 -showcerts 看返回链,fullchain.pem 应 leaf 在前、intermediate 在后。不要只配 leaf,也不要重复拼 chain;Java 客户端报 PKIX path building failed 时优先查链。

不需要对外暴露 8443,Nginx 终结 TLS 后 proxy_pass 到 8080 即可。但 Tomcat 要加 RemoteIpValve 读取 X-Forwarded-Proto,否则 request.getScheme() 仍是 http,应用生成的绝对 URL 会出错。

需要,Tomcat 不会自动 reload certificateFile。用 certbot –deploy-hook 或 acme.sh –reloadcmd 触发 systemctl restart tomcat,重启后用 openssl s_client 检查 notAfter 是否更新。

TLS 握手开销主要在密钥交换,Tomcat JSSE 与 Nginx OpenSSL 都能跑 TLS 1.3。静态资源多、并发高时 Nginx 前置更常见;Tomcat 直连 8443 适合小规模或内网,具体差异要用 ab/wrk 在目标机型压测,不能只看理论值。


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

内容审核

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