跳到主要内容

Redirect 配置选项

redirect 插件为路由和服务返回可配置的 HTTP 重定向,支持用正则表达式生成目标地址,也支持从 HTTP 重定向到 HTTPS。 配置涵盖静态设置和插件参数。

静态配置​

若要让 http_to_https 重定向使用指定的 HTTPS 端口,请设置 plugin_attr.redirect.https_port。省略该配置时,插件会从 apisix.ssl.listen 已启用的端口中随机选择一个。如果没有已启用的监听器提供端口,则使用 443。此设置只修改 Location 中的端口,仍需配置网关在同一端口监听 HTTPS 请求。

根据网关的部署方式更新相应文件。

通过主机或 Docker 部署时,请将插件属性添加到持久化的网关配置文件。

config.yaml
plugin_attr:
redirect:
https_port: 8443

重新加载或重启网关,使改动生效。

参数​

所有插件均支持的配置项,请参见插件通用配置。

  • uri

    string

    有效值:

    至少 2 个字符

    重定向目标。支持 $uri 和 $host 等内置变量。

    不存在的变量会解析为空字符串。

    请在 uri、regex_uri 和 http_to_https 中选择且仅配置一项。

  • regex_uri

    array[string]

    有效值:

    必须为 2 个元素

    根据请求路径生成重定向目标的正则表达式和替换内容。第一个元素是匹配模式,第二个元素是替换内容。

    请求路径未匹配时,插件不会重定向该请求。uri、regex_uri 和 http_to_https 必须且只能配置其中一项。

  • http_to_https

    boolean


    设为 true 时,将 HTTP 请求重定向到相同主机和请求 URI 的 HTTPS 地址。GET 和 HEAD 请求使用 301,其他方法使用 308。

    仅当直接对等端属于可信转发地址时,网关才使用 X-Forwarded-Proto,否则使用网关实际接收到的连接协议。将终止 TLS 的代理配置为可信代理,可避免对客户端已通过 HTTPS 发送的请求反复重定向。

    请在 uri、regex_uri 和 http_to_https 中选择且仅配置一项。配置此字段时,不能同时配置 append_query_string。

  • ret_code

    integer

    默认值:302

    有效值:

    大于或等于 200

    用于 uri 和 regex_uri 重定向的 HTTP 状态码。标准重定向使用 3xx 状态码。

    此字段不影响 http_to_https 重定向。

  • encode_uri

    boolean

    默认值:false


    设为 true 时,按照 RFC 3986 对重定向目标进行百分号编码,并保留其查询字符串。

  • append_query_string

    boolean

    默认值:false


    设为 true 时,将原始请求的查询字符串附加到重定向目标。如果目标已包含查询字符串,则用 & 拼接原始值。

    如果目标已包含原始查询字符串(例如通过 $request_uri 引入),或已配置 http_to_https,请勿开启此字段。