Traefik RedirectScheme 中间件完整指南将 HTTP 请求安全重定向到 HTTPS 与自定义端口【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik技术导读本文系统讲解 Traefik 官方 HTTP 中间件RedirectScheme——当请求使用的 scheme协议如 http/https与目标配置不一致时向客户端返回重定向响应。文中将以当前仓库 Traefik v3 为对象覆盖多种配置源结构化 YAML/TOML、Docker/Swarm Labels、Marathon 等 Tags、Kubernetes CRD Middleware的完整写法、scheme/permanent/port三个参数的精确语义并结合 redirect_scheme.go 与 redirect_scheme_test.go 深入解析其如何依赖X-Forwarded-Proto判定 scheme、如何生成 301/302/307/308 响应以及默认端口自动归一化等底层原理。读完本文你可以独立完成全站 HTTP→HTTPS 强制跳转多端口重定向等生产级配置并能准确预判在不同反向代理场景下的行为。一、RedirectScheme 是什么RedirectScheme是 Traefik HTTP 路由链中的一种重定向类中间件。它的核心职责非常简单当客户端请求所使用的 scheme协议与配置中期望的 scheme 不同时把请求重定向到期望的 scheme。也就是说它并不会把所有请求一律跳转而是先做协议是否一致的判断请求已是目标 scheme例如配置为https且请求本身就是 HTTPS则直接放行到下一个处理器请求 scheme 与目标不一致例如配置为https但请求是 HTTP则返回 3xx 重定向并把Location指向 scheme 与可选的端口重写后的同路径 URL。最典型的生产场景是全站强制 HTTPS将监听在:80入口点的 HTTP 请求统一重定向到 HTTPS 入口点从而避免明文传输。此外它也能在多个协议端口共存的场景下如 http:8080 与 https:8443把流量引导到正确的端点。从源码结构看重定向中间件家族共包含两类成员均位于 pkg/middlewares/redirect 目录中间件依据实现文件RedirectScheme依据scheme / 端口redirect_scheme.goRedirectRegex依据正则表达式redirect_regex.go其中RedirectScheme在服务启动装配时由 pkg/server/middleware/middlewares.go#L322 调用redirect.NewRedirectScheme(ctx, next, *config.RedirectScheme, middlewareName)创建属于动态配置中声明即生效的中间件。二、部署前置条件反向代理链中的信任关系文档见 redirectscheme.md在正文开头就给出了一个重要的前置警告当 Traefik 前面还有至少一个反向代理时这个最后一跳的反向代理必须被 Traefik 视为**可信trusted**来源。原因在于 RedirectScheme 判断客户端实际使用的协议依赖的是从上游转发的X-Forwarded系列请求头详见下文scheme 判定原理。如果中间的代理不被信任Traefik 会清理掉这最后一跳传入的X-Forwarded-Proto等转发头以防止伪造此时 RedirectScheme 便无从得知真实协议重定向行为就会失效或产生错误结果。如何把前置代理加入可信来源请参阅入口点配置文档中的可信代理Forwarded Headers / trusted IPs相关小节entrypoints.md 配置选项。三、Configuration Examples五种配置源完整示例原文档给出了四段直接可用的配置示例YAML、TOML、Labels、Tags外加 Kubernetes CRD 写法此处完整保留并补充说明每一种写法的适用 Provider。1. 结构化配置YAML适用于以静态文件、Docker/K8s 等 Provider 注入的动态配置# Redirect to https http: middlewares: test-redirectscheme: redirectScheme: scheme: https permanent: true2. 结构化配置TOML# Redirect to https [http.middlewares] [http.middlewares.test-redirectscheme.redirectScheme] scheme https permanent true3. Docker / Swarm 容器标签LabelsLabels写法适用于 Docker、Docker Swarm Provider在容器或服务上以traefik.http.middlewares.name.optionvalue形式声明# Redirect to https labels: - traefik.http.middlewares.test-redirectscheme.redirectscheme.schemehttps - traefik.http.middlewares.test-redirectscheme.redirectscheme.permanenttrue4. Marathon 等 TagsTags写法适用于 Marathon、Rancher、Consul Catalog 等以键值 Tags 提供元数据的 Provider键名规则与 Labels 相同// Redirect to https { // ... Tags: [ traefik.http.middlewares.test-redirectscheme.redirectscheme.schemehttps, traefik.http.middlewares.test-redirectscheme.redirectscheme.permanenttrue ] }5. Kubernetes CRD Middleware在 Kubernetes 中推荐通过自定义资源Middlewaretraefik.io/v1alpha1声明再用注解挂载到 IngressRoute# Redirect to https apiVersion: traefik.io/v1alpha1 kind: Middleware metadata: name: test-redirectscheme spec: redirectScheme: scheme: https permanent: true注意 K8s Labels 写法中 key 的大小写容器标签场景下中间件名称段统一使用小写redirectscheme而 YAML/TOML/CRD 中字段使用驼峰redirectScheme。从源码看Labels/Tags 这类键值对最终会通过 pkg/config/label 的解析器映射到结构化字段因此键名遵循 Provider 的标签命名约定traefik.http.middlewares.*而 CRD 的spec.redirectScheme则由 pkg/provider/kubernetes/crd/kubernetes.go#L323 直接拷贝到动态配置结构体中。6. 把中间件挂载到路由器上使用声明中间件本身并不会生效必须通过路由器的middlewares引用它才会进入请求处理链。以最常用的容器 Labels 为例完整的中间件 路由器 HTTPS 入口点强制跳转组合如下labels: # 1) 声明中间件 - traefik.http.middlewares.redirect-to-https.redirectscheme.schemehttps - traefik.http.middlewares.redirect-to-https.redirectscheme.permanenttrue # 2) 在路由器上引用example.com 的 HTTP 请求将被跳转到 https://example.com/... - traefik.http.routers.my-router.ruleHost(example.com) - traefik.http.routers.my-router.entrypointsweb - traefik.http.routers.my-router.middlewaresredirect-to-https对 Kubernetes 的 IngressRoute 场景则在routes[].middlewares中按名称引用已创建的Middleware资源。四、Configuration Options参数详解原文档的参数表如下这是该中间件全部对外暴露的配置项FieldDescriptionDefaultRequiredscheme新 URL 使用的协议schemeYespermanent是否启用永久重定向对应 301/308falseNoport新 URL 使用的端口。注意必须传字符串而不是数值No三个参数的精确语义与取值约束说明如下。scheme必填目标协议决定请求应被重定向到http、https源码常量定义于 redirect.go测试用例还覆盖了wss作为目标的场景。必填构造函数中若len(conf.Scheme) 0直接返回错误you must provide a target scheme中间件创建失败见 redirect_scheme.go#L32-L34。permanent可选默认false控制重定向的永久性与返回状态码的映射关系如下详见下文源码分析permanent请求方法返回状态码false临时GET302 Foundfalse临时其他方法如 POST307 Temporary Redirecttrue永久GET301 Moved Permanentlytrue永久其他方法如 POST308 Permanent Redirect状态码会因请求方法不同而变化这一点很容易被忽略permanent对 GET 请求给出 301/302对非 GET 请求则分别给出 308/307以避免 301/302 被某些客户端改写为 GET 而破坏 POST 语义。port可选默认重定向目标 URL 的端口。文档特别强调必须写成字符串如8443而不是数值如8443这与动态配置字段声明为string类型一致。若不设置则目标 URL 保留原请求 Host 中的端口并遵循默认端口归一化规则当 http 配 80、https 配 443 时不携带端口见下文。该端口还可用于改端口跳转例如把http://foo:8080永久重定向到https://foo:8443。值得说明的内部细节结构体 RedirectScheme 实际上还有第四个字段ForcePermanentRedirect但它在 YAML/TOML/Labels 等所有外部配置载体上均被标记为忽略json/toml/yaml/label/file/kv 全部为-仅作为内部字段供Kubernetes ingress-nginx Provider使用——当 Ingress 上开启 SSL 重定向注解时translator.go#L396-L402 会构造RedirectScheme{Scheme: https, ForcePermanentRedirect: true}强制所有方法一律返回 308详见第五节状态码逻辑。五、源码级原理请求如何被判定并重定向1. 重定向目标 URL 的组装NewRedirectSchemeredirect_scheme.go#L27-L57在创建中间件时就固定了两件事目标替换模板为conf.Scheme :// ${2} port ${4}。这里的${2}与${4}引用的是正则捕获组用于匹配原请求 URL 的正则uriPattern^(https?:\/\/)?(\[[\w:.]\]|[\w\._-])?(:\d)?(.*)$即依次捕获协议前缀$1、Host支持 IPv6 字面量[...]与普通域名/IP$2、端口$3、以及其余路径部分$4。其中端口归一化规则在此完成redirect_scheme.go#L36-L39port : if len(conf.Port) 0 !(conf.Scheme schemeHTTP conf.Port 80 || conf.Scheme schemeHTTPS conf.Port 443) { port : conf.Port }含义是scheme为http且port为80或scheme为https且port为443时该端口属于协议默认端口会被省略、不写进目标 URL即http→80、https→443都被视为无端口。例如配置{scheme: http, port: 80}访问http://foo:80时新旧 URL 完全一致中间件不会触发重定向——测试用例to HTTP 80与to HTTPS 443断言返回200 OK正是这一逻辑的验证。2. 当前请求 scheme 的判定X-Forwarded-Proto 是关键中间件必须重建客户端眼中看到的原始 URL再与新目标比较。clientRequestURLredirect_scheme.go#L59-L107按照如下优先级确定 scheme从req.RequestURI中解析显式携带的协议前缀若req.TLS ! nilTraefik 本地已终止 TLS判定为https若请求头存在X-Forwarded-Proto则以它为准并做 WebSocket 语义归并见下最终还会把默认端口从 URL 中剥离http:80 / https:443 不展示。关于第 3 步有一个很关键的实现细节。由于前一跳代理可能把连接升级场景WebSocket的协议写成ws/wss而本中间件只在 HTTP(S) 语境中使用因此 redirect_scheme.go#L87-L101 会做如下转换X-Forwarded-Proto为http或ws→ 按http处理为https或wss→ 按https处理其他未知值 → 记录 Debug 日志Invalid X-Forwarded-Proto并忽略回落到原有判定。这解释了第二节信任警告的必要性如果 Traefik 不信任其前置代理并清除了X-Forwarded-Proto那么真实协议将无法被感知。测试用例HTTP to HTTPS, with X-Forwarded-Proto to HTTPS与...to wss均断言不重定向、返回 200——因为携带的转发头已表明请求实质上已是 https无需再跳转这能有效避免在代理链中形成无限重定向循环。3. 状态码决策与重定向执行真正的重定向执行位于通用实现 redirect.go。ServeHTTP的处理流程为通过rawURL(req)即上面的clientRequestURL重建原始 URL正则不匹配 → 直接放行到 next handler用replacement模板做正则替换得到newURL若newURL ! oldURL→ 交给moveHandler写Location头并返回对应状态码若替换后与原来一致 → 原地把req.URL替换为解析后的新 URL 并继续向后传递这正是已是目标 scheme 则放行的落点。状态码决策逻辑见moveHandler.ServeHTTPredirect.go#L92-L115其规则与第四节参数表中的映射完全对应status : http.StatusFound // 302 if req.Method ! http.MethodGet { status http.StatusTemporaryRedirect // 307 } if m.permanent { status http.StatusMovedPermanently // 301 if req.Method ! http.MethodGet { status http.StatusPermanentRedirect // 308 } } if m.statusCode ! nil { // ForcePermanentRedirect 时强制 308 status *m.statusCode }当ForcePermanentRedirecttrue即 ingress-nginx 的 SSL 重定向场景时permanentRedirectCode被固定为308 Permanent Redirect无论 GET 还是其他方法都返回 308以严格保留请求方法与请求体语义。测试用例HTTP to HTTPS with explicit 308 status code与...for GET request验证了这一行为。六、行为边界与典型场景验证测试用例归纳redirect_scheme_test.go 用约 30 组表格化用例固化了中间件行为以下行为边界均有测试背书可在实际排障时作为预期行为清单场景配置期望行为缺省scheme{}创建中间件报错handler 为 nilHTTP→HTTPSscheme: https302Location: https://foo已是 HTTPSscheme: https请求带X-Forwarded-Proto: https不重定向200代理头为ws/未知值scheme: httpsX-Forwarded-Proto: ws/bar判定为 http →302跳 https代理头为wssscheme: httpsX-Forwarded-Proto: wss判定为 https → 不重定向改端口跳转scheme: https, port: 8443http://foo:8000→https://foo:8443302永久重定向scheme: https, port: 8443, permanent: truehttp://foo→https://foo:8443301默认端口归一scheme: http, port: 80或 https/443与现 URL 相同 → 不重定向200IPv6 支持scheme: httpshttp://[::1]:80→https://[::1]保留方括号与地址WebSocket 目标scheme: wss, port: 9443http://foo→wss://foo:9443302几点从用例中可以总结出的生产经验不要担心多一跳代理后死循环只要前置代理正确设置X-Forwarded-Proto: https即便用户通过 http URL 进入只要 Traefik 接收到的已是 TLS 连接且转发头为 https中间件也会放行但反过来若信任配置缺失导致转发头被清理就会退化为不断跳转。端口跳转时会改写原端口https://foo:8000在scheme: https不带 port的配置下会被归一为https://foo即目标 URL 的端口不是自动沿用原端口而是按配置或默认端口剥离重算。URL 中其他部分路径、查询串保持不变重定向只作用于 scheme/host/port 前缀正则$4捕获的路径部分被原样拼接回目标 URL。IPv6 地址能够正确处理正则中的\[[\w:.]\]分支专门处理[::1]这类字面量跳转后不会丢失方括号。七、与本仓库其他能力的关系与延伸阅读若你需要比 scheme 更复杂的重写规则例如同时改写路径、host应使用同一家族的 RedirectRegex 中间件其实现位于 redirect_regex.go。RedirectScheme 的响应不会被再次套娃处理它属于服务端返回的 3xx 响应若你希望搭配错误页/自定义响应体可结合 customerrors 等机制但最典型的组合仍是HTTPS 入口点只挂 RedirectScheme真实服务放在 HTTPS 路由上。想让 Traefik 自动签发证书配合本中间件实现零人工配置的 HTTPS可结合 Lets Encrypt 配置 与 HTTPS 路由相关文档使用。关于中间件在请求链中的顺序编排、以及chain中间件把多个中间件打包复用可阅读 HTTP 中间件 overview。综上RedirectScheme虽是一个小而专的中间件但其对X-Forwarded-Proto的依赖、对 301/302/307/308 的方法感知选择、对默认端口的归一化处理共同决定了它在反向代理拓扑与 Kubernetes 场景下的精确行为。把握上述源码级细节即可在生产中写出可靠且不会产生重定向风暴的强制 HTTPS 规则。【免费下载链接】traefikThe Cloud Native Application Proxy项目地址: https://gitcode.com/GitHub_Trending/tr/traefik创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考