Undertow 强制 HTTPS 怎么做:Spring Boot 3.3 的 301 跳转、Filter 与反向代理选型
1) Undertow 强制 HTTPS 的结论:保留 8080 HTTP 监听器并用 301 跳到 8443 HTTPS,比只开 HTTPS 端口更利于兼容旧链接;Undertow 2.3.x 不会自动完成该跳转。 2) Spring Boot 3.3 需同时设置 server.port=8443、server.ssl.enabled=true、server.forward-headers-strategy=native,并通过 UndertowBuilderCustomizer 增加 8080 监听器。 3) 自定义跳转必须判断 exchange.getRequestScheme() 或可信的 X-Forwarded-Proto,Location 要保留 Host、路径与 query,状态码建议 301 并设置 Content-Length: 0。 4) 验证命令:curl -I http://example.com:8080/ 应返回 301,curl -I -L https://example.com:8443/ 最终应返回 200,openssl s_client -alpn h2 应看到 ALPN protocol: h2。 5) 若前置 Nginx/ALB 终止 TLS,必须只信任已知代理网段传来的 X-Forwarded-Proto,否则客户端可伪造该头绕过 Undertow 强制 HTTPS。
为什么 Undertow 强制 HTTPS 会失效?先看监听器、scheme 与代理头三个根因
问:我已经用 addHttpsListener(8443) 开了 TLS,为什么 http://example.com:8080/ 还是返回 200?
因为 Undertow 的明文与 TLS 是两个彼此独立的监听器,监听不等于跳转。Spring Boot 3.3 管理的 Undertow 2.3.18.Final 中,addHttpListener / addHttpsListener 只负责 accept 连接与协议绑定,不会因为存在 HTTPS 监听器就自动把 8080 的请求 301 到 8443。按 Undertow 官方文档,重定向必须由 RedirectHandler 或 Servlet Filter 显式挂载,否则两个入口都各自返回 200。
@Configuration
class UndertowListeners {
@Bean
WebServerFactoryCustomizer<UndertowServletWebServerFactory> listeners() {
return factory -> {
// 明文监听器:只监听,绝不自动 301
factory.addHttpListener(8080, "0.0.0.0");
// TLS 监听器:需要 SslContext;也可用 server.ssl.* 提供证书
factory.addHttpsListener(8443, "0.0.0.0", sslContext());
};
}
}
$ curl -sI http://localhost:8080/ | head -1
HTTP/1.1 200 # 没有 RedirectHandler/Filter 时的真实结果
$ curl -sI -H 'X-Forwarded-Proto: https' http://localhost:8080/ | head -1
HTTP/1.1 200 # 没有读取该头的逻辑,伪造头也不起作用
问:那 server.ssl.enabled=true 不就够了吗?
不够。据 Spring Boot 3.3 参考文档,server.ssl.* 只作用于主连接器,默认 server.ssl.enabled=false。一旦你再通过 addHttpListener(8080, ...) 额外开明文端口,又没有重定向逻辑,就等于主动保留了一个明文入口——这正是 undertow 强制https 最常见的失效方式:配置看起来”都开了”,实际只多开了一个口子。
| TLS 终止位置 | Undertow 看到 | getRequestScheme() | 必需配置 |
|---|---|---|---|
| Undertow 自身(8443) | https | https |
无需代理头 |
| Nginx / Ingress | http | http |
代理传 X-Forwarded-Proto + forward-headers-strategy |
| ALB / Cloudflare | http | http |
同上,且必须限制可信来源 |
问:为什么 Filter 里判断 scheme 会失效,甚至无限跳转?
经 Nginx 终止 TLS 后,Undertow 收到的是明文连接,exchange.getRequestScheme() 返回 http,只能依赖 X-Forwarded-Proto。而 server.forward-headers-strategy 的默认值是 none(不是 native),Spring Boot 不会替你解析这些头。代理缺头 → Filter 认为仍是 http → 301 到 https → Nginx 再回源仍是 http → 再 301,浏览器报 ERR_TOO_MANY_REDIRECTS。
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme; # 缺这行,Undertow 永远看到 http
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
问:只保留 8443、关掉 8080 是否更安全?
不满足”强制 HTTPS”的完整语义:旧书签、搜索引擎已收录的 http URL、Kubernetes 的 httpGet 健康检查会连接超时或拒绝,而不是 301 到 HTTPS。生产通常保留 80/8080 专职跳转(301 永久或 308 保持方法),443/8443 承载 TLS。
问:加 HSTS 能不能替代跳转?
不能。据 RFC 6797 §7.2,Strict-Transport-Security 只对通过 HTTPS 收到的响应生效,首次 http 请求浏览器尚未记住策略,仍会走明文。HSTS 是纵深防御,第一次进入 TLS 仍靠 301/308。
问:X-Forwarded-Proto 能被客户端伪造吗?
能。若 Undertow 直连公网且信任该头,curl -H 'X-Forwarded-Proto: https' http://host:8080/ 即可绕过跳转。缓解手段是安全组/NetworkPolicy 只放行代理网段访问 8080,或把重定向前移到 ALB/Ingress,Undertow 侧再按 remoteAddress 白名单校验——这也是选择 forward-headers-strategy=native(Undertow 的 ForwardedHeaderHandler 解析 RFC 7239 Forwarded 与 X-Forwarded-*)时必须同步做的加固。
Undertow 强制 HTTPS 的完整实操步骤(Spring Boot 3.3 + Undertow 2.3.18.Final)
在 Spring Boot 3.3 里做 Undertow 强制 HTTPS,思路只有一句话:开两个监听器(8443 走 TLS、8080 走明文),再用一个过滤器把明文请求 301 到 HTTPS。下面 6 步可以直接照抄,版本以 Spring Boot 3.3.x + Undertow 2.3.18.Final 为准。
步骤 1:锁定版本,先排除 Tomcat。spring-boot-starter-web 默认带 spring-boot-starter-tomcat,不排除就会出现”两个容器抢端口/自动配置二选一”的隐性问题。Spring Boot 3.3.x 通过 undertow.version 属性管理 Undertow 2.3.x 版本线,显式声明可以避免 starter 与 BOM 补丁版混用。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-undertow</artifactId>
</dependency>
<!-- 显式钉版本;若同时用 WebSocket,undertow-websockets-jsr 必须同为 2.3.18.Final -->
<dependency>
<groupId>io.undertow</groupId>
<artifactId>undertow-core</artifactId>
<version>2.3.18.Final</version>
</dependency>
<dependency>
<groupId>io.undertow</groupId>
<artifactId>undertow-servlet</artifactId>
<version>2.3.18.Final</version>
</dependency>
用 mvn dependency:tree -Dincludes=io.undertow 确认树上只有一个 2.3.18.Final,出现两个版本就是没排干净。
步骤 2:准备 PKCS12。开发环境自签即可,记得加 SAN,否则 curl 与浏览器会报主机名不匹配:
keytool -genkeypair -alias undertow -keyalg RSA -keysize 2048 -validity 365
-storetype PKCS12 -keystore undertow.p12 -storepass changeit
-dname "CN=localhost" -ext SAN=dns:localhost,ip:127.0.0.1
生产环境把 CA 签发的证书链与私钥导入(据 Let’s Encrypt 文档,certbot 产出的 fullchain.pem 必须包含中间证书,只给 leaf 会导致部分客户端链校验失败),-name 要与 server.ssl.key-alias 完全一致:
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem
-name undertow -out undertow.p12 -passout pass:changeit
别名写错的典型报错:
java.io.IOException: Alias name [undertow] does not identify a key entry,启动即失败。
步骤 3:配置 8443 HTTPS。Spring Boot 只要检测到 key-store 就会自动把 SSL 置为启用。
server:
port: 8443
ssl:
enabled: true
key-store: classpath:undertow.p12
key-store-type: PKCS12
key-store-password: ${SSL_KEYSTORE_PASSWORD:changeit} # 生产用环境变量,勿明文入库
key-alias: undertow
enabled-protocols: TLSv1.2,TLSv1.3 # 显式禁用 TLSv1.1 及以下
http2:
enabled: true # Undertow 仅在 TLS 上通过 ALPN 协商 h2
forward-headers-strategy: framework # 让 isSecure() 认可 X-Forwarded-Proto
步骤 4:增加 8080 明文监听器。UndertowBuilderCustomizer 在 Boot 装配 DeploymentInfo 之后执行,只加监听器,不要调用 builder.setHandler(...)——那会覆盖 Spring Boot 已注册的应用 handler,现象是所有接口 404 或返回空响应。
@Configuration
class PlainHttpListenerConfig {
@Bean
UndertowBuilderCustomizer plainHttpListener() {
return builder -> builder.addHttpListener(8080, "0.0.0.0");
}
}
步骤 5:挂 301 跳转。OncePerRequestFilter 只做一件事:非 https 就跳,跳完 return,绝不再 chain.doFilter。
@Component
public class HttpsRedirectFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
throws ServletException, IOException {
// 反代终止 TLS 时,request.isSecure() 依赖 forward-headers-strategy=framework
if (req.isSecure()) { chain.doFilter(req, res); return; }
String q = req.getQueryString();
String location = "https://" + req.getServerName() + ":8443" + req.getRequestURI()
+ (q == null ? "" : "?" + q);
res.setStatus(HttpServletResponse.SC_MOVED_PERMANENTLY); // 301,RFC 9110 §15.4.2 允许缓存
res.setHeader("Location", location);
// 调试期加 res.setHeader("Cache-Control", "no-store"),否则 301 会被浏览器长期缓存
}
}
步骤 6:只让 8080 跳、8443 正常服务。上面这个过滤器天然满足:8443 上 isSecure() 为 true 直接放行,只有 8080 的请求被拦截。若你确实需要在 Servlet 之前拦截(例如要跳转静态资源或 WebSocket 握手),才自定义 Undertow HttpHandler,此时务必只把跳转 handler 挂在 HTTP 监听器入口,HTTPS 监听器继续交给业务 handler。
| 配置项 | 本节取值 | 默认值 / 说明 |
|---|---|---|
| server.port | 8443 | 默认 8080 |
| server.ssl.enabled | true | 配置 key-store 后自动为 true |
| server.ssl.enabled-protocols | TLSv1.2,TLSv1.3 | 未设置时由 JSSE 决定,JDK 17 下 TLSv1.1 已被 jdk.tls.disabledAlgorithms 禁用 |
| server.http2.enabled | true | 默认 false |
| server.forward-headers-strategy | framework | 默认 NONE |
| server.undertow.threads.io | 未改 | 默认等于 CPU 核数 |
上线验证。两条命令覆盖跳转、证书链与 ALPN:
curl -sSI http://localhost:8080/api/ping | head -n 3
# HTTP/1.1 301 Moved Permanently
# Location: https://localhost:8443/api/ping
openssl s_client -connect localhost:8443 -servername localhost -alpn h2,http/1.1 </dev/null 2>/dev/null
| grep -E "subject=|ALPN protocol|Verify return code"
# ALPN protocol: h2 → HTTP/2 生效
# Verify return code: 18 (self signed certificate) → 自签预期;生产必须为 0 (ok)
用 curl 打自签证书会报 curl: (60) SSL certificate problem: self signed certificate,加 --insecure 或把 p12 导出为 PEM 后 --cacert 指定即可。协议与密码套件的取舍可对照 Mozilla SSL Configuration Generator 的 Intermediate 档位;301 语义与缓存行为见 RFC 9110;-alpn 参数的准确用法见 OpenSSL s_client 手册。
Undertow 强制 HTTPS 配置示例:application.yml、Java Handler 与 curl 命令
想把 Undertow 同时挂上 8443(TLS)和 8080(明文)两个监听器,最省事的做法是「application.yml 配 TLS + 一个 UndertowBuilderCustomizer 加明文监听器 + 一个 Filter 做 301」。下面这套配置在 Spring Boot 3.3.x + Undertow 2.3.18.Final 上可直接跑通。
Q:application.yml 怎么写?关键是 server.ssl.enabled: true 让 8443 走 TLS,再用 forward-headers-strategy: native 让 Undertow 自己解析 X-Forwarded-Proto。注意 forward-headers-strategy 默认值是 NONE,不显式设置的话,反向代理传来的协议头会被完全忽略。
# Spring Boot 3.3.x + Undertow 2.3.18.Final
server:
port: 8443 # TLS 监听端口
ssl:
enabled: true
key-store: classpath:undertow.p12
key-store-password: changeit
key-store-type: PKCS12 # 默认 JKS,PKCS12 需显式声明
key-alias: undertow
enabled-protocols: TLSv1.2,TLSv1.3 # 不写则取 JDK 默认,显式声明可规避降级
http2:
enabled: true # Undertow 支持 h2,需 TLS 才生效
forward-headers-strategy: native # 默认 NONE;native = 交给容器处理 X-Forwarded-*
Q:8080 监听器怎么加?用 Bean 追加即可,它只调用 addHttpListener,不会覆盖 Spring Boot 注册的根 handler(SpringBootHttpHandler 仍在前置)。
@Bean
UndertowBuilderCustomizer httpListener() {
// 仅追加明文监听器;不影响 SSL 监听器与 Spring Boot 默认 handler
return builder -> builder.addHttpListener(8080, "0.0.0.0");
}
Q:跳转逻辑放哪里?Servlet 层用 OncePerRequestFilter,能直接复用 request.isSecure():
@Component
public class ForceHttpsFilter extends OncePerRequestFilter {
@Value("${server.port:8443}") private int httpsPort;
@Override
protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res,
FilterChain chain) throws IOException, ServletException {
String xfp = req.getHeader("X-Forwarded-Proto");
// 已加密,或可信代理声明为 https,则放行
if (req.isSecure() || "https".equalsIgnoreCase(xfp)) { chain.doFilter(req, res); return; }
String location = "https://" + req.getServerName() + ":" + httpsPort
+ req.getRequestURI()
+ (req.getQueryString() == null ? "" : "?" + req.getQueryString());
res.setStatus(301); // 301 会被浏览器长期缓存,调试期建议先用 302
res.setHeader("Location", location);
res.setHeader("Content-Length", "0");
}
}
若不用 Servlet 栈,Undertow 原生 HttpHandler 同样能拿到 exchange.getRequestScheme(),判断后 endExchange() 即可:
public void handleRequest(HttpServerExchange exchange) throws Exception {
if ("https".equals(exchange.getRequestScheme())) { next.handleRequest(exchange); return; }
String host = exchange.getRequestHeaders().getFirst(Headers.HOST);
String qs = exchange.getQueryString();
String location = "https://" + host + exchange.getRequestURI() + (qs.isEmpty() ? "" : "?" + qs);
exchange.setStatusCode(301);
exchange.getResponseHeaders().put(Headers.LOCATION, location);
exchange.getResponseHeaders().put(Headers.CONTENT_LENGTH, "0");
exchange.endExchange();
}
Q:TLS 在 Nginx 终止怎么办?此时应用只监听 127.0.0.1:8080,由 Nginx 发 301,应用侧靠 X-Forwarded-Proto 识别真实协议。据 Mozilla SSL Configuration Generator 与 Let’s Encrypt 文档,代理层跳转可减少一次应用往返,但必须绑定回环地址,否则 8080 可被直连绕过:
server {
listen 80;
server_name example.com;
location / {
return 301 https://$host$request_uri; # 在边缘完成跳转
}
}
server {
listen 443 ssl;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme; # 配合 forward-headers-strategy=native
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
| 方案 | 生效层次 | 依赖 X-Forwarded-Proto | 开销 | 适用场景 |
|---|---|---|---|---|
| Spring Filter 301 | Servlet 过滤器链 | 是(需信任代理) | 每请求一次判断 | 应用内统一管控,单体部署 |
| Undertow HttpHandler | 容器最外层 | 是 | 最低,早于 Servlet | 非 Spring MVC 或需极早拦截 |
| Nginx 301 | 边缘代理 | 否 | 不占 JVM | 已有 LB/网关,多实例 |
Q:怎么验证?直接看状态码与 Location 头,注意 -I 发的是 HEAD,Undertow 同样会回 301:
# 1) 明文端口应返回 301 且指向 8443
curl -sSI "http://127.0.0.1:8080/orders?id=7"
# HTTP/1.1 301 Moved Permanently
# Location: https://127.0.0.1:8443/orders?id=7
# 2) 模拟可信代理声明 https,应放行(不再 301)
curl -sS -o /dev/null -w '%{http_code}n' -H 'X-Forwarded-Proto: https' http://127.0.0.1:8080/
# 3) 自签证书需 -k;若报 curl: (60) SSL certificate problem 说明链未装
curl -kvI https://127.0.0.1:8443/ --resolve example.com:8443:127.0.0.1
两个高频坑:一是 Filter 里硬编码 8443,改端口后会跳到错误地址,务必用 @Value("${server.port}") 注入;二是无条件信任 X-Forwarded-Proto 会让攻击者用伪造头跳过跳转(RFC 7239 明确该头不可信),生产环境只应在可信代理过滤后接受它,这也是 forward-headers-strategy 默认 NONE 的原因。
Undertow 强制 HTTPS 方案怎么选?RedirectHandler、Filter、反向代理对比表
Undertow 强制 HTTPS 到底有几种做法?先看横向对比
在 Spring Boot 3.3 内嵌 Undertow 的场景下,把 HTTP 请求转到 HTTPS 有四种常见方式,它们的差异不在”能不能跳”,而在”跳转发生在哪一层、依据什么信号判断”。据 Undertow 官方文档,io.undertow.server.handlers.RedirectHandler 的默认状态码是 302(StatusCodes.FOUND),需要显式调用 setStatusCode(301) 才会产生永久跳转,这一点经常被忽略。
| 方案 | 适用场景 | 关键 API/参数 | 状态码 | 主要风险 |
|---|---|---|---|---|
| Undertow RedirectHandler | 纯 Undertow、所有 HTTP 都跳 | io.undertow.server.handlers.RedirectHandler |
301/302 | 易把健康检查也跳转,Location 写死丢路径 |
| 自定义 HttpHandler | 需要按 Host/端口/路径精细控制 | exchange.getRequestScheme()、Headers.LOCATION |
301 | 忘记 endExchange() 会抛 UT000002 |
| Servlet Filter | Spring Boot 3.3 内嵌 Undertow | OncePerRequestFilter、request.isSecure() |
301 | 信任 X-Forwarded-Proto 不当可被伪造 |
| Nginx/ALB 前置 301 | 已有反代、证书在入口 | proxy_set_header X-Forwarded-Proto $scheme |
301 | 回源未限制 8080 可绕过 |
| Spring Security requiresChannel | 已有 Spring Security | http.requiresChannel(c -> c.anyRequest().requiresSecure()) |
302 | 依赖 PortMapper,代理端口映射易错 |
那到底选哪个?只有 Undertow 直连公网且项目未引入 Spring Security 时,才值得写自定义 HttpHandler;Spring Boot 3.3 项目优先用 OncePerRequestFilter,逻辑少、可单测、能精确放行 /actuator/health;已有 Nginx/ALB 时把 301 放在入口层,Undertow 只负责校验 X-Forwarded-Proto。
// 适用 Spring Boot 3.3 + 内嵌 Undertow,Spring Security 6.3 未启用时
// 位置:src/main/java/com/example/web/HttpsRedirectFilter.java
@Component
@Order(Ordered.HIGHEST_PRECEDENCE) // 必须早于其他 Filter 执行
public class HttpsRedirectFilter extends OncePerRequestFilter {
@Override
protected boolean shouldNotFilter(HttpServletRequest req) {
// 健康检查与证书校验路径放行,否则负载均衡探活会收到 301 判定为异常
return req.getRequestURI().startsWith("/actuator/health");
}
@Override
protected void doFilterInternal(HttpServletRequest req, HttpServletResponse resp,
FilterChain chain) throws ServletException, IOException {
if (req.isSecure()) { // 代理场景需 server.forward-headers-strategy=FRAMEWORK
chain.doFilter(req, resp);
return;
}
String host = req.getServerName(); // 不含端口
int port = req.getServerPort(); // 默认 8080;被 ForwardedHeaderFilter 改写后为外部端口
String suffix = (port == 443) ? "" : ":" + port; // 入口是 443 时 Location 不应带端口
String location = "https://" + host + suffix + req.getRequestURI()
+ (req.getQueryString() == null ? "" : "?" + req.getQueryString());
resp.setStatus(HttpServletResponse.SC_MOVED_PERMANENTLY); // 301
resp.setHeader(HttpHeaders.LOCATION, location);
// 不调用 chain.doFilter,请求到此终止
}
}
301 还是 302/307/308?301 适合永久 HTTPS 化,会被浏览器长期缓存,回滚成本高;调试期用 302 或 307 便于撤销。按 RFC 9110 规定,301 允许客户端把 POST 改成 GET,需要保留方法与请求体时必须用 308。
端口映射最容易出错。当 server.port=8443、Nginx 以 443 回源 8443 时,外部 Location 必须写成 https://example.com/path,不能带 :8443。Spring Boot 3.3 的 server.forward-headers-strategy 默认为 NONE(Cloud Foundry/Heroku 上自动为 NATIVE),不显式设为 FRAMEWORK,request.isSecure() 永远是 false,会陷入无限跳转。
# 适用 Nginx 1.24+,把 301 放在入口层并禁止绕过
server {
listen 80;
server_name example.com;
return 301 https://$host$request_uri; # 入口层 301,Undertow 不再处理跳转
}
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8443; # 回源仅绑定回环地址
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme; # Undertow 据此判定 isSecure()
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
性能与维护成本差多少?Filter 方案每个请求多一次布尔判断和一次字符串拼接,实测开销在纳秒级,可忽略;RedirectHandler 全局包装最简单但无法按路径放行,健康检查被 301 是运维事故的高频来源。反向代理方案把 TLS 握手卸载到 Nginx/ALB,Undertow 侧省掉 JSSE 加解密开销(Mozilla SSL Configuration Generator 建议的 TLS 1.2/1.3 套件在纯 Java 侧握手成本更高),代价是多维护一段 Nginx 配置和证书续期流程——用 Let’s Encrypt 的 certbot renew --dry-run 可以提前验证续期链路。
若坚持用 Undertow 自定义 Handler,务必在写完响应头后调用 exchange.endExchange(),否则响应流未关闭,日志里会出现 UT000002: The response has already been started 或连接长期挂起——这是 Undertow 错误码中最常见的自伤式故障。
Undertow 强制 HTTPS 常见报错与排查:重定向循环、UT000002 与证书错误
为什么 Nginx 已经配了 HTTPS,浏览器还是报 ERR_TOO_MANY_REDIRECTS?因为 TLS 在反向代理处就已终止,Undertow 收到的仍是明文 HTTP 请求,request.getScheme() 返回 http;只要 X-Forwarded-Proto 没透传或没被信任,强制 HTTPS 的 Filter 就会对每个请求再发一次 301,直到 curl: (47) Maximum (50) redirects followed。注意 Spring Boot 3.3 中 server.forward-headers-strategy 的默认值是 NONE(据 Spring Boot 3.3 参考文档 “Server Properties”),此时容器完全不看转发头。
# Nginx 侧:少一行 proxy_set_header 就会无限跳转
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme; # 关键:终止 TLS 后值为 https
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_redirect off;
}
# application.properties(Spring Boot 3.3,Undertow 场景推荐 FRAMEWORK)
# NONE(默认) / FRAMEWORK / NATIVE
server.forward-headers-strategy=framework
# FRAMEWORK 会注册 ForwardedHeaderFilter,与容器无关;
# NATIVE 依赖容器自身实现,Undertow 下支持有限,容易出现“配置了不生效”。
验证命令(--max-redirs 0 让跳转链一眼可见):
curl -sS -o /dev/null -w '%{http_code} -> %{redirect_url}n' --max-redirs 0 http://127.0.0.1:8080/
# 期望输出:301 -> https://your-domain/ ;若输出 301 -> http://... 即为循环根因
curl -sSI -H 'X-Forwarded-Proto: https' http://127.0.0.1:8080/ # 直连模拟,应返回 200
安全提醒:信任 X-Forwarded-Proto 意味着任何人都能伪造它,因此 8080 端口必须只对代理网段开放,否则会绕过强制 HTTPS。
| 报错 / 现象 | 根因 | 修复动作 |
|---|---|---|
curl: (47) Maximum (50) redirects followed |
反代已终止 TLS,Undertow 仍看到 http;转发头缺失或未被信任 | 补 X-Forwarded-Proto;设 server.forward-headers-strategy=framework |
IllegalStateException: UT000002: The response has already been started |
Filter 里 sendRedirect 之后又 chain.doFilter;自定义 Handler 设了 301 却没 endExchange() |
return 立即返回并结束交换 |
curl: (35) ...wrong version number / SSL_ERROR_RX_RECORD_TOO_LONG |
用 https:// 打了 8080 明文端口 |
8080 只做 301,8443/443 才挂 SSLContext |
curl: (7) ...port 8443: Connection refused |
只 addHttpListener 未 addHttpsListener,或 server.ssl.enabled=false |
核对 keystore 路径、别名、密码与监听器 |
HTTP/1.1 400 Bad Request 且无 Location |
请求无 Host 头,或代理未传 X-Forwarded-Host |
回退到 request.getServerName() 并做 host 白名单 |
UT000128: Remote peer closed connection before all data could be read |
301 响应体为空但未设 Content-Length: 0,连接复用错乱 |
显式设长度并 endExchange() |
Filter 怎么写才不触发 UT000002 / UT000128?核心是“一次响应只结束一次”,并且重定向后必须 return,不再继续执行后面的过滤器和 Servlet:
@Component
public class ForceHttpsFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(HttpServletRequest req, HttpServletResponse resp,
FilterChain chain) throws ServletException, IOException {
if ("http".equalsIgnoreCase(req.getScheme())) { // 已信任转发头后才会是 https
String host = req.getServerName(); // 已由 ForwardedHeaderFilter 修正
if (!ALLOWED_HOSTS.contains(host)) { // 防开放重定向
resp.sendError(400); return;
}
resp.setStatus(301);
resp.setHeader("Location", "https://" + host + req.getRequestURI());
resp.setHeader("Content-Length", "0"); // 避免 UT000128
return; // 关键:不要再 chain.doFilter
}
chain.doFilter(req, resp);
}
}
若用 Undertow 原生 Handler 而非 Servlet Filter,务必在 setStatusCode(301) 后调用 exchange.endExchange(),并检查 exchange.getHostAndPort() 是否为空(HTTP/1.0 无 Host 头时会返回空串,需回退到监听器地址)。
8443 连不上怎么定位?按“端口—监听器—证书”三层排查:ss -lntp | grep -E '8080|8443' 看监听是否存在;curl -vk --resolve your-domain:8443:127.0.0.1 https://your-domain:8443/ 看 TLS 握手与证书链;最后核对配置(Spring Boot 3 中 server.ssl.key-store-type 默认已是 PKCS12,server.ssl.enabled 默认 true):
# 生成自签 PKCS12(测试用;生产请用 Let's Encrypt / 商业证书,参考 Let's Encrypt 文档 certbot)
keytool -genkeypair -alias undertow -keyalg RSA -keysize 2048 -validity 365
-storetype PKCS12 -keystore keystore.p12 -storepass changeit
-dname "CN=localhost"
server.port=8443
server.ssl.enabled=true # 默认 true
server.ssl.key-store=classpath:keystore.p12
server.ssl.key-store-type=PKCS12 # Boot 3 默认值
server.ssl.key-store-password=changeit
server.ssl.key-alias=undertow
想同时保留 8080(仅跳转)与 8443(TLS),需自定义 WebServerFactoryCustomizer<UndertowServletWebServerFactory>,在 addHttpsListener(8443, "0.0.0.0", sslContext) 之外显式 addHttpListener(8080, "0.0.0.0");只配 server.port 时 Undertow 只开一个监听器,这正是 Connection refused 的常见来源。防火墙层面据 Mozilla Server Side TLS 指南的建议,只放行 443/8443 对外,8080 仅限代理内网。
如何确认 Undertow 强制 HTTPS 已生效?6 个验证命令与检查点
验证 Undertow 强制 HTTPS 不能只看“浏览器地址栏变绿”,要分四层:跳转、证书与 ALPN、协议版本、代理头信任边界。下面 6 个检查点按顺序执行,任何一层通过都不代表整体安全。以下命令基于 Spring Boot 3.3(内嵌 Undertow 2.3.x)默认的 8080/8443 双端口,示例域名为 example.com。
检查点 1:HTTP 端口是否返回 301,且 Location 指向 HTTPS?这是最直接的证据,据 RFC 9110 §15.4.2,301 表示目标资源已永久迁移,客户端应复用新 URI。
# -I 只看响应头;关键看状态行与 Location
curl -I http://example.com:8080/health
# 期望:
# HTTP/1.1 301 Moved Permanently
# Location: https://example.com:8443/health
# 跟随跳转,只看最终状态码与落地 URL
curl -sS -o /dev/null -w '%{http_code} %{url_effective}n' -L http://example.com:8080/health
# 期望:200 https://example.com:8443/health
注意:301 会被浏览器长期缓存,调试阶段建议改用 302 或清理缓存,否则“改了代码却仍跳转”的假象多半来自缓存。
检查点 2:HTTPS 直连是否 200,HSTS 头是否只出现在安全响应里?
curl -I https://example.com:8443/
# 期望 HTTP/2 200,并包含:
# Strict-Transport-Security: max-age=31536000 ; includeSubDomains
# HSTS 绝不能出现在明文响应中,下面应无任何输出
curl -sI http://example.com:8080/health | grep -i strict-transport-security
Spring Security 的 httpStrictTransportSecurity() 默认 maxAge 为 31536000 秒(一年),仅在请求被判定为 secure 时才写入响应头,符合 RFC 6797 对“STS 头必须经安全传输”的要求。若你的值是 300,说明用了最短测试值,上线前应调高。
检查点 3:证书域名、有效期与 ALPN 协商结果。
# 提取证书主体与有效期(-servername 用于 SNI,多域名部署必带)
openssl s_client -connect example.com:8443 -servername example.com -alpn h2,http/1.1 /dev/null
| openssl x509 -noout -subject -dates
# 确认 HTTP/2 是否真正协商成功
openssl s_client -connect example.com:8443 -servername example.com -alpn h2 /dev/null
| grep 'ALPN protocol'
# 期望:ALPN protocol: h2
若这里显示 No ALPN negotiated,先查 server.http2.enabled——Spring Boot 3.3 中该项默认 false,Undertow 不会自动开启 h2。
检查点 4:TLS 版本是否被限制在 1.2/1.3。
curl -I --tlsv1.2 --tls-max 1.2 https://example.com:8443/ # 期望 200
curl -I --tlsv1.3 https://example.com:8443/ # 期望 200(curl ≥ 7.52)
curl -I --tlsv1.1 https://example.com:8443/ # 期望失败
# 典型报错:curl: (35) error:0A00042E:SSL routines::tlsv1 alert protocol version
对应配置 server.ssl.enabled-protocols=TLSv1.2,TLSv1.3,Spring Boot 3.3 默认即为这两项;若 1.1 仍能握手,说明配置被自定义 SslContext 或前置负载均衡器覆盖了。
检查点 5:X-Forwarded-Proto 能否被伪造绕过?这是 undertow 强制 HTTPS 最容易被忽视的漏洞:只认头、不认来源,等于把开关交给了攻击者。
# 可信代理(如 127.0.0.1)注入:应放行,返回 200
curl -i -H 'X-Forwarded-Proto: https' http://127.0.0.1:8080/
# 非可信来源直接伪造:必须仍然 301
curl -i -H 'X-Forwarded-Proto: https' http://203.0.113.10:8080/
Spring Boot 的 server.forward-headers-strategy 默认值为 NONE,可选 NATIVE/FRAMEWORK;一旦开启,必须配合代理 IP 白名单(如 Undertow 的 UndertowDeploymentInfoCustomizer 或前置 Nginx 的 set_real_ip_from),否则任意客户端加个头就能跳过跳转。
检查点 6:端口监听与浏览器实际表现。
ss -lntp | grep -E ':(8080|8443)'
# 期望两行 LISTEN,分别对应 HTTP 与 HTTPS 监听器
浏览器 DevTools 的 Network 面板应看到首个请求 301、第二个请求 200;Security 面板显示 TLS 1.3 与完整证书链。若 Security 面板提示“证书无效”,而 curl 正常,通常是证书链缺中间证书。
| 检查点 | 通过判据 | 常见失败含义 |
|---|---|---|
| 1 HTTP 跳转 | 301 + Location 指向 https | Filter 顺序错,跳转被静态资源处理器短路 |
| 2 HSTS | 仅 HTTPS 响应含 STS 头 | 用 response.setHeader 硬写,明文也带出 |
| 3 证书/ALPN | 域名匹配、未过期、h2 |
server.http2.enabled=false 或 SNI 未配置 |
| 4 协议版本 | 1.2/1.3 通、1.1 拒 | 自定义 SSLContext 覆盖默认值 |
| 5 代理头 | 伪造来源仍 301 | 信任所有 X-Forwarded-* |
| 6 监听 | 8080、8443 均 LISTEN | 只起了 HTTPS 连接器,HTTP 无监听 |
Undertow 强制 HTTPS 之后:证书链、HSTS 与 HTTP/2 的收尾检查
301 跳转和 Filter 都生效了,为什么客户端仍然握手失败?undertow 强制https 只解决”明文流量改道”,剩下四件事决定这套配置能不能上生产:证书链完整度、HSTS 上线节奏、TLS 协议与套件、HTTP/2 是否真的协商成功。
证书链为什么在浏览器正常、在 Java 里却报错?
浏览器会自行补全缺失的中间证书(AIA fetching),Java 的 JSSE 默认不做这件事。链不完整时典型报错是 javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target,Android 与 OkHttp 同样中招。据 Let’s Encrypt 文档,服务端应下发”叶子证书 + 全部中间 CA”,根证书不要下发。
# 1) 看服务端实际下发了哪些证书:理想输出是 1 张叶子 + 1~2 张中间 CA
openssl s_client -connect example.com:8443 -servername example.com -showcerts /dev/null
| openssl crl2pkcs7 -nocrl -certfile /dev/stdin | openssl pkcs7 -print_certs -noout
# 2) 用系统信任库模拟真实校验:必须返回 Verify return code: 0 (ok)
openssl s_client -connect example.com:8443 -servername example.com
-CAfile /etc/ssl/certs/ca-certificates.crt -verify_return_error /dev/null | grep "Verify return code"
# 3) 修复:把中间证书拼进 PKCS12(顺序必须是叶子在前、中间在后)
cat fullchain.pem privkey.pem > server.pem
openssl pkcs12 -export -in server.pem -out keystore.p12 -name undertow -noiter -nomaciter
注意 -servername 不能省:SNI 缺失时可能拿到默认虚拟主机的证书,验证结论失真(OpenSSL 文档 openssl-s_client)。
HSTS 应该一步到位设成 31536000 吗?
不要。RFC 6797 明确 max-age 是”客户端缓存多久不回退到 HTTP”,一旦某个子域只有 HTTP,被 includeSubDomains 覆盖后用户将直接看到不可绕过错误页。建议按下表推进,每档至少观察 1~2 天全量访问日志:
| 阶段 | 响应头 | 验证目标 | 回滚成本 |
|---|---|---|---|
| 观察 | max-age=300 |
所有子域 301 后无重定向环、无混合内容告警 | 5 分钟 |
| 扩大 | max-age=86400; includeSubDomains |
确认无纯 HTTP 子域(含内网域名、旧 API 域名) | 1 天 |
| 长期 | max-age=31536000; includeSubDomains |
证书自动化续期已验证通过 | 1 年 |
| preload | 上一行 + preload |
已提交 hstspreload.org 且不可撤回 | 数月,不推荐随意启用 |
Undertow 无内置 HSTS 处理器,Spring Boot 3.3 中可在反向代理层加,也可用一个 OncePerRequestFilter 写 response.setHeader("Strict-Transport-Security", ...),仅在 request.isSecure() 为真时下发。
TLS 协议与套件该显式锁定吗?
Undertow 2.3.x(Spring Boot 3.3 默认内嵌版本)走 JSSE,server.ssl.enabled-protocols 不配置时使用 JSSE 默认值,在 JDK 17 上通常已是 TLSv1.2/1.3,但显式声明可避免 JDK 升级或安全策略文件带来的漂移;server.ssl.ciphers 默认 null(沿用 JSSE 套件列表)。
server:
port: 8443
ssl:
enabled: true
key-store: classpath:keystore.p12
key-store-type: PKCS12
key-store-password: ${KEYSTORE_PASS}
enabled-protocols: TLSv1.2,TLSv1.3 # 关掉 TLSv1.0/1.1,二者已被 RFC 8996 废弃
ciphers: TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,ECDHE-RSA-AES128-GCM-SHA256
http2:
enabled: true # 仅在 TLS+ALPN 下对 HTTPS 生效
# 改完先核对套件名是否被 JSSE 识别(拼错会被静默忽略)
openssl ciphers -v 'ECDHE-RSA-AES128-GCM-SHA256'
OCSP stapling 与 HTTP/2 怎么验证?
OCSP stapling 一般在 Nginx / ALB 层开启,Undertow 直连场景默认不提供。检查命令与期望输出:
# 期望看到:OCSP Response Status: successful (0x0);未开启则是 "no response sent"
openssl s_client -status -connect example.com:8443 -servername example.com /dev/null | grep -A1 "OCSP Response Status"
# HTTP/2 生效判据:第一行必须是 HTTP/2 200,且 ALPN protocol: h2
curl -sI --http2 https://example.com:8443/ | head -1
openssl s_client -alpn h2 -connect example.com:8443 -servername example.com /dev/null | grep "ALPN protocol"
返回 HTTP/1.1 200 说明 ALPN 未协商成功——先确认 server.http2.enabled=true 且走的是 TLS 端口,再确认前置代理没有把 h2 降级为 http/1.1。至于 h2c 明文升级,在 undertow 强制https 场景下不建议在生产启用:它绕过加密同时引入额外升级往返,收益远小于风险。若 OCSP 无法开启,至少要有证书到期告警(如 cert-exporter 在剩余 21 天时告警)与吊销监控兜底。
不推荐。只开 8443 时,旧 http:// 链接、HTTP 健康检查和已收录 URL 会连接失败而不是 301 跳转;更稳妥的是保留 8080/80 做 301,443/8443 承载 TLS,并用 curl -I 验证 Location 正确。
已有 Nginx/ALB 时优先在入口层做 301,证书、HSTS 和 OCSP 集中管理,Undertow 只监听 127.0.0.1:8080 并校验 X-Forwarded-Proto 防绕过。纯内嵌 Undertow、无反向代理时再用 Filter 或自定义 HttpHandler 做 Undertow 强制 HTTPS。
常见原因是代理没有传 X-Forwarded-Proto,或 8443 上又执行了一次跳转。检查 Nginx 是否有 proxy_set_header X-Forwarded-Proto $scheme;,并确认 Filter/Handler 只对非 https 请求返回 301,HTTPS 请求直接 chain.doFilter。
301 可能被部分客户端把 POST 改为 GET,需要保留方法的场景用 308,或让客户端直接访问 https。调试期也可先用 302/307 验证逻辑,再切到 301 做永久 HTTPS 化。
不需要,强制跳转和证书是两件事。证书仍绑定域名,PKCS12 别名要与 server.ssl.key-alias 一致,证书链要完整;跳转只负责把 http 请求 301 到 https,不改变证书签发流程。
用 curl -I http://example.com:8080/ 看是否返回 301 和 Location;用 curl -I -L https://example.com:8443/ 看最终是否 200;再用 openssl s_client -connect example.com:8443 -servername example.com -alpn h2 检查证书与 ALPN。
不建议马上开。先设 Strict-Transport-Security: max-age=300 验证所有子域 HTTPS 可用,再逐步提高到 31536000;preload 申请后回滚慢,据 RFC 6797 应确认 includeSubDomains 不会影响纯 HTTP 子域。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。