基本功能

將某個長鏈接，使用一個域名代替它，在瀏覽器上輸入域名，可以直接重定向到這個鏈接對接的網絡

使用方法

{
  "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 插件實現。