API7 网关 AI Agent Skill：redirect 插件

概览

redirect 插件会向客户端返回 HTTP 重定向响应（如 301、302 等）， 可将客户端重定向到新的 URI、强制使用 HTTPS，或使用正则表达式执行复杂的路径转换。与 proxy-rewrite（只会在转发到上游前重写请求）不同，该插件会直接向客户端返回重定向响应。

适用场景

• 通过将所有 HTTP 请求重定向到 HTTPS 来强制使用 HTTPS。
• 将旧 URL 重定向到新地址（301 永久重定向）。
• 使用正则捕获组进行基于模式的 URI 重写
• 重定向到外部域名。
• 在重定向期间追加或保留查询字符串。

插件配置参考（路由/服务）

字段	类型	是否必填	默认值	说明
http_to_https	boolean	否	false	将 HTTP 重定向到 HTTPS，保留 URI 和查询字符串，并使用 301 状态码。
uri	string	否	—	目标重定向 URI。支持 Nginx 变量（$uri、$host 等），也可以是绝对 URL。
regex_uri	array[string]	否	—	包含两个元素的数组：["regex_pattern", "replacement"]。PCRE 正则表达式支持捕获组。
ret_code	integer	否	302	重定向响应使用的 HTTP 状态码。
encode_uri	boolean	否	false	根据 RFC 3986 对 Location 请求头中的 URI 编码。
append_query_string	boolean	否	false	将原始请求查询字符串追加到重定向 Location。

互斥关系：http_to_https、uri 和 regex_uri 一次只能配置其中一项。

注意：http_to_https 和 append_query_string 不能同时使用（http_to_https 已经会保留查询字符串）。

HTTPS 端口选择（用于 http_to_https）

当 http_to_https 为 true 时，HTTPS 端口按以下优先级确定：

1. plugin_attr.redirect.https_port 在 conf/config.yaml
2. 如果配置了 SSL，则从 apisix.ssl.listen 中选择随机端口。
3. 默认值：443

分步指南：在路由上启用 redirect

1. HTTP 到 HTTPS 重定向

在网关组 default 中启用 HTTPS：

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "force-https",
  "uri": "/*",
  "plugins": {
    "redirect": {
      "http_to_https": true
    }
  }
}
EOF

结果：http://example.com/path?q=1 → https://example.com/path?q=1（301）

2. 简单 URI 重定向（永久移动）

a7 route create --gateway-group prod -f - <<'EOF'
{
  "id": "old-to-new",
  "uri": "/old-page",
  "plugins": {
    "redirect": {
      "uri": "/new-page",
      "ret_code": 301
    }
  }
}
EOF

3. 使用捕获组进行正则重定向

a7 route create --gateway-group stage -f - <<'EOF'
{
  "id": "regex-redirect",
  "uri": "/blog/*",
  "plugins": {
    "redirect": {
      "regex_uri": ["^/blog/(\\d{4})/(\\d{2})/(.*)$", "/articles/$1-$2-$3"],
      "ret_code": 301
    }
  }
}
EOF

结果：/blog/2024/03/my-post → /articles/2024-03-my-post

常见模式

重定向到外部域名

{
  "plugins": {
    "redirect": {
      "uri": "https://new-domain.com/api/v2",
      "ret_code": 301
    }
  }
}

使用 NGINX 变量重定向

{
  "plugins": {
    "redirect": {
      "uri": "https://new-domain.com$request_uri",
      "ret_code": 301
    }
  }
}

保留完整的原始路径和查询字符串。

追加尾部斜杠

{
  "plugins": {
    "redirect": {
      "uri": "$uri/",
      "ret_code": 301
    }
  }
}

保留查询字符串进行重定向

{
  "plugins": {
    "redirect": {
      "uri": "/new-path",
      "append_query_string": true,
      "ret_code": 302
    }
  }
}

请求：/old-path?foo=bar&baz=1 → Location：/new-path?foo=bar&baz=1

对 URI 中的特殊字符编码

{
  "plugins": {
    "redirect": {
      "uri": "/path with spaces/resource",
      "encode_uri": true,
      "ret_code": 302
    }
  }
}

Location 请求头：/path%20with%20spaces/resource

用于维护的临时重定向（302）

{
  "plugins": {
    "redirect": {
      "uri": "/maintenance.html",
      "ret_code": 302
    }
  }
}

使用 302（临时重定向），避免浏览器缓存该重定向。

故障排查

现象	原因	解决方法
重定向循环	路由匹配了重定向目标	确保目标 URI 不会匹配同一路由
HTTPS 端口错误	默认端口选择不正确	在 config.yaml 中设置 plugin_attr.redirect.https_port
查询字符串丢失	使用 uri 时未设置 append_query_string	添加 "append_query_string": true，或使用 $request_uri
查询字符串重复	append_query_string 与 $request_uri 同时使用	不要同时使用二者；$request_uri 已包含查询字符串
Nginx 变量为空	变量不存在	不存在的变量会解析为空字符串（不会报错）
正则表达式未匹配	转义或模式有误	在 JSON 中转义反斜杠：\\d+；使用 PCRE 语法测试正则表达式
同时设置多个重定向选项	http_to_https、uri 和 regex_uri 互斥	三个选项只能选择其中一个
配置未生效	指定了错误的网关组	确保 --gateway-group 与目标集群一致

配置同步示例

version: "1"
gateway_group: default
routes:
  - id: force-https
    uri: /*
    plugins:
      redirect:
        http_to_https: true
  - id: old-blog-redirect
    uri: /blog/*
    plugins:
      redirect:
        regex_uri:
          - "^/blog/(\\d{4})/(\\d{2})/(.*)"
          - "/articles/$1-$2-$3"
        ret_code: 301

---

本页面由 api7/a7 仓库中的 a7-plugin-redirect/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。