mirror of
https://gitee.com/iresty/apisix.git
synced 2024-12-05 13:37:34 +08:00
feat(proxy-cache): the cache_zone field in the schema should be optional (#2776)
This commit is contained in:
parent
53e2d5387f
commit
e4de3d5b9b
@ -34,7 +34,9 @@ local schema = {
|
||||
properties = {
|
||||
cache_zone = {
|
||||
type = "string",
|
||||
minLength = 1
|
||||
minLength = 1,
|
||||
maxLength = 100,
|
||||
default = "disk_cache_one",
|
||||
},
|
||||
cache_key = {
|
||||
type = "array",
|
||||
@ -91,7 +93,6 @@ local schema = {
|
||||
},
|
||||
},
|
||||
},
|
||||
required = {"cache_zone"},
|
||||
}
|
||||
|
||||
local _M = {
|
||||
|
@ -31,7 +31,7 @@ The proxy-cache plugin, which provides the ability to cache upstream response da
|
||||
|
||||
| Name | Type | Requirement | Default | Valid | Description |
|
||||
| ------------------ | -------------- | ----------- | ------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| cache_zone | string | required | | | Specify which cache area to use, each cache area can be configured with different paths. In addition, cache areas can be predefined in conf/config.yaml file |
|
||||
| cache_zone | string | optional | disk_cache_one | | Specify which cache area to use, each cache area can be configured with different paths. In addition, cache areas can be predefined in conf/config.yaml file. When the default value is not used, the specified cache area is inconsistent with the pre-defined cache area in the conf/config.yaml file, and the cache is invalid. |
|
||||
| cache_key | array[string] | optional | ["$host", "$request_uri"] | | key of a cache, can use variables. For example: ["$host", "$uri", "-cache-id"] |
|
||||
| cache_bypass | array[string] | optional | | | Whether to skip cache retrieval. That is, do not look for data in the cache. It can use variables, and note that cache data retrieval will be skipped when the value of this attribute is not empty or not '0'. For example: ["$arg_bypass"] |
|
||||
| cache_method | array[string] | optional | ["GET", "HEAD"] | ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD","OPTIONS", "CONNECT", "TRACE"] | Decide whether to be cached according to the request method |
|
||||
@ -43,10 +43,26 @@ Note:
|
||||
1. The variable starts with $.
|
||||
2. The attribute can use a combination of the variable and the string, but it needs to be written separately as an array, and the final values are stitched together after the variable is parsed.
|
||||
|
||||
Example configuration in the `conf/config.yaml` file:
|
||||
|
||||
```yaml
|
||||
proxy_cache: # Proxy Caching configuration
|
||||
cache_ttl: 10s # The default caching time if the upstream does not specify the cache time
|
||||
zones: # The parameters of a cache
|
||||
- name: disk_cache_one # The name of the cache, administrator can be specify
|
||||
# which cache to use by name in the admin api
|
||||
memory_size: 50m # The size of shared memory, it's used to store the cache index
|
||||
disk_size: 1G # The size of disk, it's used to store the cache data
|
||||
disk_path: "/tmp/disk_cache_one" # The path to store the cache data
|
||||
cache_levels: "1:2" # The hierarchy levels of a cache
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
#### Enable the plugin
|
||||
|
||||
Example 1: The cache_zone parameter defaults to `disk_cache_one`
|
||||
|
||||
1: enable the proxy-cache plugin for a specific route :
|
||||
|
||||
```shell
|
||||
@ -54,13 +70,12 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
|
||||
{
|
||||
"plugins": {
|
||||
"proxy-cache": {
|
||||
"cache_zone": "disk_cache_one",
|
||||
"cache_key": ["$uri", "-cache-id"],
|
||||
"cache_bypass": ["$arg_bypass"],
|
||||
"cache_method": ["GET"],
|
||||
"cache_http_status": [200],
|
||||
"hide_cache_headers": true,
|
||||
"no_cache": ["$arg_test"]
|
||||
"cache_key": ["$uri", "-cache-id"],
|
||||
"cache_bypass": ["$arg_bypass"],
|
||||
"cache_method": ["GET"],
|
||||
"cache_http_status": [200],
|
||||
"hide_cache_headers": true,
|
||||
"no_cache": ["$arg_test"]
|
||||
}
|
||||
},
|
||||
"upstream": {
|
||||
@ -88,10 +103,10 @@ Apisix-Cache-Status: MISS
|
||||
|
||||
hello
|
||||
```
|
||||
> http status is '200' and the response header contains 'Apisix-Cache-Status' to indicate that the plug-in is enabled.
|
||||
|
||||
2: Verify that the file is cached, request the address above again:
|
||||
> http status is '200' and the response header contains 'Apisix-Cache-Status' to indicate that the plugin is enabled.
|
||||
|
||||
2: Verify that the data is cached, request the address above again:
|
||||
|
||||
```shell
|
||||
$ curl http://127.0.0.1:9080/hello -i
|
||||
@ -107,10 +122,120 @@ Apisix-Cache-Status: HIT
|
||||
hello
|
||||
```
|
||||
|
||||
> Response header Apisix-Cache-Status has changed to HIT, indicating that the file has been cached.
|
||||
Example 2: Customize the cache_zone parameter to `disk_cache_two`
|
||||
|
||||
3: How to clean up the cached file, simply specify the request method as PURGE:
|
||||
1. Specify the cache area and other information in the `conf/config.yaml` file:
|
||||
|
||||
```yaml
|
||||
proxy_cache:
|
||||
cache_ttl: 10s
|
||||
zones:
|
||||
- name: disk_cache_two
|
||||
memory_size: 50m
|
||||
disk_size: 1G
|
||||
disk_path: "/tmp/disk_cache_one"
|
||||
cache_levels: "1:2"
|
||||
```
|
||||
|
||||
2. Enable the `proxy-cache` plugin for a specific route:
|
||||
|
||||
```shell
|
||||
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
|
||||
{
|
||||
"plugins": {
|
||||
"proxy-cache": {
|
||||
"cache_zone": "disk_cache_two",
|
||||
"cache_key": ["$uri", "-cache-id"],
|
||||
"cache_bypass": ["$arg_bypass"],
|
||||
"cache_method": ["GET"],
|
||||
"cache_http_status": [200],
|
||||
"hide_cache_headers": true,
|
||||
"no_cache": ["$arg_test"]
|
||||
}
|
||||
},
|
||||
"upstream": {
|
||||
"nodes": {
|
||||
"127.0.0.1:1999": 1
|
||||
},
|
||||
"type": "roundrobin"
|
||||
},
|
||||
"uri": "/hello"
|
||||
}'
|
||||
```
|
||||
|
||||
Test Plugin:
|
||||
|
||||
```shell
|
||||
$ curl http://127.0.0.1:9080/hello -i
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/octet-stream
|
||||
Content-Length: 6
|
||||
Connection: keep-alive
|
||||
Server: APISIX web server
|
||||
Date: Tue, 03 Mar 2020 10:45:36 GMT
|
||||
Last-Modified: Tue, 03 Mar 2020 10:36:38 GMT
|
||||
Apisix-Cache-Status: MISS
|
||||
|
||||
hello
|
||||
```
|
||||
|
||||
> http status is '200' and the response header contains 'Apisix-Cache-Status' to indicate that the plug-in is enabled.
|
||||
|
||||
3. Verify that the data is cached and request the above address again:
|
||||
|
||||
```shell
|
||||
$ curl http://127.0.0.1:9080/hello -i
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/octet-stream
|
||||
Content-Length: 6
|
||||
Connection: keep-alive
|
||||
Server: APISIX web server
|
||||
Date: Tue, 03 Mar 2020 11:14:46 GMT
|
||||
Last-Modified: Thu, 20 Feb 2020 14:21:41 GMT
|
||||
Apisix-Cache-Status: HIT
|
||||
|
||||
hello
|
||||
```
|
||||
|
||||
> The response header `Apisix-Cache-Status` value has changed to HIT, indicating that the data has been cached
|
||||
|
||||
Example 3: Specifying cache_zone as `invalid_disk_cache` is inconsistent with the cache area `disk_cache_one` specified in the `conf/config.yaml` file.
|
||||
|
||||
```shell
|
||||
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
|
||||
{
|
||||
"plugins": {
|
||||
"proxy-cache": {
|
||||
"cache_zone": "invalid_disk_cache",
|
||||
"cache_key": ["$uri", "-cache-id"],
|
||||
"cache_bypass": ["$arg_bypass"],
|
||||
"cache_method": ["GET"],
|
||||
"cache_http_status": [200],
|
||||
"hide_cache_headers": true,
|
||||
"no_cache": ["$arg_test"]
|
||||
}
|
||||
},
|
||||
"upstream": {
|
||||
"nodes": {
|
||||
"127.0.0.1:1999": 1
|
||||
},
|
||||
"type": "roundrobin"
|
||||
},
|
||||
"uri": "/hello"
|
||||
}'
|
||||
```
|
||||
|
||||
```json
|
||||
{"error_msg":"failed to check the configuration of plugin proxy-cache err: cache_zone invalid_disk_cache not found"}
|
||||
```
|
||||
|
||||
In response to an error message, the plug-in configuration is invalid.
|
||||
|
||||
#### Clear cached data
|
||||
|
||||
How to clean the cached data only needs to specify the requested method as PURGE.
|
||||
|
||||
Test Plugin:
|
||||
|
||||
```shell
|
||||
$ curl -i http://127.0.0.1:9080/hello -X PURGE
|
||||
@ -122,13 +247,32 @@ Connection: keep-alive
|
||||
Server: APISIX web server
|
||||
```
|
||||
|
||||
> The response status is 200, indicating that the file was deleted successfully. And return 404 if the file is not found.
|
||||
> If the response code is 200, it means the deletion is successful. If the cached data is not found, 404 will be returned.
|
||||
|
||||
Request again, the cached data is not found and return 404:
|
||||
|
||||
```shell
|
||||
$ curl -i http://127.0.0.1:9080/hello -X PURGE
|
||||
HTTP/1.1 404 Not Found
|
||||
Date: Wed, 18 Nov 2020 05:46:34 GMT
|
||||
Content-Type: text/plain
|
||||
Transfer-Encoding: chunked
|
||||
Connection: keep-alive
|
||||
Server: APISIX web server
|
||||
|
||||
<html>
|
||||
<head><title>404 Not Found</title></head>
|
||||
<body>
|
||||
<center><h1>404 Not Found</h1></center>
|
||||
<hr><center>openresty</center>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
## Disable Plugin
|
||||
|
||||
Remove the corresponding JSON in the plugin configuration to disable the plugin immediately without restarting the service:
|
||||
|
||||
|
||||
```shell
|
||||
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
|
||||
{
|
||||
|
@ -31,7 +31,7 @@
|
||||
|
||||
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
|
||||
| ------------------ | -------------- | ------ | ------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| cache_zone | string | 必须 | | | 指定使用哪个缓存区域,不同的缓存区域可以配置不同的路径,在conf/config.yaml文件中可以预定义使用的缓存区域 |
|
||||
| cache_zone | string | 可选 | disk_cache_one | | 指定使用哪个缓存区域,不同的缓存区域可以配置不同的路径,在 conf/config.yaml 文件中可以预定义使用的缓存区域。当不使用默认值时,指定的缓存区域与 conf/config.yaml 文件中预定义的缓存区域不一致,缓存无效。 |
|
||||
| cache_key | array[string] | 可选 | ["$host", "$request_uri"] | | 缓存key,可以使用变量。例如:["$host", "$uri", "-cache-id"] |
|
||||
| cache_bypass | array[string] | 可选 | | | 是否跳过缓存检索,即不在缓存中查找数据,可以使用变量,需要注意当此参数的值不为空或非'0'时将会跳过缓存的检索。例如:["$arg_bypass"] |
|
||||
| cache_method | array[string] | 可选 | ["GET", "HEAD"] | ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD","OPTIONS", "CONNECT", "TRACE"] | 根据请求method决定是否需要缓存 |
|
||||
@ -39,27 +39,40 @@
|
||||
| hide_cache_headers | boolean | 可选 | false | | 是否将 Expires 和 Cache-Control 响应头返回给客户端 |
|
||||
| no_cache | array[string] | 可选 | | | 是否缓存数据,可以使用变量,需要注意当此参数的值不为空或非'0'时将不会缓存数据 |
|
||||
|
||||
|
||||
注:变量以$开头,也可以使用变量和字符串的结合,但是需要以数组的形式分开写,最终变量被解析后会和字符串拼接在一起。
|
||||
|
||||
在 `conf/config.yaml` 文件中的配置示例:
|
||||
|
||||
```yaml
|
||||
proxy_cache: # 代理缓存配置
|
||||
cache_ttl: 10s # 如果上游未指定缓存时间,则为默认缓存时间
|
||||
zones: # 缓存的参数
|
||||
- name: disk_cache_one # 缓存名称(缓存区域),管理员可以通过admin api中的 cache_zone 字段指定要使用的缓存区域
|
||||
memory_size: 50m # 共享内存的大小,用于存储缓存索引
|
||||
disk_size: 1G # 磁盘大小,用于存储缓存数据
|
||||
disk_path: "/tmp/disk_cache_one" # 存储缓存数据的路径
|
||||
cache_levels: "1:2" # 缓存的层次结构级别
|
||||
```
|
||||
|
||||
### 示例
|
||||
|
||||
#### 启用插件
|
||||
|
||||
示例1:为特定路由启用 `proxy-cache` 插件:
|
||||
示例一:cache_zone 参数默认为 `disk_cache_one`
|
||||
|
||||
1、为特定路由启用 `proxy-cache` 插件:
|
||||
|
||||
```shell
|
||||
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
|
||||
{
|
||||
"plugins": {
|
||||
"proxy-cache": {
|
||||
"cache_zone": "disk_cache_one",
|
||||
"cache_key": ["$uri", "-cache-id"],
|
||||
"cache_bypass": ["$arg_bypass"],
|
||||
"cache_method": ["GET"],
|
||||
"cache_http_status": [200],
|
||||
"hide_cache_headers": true,
|
||||
"no_cache": ["$arg_test"]
|
||||
"cache_key": ["$uri", "-cache-id"],
|
||||
"cache_bypass": ["$arg_bypass"],
|
||||
"cache_method": ["GET"],
|
||||
"cache_http_status": [200],
|
||||
"hide_cache_headers": true,
|
||||
"no_cache": ["$arg_test"]
|
||||
}
|
||||
},
|
||||
"upstream": {
|
||||
@ -88,11 +101,9 @@ Apisix-Cache-Status: MISS
|
||||
hello
|
||||
```
|
||||
|
||||
> http status 返回`200`并且响应头中包含`Apisix-Cache-Status`,表示该插件已启用。
|
||||
> http status 返回`200`并且响应头中包含 `Apisix-Cache-Status`,表示该插件已启用。
|
||||
|
||||
示例2:验证文件是否被缓存,再次请求上边的地址:
|
||||
|
||||
测试:
|
||||
2、验证数据是否被缓存,再次请求上边的地址:
|
||||
|
||||
```shell
|
||||
$ curl http://127.0.0.1:9080/hello -i
|
||||
@ -108,9 +119,120 @@ Apisix-Cache-Status: HIT
|
||||
hello
|
||||
```
|
||||
|
||||
> 响应头 Apisix-Cache-Status 值变为了 HIT,说明文件已经被缓存
|
||||
> 响应头 Apisix-Cache-Status 值变为了 HIT,说明数据已经被缓存
|
||||
|
||||
示例3:如何清理缓存的文件,只需要指定请求的 method 为 PURGE:
|
||||
示例二:自定义 cache_zone 参数为 `disk_cache_two`
|
||||
|
||||
1、在 `conf/config.yaml` 文件中的指定缓存区域等信息:
|
||||
|
||||
```yaml
|
||||
proxy_cache:
|
||||
cache_ttl: 10s
|
||||
zones:
|
||||
- name: disk_cache_two
|
||||
memory_size: 50m
|
||||
disk_size: 1G
|
||||
disk_path: "/tmp/disk_cache_one"
|
||||
cache_levels: "1:2"
|
||||
```
|
||||
|
||||
2、为特定路由启用 `proxy-cache` 插件:
|
||||
|
||||
```shell
|
||||
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
|
||||
{
|
||||
"plugins": {
|
||||
"proxy-cache": {
|
||||
"cache_zone": "disk_cache_two",
|
||||
"cache_key": ["$uri", "-cache-id"],
|
||||
"cache_bypass": ["$arg_bypass"],
|
||||
"cache_method": ["GET"],
|
||||
"cache_http_status": [200],
|
||||
"hide_cache_headers": true,
|
||||
"no_cache": ["$arg_test"]
|
||||
}
|
||||
},
|
||||
"upstream": {
|
||||
"nodes": {
|
||||
"127.0.0.1:1999": 1
|
||||
},
|
||||
"type": "roundrobin"
|
||||
},
|
||||
"uri": "/hello"
|
||||
}'
|
||||
```
|
||||
|
||||
测试:
|
||||
|
||||
```shell
|
||||
$ curl http://127.0.0.1:9080/hello -i
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/octet-stream
|
||||
Content-Length: 6
|
||||
Connection: keep-alive
|
||||
Server: APISIX web server
|
||||
Date: Tue, 03 Mar 2020 10:45:36 GMT
|
||||
Last-Modified: Tue, 03 Mar 2020 10:36:38 GMT
|
||||
Apisix-Cache-Status: MISS
|
||||
|
||||
hello
|
||||
```
|
||||
|
||||
> http status 返回`200`并且响应头中包含 `Apisix-Cache-Status`,表示该插件已启用。
|
||||
|
||||
3、验证数据是否被缓存,再次请求上面的地址:
|
||||
|
||||
```shell
|
||||
$ curl http://127.0.0.1:9080/hello -i
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/octet-stream
|
||||
Content-Length: 6
|
||||
Connection: keep-alive
|
||||
Server: APISIX web server
|
||||
Date: Tue, 03 Mar 2020 11:14:46 GMT
|
||||
Last-Modified: Thu, 20 Feb 2020 14:21:41 GMT
|
||||
Apisix-Cache-Status: HIT
|
||||
|
||||
hello
|
||||
```
|
||||
|
||||
> 响应头 `Apisix-Cache-Status` 值变为了 HIT,说明数据已经被缓存
|
||||
|
||||
示例3:指定 cache_zone 为 `invalid_disk_cache` 与 `conf/config.yaml` 文件中指定的缓存区域 `disk_cache_one` 不一致。
|
||||
|
||||
```shell
|
||||
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
|
||||
{
|
||||
"plugins": {
|
||||
"proxy-cache": {
|
||||
"cache_zone": "invalid_disk_cache",
|
||||
"cache_key": ["$uri", "-cache-id"],
|
||||
"cache_bypass": ["$arg_bypass"],
|
||||
"cache_method": ["GET"],
|
||||
"cache_http_status": [200],
|
||||
"hide_cache_headers": true,
|
||||
"no_cache": ["$arg_test"]
|
||||
}
|
||||
},
|
||||
"upstream": {
|
||||
"nodes": {
|
||||
"127.0.0.1:1999": 1
|
||||
},
|
||||
"type": "roundrobin"
|
||||
},
|
||||
"uri": "/hello"
|
||||
}'
|
||||
```
|
||||
|
||||
```json
|
||||
{"error_msg":"failed to check the configuration of plugin proxy-cache err: cache_zone invalid_disk_cache not found"}
|
||||
```
|
||||
|
||||
响应错误信息,表示插件配置无效。
|
||||
|
||||
#### 清除缓存数据
|
||||
|
||||
如何清理缓存的数据,只需要指定请求的 method 为 PURGE。
|
||||
|
||||
测试:
|
||||
|
||||
@ -124,7 +246,27 @@ Connection: keep-alive
|
||||
Server: APISIX web server
|
||||
```
|
||||
|
||||
> 响应码为200即表示删除成功,如果文件未找到将返回404
|
||||
> 响应码为200即表示删除成功,如果缓存的数据未找到将返回404。
|
||||
|
||||
再次请求,缓存数据未找到返回404:
|
||||
|
||||
```shell
|
||||
$ curl -i http://127.0.0.1:9080/hello -X PURGE
|
||||
HTTP/1.1 404 Not Found
|
||||
Date: Wed, 18 Nov 2020 05:46:34 GMT
|
||||
Content-Type: text/plain
|
||||
Transfer-Encoding: chunked
|
||||
Connection: keep-alive
|
||||
Server: APISIX web server
|
||||
|
||||
<html>
|
||||
<head><title>404 Not Found</title></head>
|
||||
<body>
|
||||
<center><h1>404 Not Found</h1></center>
|
||||
<hr><center>openresty</center>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
#### 禁用插件
|
||||
|
||||
|
@ -59,7 +59,7 @@ run_tests;
|
||||
|
||||
__DATA__
|
||||
|
||||
=== TEST 1: sanity check (missing required field)
|
||||
=== TEST 1: sanity check (missing cache_zone field, the default value is disk_cache_one)
|
||||
--- config
|
||||
location /t {
|
||||
content_by_lua_block {
|
||||
@ -83,6 +83,32 @@ __DATA__
|
||||
"type": "roundrobin"
|
||||
},
|
||||
"uri": "/hello"
|
||||
}]],
|
||||
[[{
|
||||
"node": {
|
||||
"value": {
|
||||
"uri": "/hello",
|
||||
"upstream": {
|
||||
"nodes": {
|
||||
"127.0.0.1:1980": 1
|
||||
},
|
||||
"type": "roundrobin"
|
||||
},
|
||||
"plugins": {
|
||||
"proxy-cache":{
|
||||
"cache_zone":"disk_cache_one",
|
||||
"hide_cache_headers":true,
|
||||
"cache_bypass":["$arg_bypass"],
|
||||
"cache_key":["$host","$request_uri"],
|
||||
"no_cache":["$arg_no_cache"],
|
||||
"cache_http_status":[200],
|
||||
"cache_method":["GET"]
|
||||
}
|
||||
}
|
||||
},
|
||||
"key": "/apisix/routes/1"
|
||||
},
|
||||
"action": "set"
|
||||
}]]
|
||||
)
|
||||
|
||||
@ -94,9 +120,8 @@ __DATA__
|
||||
}
|
||||
--- request
|
||||
GET /t
|
||||
--- error_code: 400
|
||||
--- response_body eval
|
||||
qr/failed to check the configuration of plugin proxy-cache/
|
||||
--- response_body
|
||||
passed
|
||||
--- no_error_log
|
||||
[error]
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user