apisix~redirect重定向插件

将某个长链接，使用一个域名代替它，在浏览器上输入域名，可以直接重定向到这个链接对接的网络

{
  "uri": "/*",
  "name": "short",
  "methods": [
    "GET",
    "POST",
    "PUT",
    "DELETE",
    "PATCH",
    "HEAD",
    "OPTIONS",
    "CONNECT",
    "TRACE",
    "PURGE"
  ],
  "host": "test.short.com",
  "plugins": {
    "redirect": {
      "http_to_https": false, # 如果你的短域名也用 HTTPS，这个可能不需要或设为 true
      "uri": "https://long.abc.com/auth/realms/demo/protocol/openid-connect/auth",
      "ret_code": 301, # 使用 301 永久重定向 (推荐) 或 302
      "append_query_string": true # 非常重要！保留原始请求的任何查询参数（虽然通常没有，但安全起见加上）
    }
  }
  "status": 1
}

Apache APISIX 的 redirect 插件是用于实现 URI 重定向的核心组件，支持多种重定向场景（如路径修改、HTTP 到 HTTPS 跳转、正则匹配重定向）。以下从功能、配置到实践的详细解析：

???? 一、核心功能与属性

redirect 插件提供以下配置参数，同一时间仅能启用一种重定向类型（http_to_https/uri/regex_uri）：

⚠️ 关键限制

• http_to_https 与 append_query_string 互斥，不可同时使用。
• http_to_https 的 HTTPS 端口优先级：
  1. 配置文件中的 plugin_attr.redirect.https_port；
  2. apisix.ssl.listen 的随机端口；
  3. 默认 443 端口。

⚡ 二、典型配置示例

1. 基础 URI 重定向

将 /test/index.html 重定向到 /test/default.html，状态码 301：

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: <KEY>' -X PUT -d '  
{  
    "uri": "/test/index.html",  
    "plugins": {  
        "redirect": {  
            "uri": "/test/default.html",  
            "ret_code": 301  
        }  
    },  
    "upstream": { ... }  
}'  

测试命令：curl http://127.0.0.1:9080/test/index.html -i 返回 Location: /test/default.html 和状态码 301。

2. 动态变量重定向

使用 NGINX 变量动态生成目标路径（如将 /test 重定向到 /test/index.html）：

{  
    "redirect": {  
        "uri": "$uri/index.html",  
        "ret_code": 301  
    }  
}  

3. HTTP → HTTPS 全局跳转

实现全站 HTTP 请求自动跳转 HTTPS：

{  
    "plugins": {  
        "redirect": {  
            "http_to_https": true  
        }  
    }  
}  

测试命令：curl http://127.0.0.1:9080/hello -i 返回 Location: https://127.0.0.1:9443/hello。

4. 正则表达式重定向

匹配路径 /tls 并重定向到 /tls/（补充斜杠）：

plugins:  
- name: redirect  
  config:  
    regex_uri: ["^(/tls)$", "$1/"]  # 匹配 /tls 并重写为 /tls/  

????️ 三、最佳实践与注意事项

1. 状态码选择

   • 301：永久重定向，适用于长期迁移（如 HTTP → HTTPS）。
   • 302：临时重定向，适合 A/B 测试或临时维护。

2. 协议检测
   启用 http_to_https 前，确保 APISIX 同时监听 HTTP 和 HTTPS 端口，且 SSL 证书已配置（可通过 ApisixTls 资源管理）。

3. 性能优化

   • 全局规则：通过 Global Rule 对所有路由生效，减少重复配置。
   • 正则谨慎：复杂正则可能增加性能开销，优先使用静态 uri 或变量。

4. 查询参数处理

   • 若目标 URI 已含参数（如 https://example.com?src=apisix），启用 append_query_string 会追加为 &foo=bar。
   • 避免与 $request_uri 变量同时使用，否则导致参数重复。

❓ 四、常见问题排查

• 插件未生效：

  1. 检查插件是否启用（enable: true）；
  2. 验证路由匹配规则（如 hosts/paths 是否覆盖请求）；
  3. 排查其他插件冲突（如 proxy-rewrite 可能修改 URI）。

• 端口错误：
  HTTPS 端口未指定时，检查 plugin_attr.redirect.https_port 或 apisix.ssl.listen 配置。

• 正则匹配失败：
  使用在线工具（如 Regex101）验证 regex_uri 规则，确保捕获组与替换模板对齐。

???? 总结

APISIX 的 redirect 插件是流量调度的核心工具，通过灵活配置可覆盖路径调整、协议升级、正则重写等场景。生产环境中，建议结合监控（如 Prometheus 指标）持续跟踪重定向成功率。对于复杂需求（如跨域名跳转），可结合 response-rewrite 插件实现。

作者：仓储大叔，张占岭，
荣誉：微软MVP
QQ：853066980

支付宝扫一扫，为大叔打赏!