This is an automated email from the ASF dual-hosted git repository.
juzhiyuan 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 63a5348a3 docs: improve `proxy-cache` plugin docs (#11910)
63a5348a3 is described below
commit 63a5348a32fe3585bd9ed759672362be23f98307
Author: Traky Deng <trakyd...@gmail.com>
AuthorDate: Tue Mar 4 14:34:38 2025 +0800
docs: improve `proxy-cache` plugin docs (#11910)
---
docs/en/latest/plugins/proxy-cache.md | 365 ++++++++++++++++++++++++---------
docs/zh/latest/plugins/proxy-cache.md | 366 +++++++++++++++++++++++++---------
2 files changed, 535 insertions(+), 196 deletions(-)
diff --git a/docs/en/latest/plugins/proxy-cache.md
b/docs/en/latest/plugins/proxy-cache.md
index 34a675112..f55cdf046 100644
--- a/docs/en/latest/plugins/proxy-cache.md
+++ b/docs/en/latest/plugins/proxy-cache.md
@@ -4,8 +4,9 @@ keywords:
- Apache APISIX
- API Gateway
- Proxy Cache
-description: This document contains information about the Apache APISIX
proxy-cache Plugin, you can use it to cache the response from the Upstream.
+description: The proxy-cache Plugin caches responses based on keys, supporting
disk and memory caching for GET, POST, and HEAD requests, enhancing API
performance.
---
+
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -25,64 +26,66 @@ description: This document contains information about the
Apache APISIX proxy-ca
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/proxy-cache"; />
+</head>
+
## Description
-The `proxy-cache` Plugin can be used to cache the response from the Upstream.
It can be used with other Plugins and currently supports disk-based and
memory-based caching.
+The `proxy-cache` Plugin provides the capability to cache responses based on a
cache key. The Plugin supports both disk-based and memory-based caching options
to cache for [GET](https://anything.org/learn/serving-over-http/#get-request),
[POST](https://anything.org/learn/serving-over-http/#post-request), and
[HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) requests.
-The data to be cached can be filtered with response codes, request modes, or
more complex methods using the `no_cache` and `cache_bypass` attributes.
+Responses can be conditionally cached based on request HTTP methods, response
status codes, request header values, and more.
## Attributes
| Name | Type | Required | Default |
Valid values | Description
|
|--------------------|----------------|----------|---------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| cache_strategy | string | False | disk |
["disk","memory"] | Specifies where the cached data should be stored.
|
-| cache_zone | string | False | disk_cache_one |
| Specifies which cache area to use. Each cache area
can be configured with different paths. Cache areas can be predefined in your
configuration file (`conf/config.yaml`). If the specified cache area is
inconsistent with the pre-defined cache area in your configuration file, the
cache is invalid. |
-| cache_key | array[string] | False | ["$host", "$request_uri"] |
| Key to use for caching. For example, `["$host",
"$uri", "-cache-id"]`.
|
-| cache_bypass | array[string] | False | |
| Conditions in which response from cache is bypassed.
Whether to skip cache retrieval. If at least one value of the string parameters
is not empty and is not equal to `0` then the response will not be taken from
the cache. For example, `["$arg_bypass"]`.
|
-| cache_method | array[string] | False | ["GET", "HEAD"] |
["GET", "POST", "HEAD"] | Request methods for which the response will be
cached.
|
-| cache_http_status | array[integer] | False | [200, 301, 404] |
[200, 599] | HTTP status codes of the Upstream response for which
the response will be cached.
|
-| hide_cache_headers | boolean | False | false |
| When set to `true`, hide the `Expires` and
`Cache-Control` response headers.
|
-| cache_control | boolean | False | false |
| When set to `true`, complies with Cache-Control
behavior in the HTTP specification. Used only for memory strategy.
|
-| no_cache | array[string] | False | |
| Conditions in which the response will not be cached.
If at least one value of the string parameters is not empty and is not equal to
`0` then the response will not be saved.
|
-| cache_ttl | integer | False | 300 seconds |
| Time that a response is cached until it is deleted or
refreshed. Comes in to effect when the `cache_control` attribute is not enabled
or the proxied server does not return cache header. Used only for memory
strategy.
|
+| cache_strategy | string | False | disk |
["disk","memory"] | Caching strategy. Cache on disk or in memory.
|
+| cache_zone | string | False | disk_cache_one |
| Cache zone used with the caching strategy. The value
should match one of the cache zones defined in the [configuration
files](#static-configurations) and should correspond to the caching strategy.
For example, when using the in-memory caching strategy, you should use an
in-memory cache zone. |
+| cache_key | array[string] | False | ["$host", "$request_uri"] |
| Key to use for caching. Support [NGINX
variables](https://nginx.org/en/docs/varindex.html) and constant strings in
values. Variables should be prefixed with a `$` sign. |
+| cache_bypass | array[string] | False | |
| One or more parameters to parse value from, such that
if any of the values is not empty and is not equal to `0`, response will not be
retrieved from cache. Support [NGINX
variables](https://nginx.org/en/docs/varindex.html) and constant strings in
values. Variables should be prefixed with a `$` sign. |
+| cache_method | array[string] | False | ["GET", "HEAD"] |
["GET", "POST", "HEAD"] | Request methods of which the response should be
cached. |
+| cache_http_status | array[integer] | False | [200, 301, 404] |
[200, 599] | Response HTTP status codes of which the response
should be cached. |
+| hide_cache_headers | boolean | False | false |
| If true, hide `Expires` and `Cache-Control` response
headers. |
+| cache_control | boolean | False | false |
| If true, comply with `Cache-Control` behavior in the
HTTP specification. Only valid for in-memory strategy. |
+| no_cache | array[string] | False | |
| One or more parameters to parse value from, such that
if any of the values is not empty and is not equal to `0`, response will not be
cached. Support [NGINX variables](https://nginx.org/en/docs/varindex.html) and
constant strings in values. Variables should be prefixed with a `$` sign.
|
+| cache_ttl | integer | False | 300 | >=1
| Cache time to live (TTL) in seconds when caching in memory. To adjust
the TTL when caching on disk, update `cache_ttl` in the [configuration
files](#static-configurations). The TTL value is evaluated in conjunction with
the values in the response headers
[`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)
and [`Expires`](https://developer.mozilla.org/en-US/docs/ [...]
-:::note
+## Static Configurations
-- The cache expiration time cannot be configured dynamically. It can only be
set by the Upstream response header `Expires` or `Cache-Control`. The default
expiration time is 10s if there is no `Expires` or `Cache-Control` in the
Upstream response header.
-- If the Upstream service is not available and APISIX returns a `502` or `504`
status code, it will be cached for 10s.
-- Variables (start with `$`) can be specified in `cache_key`, `cache_bypass`
and `no_cache`. It's worth mentioning that the variable value will be an empty
string if it doesn't exist.
-- You can also combine a number of variables and strings (constants), by
writing them into an array, eventually, variables will be parsed and stitched
together with strings.
+By default, values such as `cache_ttl` when caching on disk and cache `zones`
are pre-configured in the [default
configuration](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua).
-:::
+To customize these values, add the corresponding configurations to
`config.yaml`. For example:
-## Enable Plugin
-
-You can add your cache configuration in you APISIX configuration file
(`conf/config.yaml`) as shown below:
-
-```yaml title="conf/config.yaml"
+```yaml
apisix:
proxy_cache:
- cache_ttl: 10s # default cache TTL for caching on disk
+ cache_ttl: 10s # default cache TTL used when caching on disk, only if
none of the `Expires`
+ # and `Cache-Control` response headers is present, or if
APISIX returns
+ # `502 Bad Gateway` or `504 Gateway Timeout` due to
unavailable upstreams
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: 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
```
-### Use disk-based caching
+Reload APISIX for changes to take effect.
+
+## Examples
-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:
+The examples below demonstrate how you can configure `proxy-cache` for
different scenarios.
:::note
+
You can fetch the `admin_key` from `config.yaml` and save to an environment
variable with the following command:
```bash
@@ -91,118 +94,286 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
+### Cache Data on Disk
+
+On-disk caching strategy offers the advantages of data persistency when system
restarts and having larger storage capacity compared to in-memory cache. It is
suitable for applications that prioritize durability and can tolerate slightly
larger cache access latency.
+
+The following example demonstrates how you can use `proxy-cache` Plugin on a
Route to cache data on disk.
+
+When using the on-disk caching strategy, the cache TTL is determined by value
from the response header `Expires` or `Cache-Control`. If none of these headers
is present or if APISIX returns `502 Bad Gateway` or `504 Gateway Timeout` due
to unavailable Upstreams, the cache TTL defaults to the value configured in the
[configuration files](#static-configuration).
+
+Create a Route with the `proxy-cache` Plugin to cache data on disk:
+
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/ip",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "proxy-cache-route",
+ "uri": "/anything",
"plugins": {
- "proxy-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"]
- }
+ "proxy-cache": {
+ "cache_strategy": "disk"
+ }
},
"upstream": {
- "nodes": {
- "httpbin.org": 1
- },
- "type": "roundrobin"
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org": 1
+ }
}
-}'
+ }'
```
-### Use memory-based caching
+Send a request to the Route:
-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 -i "http://127.0.0.1:9080/anything";
+```
+
+You should see an `HTTP/1.1 200 OK` response with the following header,
showing the Plugin is successfully enabled:
+
+```text
+Apisix-Cache-Status: MISS
+```
+
+As there is no cache available before the first response,
`Apisix-Cache-Status: MISS` is shown.
+
+Send the same request again within the cache TTL window. You should see an
`HTTP/1.1 200 OK` response with the following headers, showing the cache is hit:
+
+```text
+Apisix-Cache-Status: HIT
+```
+
+Wait for the cache to expire after the TTL and send the same request again.
You should see an `HTTP/1.1 200 OK` response with the following headers,
showing the cache has expired:
+
+```text
+Apisix-Cache-Status: EXPIRED
+```
+
+### Cache Data in Memory
+
+In-memory caching strategy offers the advantage of low-latency access to the
cached data, as retrieving data from RAM is faster than retrieving data from
disk storage. It also works well for storing temporary data that does not need
to be persisted long-term, allowing for efficient caching of frequently
changing data.
+
+The following example demonstrates how you can use `proxy-cache` Plugin on a
Route to cache data in memory.
+
+Create a Route with `proxy-cache` and configure it to use memory-based caching:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/ip",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "proxy-cache-route",
+ "uri": "/anything",
"plugins": {
- "proxy-cache": {
- "cache_strategy": "memory",
- "cache_zone": "memory_cache",
- "cache_ttl": 10
- }
+ "proxy-cache": {
+ "cache_strategy": "memory",
+ "cache_zone": "memory_cache",
+ "cache_ttl": 10
+ }
},
"upstream": {
- "nodes": {
- "httpbin.org": 1
- },
- "type": "roundrobin"
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org": 1
+ }
}
-}'
+ }'
```
-## Example usage
-
-Once you have configured the Plugin as shown above, you can make an initial
request:
+Send a request to the Route:
```shell
-curl http://127.0.0.1:9080/ip -i
+curl -i "http://127.0.0.1:9080/anything";
```
-```shell
-HTTP/1.1 200 OK
-···
+You should see an `HTTP/1.1 200 OK` response with the following header,
showing the Plugin is successfully enabled:
+
+```text
Apisix-Cache-Status: MISS
+```
+
+As there is no cache available before the first response,
`Apisix-Cache-Status: MISS` is shown.
-hello
+Send the same request again within the cache TTL window. You should see an
`HTTP/1.1 200 OK` response with the following headers, showing the cache is hit:
+
+```text
+Apisix-Cache-Status: HIT
```
-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:
+### Cache Responses Conditionally
+
+The following example demonstrates how you can configure the `proxy-cache`
Plugin to conditionally cache responses.
+
+Create a Route with the `proxy-cache` Plugin and configure the `no_cache`
attribute, such that if at least one of the values of the URL parameter
`no_cache` and header `no_cache` is not empty and is not equal to `0`, the
response will not be cached:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "proxy-cache-route",
+ "uri": "/anything",
+ "plugins": {
+ "proxy-cache": {
+ "no_cache": ["$arg_no_cache", "$http_no_cache"]
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org": 1
+ }
+ }
+ }'
+```
+
+Send a few requests to the Route with the URL parameter `no_cache` value
indicating cache bypass:
```shell
-curl http://127.0.0.1:9080/ip -i
+curl -i "http://127.0.0.1:9080/anything?no_cache=1";
+```
+
+You should receive `HTTP/1.1 200 OK` responses for all requests and observe
the following header every time:
+
+```text
+Apisix-Cache-Status: EXPIRED
```
+Send a few other requests to the Route with the URL parameter `no_cache` value
being zero:
+
```shell
-HTTP/1.1 200 OK
-···
+curl -i "http://127.0.0.1:9080/anything?no_cache=0";
+```
+
+You should receive `HTTP/1.1 200 OK` responses for all requests and start
seeing the cache being hit:
+
+```text
Apisix-Cache-Status: HIT
+```
+
+You can also specify the value in the `no_cache` header as such:
-hello
+```shell
+curl -i "http://127.0.0.1:9080/anything"; -H "no_cache: 1"
```
-If you set `"cache_zone": "invalid_disk_cache"` attribute to an invalid value
(cache not configured in the your configuration file), then it will return a
`404` response.
+The response should not be cached:
-:::tip
+```text
+Apisix-Cache-Status: EXPIRED
+```
+
+### Retrieve Responses from Cache Conditionally
+
+The following example demonstrates how you can configure the `proxy-cache`
Plugin to conditionally retrieve responses from cache.
-To clear the cached data, you can send a request with `PURGE` method:
+Create a Route with the `proxy-cache` Plugin and configure the `cache_bypass`
attribute, such that if at least one of the values of the URL parameter
`bypass` and header `bypass` is not empty and is not equal to `0`, the response
will not be retrieved from the cache:
```shell
-curl -i http://127.0.0.1:9080/ip -X PURGE
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "proxy-cache-route",
+ "uri": "/anything",
+ "plugins": {
+ "proxy-cache": {
+ "cache_bypass": ["$arg_bypass", "$http_bypass"]
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org": 1
+ }
+ }
+ }'
```
+Send a request to the Route with the URL parameter `bypass` value indicating
cache bypass:
+
```shell
-HTTP/1.1 200 OK
+curl -i "http://127.0.0.1:9080/anything?bypass=1";
```
-If the response code is `200`, the deletion is successful. If the cached data
is not found, a `404` response code will be returned.
+You should see an `HTTP/1.1 200 OK` response with the following header:
-:::
+```text
+Apisix-Cache-Status: BYPASS
+```
-## Delete Plugin
+Send another request to the Route with the URL parameter `bypass` value being
zero:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything?bypass=0";
+```
-To remove the `proxy-cache` Plugin, you can delete the corresponding JSON
configuration from the Plugin configuration. APISIX will automatically reload
and you do not have to restart for this to take effect.
+You should see an `HTTP/1.1 200 OK` response with the following header:
+
+```text
+Apisix-Cache-Status: MISS
+```
+
+You can also specify the value in the `bypass` header as such:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/ip",
- "plugins": {},
+curl -i "http://127.0.0.1:9080/anything"; -H "bypass: 1"
+```
+
+The cache should be bypassed:
+
+```text
+Apisix-Cache-Status: BYPASS
+```
+
+### Cache for 502 and 504 Error Response Code
+
+When the Upstream services return server errors in the 500 range,
`proxy-cache` Plugin will cache the responses if and only if the returned
status is `502 Bad Gateway` or `504 Gateway Timeout`.
+
+The following example demonstrates the behavior of `proxy-cache` Plugin when
the Upstream service returns `504 Gateway Timeout`.
+
+Create a Route with the `proxy-cache` Plugin and configure a dummy Upstream
service:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "proxy-cache-route",
+ "uri": "/timeout",
+ "plugins": {
+ "proxy-cache": { }
+ },
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "httpbin.org": 1
- }
+ "type": "roundrobin",
+ "nodes": {
+ "12.34.56.78": 1
+ }
}
-}'
+ }'
```
+
+Generate a few requests to the Route:
+
+```shell
+seq 4 | xargs -I{} curl -I "http://127.0.0.1:9080/timeout";
+```
+
+You should see a response similar to the following:
+
+```text
+HTTP/1.1 504 Gateway Time-out
+...
+Apisix-Cache-Status: MISS
+
+HTTP/1.1 504 Gateway Time-out
+...
+Apisix-Cache-Status: HIT
+
+HTTP/1.1 504 Gateway Time-out
+...
+Apisix-Cache-Status: HIT
+
+HTTP/1.1 504 Gateway Time-out
+...
+Apisix-Cache-Status: HIT
+```
+
+However, if the Upstream services returns `503 Service Temporarily
Unavailable`, the response will not be cached.
diff --git a/docs/zh/latest/plugins/proxy-cache.md
b/docs/zh/latest/plugins/proxy-cache.md
index ff0decb18..1fdf78c78 100644
--- a/docs/zh/latest/plugins/proxy-cache.md
+++ b/docs/zh/latest/plugins/proxy-cache.md
@@ -1,10 +1,10 @@
---
title: proxy-cache
keywords:
- - APISIX
+ - Apache APISIX
- API 网关
- - Request Validation
-description: 本文介绍了 Apache APISIX proxy-cache 插件的相关操作，你可以使用此插件缓存来自上游的响应。
+ - Proxy Cache
+description: proxy-cache 插件根据键缓存响应，支持 GET、POST 和 HEAD 请求的磁盘和内存缓存，从而增强 API 性能。
---
<!--
@@ -26,59 +26,63 @@ description: 本文介绍了 Apache APISIX proxy-cache 插件的相关操作，
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/proxy-cache"; />
+</head>
+
## 描述
-`proxy-cache`
插件提供缓存后端响应数据的能力，它可以和其他插件一起使用。该插件支持基于磁盘和内存的缓存。目前可以根据响应码和请求模式来指定需要缓存的数据，也可以通过
`no_cache` 和 `cache_bypass`属性配置更复杂的缓存策略。
+`proxy-cache` 插件提供了根据缓存键缓存响应的功能。该插件支持基于磁盘和基于内存的缓存选项，用于缓存
[GET](https://anything.org/learn/serving-over-http/#get-request)、[POST](https://anything.org/learn/serving-over-http/#post-request)
和 [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) 请求。
+
+可以根据请求 HTTP 方法、响应状态代码、请求标头值等有条件地缓存响应。
## 属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值
| 描述
|
| ------------------ | -------------- | ------ | ------------------------- |
-------------------------------------------------------------------------------
|
----------------------------------------------------------------------------------------------------------------------------------
|
-| cache_strategy | string | 否 | disk |
["disk","memory"]
| 缓存策略，指定缓存数据存储在磁盘还是内存中。 |
-| cache_zone | string | 否 | disk_cache_one |
|
指定使用哪个缓存区域，不同的缓存区域可以配置不同的路径，在 `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", "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` 未开启或开启以后服务端没有返回缓存控制头时，提供的默认缓存时间。 |
-
-:::note 注意
-
-- 对于基于磁盘的缓存，不能动态配置缓存的过期时间，只能通过后端服务响应头 `Expires` 或 `Cache-Control`
来设置过期时间，当后端响应头中没有 `Expires` 或 `Cache-Control` 时，默认缓存时间为 10 秒钟
-- 当上游服务不可用时，APISIX 将返回 `502` 或 `504` HTTP 状态码，默认缓存时间为 10 秒钟；
-- 变量以 `$` 开头，不存在时等价于空字符串。也可以使用变量和字符串的结合，但是需要以数组的形式分开写，最终变量被解析后会和字符串拼接在一起。
+| cache_strategy | string | 否 | disk | ["disk","memory"] | 缓存策略。缓存在磁盘还是内存中。 |
+| cache_zone | string | 否 | disk_cache_one | |
与缓存策略一起使用的缓存区域。该值应与[配置文件](#static-configurations)中定义的缓存区域之一匹配，并与缓存策略相对应。例如，当使用内存缓存策略时，应该使用内存缓存区域。
|
+| cache_key | array[string] | 否 | ["$host", "$request_uri"] | |
用于缓存的键。支持[NGINX 变量](https://nginx.org/en/docs/varindex.html)和值中的常量字符串。变量应该以 `$`
符号为前缀。 |
+| cache_bypass | array[string] | 否 | | |一个或多个用于解析值的参数，如果任何值不为空且不等于
`0`，则不会从缓存中检索响应。支持值中的 [NGINX 变量](https://nginx.org/en/docs/varindex.html)
和常量字符串。变量应该以 `$` 符号为前缀。|
+| cache_method | array[string] | 否 | ["GET", "HEAD"] | ["GET", "POST", "HEAD"]
| 应缓存响应的请求方法。|
+| 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`，则不会缓存响应。支持
[NGINX 变量](https://nginx.org/en/docs/varindex.html) 和值中的常量字符串。变量应以 `$` 符号为前缀。 |
+| cache_ttl | integer | 否 | 300 | >=1 | 在内存中缓存时的缓存生存时间 (TTL)，以秒为单位。要调整在磁盘上缓存时的
TTL，请更新[配置文件](#static-configurations) 中的 `cache_ttl`。TTL 值与从上游服务收到的响应标头
[`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)
和
[`Expires`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires)
中的值一起评估。|
-:::
+## 静态配置
-## 启用插件
+默认情况下，磁盘缓存时的 `cache_ttl` 和缓存 `zones` 等值已在
[默认配置](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua)
中预先配置。
-你可以在 APISIX 配置文件 `conf/config.yaml` 中添加你的缓存配置，示例如下：
+要自定义这些值，请将相应的配置添加到 `config.yaml`。例如：
-```yaml title="conf/config.yaml"
+```yaml
apisix:
proxy_cache:
- cache_ttl: 10s # 如果上游未指定缓存时间，则为默认磁盘缓存时间
+ cache_ttl: 10s # 仅当 `Expires` 和 `Cache-Control` 响应标头均不存在，或者 APISIX 返回
+ # 由于上游不可用导致 `502 Bad Gateway` 或 `504 Gateway Timeout` 时
+ # 才会在磁盘上缓存时使用默认缓存 TTL
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: 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
```
-### 使用基于磁盘的缓存
+重新加载 APISIX 以使更改生效。
-以下示例展示了如何在路由上启用 `proxy-cache` 插件。该插件默认使用基于磁盘的 `cache_strategy`
和默认使用`disk_cache_one` 为 `cache_zone`：
+## 示例
+
+以下示例演示了如何为不同场景配置 `proxy-cache`。
:::note
@@ -90,122 +94,286 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
+### 在磁盘上缓存数据
+
+磁盘缓存策略具有系统重启时数据持久性以及与内存缓存相比具有更大存储容量的优势。它适用于优先考虑耐用性且可以容忍稍大的缓存访问延迟的应用程序。
+
+以下示例演示了如何在路由上使用 `proxy-cache` 插件将数据缓存在磁盘上。
+
+使用磁盘缓存策略时，缓存 TTL 由响应标头 `Expires` 或 `Cache-Control` 中的值确定。如果这些标头均不存在，或者 APISIX
由于上游不可用而返回 `502 Bad Gateway` 或 `504 Gateway Timeout`，则缓存 TTL 默认为
[配置文件](#static-configuration) 中配置的值。
+
+使用 `proxy-cache` 插件创建路由以将数据缓存在磁盘上：
+
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/ip",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "proxy-cache-route",
+ "uri": "/anything",
"plugins": {
- "proxy-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"]
- }
+ "proxy-cache": {
+ "cache_strategy": "disk"
+ }
},
"upstream": {
- "nodes": {
- "httpbin.org": 1
- },
- "type": "roundrobin"
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org": 1
+ }
}
-}'
+ }'
+```
+
+向路由发送请求：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything";
+```
+
+您应该看到带有以下标头的 `HTTP/1.1 200 OK` 响应，表明插件已成功启用：
+
+```text
+Apisix-Cache-Status: MISS
+```
+
+由于在第一次响应之前没有可用的缓存，因此显示 `Apisix-Cache-Status: MISS`。
+
+在缓存 TTL 窗口内再次发送相同的请求。您应该看到带有以下标头的 `HTTP/1.1 200 OK` 响应，显示缓存已命中：
+
+```text
+Apisix-Cache-Status: HIT
+```
+
+等待缓存在 TTL 之后过期，然后再次发送相同的请求。您应该看到带有以下标头的 `HTTP/1.1 200 OK` 响应，表明缓存已过期：
+
+```text
+Apisix-Cache-Status: EXPIRED
```
-### 使用基于内存的缓存
+### 在内存中缓存数据
+
+内存缓存策略具有低延迟访问缓存数据的优势，因为从 RAM
检索数据比从磁盘存储检索数据更快。它还适用于存储不需要长期保存的临时数据，从而可以高效缓存频繁更改的数据。
+
+以下示例演示了如何在路由上使用 `proxy-cache` 插件在内存中缓存数据。
-以下示例展示了如何在路由上启用 `proxy-cache` 插件，并使用基于内存的 `cache_strategy` 和相应的基于内存的
`cache_zone`。
+使用 `proxy-cache` 创建路由并将其配置为使用基于内存的缓存：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/ip",
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "proxy-cache-route",
+ "uri": "/anything",
"plugins": {
- "proxy-cache": {
- "cache_strategy": "memory",
- "cache_zone": "memory_cache",
- "cache_ttl": 10
- }
+ "proxy-cache": {
+ "cache_strategy": "memory",
+ "cache_zone": "memory_cache",
+ "cache_ttl": 10
+ }
},
"upstream": {
- "nodes": {
- "httpbin.org": 1
- },
- "type": "roundrobin"
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org": 1
+ }
}
-}'
+ }'
```
-## 测试插件
-
-按上述配置启用插件后，使用 `curl` 命令请求该路由：
+向路由发送请求：
```shell
-curl http://127.0.0.1:9080/ip -i
+curl -i "http://127.0.0.1:9080/anything";
```
-如果返回 `200` HTTP 状态码，并且响应头中包含 `Apisix-Cache-Status`字段，则表示该插件已启用：
+您应该看到带有以下标头的 `HTTP/1.1 200 OK` 响应，表明插件已成功启用：
-```shell
-HTTP/1.1 200 OK
-···
+```text
Apisix-Cache-Status: MISS
+```
+
+由于在第一次响应之前没有可用的缓存，因此显示 `Apisix-Cache-Status: MISS`。
+
+在缓存 TTL 窗口内再次发送相同的请求。您应该看到带有以下标头的 `HTTP/1.1 200 OK` 响应，显示缓存已命中：
+
+```text
+Apisix-Cache-Status: HIT
+```
+
+### 有条件地缓存响应
-hello
+以下示例演示了如何配置 `proxy-cache` 插件以有条件地缓存响应。
+
+使用 `proxy-cache` 插件创建路由并配置 `no_cache` 属性，这样如果 URL 参数 `no_cache` 和标头 `no_cache`
的值中至少有一个不为空且不等于 `0`，则不会缓存响应：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "proxy-cache-route",
+ "uri": "/anything",
+ "plugins": {
+ "proxy-cache": {
+ "no_cache": ["$arg_no_cache", "$http_no_cache"]
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org": 1
+ }
+ }
+ }'
```
-如果你是第一次请求该路由，数据未缓存，那么 `Apisix-Cache-Status` 字段应为 `MISS`。此时再次请求该路由：
+向路由发送一些请求，其中 URL 参数的 `no_cache` 值表示绕过缓存：
```shell
-curl http://127.0.0.1:9080/ip -i
+curl -i "http://127.0.0.1:9080/anything?no_cache=1";
+```
+
+您应该收到所有请求的 `HTTP/1.1 200 OK` 响应，并且每次都观察到以下标头：
+
+```text
+Apisix-Cache-Status: EXPIRED
```
-如果返回的响应头中 `Apisix-Cache-Status` 字段变为 `HIT`，则表示数据已被缓存，插件生效：
+向路由发送一些其他请求，其中 URL 参数 `no_cache` 值为零：
```shell
-HTTP/1.1 200 OK
-···
+curl -i "http://127.0.0.1:9080/anything?no_cache=0";
+```
+
+您应该收到所有请求的 `HTTP/1.1 200 OK` 响应，并开始看到缓存被命中：
+
+```text
Apisix-Cache-Status: HIT
+```
+
+您还可以在 `no_cache` 标头中指定以下值：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything"; -H "no_cache: 1"
+```
-hello
+响应不应该被缓存：
+
+```text
+Apisix-Cache-Status: EXPIRED
```
-如果你设置 `"cache_zone": "invalid_disk_cache"` 属性为无效值，即与配置文件 `conf/config.yaml`
中指定的缓存区域不一致，那么它将返回 `404` HTTP 响应码。
+### 有条件地从缓存中检索响应
-:::tip 提示
+以下示例演示了如何配置 `proxy-cache` 插件以有条件地从缓存中检索响应。
-为了清除缓存数据，你只需要指定请求的 method 为 `PURGE`：
+使用 `proxy-cache` 插件创建路由并配置 `cache_bypass` 属性，这样如果 URL 参数 `bypass` 和标头 `bypass`
的值中至少有一个不为空且不等于 `0`，则不会从缓存中检索响应：
```shell
-curl -i http://127.0.0.1:9080/ip -X PURGE
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "proxy-cache-route",
+ "uri": "/anything",
+ "plugins": {
+ "proxy-cache": {
+ "cache_bypass": ["$arg_bypass", "$http_bypass"]
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org": 1
+ }
+ }
+ }'
```
-HTTP 响应码为 `200` 即表示删除成功，如果缓存的数据未找到将返回 `404`：
+向路由发送一个请求，其中 URL 参数值为 `bypass`，表示绕过缓存：
```shell
-HTTP/1.1 200 OK
+curl -i "http://127.0.0.1:9080/anything?bypass=1";
```
-:::
+您应该看到带有以下标头的 `HTTP/1.1 200 OK` 响应：
+
+```text
+Apisix-Cache-Status: BYPASS
+```
+
+向路由发送另一个请求，其中 URL 参数 `bypass` 值为零：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything?bypass=0";
+```
+
+您应该看到带有以下标头的 `HTTP/1.1 200 OK` 响应：
+
+```text
+Apisix-Cache-Status: MISS
+```
+
+您还可以在 `bypass` 标头中指定以下值：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything"; -H "bypass: 1"
+```
+
+响应应该显示绕过缓存：
+
+```text
+Apisix-Cache-Status: BYPASS
+```
+
+### 缓存 502 和 504 错误响应代码
-## 删除插件
+当上游服务返回 500 范围内的服务器错误时，`proxy-cache` 插件将缓存响应，当且仅当返回的状态为 `502 Bad Gateway` 或
`504 Gateway Timeout`。
-当你需要删除该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+以下示例演示了当上游服务返回 `504 Gateway Timeout` 时 `proxy-cache` 插件的行为。
+
+使用 `proxy-cache` 插件创建路由并配置虚拟上游服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "uri": "/ip",
- "plugins": {},
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "proxy-cache-route",
+ "uri": "/timeout",
+ "plugins": {
+ "proxy-cache": { }
+ },
"upstream": {
- "type": "roundrobin",
- "nodes": {
- "httpbin.org": 1
- }
+ "type": "roundrobin",
+ "nodes": {
+ "12.34.56.78": 1
+ }
}
-}'
+ }'
+```
+
+生成一些对路由的请求：
+
+```shell
+seq 4 | xargs -I{} curl -I "http://127.0.0.1:9080/timeout";
+```
+
+您应该会看到类似以下内容的响应：
+
+```text
+HTTP/1.1 504 Gateway Time-out
+...
+Apisix-Cache-Status: MISS
+
+HTTP/1.1 504 Gateway Time-out
+...
+Apisix-Cache-Status: HIT
+
+HTTP/1.1 504 Gateway Time-out
+...
+Apisix-Cache-Status: HIT
+
+HTTP/1.1 504 Gateway Time-out
+...
+Apisix-Cache-Status: HIT
```
+
+但是，如果上游服务返回 `503 Service Temporarily Unavailable`，则响应将不会被缓存。
