Tomcat 强制 HTTPS 怎么做?redirectPort、security-constraint 与反向代理三层配置指南
Tomcat 强制 HTTPS 不能只改 redirectPort:必须同时启用 8443 Connector、在 8080 上配置 redirectPort='8443',并用 web.xml 的 security-constraint(transport-guarantee=CONFIDENTIAL)或 Spring Security 的 requiresChannel() 触发跳转,否则 http:// 仍返回 200 明文。 Tomcat 9.0.x 默认 server.xml 中 8080 Connector 已带 redirectPort='8443',但 8443 Connector 默认被注释,未启用时跳转目标直接连接失败。 反向代理场景下,Nginx 必须加 proxy_set_header X-Forwarded-Proto $scheme,并在 Tomcat 配置 RemoteIpValve 的 protocolHeader='X-Forwarded-Proto',否则应用反复 302 造成 ERR_TOO_MANY_REDIRECTS。 验证命令:curl -sSI http://example.com/ 应返回 302 且 Location 为 https://;curl -sSI https://example.com/ 应返回 200 并带 Strict-Transport-Security: max-age=31536000。 Tomcat 10.1 要求 Java 11+、Servlet 6.0(jakarta.* 命名空间),Tomcat 11 要求 Java 17+;security-constraint 语法在 8.5/9.0/10.1/11 中保持一致。
为什么改了 redirectPort 还是明文?Tomcat 强制 HTTPS 失效的 5 个根本原因
很多人把 redirectPort 当成”HTTP 自动跳 HTTPS 的开关”,改完重启发现 http://host:8080/ 依然返回 200 明文。这是对 Tomcat 配置语义的误读:据 Tomcat 9 文档《SSL/TLS Configuration HOW-TO》,redirectPort 只声明”当请求被判定为需要安全传输时,把客户端指向哪个端口”,它本身不产生任何 302。下面按排查顺序拆开 5 个根本原因。
原因 1:缺少 CONFIDENTIAL 约束,跳转永远不会被触发。跳转的触发源是 Servlet 规范(Jakarta Servlet 6.0 第 13 章)里的 transport-guarantee,不是 Connector。默认 conf/server.xml 中 8080 段落写作 <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />,必须配合 web.xml 才会生效:
<!-- WEB-INF/web.xml:Tomcat 9/10/11 通用,容器据此把 http 请求 302 到 redirectPort -->
<security-constraint>
<web-resource-collection>
<web-resource-name>All</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee> <!-- 关键行:CONFIDENTIAL/INTEGRAL 才触发跳转 -->
</user-data-constraint>
</security-constraint>
用框架的等价做法是判断 request.isSecure()==false 后主动重定向,例如 Spring Security 6 的 http.requiresChannel(c -> c.anyRequest().requiresSecure())。
原因 2:8443 Connector 根本没启用。这是最常见的”半成品”配置——Tomcat 9.0.x 默认 server.xml 里 8443 段落整段被注释。跳转虽然发出去了,落点却是死端口,浏览器直接连接失败,catalina.out 常见报错为 java.io.FileNotFoundException: /etc/tomcat/keystore.jks (No such file or directory)。启用前先确认证书文件存在:
# 生成自签测试证书(生产请用 Let's Encrypt/certbot 或 CA 签发证书)
keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -validity 365
-keystore conf/keystore.jks -storepass changeit -dname "CN=example.com"
# 验证 8443 是否真的在监听 TLS
openssl s_client -connect 127.0.0.1:8443 -servername example.com </dev/null | openssl x509 -noout -subject -dates
原因 3:反向代理丢头,Tomcat 仍认为 scheme=http。Nginx 终止 TLS 后转发到 8080,若未带 X-Forwarded-Proto,Tomcat 的 request.getScheme() 返回 http,应用层再 302 到 https,形成死循环,浏览器报 ERR_TOO_MANY_REDIRECTS。Cloudflare 的 SSL/TLS 模式设为 Flexible 时复现同一现象(源站收到的就是 HTTP)。修复:
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;
}
同时在 server.xml 的 <Host> 内加 <Valve className="org.apache.catalina.valves.RemoteIpValve" remoteIpHeader="X-Forwarded-For" protocolHeader="X-Forwarded-Proto" />,让 isSecure() 返回正确值。
| # | 根本原因 | 典型现象 | 一行验证 | 修复动作 |
|---|---|---|---|---|
| 1 | 无 transport-guarantee | 8080 返回 200 明文 | curl -sSI http://127.0.0.1:8080/ |
web.xml 加 CONFIDENTIAL |
| 2 | 8443 Connector 被注释 | 跳转后连接被拒 | ss -lntp | grep 8443 |
启用 SSL Connector + keystore |
| 3 | 代理缺 X-Forwarded-Proto | ERR_TOO_MANY_REDIRECTS | curl -sSI -H 'X-Forwarded-Proto: https' … |
Nginx 加头 + RemoteIpValve |
| 4 | 应用层与容器层双重跳转 | 302 链路叠加 2 次 | 看 Location 是否二次跳转 |
只保留一层强制 HTTPS |
| 5 | HSTS 未启用 | 每次首跳多 1 RTT | curl -sSI https://… | grep -i strict |
加 Strict-Transport-Security |
原因 4/5:双重跳转与缺少 HSTS。容器层 security-constraint 与应用层 requiresSecure() 同时开启时,第一次 302 可能被再跳一次;建议只保留一层(有反向代理时通常在 Nginx 做 301,Tomcat 只认 X-Forwarded-Proto)。性能上,一次 302 多消耗 1 个 RTT,移动网络实测约 100–300 ms;按 RFC 6797 下发 Strict-Transport-Security: max-age=31536000; includeSubDomains 后,浏览器后续请求直接走 HTTPS,但首次访问仍无法省掉这次跳转——所以 tomcat 强制https 的完整方案应是”301 跳转 + HSTS + 后端只信任代理头”三层配合,而不是改一个 redirectPort。
最后用一条命令确认整条链路:curl -sSI http://example.com/ | head -3,期望输出 HTTP/1.1 301 且 Location: https://example.com/;若仍是 200,回到上表逐行核对。
Tomcat 强制 HTTPS 完整实操:从证书到 8443 Connector 的 7 个步骤
证书有了、Connector 开了,不等于 HTTPS 被强制。Tomcat 的强制跳转由 redirectPort 与 security-constraint 配合完成:前者只声明“该跳到哪个端口”,后者才真正触发 302。下面按依赖顺序给出可直接复制的 7 步,适用于 Tomcat 9 / 10.1 / 11(Servlet 4.0–6.0)与 Spring Boot 内嵌 Tomcat。
第 1 步:用 certbot 签发证书。据 Let’s Encrypt 文档,证书有效期固定 90 天,官方建议在剩余 30 天时续期,certbot 的 systemd timer 默认即按此窗口执行。
# standalone 模式需临时占用 80 端口做 HTTP-01 校验,先停掉占用 80 的服务
systemctl stop nginx # 若已有 Nginx,改用 --webroot -w /var/www/html
certbot certonly --standalone -d example.com -d www.example.com
ls /etc/letsencrypt/live/example.com/
# cert.pem chain.pem fullchain.pem privkey.pem
# fullchain.pem = 站点证书 + 中间证书,Tomcat 必须用这个而不是 cert.pem
certbot renew --dry-run # 演练续期,确认钩子与端口放行无误
第 2 步:转成 PKCS12 密钥库。Tomcat 9 的 keystoreType 默认值仍是 JKS,但官方文档推荐 PKCS12;JDK 9 起 keytool 的默认格式也已切换为 PKCS12。
openssl pkcs12 -export
-in /etc/letsencrypt/live/example.com/fullchain.pem
-inkey /etc/letsencrypt/live/example.com/privkey.pem
-out /etc/tomcat/tomcat.p12
-name tomcat
-CAfile /etc/letsencrypt/live/example.com/chain.pem -caname root
-password pass:ChangeIt
# -name tomcat 生成的 alias 必须与 Connector 的 keyAlias 一致
chown tomcat:tomcat /etc/tomcat/tomcat.p12 && chmod 600 /etc/tomcat/tomcat.p12
openssl pkcs12 -info -in /etc/tomcat/tomcat.p12 -password pass:ChangeIt -noout
| 维度 | JKS | PKCS12 |
|---|---|---|
| OpenSSL 直接读写 | 不支持 | 支持(openssl pkcs12) |
| JDK 9+ keytool 默认格式 | 否 | 是 |
| Tomcat 支持版本 | 全部版本 | 8.5 及以上 |
| 证书链存储 | 需先 import 中间证书 | 导出时随 -CAfile 一并写入 |
第 3 步:启用 8443 Connector。编辑 $CATALINA_BASE/conf/server.xml,放在 Service 节点内:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
SSLEnabled="true" scheme="https" secure="true"
maxThreads="200" acceptCount="100"
sslEnabledProtocols="TLSv1.2,TLSv1.3"
keystoreFile="/etc/tomcat/tomcat.p12"
keystoreType="PKCS12" keystorePass="ChangeIt" keyAlias="tomcat"
clientAuth="false" sslProtocol="TLS"/>
<!-- maxThreads 默认 200,acceptCount 默认 100,均为 Tomcat HTTP Connector 文档默认值 -->
<!-- sslEnabledProtocols 留空则沿用 JVM 默认;显式写死可避免 JDK 升级带来的协议漂移 -->
第 4 步:对齐 8080 的 redirectPort。Tomcat 文档明确:redirectPort 是收到需要机密传输的请求后跳转的目标端口。若你把 8443 改成 9443 却漏改这里,302 的 Location 会指向错误端口,浏览器表现为连接被拒。
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443"/>
<!-- 8443 → 9443 时,此处的 8443 必须同步改成 9443 -->
第 5 步:加应用级开关 security-constraint。写入 WEB-INF/web.xml 的 <web-app> 内部,Servlet 3.1/4.0/5.0/6.0 语法完全一致:
<security-constraint>
<web-resource-collection>
<web-resource-name>Entire Application</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<!-- transport-guarantee 取值:NONE(默认)/ INTEGRAL / CONFIDENTIAL,后两者都触发跳转 -->
第 6 步:重启并验证跳转。包名因发行版而异:RHEL/CentOS 为 tomcat,Debian/Ubuntu 为 tomcat9 或 tomcat10。
systemctl restart tomcat9
tail -f /var/log/tomcat9/catalina.out
# 成功标志:Server startup in [xxxx] milliseconds
curl -I http://example.com:8080/
# HTTP/1.1 302
# Location: https://example.com:8443/
curl -I https://example.com:8443/ --insecure
# 若误用 https 访问 8080,会得到:javax.net.ssl.SSLException: Unrecognized SSL message, plaintext connection?
第 7 步:Spring Boot 内嵌 Tomcat。server.port 只管主 Connector,8080 必须靠 addAdditionalTomcatConnectors 补上,并用 postProcessContext 注入约束——这正是 Spring Boot 中实现 tomcat 强制https 的等价写法。
# application.properties
server.port=8443
server.ssl.enabled=true
server.ssl.key-store=/etc/tomcat/tomcat.p12
server.ssl.key-store-type=PKCS12
server.ssl.key-store-password=ChangeIt
server.ssl.key-alias=tomcat
// 配置类:追加 8080 并绑定 redirectPort
@Bean
public TomcatServletWebServerFactory servletContainer() {
TomcatServletWebServerFactory factory = new TomcatServletWebServerFactory() {
@Override
protected void postProcessContext(Context context) { // Context = org.apache.catalina.Context
SecurityConstraint c = new SecurityConstraint();
c.setUserConstraint("CONFIDENTIAL");
SecurityCollection col = new SecurityCollection();
col.addPattern("/*");
c.addCollection(col);
context.addConstraint(c);
}
};
Connector http = new Connector(TomcatServletWebServerFactory.DEFAULT_PROTOCOL);
http.setPort(8080);
http.setScheme("http");
http.setSecure(false);
http.setRedirectPort(8443); // 与 server.port 保持一致
factory.addAdditionalTomcatConnectors(http);
return factory;
}
注意:Spring Boot 3.x 的包名为
jakarta.servlet.*,而org.apache.catalina.Context、org.apache.tomcat.util.descriptor.web.SecurityConstraint不变;postProcessContext是TomcatServletWebServerFactory的 protected 钩子,仅在自定义子类中生效,不要在 lambda 里调用super之外的同名方法。
Tomcat 强制 HTTPS 配置示例:server.xml、web.xml、HSTS 与 RewriteValve 参数
Tomcat 强制 HTTPS 的落地通常要在三层同时配置:Connector 层(让 Tomcat 认识 TLS 与真实协议)、应用层(security-constraint 或 Spring Security 把 http 请求挡回去)、边缘层(Nginx / HSTS 兜底)。只做其中一层,常见结果是 302 循环或混合内容告警。下面按文件给出可直接复制的片段,适用于 Tomcat 9.0.x 与 10.1.x(Catalina 组件名一致)。
1. server.xml:8443 Connector 怎么写
关键不是证书路径,而是 scheme="https" secure="true"——它们决定 request.isSecure() 与 request.getScheme() 的返回值,security-constraint 和 Spring 的 requiresSecure() 都依赖这个判断。据 Tomcat 官方 HTTP Connector 文档,sslEnabledProtocols 在 Tomcat 9 起建议改用 sslEnabledProtocols 的继任属性 SSLProtocol(JSSE 实现下二者等价),默认值为 TLSv1.2,TLSv1.3(Tomcat 9.0.30+ 起 JSSE 默认禁用 TLS1.0/1.1)。
<!-- conf/server.xml:8443 端口 + PKCS12 密钥库 -->
<Connector port="8443"
protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="200"
SSLEnabled="true"
scheme="https" secure="true" <!-- 让 isSecure() 返回 true,务必显式写 -->
keystoreFile="/etc/tomcat/tomcat.p12"
keystoreType="PKCS12" <!-- JKS 已不推荐;p12 由 keytool -importkeystore 生成 -->
keystorePass="ChangeIt" <!-- 生产建议改用 SSLPassword 或 environment variable -->
clientAuth="false" <!-- 默认 false;双向认证才设 true/want -->
sslEnabledProtocols="TLSv1.2,TLSv1.3" />
注意 port="8443" 不是强制项,若前面有 Nginx 终止 TLS,Tomcat 只需监听 8080 并在 Connector 上加 proxyPort="443" scheme="https" secure="true" 即可,无需 keystore。
2. web.xml:security-constraint 的 CONFIDENTIAL 语义
<!-- WEB-INF/web.xml:任何 http 访问都会被容器 302 到 https 同路径 -->
<security-constraint>
<web-resource-collection>
<web-resource-name>Entire App</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
Servlet 规范(Jakarta Servlet 6.0, §13.8.1)规定 CONFIDENTIAL 表示传输需保证数据完整性,Tomcat 的实现是返回 302 重定向到 redirectPort(默认 443,取自该 Connector 的 redirectPort 属性),不会发 301。SEO 场景想要 301 必须换方案。
3. 四种强制跳转方案怎么选
| 方案 | 状态码 | 生效范围 | 适用/限制 |
|---|---|---|---|
| web.xml security-constraint | 302 | 整个 Web 应用 | 零依赖;无法自定义状态码,静态资源也走容器跳转 |
| RewriteValve | 可指定 301 | 按 Host/Context | 需 rewrite.config;适合要 301 保权重的站点 |
| Spring Security 6 | 302(可配) | Spring 应用 | 与 web.xml 方案二选一,同时管 HSTS |
| Nginx 边缘跳转 | 301 | 全站 | Tomcat 完全不用感知 TLS,最省 CPU |
4. RewriteValve:需要 301 时用它
先确认 conf/Catalina/localhost/ROOT.xml 存在(没有就新建),再加 Valve 与规则文件。RewriteValve 默认 useQueryString="false",若原 URL 带参数需显式设 true 才能保留 query。
<!-- conf/Catalina/localhost/ROOT.xml -->
<Context>
<Valve className="org.apache.catalina.valves.rewrite.RewriteValve" />
</Context>
# WEB-INF/rewrite.config(或 conf/Catalina/localhost/rewrite.config)
RewriteCond %{HTTPS} !=on
RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L] # L 停止后续规则,R=301 永久跳转
反代场景下 %{HTTPS} 会恒为 off(Tomcat 看到的是明文),必须配合下节的 RemoteIpValve 才有意义。
5. Nginx + RemoteIpValve:让 Tomcat 知道“外面是 HTTPS”
# nginx.conf:server 段内,upstream 指向 8080
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme; # Tomcat 据此判定 scheme=https
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
<!-- server.xml 的 <Host> 内,只信任内网代理 -->
<Valve className="org.apache.catalina.valves.RemoteIpValve"
protocolHeader="X-Forwarded-Proto"
protocolHeaderHttpsValue="https"
remoteIpHeader="X-Forwarded-For"
internalProxies="10.d+.d+.d+|127.0.0.1" />
据 Tomcat Valve 文档,internalProxies 默认是 10.d{1,3}.d{1,3}.d{1,3}|192.168.d{1,3}.d{1,3}|169.254.d{1,3}.d{1,3}|127.d{1,3}.d{1,3}.d{1,3}|172.1[6-9].…|172.2d.…|172.3[01].…|0:0:0:0:0:0:0:1;公网直连 Tomcat 时必须显式收窄,否则任何客户端都能伪造 X-Forwarded-Proto 绕过 HTTPS 检查。
6. HSTS:HttpHeaderSecurityFilter 的参数与默认值
Tomcat 自带 org.apache.catalina.filters.HttpHeaderSecurityFilter,据其 Javadoc,hstsMaxAgeSeconds 默认 0(即不下发 HSTS 头),hstsIncludeSubDomains 默认 false,hstsPreload 默认 false。所以“加了 Filter 就自动 HSTS”是错的,必须显式赋值。
<!-- WEB-INF/web.xml:放在 security-constraint 之后 -->
<filter>
<filter-name>httpHeaderSecurity</filter-name>
<filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
<init-param><param-name>hstsMaxAgeSeconds</param-name><param-value>31536000</param-value></init-param>
<init-param><param-name>hstsIncludeSubDomains</param-name><param-value>true</param-value></init-param>
<init-param><param-name>hstsPreload</param-name><param-value>false</param-value></init-param>
<!-- 同时下发 antiClickJacking / X-Content-Type-Options 等,blockContentTypeSniffingEnabled 默认 true -->
</filter>
<filter-mapping>
<filter-name>httpHeaderSecurity</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
HSTS 一旦下发,浏览器在 max-age 内会拒绝任何 http 连接;preload 会写入 Chrome 的 HSTS Preload List,撤销需数月。据 Let’s Encrypt 与 hstspreload.org 的说明,申请 preload 要求 max-age ≥ 31536000、含 includeSubDomains、且所有子域已支持 https,因此“确认全站 https 后再考虑”不是保守,而是硬性条件。
7. Spring Security 6 的等价写法
// Spring Security 6.x:与 web.xml 方案二选一,勿重复
http.requiresChannel(c -> c.anyRequest().requiresSecure()) // 非 https 请求 → 302 跳转
.headers(h -> h.httpStrictTransportSecurity(s ->
s.includeSubDomains(true)
.maxAgeInSeconds(31536000)
.preload(false))); // preload 默认 false
注意 requiresSecure() 在反向代理后同样依赖 X-Forwarded-Proto;Spring Boot 3 需设 server.forward-headers-strategy=native(Tomcat 下等价于启用 RemoteIpValve)或 framework,否则会被判为 http 而陷入重定向循环——这是“Tomcat 强制 https”最常见的线上故障。
Tomcat 强制 HTTPS 五种方案对比:该在 Connector、应用还是代理层做?
先回答最常被搜到的那个问题:只改 redirectPort 为什么 http 访问还是 200?因为 redirectPort(Tomcat 默认 8443)只是一个“目标端口声明”,它仅在请求命中 security-constraint 的 CONFIDENTIAL 约束、或应用内部调用 response.sendRedirect() 需要安全跳转时才被读取。据 Apache Tomcat 官方文档,单独修改该属性不会产生任何跳转。想真正实现 tomcat 强制https,必须让某一层主动发出 3xx。
| 方案 | 生效层 | 状态码 | 代理场景 | 典型坑 |
|---|---|---|---|---|
| 仅改 redirectPort | Connector | 无跳转 | 不适用 | 不触发,http 仍 200 |
| security-constraint | 应用(web.xml) | 302 | 需 X-Forwarded-Proto | 静态资源也会跳,注意排除健康检查 |
| RewriteValve | Connector/Valve | 可指定 301 | 需排除 /health | 规则写错易循环 |
| Nginx / ALB 301 | 代理层 | 301 | 天然支持 | 内网直连 8080 仍明文 |
| Spring Security requiresChannel | 应用框架 | 302 | 需 forward-headers-strategy | 只覆盖 Spring 管理的路径 |
Tomcat 8.0 起 RewriteValve 已内置到核心包(无需再放 rewrite.jar),在 conf/context.xml 或 META-INF/context.xml 中声明后读取 WEB-INF/rewrite.config:
<!-- $CATALINA_BASE/conf/context.xml,对所有应用生效;Tomcat 8.5/9/10/11 通用 -->
<Context>
<Valve className="org.apache.catalina.valves.rewrite.RewriteValve" />
</Context>
# WEB-INF/rewrite.config —— 用 301 便于 CDN/浏览器缓存
RewriteCond %{HTTPS} !=on
RewriteCond %{REQUEST_URI} !^/health$ # 排除探针,否则 kubelet 收到 301 判活失败
RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]
若前面有 Nginx 或 ALB,Tomcat 看到的 scheme 永远是 http,此时需启用 RemoteIpValve 让 %{HTTPS} 与 request.isSecure() 正确反映真实协议(protocolHeader 默认 X-Forwarded-Proto,protocolHeaderHttpsValue 默认 https):
<!-- server.xml 的 <Host> 内 -->
<Valve className="org.apache.catalina.valves.RemoteIpValve"
remoteIpHeader="X-Forwarded-For"
protocolHeader="X-Forwarded-Proto" />
# Nginx 侧优先做 301(RFC 9110 定义 301 为可缓存永久重定向)
server {
listen 80;
server_name example.com;
return 301 https://$host$request_uri;
}
怎么选?只面向公网且已有 Nginx/ALB,优先在代理层做 301,再用 security-constraint 兜底形成双层防护,避免内网直连 8080 漏明文;需要严格 301 缓存语义时选 RewriteValve 或代理层——security-constraint 在 Tomcat 中返回 302,短期可接受,长期建议配合 HSTS(Mozilla 建议 max-age 至少 6 个月,首次上线先用短值灰度)减少跳转次数。多应用共用 Tomcat 时,约束写在每个应用的 WEB-INF/web.xml,或写进 conf/web.xml 全局生效——注意后者会连带 /manager 与 /host-manager,需同步调整访问策略。Kubernetes Ingress 场景:设 ssl-redirect: "true" 后,Tomcat 侧保留约束时必须确保 Ingress 传递 X-Forwarded-Proto,否则 Pod 内应用会陷入循环跳转。
Nginx / ALB 已经把 HTTP 跳成 HTTPS 了,为什么 Tomcat 还在跳,甚至死循环?
因为 Tomcat 判断协议时只看自己 connector 的 scheme。反向代理回源到 8080 走的是明文 HTTP,Tomcat 里 request.getScheme() 就是 http、request.isSecure() 是 false;此时如果 security-constraint 声明了 CONFIDENTIAL,Tomcat 会按 redirectPort 再跳一次 https,代理层再把它降回 http,于是一圈接一圈。据 Tomcat 官方文档,RemoteIpValve 正是用来消费 X-Forwarded-Proto 并改写 isSecure() / getScheme() 的组件——不装它,代理层做多少跳转都没用。
internalProxies 默认信任哪些网段?为什么常常“配了也不生效”?
Tomcat 9.0.x / 10.1.x 的默认值是下面这条正则(源码里写死在 RemoteIpValve):
10.d{1,3}.d{1,3}.d{1,3}|192.168.d{1,3}.d{1,3}|169.254.d{1,3}.d{1,3}|127.d{1,3}.d{1,3}.d{1,3}|172.1[6-9]{1}.d{1,3}.d{1,3}|172.2[0-9]{1}.d{1,3}.d{1,3}|172.3[0-1]{1}.d{1,3}.d{1,3}|0:0:0:0:0:0:0:1|::1
只要请求的直连来源 IP不匹配这条正则,Valve 就直接忽略 X-Forwarded-Proto,scheme 仍是 http,tomcat 强制 https 的跳转自然失效或进入循环。公网 ALB、云厂商 NAT 出口、K8s NodePort 回源都经常落在这条正则之外。关键坑:一旦显式写 internalProxies,它会整体替换默认值,本机和内网段必须一起补上。
<!-- conf/server.xml,Tomcat 9.0.x / 10.1.x 通用;放在 <Host> 或 <Engine> 内 -->
<Valve className="org.apache.catalina.valves.RemoteIpValve"
internalProxies="10.0.0.d{1,3}|172.20.d{1,3}.d{1,3}|127.0.0.1"
remoteIpHeader="X-Forwarded-For" <!-- 默认 x-forwarded-for -->
protocolHeader="X-Forwarded-Proto" <!-- 默认 x-forwarded-proto,大小写不敏感 -->
protocolHeaderHttpsValue="https" <!-- 默认 https,匹配即视为安全 -->
portHeader="X-Forwarded-Port" <!-- 默认 x-forwarded-port -->
hostHeader="X-Forwarded-Host" <!-- 默认 x-forwarded-host -->
requestAttributesEnabled="true" /> <!-- 默认 false;开启后 remoteAddr 等属性被改写 -->
Spring Boot 3.x 还要不要自己在 server.xml 里写 Valve?
内嵌 Tomcat 时用 server.forward-headers-strategy 即可,三种取值的实际效果差别很大,选错就会与手写 Valve 打架:
- SSL/HTTPS 证书配置 · 证书安装 · 证书申请
- SSL域名证书申请 · 小程序证书 · 国外SSL证书
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
| 取值 | 实际启用的组件 | 是否还需 server.xml 配 Valve | 说明 |
|---|---|---|---|
none(默认) |
无 | 需要,否则 scheme 恒为 http | 默认值,代理场景下 tomcat 强制https 必然失效 |
native |
Tomcat RemoteIpValve(自动注册) |
不要,重复注册会互相覆盖 | 推荐;等价于手写 Valve,改 internalProxies 仍需在 server.xml 或 TomcatServletWebServerFactory 中补 |
framework |
Servlet 侧 ForwardedHeaderFilter / WebFlux 侧 ForwardedHeaderTransformer |
不要 | 在应用层包一层 request 包装器,Tomcat 层 scheme 不变 |
native 与 framework 同时生效时,scheme 判断可能被后者覆盖回 http,表现为“配了还在循环”——二者只能选一个。
AWS ALB 场景怎么落地?
- ALB 只保留 443 监听,默认规则配 301 跳到 https,80 监听直接拒绝或同样 301;
- Tomcat 8443 不对外暴露,安全组仅允许 ALB 网段访问 8080;
- 健康检查路径用
/health,并在security-constraint里用transport-guarantee=NONE单独排除,否则健康检查拿到 302 会被判定为 unhealthy:
<!-- web.xml:/health 不强制 HTTPS,供 ALB 探活 -->
<security-constraint>
<web-resource-collection>
<web-resource-name>health</web-resource-name>
<url-pattern>/health</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
Cloudflare 上为什么会无限 302?
必须用 Full (strict),不能用 Flexible。Flexible 下 Cloudflare 回源是 http,Tomcat 看到 scheme=http 又跳一次,形成闭环;可用 curl -sSIL http://example.com/ | grep -Ei '^(HTTP/|location)' 观察 Location 链长度确认。据 Let’s Encrypt 与 Cloudflare 文档,Full (strict) 要求源站持有有效证书(可用 Let’s Encrypt 签发的 90 天证书),否则报 526。
Tomcat 10.1 的 Valve 类名变了吗?
没变,仍是 org.apache.catalina.valves.RemoteIpValve。Jakarta 命名空间只影响 Servlet API(jakarta.servlet.*),org.apache.catalina.* 包名保持原样,从 Tomcat 9 迁移过来的 server.xml 片段可以直接复用。
怎么快速判断是正常跳转还是循环?
# 打印完整跳转链;正常不超过 2 次(http→https,必要时补斜杠),超过 3 次基本可判定为循环
curl -sSIL http://example.com/ | grep -Ei '^(HTTP/|location)'
# 直接验证 Tomcat 是否信任代理头:应返回 200 而不是 302
curl -sSI -H 'X-Forwarded-Proto: https' http://127.0.0.1:8080/ | head -1
Tomcat 强制 HTTPS 常见报错:ERR_TOO_MANY_REDIRECTS、400 与证书链错误怎么排查
强制 HTTPS 上线后出问题,多数情况不是证书坏了,而是“谁在跳转、跳到哪个端口”没对齐。按报错分类定位,比反复改 server.xml 快得多。
ERR_TOO_MANY_REDIRECTS:为什么一配 redirectPort 就死循环?
典型拓扑是 Nginx 终止 TLS 后回源 8080,Tomcat 仍以为自己是明文 HTTP,security-constraint 又跳一次,浏览器就在两者之间来回撞。先绕过浏览器验证:
# 伪造代理头,看 Tomcat 是否还发 302
curl -I -H 'X-Forwarded-Proto: https' http://127.0.0.1:8080/
# 200 = 已信任代理头;302 Location: https://... = 未识别,循环的根源
两个开关必须同时存在:Nginx 侧 proxy_set_header X-Forwarded-Proto $scheme;,Tomcat 侧在 <Host> 内启用 RemoteIpValve(Tomcat 8.5/9/10 的 server.xml 里默认被注释掉,需手动开启):
<!-- conf/server.xml -->
<Valve className="org.apache.catalina.valves.RemoteIpValve"
protocolHeader="X-Forwarded-Proto" />
<!-- internalProxies 默认只信任 10.x / 172.16-31.x / 192.168.x / 127.x -->
<!-- 容器网络里的反代若不在上述网段,代理头会被直接忽略 -->
400 和 SSL_ERROR_RX_RECORD_TOO_LONG 是同一类错:协议打错端口
| 报错 | 成因 | 验证命令 |
|---|---|---|
400 The plain HTTP request was sent to HTTPS port |
用 http:// 访问了 8443;或 LB 把 80 错映射到 8443 | curl -v http://host:8443/ |
SSL_ERROR_RX_RECORD_TOO_LONG |
用 https:// 访问了 8080 明文端口,TLS 握手收到的是 HTTP 文本 | curl -vk https://host:8080/ |
| 跳转到 8443 但外部打不开 | redirectPort 与防火墙/NAT 不一致 |
ss -lntp | grep -E '8080|8443' |
正确分工是 8080 只负责跳转、8443 或 443 只负责 TLS,二者不要互相指错。
Keystore was tampered with, or password was incorrect
PKCS12 密码区分大小写,keystorePass 必须与导出时逐字符一致;改完要重启 Tomcat,reload 不会重新读取密钥库。
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem
-out tomcat.p12 -name tomcat -password pass:ChangeIt123
# server.xml 里 keystorePass="ChangeIt123" 与之对应
curl: (60) unable to get local issuer certificate
据 Let’s Encrypt 文档,服务器必须下发中间证书,所以配置里应写 fullchain.pem 而非 cert.pem:
openssl s_client -connect example.com:443 -showcerts /dev/null
| grep -c 'BEGIN CERTIFICATE'
# ≥2 表示链完整;=1 说明缺中间 CA
Invalid character found in the request target 怎么处理?
Tomcat 8.5.7 起按 RFC 7230 校验请求目标,URL 里的 |、{、} 默认被拒。优先让客户端做百分号编码(%7C);放宽需在 Connector 上加 relaxedPathChars="|{}",这会把 Tomcat 暴露在请求走私类风险下,不应作为首选。
Tomcat 8.5 / 9.0 / 10.1 / 11 的强制 HTTPS 差异与默认参数
先把结论摆出来:同一份 security-constraint 写法在 8.5 到 11 上都能用,真正会咬人的是 JDK 版本、web.xml 的 version 属性以及 Connector 的默认参数。下面按版本拆开讲,附可复制的配置和验证命令。
| 版本 | Servlet 规范 | 包命名空间 | 最低 JDK | web.xml 根元素 version | TLS 1.3 |
|---|---|---|---|---|---|
| Tomcat 8.5.x | 3.1 | javax.servlet.* | Java 7 | 3.1 | 官方未声明,建议只开 TLSv1.2 |
| Tomcat 9.0.x | 4.0 | javax.servlet.* | Java 8 | 4.0 | 需运行在 Java 11+ |
| Tomcat 10.1.x | 6.0 | jakarta.servlet.* | Java 11 | 6.0 | 支持 |
| Tomcat 11.x | 6.1 | jakarta.servlet.* | Java 17 | 6.1 | 支持 |
据 Apache Tomcat 官方 Setup 文档,10.1 与 11 的 security-constraint、transport-guarantee 语法一字未改,从 9 迁移到 10.1 时你要改的只有 import 语句里的 javax. → jakarta.。web.xml 写错 version 不会启动失败,但会静默降级——Tomcat 9 遇到 version="6.0" 会打印:org.apache.tomcat.util.descriptor.web.WebXml.setVersion Unknown version string [6.0]. Default version will be used.,此时 Servlet 4.0 的 <cookie-config> 等特性被忽略,强制 HTTPS 的规则可能不生效,这是最隐蔽的坑。
<!-- conf/server.xml,以 Tomcat 9.0 / 10.1 / 11 通用写法为例 -->
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000" <!-- 默认 20000 ms -->
redirectPort="8443" <!-- 默认 443,生产建议显式写成与下面一致 -->
maxThreads="200" <!-- 默认 200 -->
acceptCount="100" <!-- 默认 100 -->
maxConnections="8192" /> <!-- NIO 默认 8192;APR 默认 -1 即等于 maxThreads -->
<Connector port="8443" protocol="HTTP/1.1"
SSLEnabled="true"
maxThreads="150"
scheme="https" secure="true"
sslEnabledProtocols="TLSv1.2,TLSv1.3" <!-- 8.5 上请删掉 TLSv1.3,只留 TLSv1.2 -->
keystoreFile="/etc/tomcat/keystore.p12"
keystoreType="PKCS12"
keystorePass="changeit" />
<!-- 注:8443 Connector 未配置时 Tomcat 根本不会监听该端口 -->
验证是否真的生效,别信配置文件,信端口和握手结果:
# 1. 看 8443 是否在监听;没有任何输出说明 Connector 没生效
ss -lntp | grep -E ':(8080|8443)'
# 2. 确认实际协商出的协议版本(据 OpenSSL 文档,-brief 只输出摘要)
openssl s_client -connect 127.0.0.1:8443 -servername example.com -brief </dev/null
# 3. 确认 JVM 支持哪些协议,TLSv1.3 缺失通常是 JDK 版本问题
java -version
$CATALINA_HOME/bin/version.sh # 输出 Server version / JVM Version 两行
还有两个容易被忽略的默认行为:其一,protocol="HTTP/1.1" 在 Tomcat 9/10/11 中会自动映射为 org.apache.coyote.http11.Http11NioProtocol,无需手写全类名;若要用 APR,必须显式写 org.apache.coyote.http11.Http11AprProtocol 并安装 tomcat-native,否则启动即报 ClassNotFoundException。其二,redirectPort 的默认值就是 443,很多人只配了 8443 的 Connector 却忘了改 8080 上的 redirectPort,结果 tomcat 强制https 的 302 把用户甩到 443 上直接连接被拒。想让 tomcat 强制https 在反向代理后面也正确工作,还需配合 RemoteIpValve 读取 X-Forwarded-Proto,这部分与 Nginx 的 proxy_set_header 配置属于同一组话题。
怎么确认 Tomcat 强制 HTTPS 已生效?6 条命令与 3 个检查点
配好 redirectPort、security-constraint 和 Nginx 的 301/302 之后,最容易出现的尴尬是:你以为已经全站 HTTPS,实际某条路径仍然走明文。验证要分三层做——跳转层、加密层、监听层,任何一层漏检都会给出假阳性。下面 6 条命令对应 3 个检查点,全部可直接复制。
检查点一:跳转层是否真的返回 302。据 Tomcat 官方文档,<security-constraint> 中的 <transport-guarantee>CONFIDENTIAL</transport-guarantee> 会让容器对匹配的 URL 发起重定向到 redirectPort 指定的端口,这是 Tomcat 强制 https 的第一道闸门。
# 1) 只看响应头前 5 行,避免下载整个页面
curl -sSI http://example.com/ | head -n 5
# 期望输出(首行必须是 302,Location 必须是 https)
# HTTP/1.1 302
# Location: https://example.com/
# 若首行是 HTTP/1.1 200,说明 tomcat 强制https 根本没触发:
# 检查 web.xml 的 url-pattern 是否为 /*,以及 Connector 上 redirectPort="8443" 是否写了
检查点二:HSTS 与 TLS 版本。据 RFC 6797,HSTS 只能通过安全连接下发;Tomcat 8.0 起内置 org.apache.catalina.filters.HttpHeaderSecurityFilter,但 hstsMaxAgeSeconds 的默认值是 0——也就是默认不发 HSTS 头,必须显式配置。
# 2) 检查 HSTS 头
curl -sSI https://example.com/ | grep -i strict-transport-security
# 期望:Strict-Transport-Security: max-age=31536000; includeSubDomains
# 无输出 → 过滤器未启用,或 hstsMaxAgeSeconds 仍是默认 0
# 3) 确认 TLSv1.2 可握手
openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null 2>/dev/null | grep -E 'Protocol|Cipher'
# 期望:Protocol : TLSv1.2 / Cipher : ECDHE-RSA-AES128-GCM-SHA256
# 4) 确认 TLSv1.1 已关闭(RFC 8996 已正式弃用 TLS 1.0/1.1)
openssl s_client -connect example.com:443 -servername example.com -tls1_1 </dev/null 2>/dev/null | grep -E 'Protocol|alert'
# 期望:握手失败,出现 alert handshake failure 或 no protocols available
检查点三:端口暴露面与外部复核。AJP 连接器是常被忽略的明文入口,CVE-2020-1938(Ghostcat)正是通过 8009 读取 webapp 文件;Tomcat 9.0.31 / 8.5.51 起 secretRequired 默认改为 true,但仍建议绑定回环地址。
# 5) 看监听:8443 必须在 LISTEN,8009 最好不存在
ss -lntp | grep -E ':(8080|8443|8009)'
# 期望:LISTEN 0 ... :::8443 ... java
# 不用 AJP 就在 server.xml 注释掉 AJP Connector;要用则加 address="127.0.0.1" secretRequired="true"
# 6) 本地复现 SSL Labs 的判定逻辑
testssl.sh --severity HIGH example.com
# 输出中 "HTTP Strict Transport Security" 应为 offered,且不得出现 RC4 / 3DES / EXPORT
浏览器侧同样别跳过:DevTools → Network 里 302 链长度应为 1(出现 2 跳以上通常是代理与容器互相重定向),Security 面板应显示 TLS 1.3 与完整证书链;若提示「证书无效」,优先查中间证书是否漏配,而不是换证书。外部可用 Qualys SSL Labs 打分,目标 A/A+,其评分项明确要求 HSTS、TLS 1.2+ 且禁用 RC4/3DES。
| 观察到的现象 | 含义 | 定位动作 |
|---|---|---|
| HTTP 返回 200 而非 302 | security-constraint 未覆盖该 URL,或代理层已先终止连接 |
核对 <url-pattern>/*</url-pattern> 与 Connector 的 redirectPort |
有 302,但 Location 是 http:// |
TLS 在 Nginx 终止,Tomcat 认为请求是明文 | Nginx 加 proxy_set_header X-Forwarded-Proto https;,Tomcat 侧启用 RemoteIpValve |
| 无 Strict-Transport-Security 头 | HttpHeaderSecurityFilter 未映射,或 hstsMaxAgeSeconds="0"(默认值) |
在 web.xml 中显式设 hstsMaxAgeSeconds=31536000 |
| 8443 不在 LISTEN | Connector 未加 SSLEnabled="true",或 keystore 密码错误 |
查 logs/catalina.out 中的 Keystore was tampered with, or password was incorrect |
典型误判:Tomcat 前面挂 Nginx 做 TLS 终止时,Tomcat 收到的 scheme 仍是
http,security-constraint会持续 302 到自己,形成重定向循环。此时不要在 Tomcat 里关掉强制 https,而是让代理传递X-Forwarded-Proto并启用 RemoteIpValve,两层各司其职:Nginx 负责证书与 HSTS,Tomcat 负责应用级兜底。
不能。redirectPort 只是跳转目标端口,必须由 web.xml 的 security-constraint(transport-guarantee=CONFIDENTIAL)或应用框架的 requiresChannel() 触发,Tomcat 才会返回 302 到 https。实际配置要同时满足 8443 Connector 已启用、8080 的 redirectPort 指向 8443、应用声明需要机密传输三个条件。
先确认代理是否传递 X-Forwarded-Proto:Nginx 加 proxy_set_header X-Forwarded-Proto $scheme,Tomcat 配 RemoteIpValve 的 protocolHeader='X-Forwarded-Proto'。若使用 Cloudflare,把 SSL 模式从 Flexible 改为 Full (strict)。可用 curl -I -H 'X-Forwarded-Proto: https' http://127.0.0.1:8080/ 判断应用是否仍返回 302。
security-constraint 在 Tomcat 中返回 302,适合快速上线;RewriteValve 或 Nginx 可指定 301,浏览器会缓存,适合确定长期 https 的站点。更稳妥的做法是 301 配合 HSTS,让后续请求不再经过跳转,同时保留 302 作为回退。
建议保留。代理层 301 只覆盖公网入口,内网直连 8080、健康检查或容器间调用仍可能是明文;在 Tomcat 用 security-constraint 做兜底更稳。但要排除 /health 等探针路径,并确保代理传递 X-Forwarded-Proto,避免双重重定向。
不用 AJP 就删除 Connector 或注释掉;必须使用时设置 secretRequired='true'、secret 为强随机值,并绑定 address='127.0.0.1'。AJP 暴露在公网会带来 CVE-2020-1938(Ghostcat)风险,Tomcat 9 默认已注释该 Connector。
该 400 错误表示用 http:// 访问了 8443 这类 TLS 端口。应让 8080 负责跳转,检查负载均衡是否把 80 映射到 8443,以及 redirectPort 是否与实际 TLS 端口一致。修正后用 curl -I http://example.com/ 确认返回 302 而非 400。
用 certbot renew –deploy-hook 在续期后执行 openssl pkcs12 重新导出 tomcat.p12,然后 systemctl restart tomcat9 让新证书加载。也可把 TLS 终止放到 Nginx 并只让 Tomcat 处理 8080,这样续期只需 reload nginx,减少 Tomcat 重启次数。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。