Skip to content

重定向示例 ​

通常 省略 backend.type:仅在配置了 backend.redirect 时会推断为 redirect。examples/ssl-tls/route-redirect.yaml 用两个 host 分别演示 type: redirect 与省略。examples/redirect/capture-and-mixed.yaml 在同一文件里混用「部分 backend 显式写 backend.type、部分省略」。若 ingress validate 提示歧义再显式写 backend.type: redirect。不要在同一个 backend 上同时配置 backend.service / backend.handler 与 backend.redirect——同一 host 需要反代与跳转时请拆到不同 paths(见下例)。

全局 HTTP→HTTPS(在路由之前)请用 https.redirect_from_http,见 SSL/TLS。

配置文件:examples/redirect/;最简单的 host 级跳转见 route-redirect.yaml。

跳转状态码(duration + preserve_request) ​

用 duration(temporary | permanent)和 preserve_request(true | false)选择 302 / 301 / 307 / 308,无需死记数字。旧字段 permanent / with_origin_method_and_body 仍兼容,请优先用新字段。

durationpreserve_request状态码
temporaryfalse302
permanentfalse301
temporarytrue307
permanenttrue308
yaml
version: v1
port: 8080

# Redirect status codes (scheme A: duration + preserve_request).
# Each host returns a different status when probed with GET.

rules:
  - host: r302.example.com
    backend:
      redirect:
        url: https://target.example.com
        duration: temporary
  - host: r301.example.com
    backend:
      redirect:
        url: https://target.example.com
        duration: permanent
  - host: r307.example.com
    backend:
      redirect:
        url: https://target.example.com
        duration: temporary
        preserve_request: true
  - host: r308.example.com
    backend:
      redirect:
        url: https://target.example.com
        duration: permanent
        preserve_request: true

示例中每个 host 在 GET 时返回不同状态码。POST/API 场景若需保留方法与 body,请设 preserve_request: true(307/308)。

路径正则 redirect ​

paths[].path 为 Go 正则(编译时隐式加前缀 ^)。path 级 backend.redirect 与 service/handler 共用同一套匹配;在 redirect.url 中用 ${path.N} 引用捕获组,需要精确匹配时在 pattern 末尾加 $。Path 级 url 默认按配置原样使用(不追加请求的 path/query),需要保留时在该 path backend 上写 preserve_path: true;host 级 redirect 始终保留。

yaml
version: v1
port: 8080

rules:
  - host: redirect.example.com
    backend:
      redirect:
        url: https://new.example.com
        permanent: true
    paths:
      # Path-level redirects use redirect.url as configured: the request path/query are not appended.
      # Prefix match: /legacy/* → fixed archive URL (explicit path in url).
      - path: /legacy/
        backend:
          redirect:
            url: https://archive.example.com/docs
            permanent: true
      # Path-level default: url has no path → Location is exactly https://landing.example.com
      # (the /root-only/... request path and query are dropped).
      - path: /root-only/
        backend:
          redirect:
            url: https://landing.example.com
      # preserve_path: true restores the host-level whole-site semantics for this path:
      # /mirror/docs?lang=en → https://mirror.example.com/mirror/docs?lang=en
      - path: /mirror/
        backend:
          redirect:
            url: https://mirror.example.com
            preserve_path: true
      # Regex capture: /go/{segment} → templated host from ${path.1}.
      - path: /go/([^/]+)$
        backend:
          redirect:
            url: https://seg.${path.1}.example.com/app
      # Exact match: only /promo → fixed campaign landing (explicit path in url).
      - path: /promo$
        backend:
          redirect:
            url: https://campaign.example.com/special

/legacy/ 为前缀匹配并跳到固定 URL;/root-only/ 演示 path 级默认行为(Location 就是配置的 url);/mirror/ 用 preserve_path: true 找回保留语义;/go/([^/]+)$ 用 ${path.1} 展开;/promo$ 仅匹配 /promo 并跳到明确 landing path。未命中任何 path 时回退到 host 级 redirect(保留 path 与 query)。

正则 host:redirect.url 中的捕获 ​

与 service.name 相同的占位规则:$1、${host.1} 等。

下例同时演示:正则 host 重定向、host 默认重定向 + 路径反代、以及路径捕获 ${path.N}:

yaml
version: v1
port: 8080

rules:
  - host: '^bigscreen-([^.]+)\.example\.com$'
    host_type: regex
    backend:
      type: redirect
      redirect:
        url: https://bigscreen-$1.other.example.com
  - host: app.example.com
    backend:
      redirect:
        url: https://www.example.com/landing
    paths:
      - path: ^/api/
        backend:
          type: service
          service:
            name: api-svc
            port: 8080
            protocol: http
  - host: api.example.com
    backend:
      service:
        name: default-upstream
        port: 8080
        protocol: http
    paths:
      - path: ^/go/([^/]+)$
        backend:
          redirect:
            url: https://seg.${path.1}.example.com/resource

每条规则在演示什么 ​

  1. 正则 host:^bigscreen-([^.]+)\.example\.com$,在 redirect.url 里使用 $1。
  2. Host 默认重定向 + 路径服务:未匹配的 path 走跳转;匹配 ^/api/ 的走后端。
  3. ${path.N}:路径正则捕获填入 redirect.url。

Released under the MIT License.