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	boolean	否	false	设为 true 时，将 HTTP 请求重定向到相同 URI 的 HTTPS 地址，状态码为 301。支持保留查询参数。
uri	string	否	-	目标 URI，支持 NGINX 变量（如 $uri/index.html 或 ${uri}/index.html）。变量不存在时视为空值。
regex_uri	string[]	否	-	通过正则表达式匹配并重写 URI，格式为 ["匹配规则", "替换模板"]。例：["^/user/(.*)/(.*)", "/profile/$1-$2"]。
ret_code	integer	否	302	重定向的 HTTP 状态码（如 301 永久跳转、302 临时跳转）。
encode_uri	boolean	否	false	设为 true 时，按 RFC3986 编码 Location 头。
append_query_string	boolean	否	false	设为 true 时，将原始请求的查询参数追加到重定向 URL 后。若目标 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 插件实现。