Tomcat默认根路径HSTS配置未生效问题技术问询

开发者阿泽

2026-9-29

排查思路

确认访问协议：HSTS头仅会在HTTPS协议的响应中返回，HTTP请求的响应默认不会携带Strict-Transport-Security头，先确认你是直接用HTTPS访问根路径，还是先访问HTTP再跳转，跳转前的HTTP响应自然不会携带HSTS头。
清除浏览器缓存测试：浏览器会缓存历史HSTS规则，可先清空对应域名的安全状态缓存，再直接用HTTPS访问根路径，校验响应头是否正常返回。
检查web.xml配置优先级：Tomcat存在全局conf/web.xml和应用私有WEB-INF/web.xml两个配置文件，如果你把过滤器规则写在全局配置中，要确认对应应用没有自定义的HttpHeaderSecurityFilter配置覆盖全局规则；如果写在应用私有配置中，要确认没有其他同优先级过滤器修改了响应头。
检查过滤器触发范围：你当前配置的dispatcher仅包含REQUEST，如果根路径资源是通过转发（FORWARD）、包含（INCLUDE）、错误页跳转的方式返回，过滤器不会触发，自然无法写入HSTS头。
检查响应是否提前提交：如果根路径对应的业务逻辑在过滤器执行前就已经提交了响应（比如调用了response.flushBuffer()、输出内容超出缓冲区大小），后续过滤器无法再修改响应头。
确认Tomcat版本兼容性：HttpHeaderSecurityFilter的完整HSTS参数仅在Tomcat 7.0.63+、8.0.24+版本支持，低于该版本的Tomcat会忽略相关配置。

解决方案

配置HTTP强制跳转HTTPS：在Tomcat的server.xml中配置HTTP Connector的跳转端口，确保所有HTTP请求自动跳转到HTTPS，后续HTTPS响应会正常携带HSTS头，配置示例如下：

<Connector port="80" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="443" />

补充过滤器触发场景：修改filter-mapping配置，覆盖所有请求场景：

<filter-mapping>
    <filter-name>httpHeaderSecurity</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>INCLUDE</dispatcher>
    <dispatcher>ERROR</dispatcher>
</filter-mapping>

调整过滤器执行顺序：把HttpHeaderSecurityFilter的配置放到所有自定义过滤器的最前面，避免其他过滤器提前提交响应、或者删除已写入的HSTS头。
配置根路径默认响应：如果Tomcat根路径默认返回空响应或者临时跳转，部分场景下不会携带响应头，可给根路径配置默认欢迎页，确保响应完整输出时携带HSTS头。
升级Tomcat到兼容版本：如果当前Tomcat版本低于最低支持版本，升级到Tomcat 7.0.100+、8.5.x以上的稳定版本即可。

内容的提问来源于stack exchange，提问作者Avi