概述
目前云原生网关共支持8种插件配置，可以满足用户的身份认证、流量控制、安全、信息重写等需求。每个插件的配置详情与使用方式可参考以下介绍。
身份认证类
key-auth插件
描述
key-auth 是一个认证插件，在header或者query中匹配key值即可通过认证
作用范围
该插件即可用于全局插件，也可用于路由级插件。全局插件配置的优先级高于路由级插件配置，当同时在某一路由上配置了key-auth的全局插件和路由级插件时，需带上全局插件配置中的key值才能通过。
属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
|---|---|---|---|---|---|
| key | string | 必需 | -- | -- | 在header或者query中通过apikey携带key值进行认证。 |
如何启用
在配置窗口页以YAML格式填写
配置示例
下面是一个示例，填写key-auth配置信息:
“key”:”test”
启用/停用
在配置页面设置生效开关
验证插件
未启用插件时API请求结果
$ curl -i http://198.20.4.150:27151/apitest
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Date: Fri, 23 Dec 2022 03:53:53 GMT
Server: APISIX/2.13.3
rspTest: hello,world
[{"id":1,"productID":1,"reviewer":"Reviewer1","text":"THIS IS A GRAY VERSION "}]
启用插件不带apikey时API的请求结果
$ curl -i http://198.20.4.150:27151/apitest
HTTP/1.1 401 Unauthorized
Date: Fri, 23 Dec 2022 03:54:31 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.13.3
{"message":"Missing API key found in request"}
启用插件带apikey时API的请求结果
apikey的位置可以在header中也可以在query中
- 在header中使用
$ curl -i http://198.20.4.150:27151/apitest -H "apikey: test"
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Date: Fri, 23 Dec 2022 03:54:55 GMT
Server: APISIX/2.13.3
rspTest: hello,world
[{"id":1,"productID":1,"reviewer":"Reviewer1","text":"THIS IS A GRAY VERSION"}]
- 在query中使用
$ curl -i http://198.20.4.150:27151/apitest?apikey=test
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Date: Fri, 23 Dec 2022 03:55:28 GMT
Server: APISIX/2.13.3
rspTest: hello,world
[{"id":1,"productID":1,"reviewer":"Reviewer1","text":"An extremely entertaining play by Shakespeare"}]
basic-auth插件
描述
Basic-auth 是一个认证插件，匹配指定的用户名和密码即可通过认证。
作用范围
该插件即可用于全局插件，也可用于路由级插件。全局插件配置的优先级高于路由级插件配置，当同时在某一路由上配置了basic-auth的全局插件和路由级插件时，需正确带上全局插件配置中的用户名和密码值才能通过。
属性
consumer 端配置
| 名称 | 类型 | 必选项 | 描述 |
|---|---|---|---|
| username | string | 必须 | 用户名 |
| password | string | 必须 | 用户的密码 |
如何启用
在配置窗口页以YAML格式填写
配置示例
填写basic-auth的配置信息
username: "xxx"
password: "********"
启用/停用
在配置页面设置生效开关
验证插件
未启用插件时API请求结果
$ curl -i http://198.20.4.150:27151/apitest
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Date: Fri, 23 Dec 2022 03:53:53 GMT
Server: APISIX/2.13.3
rspTest: hello,world
[{"id":1,"productID":1,"reviewer":"Reviewer1","text":"THIS IS A GRAY VERSION "}]
启用插件时API请求结果
- 缺少 Authorization header
$ curl -i http://198.20.4.150:27151/apitest
HTTP/1.1 401 Unauthorized
Date: Fri, 23 Dec 2022 04:23:56 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
WWW-Authenticate: Basic realm='.'
Server: APISIX/2.13.3
{"message":"Missing authorization in request"}
- 用户名不存在
$ curl -i -umse:msegW@9527 http://198.20.4.150:27151/apitest
HTTP/1.1 401 Unauthorized
Date: Fri, 23 Dec 2022 04:25:08 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.13.3
{"message":"Invalid user key in authorization"}
- 密码错误
$ curl -i -umsegw:msegW http://198.20.4.150:27151/apitest
HTTP/1.1 401 Unauthorized
Date: Fri, 23 Dec 2022 04:25:49 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.13.3
{"message":"Password is error"}
- 成功请求
$ curl -i -umsegw:msegW@9527 http://198.20.4.150:27151/apitest
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Date: Fri, 23 Dec 2022 04:26:16 GMT
Server: APISIX/2.13.3
rspTest: hello,world
[{"id":1,"productID":1,"reviewer":"Reviewer1","text":"An extremely entertaining play by Shakespeare. "}]
流量控制类
并发限制limit-conn插件
描述
限制并发请求（或并发连接）插件。
作用范围
该插件即可用于全局插件，也可用于路由级插件。全局插件配置的优先级高于路由级插件配置，当同时在某一路由上配置了limit-conn的全局插件和路由级插件时，以全局插件配置中设置的属性值为准。
属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
|---|---|---|---|---|---|
| conn | integer | 是 | -- | conn > 0 | 允许的最大并发请求数。超过conn 的限制、但是低于conn +burst 的请求，将被延迟处理。 |
| burst | integer | 是 | -- | burst >= 0 | 允许被延迟处理的并发请求数。 |
| default_conn_delay | number | 是 | -- | default_conn_delay > 0 | 默认的典型连接（或请求）的处理延迟时间。 |
| only_use_default_delay | boolean | 否 | false | [true,false] | 延迟时间的严格模式。如果设置为true的话，将会严格按照设置的时间来进行延迟。 |
| key_type | string | 否 | "var" | ["var", "var_combination"] | key 的类型。 |
| key | string | 是 | -- | -- | 用来做请求计数的依据。 如果key_type 为"var"，那么 key 会被当作变量名称，如 "remote_addr" 和 "consumer_name"。 如果key_type 为"var_combination"，那么 key 会当作变量组合，如 "remote_addr consumer_name"。 如果 key 的值为空，$remote_addr 会被作为默认 key。 |
| rejected_code | string | 否 | 503 | [200,...,599] | 当请求超过conn +burst 这个阈值时，返回的HTTP 状态码。 |
| rejected_msg | string | 否 | -- | 非空 | 当请求超过conn +burst 这个阈值时，返回的响应体。 |
| allow_degradation | boolean | 否 | false | -- | 当插件功能临时不可用时是否允许请求继续。当值设置为true 时则自动允许请求继续，默认值是 false。 |
如何使用
在配置窗口页以YAML格式填写
配置示例
下面是一个示例，开启 limit-conn 插件，并设置 key_type 为var:
conn: 1
burst: 0
default_conn_delay: 0.1
rejected_code: 503
key_type: "var"
key: "remote_addr"
下面是一个示例，开启了 limit-conn 插件，并设置 key_type 为var_combination:
conn: 1
burst: 0
default_conn_delay: 0.1
rejected_code: 503
key_type: "var_combination"
key: "$consumer_name $remote_addr"
停用/启用
在配置页面设置生效开关
验证插件
上面启用的插件的参数表示只允许一个并发请求。当收到多个并发请求时，将直接返回 503 拒绝请求。
curl -i http://127.0.0.1:9080/index.html?sleep=20
503 Service Temporarily Unavailable
# 503 Service Temporarily Unavailable
---
openresty
这就表示 limit-conn 插件已经生效了。
限流limit-count插件
描述
在指定的时间范围内，限制总的请求个数。并且在 HTTP 响应头中返回剩余可以请求的个数，支持本地限流和全局限流两种限流方式。
当前配置模版中配置了三种模版可供选择：
- 基础配置为本地限流策略，云原生网关每个节点单独计算限流次数。整个集群的限流计数为配置的count 节点数。
- Redis单节点配置和Redis集群配置两种配置都是云原生网关的全局限流配置，此时count配置为集群全局限流计数。
作用范围
该插件即可用于全局插件，也可用于路由级插件。全局插件配置的优先级高于路由级插件配置，当同时在某一路由上配置了limit-count的全局插件和路由级插件时，以全局插件配置中设置的属性值为准。
属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
|---|---|---|---|---|---|
| count | integer | 必须 | -- | count > 0 | 指定时间窗口内的请求数量阈值。 |
| time_window | integer | 必须 | -- | time_window > 0 | 时间窗口的大小（以秒为单位），超过这个时间就会重置。 |
| key_type | string | 可选 | "var" | ["var", "var_combination", "constant"] | key 的类型。 |
| key | string | 可选 | "remote_addr" | -- | 用来做请求计数的依据，详情参见key的使用小节。如果 key 的值为空，$remote_addr 会被作为默认 key。 |
| rejected_code | integer | 可选 | 503 | [200,...,599] | 当请求超过阈值被拒绝时，返回的HTTP 状态码。 |
| rejected_msg | string | 可选 | -- | 非空 | 当请求超过阈值被拒绝时，返回的响应体。 |
| allow_degradation | boolean | 可选 | false | -- | 当限流插件功能临时不可用时（例如，Redis 超时）是否允许请求继续。当值设置为 true 时则自动允许请求继续，默认值是 false。 |
| show_limit_quota_header | boolean | 可选 | true | -- | 是否在响应头中显示X-RateLimit-Limit 和X-RateLimit-Remaining （限制的总请求数和剩余还可以发送的请求数），默认值是true。 |
| group | string | 可选 | -- | 非空 | 配置同样的group 的 Route 将共享同样的限流计数器。 |
| redis_host | string | 当policy为redis时必填 | -- | -- | 当使用redis 限速策略时，该属性是 Redis 服务节点的地址。 |
| redis_port | integer | 可选 | 6379 | [1,...] | 当使用redis 限速策略时，该属性是 Redis 服务节点的端口。 |
| redis_password | string | 可选 | -- | -- | 当使用redis 或者 redis-cluster 限速策略时，该属性是 Redis 服务节点的密码。 |
| redis_timeout | integer | 可选 | 1000 | [1,...] | 当使用redis 或者 redis-cluster 限速策略时，该属性是 Redis 服务节点以毫秒为单位的超时时间。 |
| redis_cluster_nodes | array | 当policy 为 redis-cluster 时必填 | -- | -- | 当使用redis-cluster 限速策略时，该属性是 Redis 集群服务节点的地址列表（至少需要两个地址）。 |
| redis_cluster_name | string | 当policy 为 redis-cluster 时必填 | -- | -- | 当使用redis-cluster 限速策略时，该属性是 Redis 集群服务节点的名称。 |
count说明
- 当使用本地计数策略，即policy设置为local时，count数值为每个网关节点的限流计数。整个集群的限流计数=count 节点数；
- 当使用redis时，即policy设置为redis或redis-cluster时，count记录在redis中，表示整个集群的全局限流计数。
key的使用说明
用来做请求计数的有效值。
key的类型
key的取值类型使用key_type标识，key_type支持三种值："var", "var_combination", "constant"
- key_type为"constant"时，那么 key 会被当作常量。
- key_type为"var"时， key 会被当作变量名称。
- key_type 为 "var_combination"，那么 key 会当作变量组。比如如果设置 "remote_addr consumer_name" 作为 key，那么插件会同时受 remote_addr 和 consumer_name 两个变量的约束。
例如，可以使用主机名（或服务器区域）作为关键字，以便限制每个主机名规定时间内的请求次数。我们也可以使用客户端地址作为关键字，这样我们就可以避免单个客户端规定时间内多次的连接我们的服务。
当前接受的 key如下：
| key | key_type为var时填写 | key_type为var_combination时填写 |
|---|---|---|
| "remote_addr"（客户端 IP 地址） | remote_addr | $remote_addr |
| "server_addr"（服务端 IP 地址） | server_addr | $server_addr |
| 请求头中的值"X-Forwarded-For" | http_x_forwarded_For | $http_x_forwarded_For |
| 请求头中的值"X-Real-IP" | http_x_real_ip | $http_x_real_ip |
| "consumer_name"（consumer 的 username） | consumer_name | $consumer_name |
| "service_id" | service_id | $service_id |
如何使用
在配置窗口页以YAML格式填写
配置示例
基于请求上下文和自定义表达式的限流配置示例。
通过将key_type设置为var或var_combination来支持基于请求上下文和自定义表达式的限流。支持各种请求参数和内置的nginx变量,以及变量组合。
常用参数示例：
remote_addr ：客户端ip
consumer_name：消费者名称；其他nginx变量也支持
arg_name: url参数，name表示参数名称
http_name: 请求header参数
cookie_name: 请求的cookie参数
下面是一个示例，开启了limit count 插件，并设置key_type 为var，key设置为remote_addr表示基于客户端ip进行请求限流：
count: 2
time_window: 60
rejected_code: 503
key_type: "var"
key: "remote_addr"
下面是一个示例，开启了limit count 插件，并设置key_type 为var，key设置为arg_userId，可对不同的url参数userId分别进行限流计数：
"allow_degradation": false,
"count": 20,
"key": "arg_userId",
"key_type": "var",
"policy": "local",
"rejected_code": 503,
"show_limit_quota_header": true,
"time_window": 30
下面是一个示例，开启了limit count 插件，并设置key_type 为var_combination, key值设置为consumer_name remote_addr，表示同时基于消费者名称和客户端ip进行限流计数。
count: 2
time_window: 60
rejected_code: 503
key_type: "var_combination"
key: "$consumer_name $remote_addr"
下面是一个示例，开启了limit count 插件，并设置key_type 为constant：
基于常量的限流配置示例
通过设置key_type 为constant，key 的值将会直接作为常量来处理
count: 2
time_window: 60
rejected_code: 503
key_type: "constant"
key: "remote_addr"
全局限流配置示例
在页面上选择Redis单节点配置或者Redis集群配置，并设置redis相关参数即可开启全局限流配置。
Redis可选择通过平台开通redis实例，或者自行部署，并在配置中填入连接信息即可。
配置示例：
# 时间窗口内的请求数量阈值
# [必填]特别地，当使用redis时，表示整个集群的请求计数。
count: 30
# [必填]时间窗口的大小（以秒为单位）
time_window: 60
# [可选]请求超过阈值被拒绝时，返回的 HTTP 状态码
rejected_code: 503
# [可选]key 的类型
key_type: "var"
# [可选]用来做请求计数的依据
key: "remote_addr"
# [可选]当设置rejected_msg时，非空。默认可不填
# rejected_msg: "Requests are too frequent, please try again later."
# [可选]当限流插件功能临时不可用时（例如，Redis 超时）是否允许请求继续。当值设置为 true 时则自动允许请求继续，默认值是 false
allow_degradation: false
# [可选]是否在响应头中显示 X-RateLimit-Limit 和 X-RateLimit-Remaining （限制的总请求数和剩余还可以发送的请求数），默认值是 true
show_limit_quota_header: true
# [必填]速率限制策略，使用单节点redis
policy: "redis"
# [必填]redis服务地址
redis_host: "127.0.0.1"
# [可选]redis服务端口
redis_port: 6379
# [可选]redis服务密码
redis_password: "password"
# [可选]redis服务的datebase
redis_database: 1
# [可选]redis服务的超时时间，单位毫秒
redis_timeout: 1000
停用/启用
在配置页面设置生效开关
验证插件
上述配置限制了 60 秒内只能访问 2 次，前两次访问都会正常访问：
curl -i http://127.0.0.1:9080/index.html
响应头里面包含了X-RateLimit-Limit 和X-RateLimit-Remaining，他们的含义分别是限制的总请求数和剩余还可以发送的请求数：
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 13175
Connection: keep-alive
X-RateLimit-Limit: 2
X-RateLimit-Remaining: 0
Server: APISIX web server
当你第三次访问的时候，就会收到包含 503 返回码的响应头：
HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: text/html
Content-Length: 194
Connection: keep-alive
Server: APISIX web server
503 Service Temporarily Unavailable
# 503 Service Temporarily Unavailable
---
openresty
同时，如果你设置了属性rejected_msg 的值为"Requests are too frequent, please try again later." ，当你第三次访问的时候，就会收到如下的响应体：
HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: text/html
Content-Length: 194
Connection: keep-alive
Server: APISIX web server
{"error_msg":"Requests are too frequent, please try again later."}
这就表示limit count 插件生效了。
结果缓存proxy-cache插件
描述
proxy-cache 插件提供了缓存后端响应数据的能力，可以根据响应码和请求模式等属性来指定需要缓存的数据。
作用范围
该插件目前只支持用于路由级插件。
属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
|---|---|---|---|---|---|
| cache_key | array[string] | 可选 | ["$host", "$request_uri"] | 缓存key，可以使用变量。例如：["$host", "$request_uri"]。 | |
| cache_bypass | array[string] | 可选 | 当该属性的值不为空或者非0时则会跳过缓存检查，即不在缓存中查找数据，可以使用变量，例如：["$arg_bypass"]。 | ||
| cache_method | array[string] | 可选 | ["GET", "HEAD"] | ["GET", "POST", "HEAD"] | 根据请求method决定是否需要缓存。 |
| cache_http_status | array[integer] | 可选 | [200, 301, 404] | [200, 599] | 根据HTTP响应码决定是否需要缓存。 |
| hide_cache_headers | boolean | 可选 | false | 当设置为true时将Expires和Cache-Control响应头返回给客户端。 | |
| cache_control | boolean | 可选 | false | 当设置为true时遵守HTTP协议规范中的Cache-Control的行为。 | |
| no_cache | array[string] | 可选 | 当此参数的值不为空或非0时将不会缓存数据，可以使用变量。 | ||
| cache_ttl | integer | 可选 | 300秒 | 当选项cache_control未开启或开启以后服务端没有返回缓存控制头时，提供的默认缓存时间。 |
如何启用
在配置窗口页以YAML 格式填写
配置示例
下面是一个示例，开启proxy-cache 插件，并配置了一些属性。表示对于路径为“/hello”的路由，在60秒内，对于返回结果为200的GET请求将返回缓存结果，其中缓存的key为请求uri+"-cache-id"的拼接字符串。
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"proxy-cache": {
"cache_key": ["$uri", "-cache-id"],
"cache_bypass": ["$arg_bypass"],
"cache_method": ["GET"],
"cache_http_status": [200],
"hide_cache_headers": true,
"cache_control": false,
"cache_ttl": 60
}
},
"upstream": {
"nodes": {
"127.0.0.1:1999": 1
},
"type": "roundrobin"
},
"uri": "/hello"
}'
启用/停用
在路由上绑定/解绑插件
验证插件
在路由上绑定结果缓存插件后，第一次请求Apisix-Cache-Status状态为MISS
$curl -i 127.0.0.1:27151/api/1/reviews
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Apisix-Cache-Status: MISS
Date: Mon, 18 Mar 2024 12:02:07 GMT
Server: APISIX/2.13.3
[{"id":1,"productId":1,"reviewer":"Reviewer1","text":"This is the 1st reviewer"}]
再次请求，命中缓存，Apisix-Cache-Status状态为HIT
$ curl -i 127.0.0.1:27151/api/1/reviews
HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Date: Mon, 18 Mar 2024 12:02:07 GMT
Server: APISIX/2.13.3
Age: 3
Apisix-Cache-Status: HIT
[{"id":1,"productId":1,"reviewer":"Reviewer1","text":"This is the 1st reviewer"}]
安全限制类
跨域CORS插件
描述
cors 是一个跨域访问插件。
作用范围
该插件即可用于全局插件，也可用于路由级插件。全局插件配置的优先级高于路由级插件配置，当同时在某一路由上配置了cores的全局插件和路由级插件时，以全局插件配置中设置的属性值为准。
属性
| 名称 | 类型 | 必选项 | 默认值 | 描述 |
|---|---|---|---|---|
| allow_origins | string | 可选 | "*" | 允许跨域访问的来源，作用于Access-Control-Allow-Origin 头部，格式如：scheme://host:port，比如:https://ctyun.com:8081。多个值时使用","分割，不允许携带凭证时可以使用"*"来表示所有Origin均允许通过。 |
| allow_methods | string | 可选 | "*" | 允许跨域访问的方法，作用于Access-Control-Allow-Methods 头部。多个值时使用","分割，支持“GET,POST,PUT,DELETE,HEAD,OPTIONS,PATCH”等方法。不允许携带凭证时可以使用"*"来表示所有 Method 均允许通过。 |
| allow_headers | string | 可选 | "*" | 允许跨域访问时请求方携带哪些非CROS 规范以外的 Header，多个值时使用","分割，不允许携带凭证时可以使用"*"来表示所有 Header 均允许通过。 |
| expose_headers | string | 可选 | "*" | 允许跨域访问时响应方携带哪些非CROS 规范以外的 Header，多个值时使用","分割，不允许携带凭证时可以使用"*"来表示所有 Header 均允许通过。 |
| max_age | integer | 可选 | 5 | 浏览器缓存CORS 结果的最大时间，单位为秒，在这个时间范围内浏览器会复用上一次的检查结果，-1 表示不缓存。作用于 Access-Control-Max-Age 头部。 |
| allow_credential | boolean | 可选 | false | 是否允许携带凭证，作用于Access-Control-Allow-Credentials 头部。 |
如何启用
在配置窗口页以 YAML 格式填写
配置示例
在服务对象中配置cors插件，此处设置缓存结果的最大时间max_age=600。
curl http://192.168.0.95:27152/apisix/admin/routes/1 -H 'X-API-KEY: 2571e288e8f4cd273cab342440068469' -X PUT -d '> {
> "name": "test12",
> "uri": "/hello",
> "plugins": {
> "cors": {
> "max_age": 600
> }
> },
> "upstream": {
> "type": "roundrobin",
> "nodes": {
> "127.0.0.1:39087": 1
> }
> }
> }'
启用/停用
在配置页面设置生效开关
验证插件
请求接口，发现已返回cors相关的 header，代表插件已经生效。
curl -v http://192.168.0.95:27151/hello -X GET
...
< Server: APISIX/2.13.3
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: *
< Access-Control-Max-Age: 600
< Access-Control-Expose-Headers: *
< Access-Control-Allow-Headers: *
...
信息重写类
重写Proxy-rewrite插件
描述
proxy-rewrite 是一个上游服务信息重写插件。
作用范围
该插件即可用于全局插件，也可用于路由级插件。全局插件配置的优先级高于路由级插件配置，当同时在某一路由上配置了proxy-rewrite的全局插件和路由级插件时，以全局插件配置中设置的属性值为准。
属性
| 名称 | 类型 | 必选项 | 有效值 | 描述 |
|---|---|---|---|---|
| uri | string | 否 | -- | 转发到上游的新uri 地址。 |
| regex_uri | array[string] | 否 | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | 转发到上游的新uri 地址, 使用正则表达式匹配来自客户端的 uri，当匹配成功后使用模板替换转发到上游的 uri, 未匹配成功时将客户端请求的 uri 转发至上游。当 uri 和 regex_uri 同时存在时，uri 优先被使用。 |
| host | string | 否 | -- | 转发到上游的新host 地址。 |
如何使用
在配置窗口页以 YAML 格式填写
配置示例
下面是一个示例，在指定的 API 上开启了proxy-rewrite 插件。
curl http://192.168.0.95:27152/apisix/admin/routes/1 -H 'X-API-KEY: 2571e288e8f4cd273cab342440068469' -X PUT -d '
{
"methods": ["GET"],
"uri": "/test/index.html",
"plugins": {
"proxy-rewrite": {
"uri": "/test/home.html",
"scheme": "http",
"host": "ctyun.com",
"headers": {
"X-Api-Version": "v1",
"X-Api-Engine": "apisix",
"X-Api-useless": ""
}
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:80": 1
}
}
}'
启用/停用
在配置页面设置生效开关
验证插件
发送请求，查看上游服务的 access.log，如果输出信息与配置一致：
curl -X GET http://192.168.0.95:27152/test/index.html
127.0.0.1 - [2/Aug/2023:10:52:20 +0800] ctyun.com GET /test/home.html HTTP/1.1 200 38 - curl/7.29.0 - 0.000 199 107
这就表示proxy-rewrite 插件已经生效了。
重写proxy-cookie插件
描述
proxy-cookie插件是对响应头部set-cookie字段中的path属性或者domain属性进行重写，校验的对象：
- 请求目标服务的返回头部Set-Cookie中Path属性。
- 请求目标服务的返回头部Set-Cookie中Domain属性。
注意set-cookie头部不区分大小写
作用范围
该插件只能用于路由级插件，因为每条路由响应头部set-cookie字段中的path属性或者domain属性不同，要视具体情况而定。
属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
|---|---|---|---|---|---|
| domain | Object | 可选 | -- | -- | domain域的重写配置 |
| domain | use | boolen | 可选 | false | [false, true] |
| domain | regex | string | -- | -- | -- |
| domain | replacement | string | -- | -- | -- |
| path | Object | 可选 | -- | -- | path域的重写配置 |
| path | use | boolen | 可选 | false | [false, true] |
| path | regex | string | -- | -- | -- |
| path | replacement | string | -- | -- | -- |
如何启用
在配置窗口页以 YAML 格式填写。
配置示例
- 样例
配置proxy-cookie插件内容，关闭domain，开启path。
curl http://192.168.0.95:27152/apisix/admin/routes/1 -H 'X-API-KEY: 2571e288e8f4cd273cab342440068469' -X PUT -d '
{
"name": "test",
"uri": "/hello",
"plugins": {
"proxy-cookie": {
"domain": {
"use": false
},
"path": {
"regex": "/c/app",
"use": true,
"replacement": "/"
},
"disable": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:39087": 1
}
}
}'
- 示例场景
以Path属性为例，Domain属性同理。
- 测试场景1：当set-cookie中不存在Path属性时
用例1-1：属性关闭
即 proxy_cookie_path = {use=false}， 表示不对Path属性进行重写
用例1-2：属性开启
proxy_cookie_path = {use=true， regex="/app/a/b", replacement="/a/b"}， 表示不对Path属性进行重写
proxy_cookie_path = {use=true， regex="^/app/a/b", replacement="/a/b"}， 表示不对Path属性进行重写
- 测试场景2：当set-cookie中存在Path属性时
如set-cookie: Path=/c/app/a/b
用例2-1 属性关闭
即 proxy_cookie_path = {use=false}， 表示不对Path属性进行重写
用例2-2 属性开启
proxy_cookie_path = {use=true， regex="/app/a/b", replacement="/a/b"}，表示对Path属性进行重写，重写后，set-cookie: Path=/c/a/b
proxy_cookie_path = {use=true， regex="*/a/b", replacement="/a/b"}， 表示对Path属性进行重写，重写后，set-cookie: Path=/a/b
proxy_cookie_path = {use=true， regex="c/a/b", replacement="/a/b"}， 表示对Path属性进行重写，重写后（未匹配时，原样输出），set-cookie: Path=/c/app/a/b
启用/启停
在配置页面设置生效开关。
验证插件
假定请求响应中的Set-cookie字段信息如下
配置示例如样例中设置，对应的yaml如下
# 对应proxy_cookie_domain
domain:
# 是否更改domain属性，默认为false, 当设置为true时匹配规则和替换值不可为空
use: false
# 匹配规则
#regex: "ctyun.com"
# 替换值
#replacement: ""
# 对应proxy_cookie_path
path:
# 是否更改path属性，默认为false, 当设置为true时匹配规则和替换值不可为空
use: true
# 匹配规则
regex: "/c/app"
# 替换值
replacement: "/"
请求接口，发现在header的Set-cookie字段中带上了Path与Domain的值，代表插件已经生效。
头部重写header-rewrite插件
描述
header-rewrite插件可以对请求/响应头部的header参数进行新增、修改和删除操作。
作用范围
该插件只能用于路由级插件，因为每条路由请求/响应头部的header参数不同，要视具体情况而定。
属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
|---|---|---|---|---|---|
| request | Object | 可选 | -- | -- | 修改请求header,支持新增、修改、删除操作。 |
| request | add | Array | -- | -- | -- |
| request | update | Array | -- | -- | -- |
| request | delete | Array | -- | -- | -- |
| response | Object | 可选 | -- | -- | 修改响应header,支持新增、修改、删除操作。 |
| response | add | Array | -- | -- | -- |
| response | update | Array | -- | -- | -- |
| response | delete | Array | -- | -- | -- |
支持的类型：
● request：请求头部类型
● response：响应头部类型
允许的操作：
● 新增：增加一个头部
● 修改：存在则更新；不存在则增加
● 删除：去掉一个指定key，不需要指定value
如何使用
在配置窗口页以 YAML 格式填写
配置示例
模板参考：
# 修改请求header,支持新增、修改、删除操作，操作类型不为空时，其目标header key也不能为空
request:
# 新增操作,当存在目标header key时，末尾追加值;否则，新增一个header
add:
num: 123
name: "cgw"
# 更新操作,当存在目标header key时，更新header值;否则，新增一个header
update:
num: 234
name: "CGW"
# 删除操作,当存在目标header key时，删除目标header;否则忽略
delete:
- id
- name
# 修改响应header,支持新增、修改、删除操作，操作类型不为空时，其目标header key也不能为空
response:
# 新增操作,当存在目标header key时，末尾追加值;否则，新增一个header
add:
num: 123
name: "cgw"
# 更新操作,当存在目标header key时，更新header值;否则，新增一个header
update:
num: 234
name: "CGW"
# 删除操作,当存在目标header key时，删除目标header;否则忽略
delete:
- id
- name
启用/停用
在配置页面设置生效开关。
验证插件
请求接口，若发现已返回header发生变更，代表插件已经生效。
