概述

目前云原生网关共支持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字段信息如下

图片204.png

配置示例如样例中设置，对应的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的值，代表插件已经生效。

图片205.png

头部重写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发生变更，代表插件已经生效。

活动

应用商城

合作伙伴

开发者

支持与服务

了解天翼云

查看所有产品

微服务引擎

微服务引擎

概述

身份认证类

key-auth插件

描述

作用范围

属性

如何启用

配置示例

启用/停用

验证插件

basic-auth插件

描述

作用范围

属性

如何启用

配置示例

启用/停用

验证插件

流量控制类

并发限制limit-conn插件

描述

作用范围

属性

如何使用

配置示例

停用/启用

验证插件

限流limit-count插件

描述

作用范围

属性

如何使用

配置示例

停用/启用

验证插件

结果缓存proxy-cache插件

描述

作用范围

属性

如何启用

配置示例

启用/停用

验证插件

安全限制类

跨域CORS插件

描述

作用范围

属性

如何启用

配置示例

启用/停用

验证插件

信息重写类

重写Proxy-rewrite插件

描述

作用范围

属性

如何使用

配置示例

启用/停用

验证插件

重写proxy-cookie插件

描述

作用范围

属性

如何启用

配置示例

启用/启停

验证插件

头部重写header-rewrite插件

描述