# Proxy Cache 配置选项

proxy-cache 插件将 HTTP 响应缓存在内存或磁盘中，以减少上游流量，并支持条件缓存和缓存清除。<!-- --> <!-- -->配置涵盖静态设置和插件参数。

## 静态配置[​](#静态配置 "静态配置的��直接链接")

网关默认配置包含磁盘缓存和缓存区域的代理缓存设置。需要更新的文件取决于网关的部署方式：

* 主机或 Docker
* Kubernetes (Helm)

对于主机或 Docker 部署，请配置以下设置：

config.yaml

```
apisix:

  proxy_cache:

    cache_ttl: 10s  # 磁盘缓存使用的默认缓存 TTL；仅当响应中不包含 `Expires`

                    # 和 `Cache-Control` 响应头，或网关因上游不可用而返回

                    # `502 Bad Gateway` 或 `504 Gateway Timeout` 时生效

    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
```

重新加载或重启网关，使更改生效。

在 APISIX Helm Chart 2.16.0 或更高版本和 API7 Gateway Helm Chart 3.10.3 或更高版本中，请设置 `apisix.proxyCache`。

两个 Chart 都会在网关配置中将此值渲染为 `apisix.proxy_cache`：

values.yaml

```
apisix:

  proxyCache:

    cacheTtl: 10s

    zones:

      - name: disk_cache_one

        memory_size: 50m

        disk_size: 1G

        disk_path: /tmp/disk_cache_one

        cache_levels: 1:2

      - name: memory_cache

        memory_size: 50m
```

然后使用该网关发布版本对应的 Chart 应用 values 文件：

```
helm upgrade <release-name> <chart-name> -n <namespace> -f values.yaml
```

## 参数[​](#参数 "参数的直接链接")

有关所有插件均可使用的配置项，请参阅[插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)。

* cache\_strategy

  string

  默认值：`disk`

  有效值：

  `disk` 或 `memory`

  ***

  缓存策略。缓存在磁盘或内存中。

* cache\_zone

  string

  默认值：`disk_cache_one`

  ***

  与缓存策略一起使用的缓存区域。该值应与[配置文件](https://docs.apiseven.com/hub/proxy-cache/configuration.md#静态配置)中定义的缓存区域之一匹配，并应对应于缓存策略。例如，当使用内存缓存策略时，你应该使用内存缓存区域。

* cache\_key

  array\[string]

  默认值：`["$host", "$request_uri"]`

  ***

  按顺序拼接并形成缓存键的值。

  支持[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)和常量字符串。变量应以 `$` 符号为前缀。

* cache\_bypass

  array\[string]

  ***

  按顺序拼接这些值。如果结果既不为空，也不完全等于 `0`，则不会从缓存中检索响应。

  支持[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)和常量字符串。变量应以 `$` 符号为前缀。

* 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` 时，内存缓存策略会遵循受支持的请求 `Cache-Control` 指令，并根据上游响应的 `s-maxage`、`max-age` 或 `Expires` 计算缓存 TTL。无论该配置为何值，包含 `Cache-Control: private`、`no-store` 或 `no-cache` 的响应都不会缓存在内存中。

* no\_cache

  array\[string]

  ***

  按顺序拼接这些值。如果结果既不为空，也不完全等于 `0`，则不会缓存响应。

  支持[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)和常量字符串。变量应以 `$` 符号为前缀。

* cache\_ttl

  integer

  默认值：`300`

  有效值：

  大于或等于 1

  ***

  使用内存缓存时的缓存生存时间（TTL），单位为秒。

  要调整磁盘缓存的 TTL，请更新[配置文件](https://docs.apiseven.com/hub/proxy-cache/configuration.md#静态配置)中的 `cache_ttl`。TTL 值会与从上游服务收到的响应头 [`Cache-Control`](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Cache-Control) 和 [`Expires`](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Expires) 的值共同计算。

* consumer\_isolation

  boolean

  默认值：`true`

  ***

  如果为 true，当请求解析出消费者或远程用户时，将已认证消费者身份添加到实际缓存键前。若 `cache_key` 已包含 `$consumer_name`、`$consumer_group_id`、`$remote_user` 或 `$http_authorization` 等携带身份的变量，则不会重复添加。自 API7 企业版 3.9.13 和 APISIX 3.17.0 起可用。

  在 API7 网关中，请勿使用 `$consumer_group_id`：控制面不会分配消费者组 ID，但只要包含该变量，仍会禁用自动消费者隔离。

* cache\_set\_cookie

  boolean

  默认值：`false`

  ***

  如果为 true，允许内存缓存策略缓存包含 `Set-Cookie` 响应头的响应。默认情况下，此类响应不会被缓存。自 API7 企业版 3.9.13 和 APISIX 3.17.0 起可用。

* max\_resp\_body\_size

  integer

  默认值：`67108864`

  有效值：

  大于或等于 1

  ***

  memory 缓存策略缓冲的响应体最大字节数。达到或超过该大小的响应会直接流式传输给客户端，不会被缓存。跨越阈值的数据块会在执行限制前先进入缓冲，因此瞬时内存用量可能超过配置值。此字段不适用于磁盘缓存。自 API7 企业版 3.9.17 和 3.10.4 以及 APISIX 3.18.0 起引入。
