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 覆盖,别两处都改。
- SSL/HTTPS 证书配置 · 证书安装 · 证书申请
- SSL证书申请 · SSL证书购买 · SSL证书安装配置
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。