Skip to main content
API7.ai Logo

Static Configurations​

The default gateway configuration includes proxy cache settings for disk caching and cache zones. The file to update depends on how the gateway is deployed:

For host or Docker deployments, configure the following settings:

config.yaml
apisix:
  proxy_cache:
    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 the gateway 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: memory_cache
        memory_size: 50m

Reload or restart the gateway for the changes to take effect.

Parameters​

See plugin common configurations for configuration options available to all plugins.

  • cache_strategy

    string

    default: disk

    vaild vaule:

    disk or memory

    Caching strategy. Cache on disk or in memory.

  • cache_zone

    string

    default: disk_cache_one

    Cache zone used with the caching strategy. The value should match one of the cache zones defined in the configuration files 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]

    default: ["$host", "$request_uri"]

    Values that are concatenated in order to form the cache key.

    Supports built-in variables and constant strings. Prefix variables with a $ sign.

  • cache_bypass

    array[string]

    Values that are concatenated in order. If the result is neither empty nor exactly 0, the response is not retrieved from the cache.

    Supports built-in variables and constant strings. Prefix variables with a $ sign.

  • cache_method

    array[string]

    default: ["GET", "HEAD"]

    vaild vaule:

    Any combination of methods from "GET", "POST", and "HEAD"

    Request methods whose responses can be cached.

  • cache_http_status

    array[integer]

    default: [200, 301, 404]

    vaild vaule:

    Any combination of integer values from 200 to 599 inclusive

    Response HTTP status codes that can be cached.

  • hide_cache_headers

    boolean

    default: false

    If true, hide Expires and Cache-Control response headers.

  • cache_control

    boolean

    default: false

    If true, the in-memory strategy honors supported request Cache-Control directives and derives the cache TTL from the upstream response's s-maxage, max-age, or Expires value. Regardless of this setting, responses containing Cache-Control: private, no-store, or no-cache are not cached in memory.

  • no_cache

    array[string]

    Values that are concatenated in order. If the result is neither empty nor exactly 0, the response is not cached.

    Supports built-in variables and constant strings. Prefix variables with a $ sign.

  • cache_ttl

    integer

    default: 300

    vaild vaule:

    greater than or equal to 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. The TTL value is evaluated in conjunction with the values in the response headers Cache-Control and Expires received from the upstream service.

  • consumer_isolation

    boolean

    default: true

    If true, prepend the authenticated consumer identity to the effective cache key when the request resolves to a consumer or remote user. This is skipped when cache_key already contains an identity-bearing variable such as $consumer_name, $consumer_group_id, $remote_user, or $http_authorization. Available in API7 Enterprise from version 3.9.13 and APISIX from version 3.17.0.

    In API7 Gateway, do not use $consumer_group_id: the control plane does not assign consumer group IDs, but including the variable still disables automatic consumer isolation.

  • cache_set_cookie

    boolean

    default: false

    If true, allow the in-memory strategy to cache responses that include a Set-Cookie header. By default, such responses are not cached. Available in API7 Enterprise from version 3.9.13 and APISIX from version 3.17.0.

  • max_resp_body_size

    integer

    default: 67108864

    vaild vaule:

    greater than or equal to 1

    Maximum response body size in bytes buffered by the memory cache strategy. A response that reaches or exceeds this size is streamed to the client without being cached. The chunk that crosses the threshold is buffered before the limit is enforced, so transient memory use can exceed the configured size. This field does not apply to disk caching. Introduced in API7 Enterprise 3.9.17 and 3.10.4, and APISIX 3.18.0.