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

Tomcat 强制 HTTPS 怎么做?redirectPort、security-constraint 与反向代理三层配置指南

tomcat 强制https — 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 打架:

取值 实际启用的组件 是否还需 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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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