# Redirect

`redirect` 插件可以在请求到达上游前，由路由或服务直接返回 HTTP 重定向。它可以将客户端从旧路径重定向到新端点，使用请求变量或正则表达式捕获的内容构建目标地址，也可以将 HTTP 流量重定向到 HTTPS。

## 请求处理[​](#request-handling "请求处理的直接链接")

只配置一种重定向模式。

| 模式            | 行为                                                                                     |
| --------------- | ---------------------------------------------------------------------------------------- |
| `uri`           | 将每个匹配的请求重定向到固定地址或基于变量生成的地址。                                   |
| `regex_uri`     | 如果请求路径匹配正则表达式，按该表达式改写路径并重定向。未匹配的请求继续转发给上游服务。 |
| `http_to_https` | 将 HTTP 请求重定向到相同主机和请求 URI 的 HTTPS 地址。                                   |

固定地址和正则表达式重定向使用配置的响应状态码，默认为 `302`。正则表达式未匹配时，请求继续转发给上游。自动将 HTTP 重定向到 HTTPS 时，`GET` 和 `HEAD` 请求使用 `301`，其他方法使用 `308`。已经使用 HTTPS 的请求继续转发给上游。

## 示例[​](#examples "示例的直接链接")

第一个示例使用正则表达式配置永久重定向，并保留原始查询字符串。第二个示例将 HTTP 请求重定向到相同主机和请求 URI 的 HTTPS 地址。

### 重定向旧路径[​](#redirect-a-legacy-path "重定向旧路径的直接链接")

此路由将 `/legacy/<path>` 映射到 `/v2/<path>`。正则表达式匹配时，网关直接返回重定向响应，请求不会到达配置的上游。

为示例创建工作目录并进入该目录。

```
mkdir redirect-example

cd redirect-example
```

如果启用了 Admin API 身份验证，请在使用 **Admin API** 标签页前将具有管理员角色的密钥导出为 `ADMIN_API_KEY`。

* Admin API
* ADC

创建路由。

```
curl "http://127.0.0.1:9180/apisix/admin/routes/redirect-legacy-route" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "uri": "/legacy/*",

    "plugins": {

      "redirect": {

        "regex_uri": ["^/legacy/(.*)", "/v2/$1"],

        "ret_code": 308,

        "append_query_string": true

      }

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "httpbin.org:80": 1

      }

    }

  }'
```

配置 ADC 以连接目标后端。后续 ADC 命令会从这些环境变量读取连接设置。

* APISIX
* API7 Gateway

如果启用了 Admin API 身份验证，请在配置 ADC 前将具有管理员角色的密钥导出为 `ADMIN_API_KEY`。

```
export ADC_BACKEND=apisix

export ADC_SERVER="http://127.0.0.1:9180"

export ADC_TOKEN="${ADMIN_API_KEY}"
```

```
export ADC_BACKEND=api7ee

export ADC_SERVER="https://{DASHBOARD_ADDR}"

export ADC_TOKEN="{DASHBOARD_TOKEN}"

export ADC_GATEWAY_GROUP="{GATEWAY_GROUP}"
```

创建服务和路由。

adc.yaml

```
services:

  - name: redirect-service

    labels:

      docs-example: redirect

    routes:

      - name: redirect-legacy-route

        uris:

          - /legacy/*

        plugins:

          redirect:

            regex_uri:

              - ^/legacy/(.*)

              - /v2/$1

            ret_code: 308

            append_query_string: true

    upstream:

      type: roundrobin

      nodes:

        - host: httpbin.org

          port: 80

          weight: 1
```

预览改动，确认仅影响本示例的资源。

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=redirect
```

核对 `diff.yaml`，再同步带有此标签的服务。

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=redirect
```

向旧路径发送请求。

```
curl --head "http://127.0.0.1:9080/legacy/orders?source=docs"
```

响应应返回 `308 Permanent Redirect`，并在 `Location` 中保留捕获的路径和查询字符串。

```
HTTP/1.1 308 Permanent Redirect

Location: /v2/orders?source=docs
```

### 将 HTTP 重定向到 HTTPS[​](#redirect-http-to-https "将 HTTP 重定向到 HTTPS的直接链接")

创建第二条路由，将 HTTP 请求重定向到相同主机和请求 URI 的 HTTPS 地址。

* Admin API
* ADC

```
curl "http://127.0.0.1:9180/apisix/admin/routes/redirect-https-route" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "uri": "/secure",

    "plugins": {

      "redirect": {

        "http_to_https": true

      }

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "httpbin.org:80": 1

      }

    }

  }'
```

在 `adc.yaml` 中，为现有服务添加一条路由。

adc.yaml (service routes)

```
routes:

  - name: redirect-https-route

    uris:

      - /secure

    plugins:

      redirect:

        http_to_https: true
```

预览并同步更新后的文件。

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=redirect



adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=redirect
```

使用示例主机名发送 HTTP 请求。

```
curl --silent --head "http://127.0.0.1:9080/secure" \

  -H "Host: api.example.com" | \

  grep -E "^(HTTP/|Location:)"
```

响应会将请求永久重定向到相同主机和路径的 HTTPS 地址。

```
HTTP/1.1 301 Moved Permanently

Location: https://api.example.com:9443/secure
```

响应会将请求重定向到选定的非默认 HTTPS 端口。如果使用 HTTPS 默认端口 443，则省略端口。
