This is an automated email from the ASF dual-hosted git repository.
monkeydluffy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 591774849 docs: add in-memory caching example for `proxy-cache` (#9969)
591774849 is described below
commit 5917748495264977635e3a135195258b31944929
Author: Traky Deng <[email protected]>
AuthorDate: Mon Aug 7 14:51:46 2023 +0800
docs: add in-memory caching example for `proxy-cache` (#9969)
---
docs/en/latest/plugins/proxy-cache.md | 67 ++++++++++++++++++++++++++---------
docs/zh/latest/plugins/proxy-cache.md | 67 ++++++++++++++++++++++++++---------
2 files changed, 101 insertions(+), 33 deletions(-)
diff --git a/docs/en/latest/plugins/proxy-cache.md
b/docs/en/latest/plugins/proxy-cache.md
index 52586cdec..885fe2334 100644
--- a/docs/en/latest/plugins/proxy-cache.md
+++ b/docs/en/latest/plugins/proxy-cache.md
@@ -60,22 +60,33 @@ The data to be cached can be filtered with response codes,
request modes, or mor
You can add your cache configuration in you APISIX configuration file
(`conf/config.yaml`) as shown below:
```yaml title="conf/config.yaml"
-proxy_cache:
- cache_ttl: 10s # default caching time if the upstream
doesn't specify the caching time
+apisix:
+ proxy_cache:
+ cache_ttl: 10s # 如果上游未指定缓存时间，则为默认磁盘缓存时间
zones:
- - name: disk_cache_one # name of the cache. Admin can specify
which cache to use in the Admin API by name
- memory_size: 50m # size of shared memory, used to store the
cache index
- disk_size: 1G # size of disk, used to store the cache data
- disk_path: "/tmp/disk_cache_one" # path to store the cache data
- cache_levels: "1:2" # hierarchy levels of the cache
+ - name: disk_cache_one
+ memory_size: 50m
+ disk_size: 1G
+ disk_path: /tmp/disk_cache_one
+ cache_levels: 1:2
+ # - name: disk_cache_two
+ # memory_size: 50m
+ # disk_size: 1G
+ # disk_path: "/tmp/disk_cache_two"
+ # cache_levels: "1:2"
+ - name: memory_cache
+ memory_size: 50m
```
-You can enable the Plugin on a specific Route as shown below:
+### Use disk-based caching
+
+You can enable the Plugin on a Route as shown below. The Plugin uses the
disk-based `cache_strategy` and `disk_cache_one` as the `cache_zone` by default:
```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
+ "uri": "/ip",
"plugins": {
"proxy-cache": {
"cache_key": ["$uri", "-cache-id"],
@@ -88,22 +99,44 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
},
"upstream": {
"nodes": {
- "127.0.0.1:1999": 1
+ "httpbin.org": 1
},
"type": "roundrobin"
- },
- "uri": "/hello"
+ }
}'
```
-In the above configuration, the `cache_zone` attribute defaults to
`disk_cache_one`.
+### Use memory-based caching
+
+You can enable the Plugin on a Route with in-memory `cache_strategy` and a
corresponding in-memory `cache_zone` as shown below:
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/ip",
+ "plugins": {
+ "proxy-cache": {
+ "cache_strategy": "memory",
+ "cache_zone": "memory_cache",
+ "cache_ttl": 10
+ }
+ },
+ "upstream": {
+ "nodes": {
+ "httpbin.org": 1
+ },
+ "type": "roundrobin"
+ }
+}'
+```
## Example usage
Once you have configured the Plugin as shown above, you can make an initial
request:
```shell
-curl http://127.0.0.1:9080/hello -i
+curl http://127.0.0.1:9080/ip -i
```
```shell
@@ -117,7 +150,7 @@ hello
The `Apisix-Cache-Status` in the response shows `MISS` meaning that the
response is not cached, as expected. Now, if you make another request, you will
see that you get a cached response:
```shell
-curl http://127.0.0.1:9080/hello -i
+curl http://127.0.0.1:9080/ip -i
```
```shell
@@ -135,7 +168,7 @@ If you set `"cache_zone": "invalid_disk_cache"` attribute
to an invalid value (c
To clear the cached data, you can send a request with `PURGE` method:
```shell
-curl -i http://127.0.0.1:9080/hello -X PURGE
+curl -i http://127.0.0.1:9080/ip -X PURGE
```
```shell
@@ -154,12 +187,12 @@ To remove the `proxy-cache` Plugin, you can delete the
corresponding JSON config
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
- "uri": "/hello",
+ "uri": "/ip",
"plugins": {},
"upstream": {
"type": "roundrobin",
"nodes": {
- "127.0.0.1:1999": 1
+ "httpbin.org": 1
}
}
}'
diff --git a/docs/zh/latest/plugins/proxy-cache.md
b/docs/zh/latest/plugins/proxy-cache.md
index 9783d99fa..ca4bea58b 100644
--- a/docs/zh/latest/plugins/proxy-cache.md
+++ b/docs/zh/latest/plugins/proxy-cache.md
@@ -58,22 +58,33 @@ description: 本文介绍了 Apache APISIX proxy-cache 插件的相关操作，
你可以在 APISIX 配置文件 `conf/config.yaml` 中添加你的缓存配置，示例如下：
```yaml title="conf/config.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" # 缓存的层次结构级别
+apisix:
+ proxy_cache:
+ cache_ttl: 10s # 如果上游未指定缓存时间，则为默认磁盘缓存时间
+ zones:
+ - name: disk_cache_one
+ memory_size: 50m
+ disk_size: 1G
+ disk_path: /tmp/disk_cache_one
+ cache_levels: 1:2
+ # - name: disk_cache_two
+ # memory_size: 50m
+ # disk_size: 1G
+ # disk_path: "/tmp/disk_cache_two"
+ # cache_levels: "1:2"
+ - name: memory_cache
+ memory_size: 50m
```
-以下示例展示了如何在指定路由上启用 `proxy-cache` 插件，`cache_zone` 字段默认设置为 `disk_cache_one`：
+### 使用基于磁盘的缓存
+
+以下示例展示了如何在路由上启用 `proxy-cache` 插件。该插件默认使用基于磁盘的 `cache_strategy`
和默认使用`disk_cache_one` 为 `cache_zone`：
```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
+ "uri": "/ip",
"plugins": {
"proxy-cache": {
"cache_key": ["$uri", "-cache-id"],
@@ -86,11 +97,35 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
},
"upstream": {
"nodes": {
- "127.0.0.1:1999": 1
+ "httpbin.org": 1
},
"type": "roundrobin"
+ }
+}'
+```
+
+### 使用基于内存的缓存
+
+以下示例展示了如何在路由上启用 `proxy-cache` 插件，并使用基于内存的 `cache_strategy` 和相应的基于内存的
`cache_zone`。
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/ip",
+ "plugins": {
+ "proxy-cache": {
+ "cache_strategy": "memory",
+ "cache_zone": "memory_cache",
+ "cache_ttl": 10
+ }
},
- "uri": "/hello"
+ "upstream": {
+ "nodes": {
+ "httpbin.org": 1
+ },
+ "type": "roundrobin"
+ }
}'
```
@@ -99,7 +134,7 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
按上述配置启用插件后，使用 `curl` 命令请求该路由：
```shell
-curl http://127.0.0.1:9080/hello -i
+curl http://127.0.0.1:9080/ip -i
```
如果返回 `200` HTTP 状态码，并且响应头中包含 `Apisix-Cache-Status`字段，则表示该插件已启用：
@@ -115,7 +150,7 @@ hello
如果你是第一次请求该路由，数据未缓存，那么 `Apisix-Cache-Status` 字段应为 `MISS`。此时再次请求该路由：
```shell
-curl http://127.0.0.1:9080/hello -i
+curl http://127.0.0.1:9080/ip -i
```
如果返回的响应头中 `Apisix-Cache-Status` 字段变为 `HIT`，则表示数据已被缓存，插件生效：
@@ -135,7 +170,7 @@ hello
为了清除缓存数据，你只需要指定请求的 method 为 `PURGE`：
```shell
-curl -i http://127.0.0.1:9080/hello -X PURGE
+curl -i http://127.0.0.1:9080/ip -X PURGE
```
HTTP 响应码为 `200` 即表示删除成功，如果缓存的数据未找到将返回 `404`：
@@ -154,12 +189,12 @@ HTTP/1.1 200 OK
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
- "uri": "/hello",
+ "uri": "/ip",
"plugins": {},
"upstream": {
"type": "roundrobin",
"nodes": {
- "127.0.0.1:1999": 1
+ "httpbin.org": 1
}
}
}'
