Redirect
redirect 插件可以在请求到达上游前,由路由或服务直接返回 HTTP 重定向。它可以将客户端从旧路径重定向到新端点,使用请求变量或正则表达式捕获的内容构建目标地址,也可以将 HTTP 流量重定向到 HTTPS。
请求处理
只配置一种重定向模式。
| 模式 | 行为 |
|---|---|
uri | 将每个匹配的请求重定向到固定地址或基于变量生成的地址。 |
regex_uri | 如果请求路径匹配正则表达式,按该表达式改写路径并重定向。未匹配的请求继续转发给上游服务。 |
http_to_https | 将 HTTP 请求重定向到相同主机和请求 URI 的 HTTPS 地址。 |
固定地址和正则表达式重定向使用配置的响应状态码,默认为 302。正则表达式未匹配时,请求继续转发给上游。自动将 HTTP 重定向到 HTTPS 时,GET 和 HEAD 请求使用 301,其他方法使用 308。已经使用 HTTPS 的请求继续转发给上游。
示例
第一个示例使用正则表达式配置永久重定向,并保留原始查询字符串。第二个示例将 HTTP 请求重定向到相同主机和请求 URI 的 HTTPS 地址。
重定向旧路径
此路由将 /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}"
创建服务和路由。
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
创建第二条路由,将 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 中,为现有服务添加一条路由。
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,则省略端口。