# Redirect 配置选项

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

## 静态配置[​](#static-configurations "静态配置的直接链接")

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

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

* 主机或 Docker
* Kubernetes (Helm)

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

config.yaml

```
plugin_attr:

  redirect:

    https_port: 8443
```

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

通过 Helm 部署时，请更新 Chart 中用于生成 `plugin_attr.redirect` 的配置项。保留配置文件中的其他内容。

APISIX Helm Chart 的配置如下。

values.yaml

```
apisix:

  pluginAttrs:

    redirect:

      https_port: 8443
```

API7 网关 Helm Chart 的配置如下。

values.yaml

```
pluginAttrs:

  redirect:

    https_port: 8443
```

使用部署网关时所用的 Chart 应用完整的 values 文件。

```
helm upgrade <release-name> <chart-name> -n <namespace> -f values.yaml
```

## 参数[​](#parameters "参数的直接链接")

所有插件均支持的配置项，请参见[插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)。

* uri

  string

  有效值：

  至少 2 个字符

  ***

  重定向目标。支持 `$uri` 和 `$host` 等[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。

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

  请在 `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`。

  仅当直接对等端属于[可信转发地址](https://docs.apiseven.com/hub/real-ip.md#信任转发的客户端信息)时，网关才使用 `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`，请勿开启此字段。
