基本功能

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

使用方法

{"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