http-cache-purge #
An nginx module that adds cache purge support for FastCGI, proxy, SCGI, and uWSGI caches. A purge operation removes the cached entry whose key matches the purge request.
Source: upstream source
Directives
cache_purge_background_queue #
syntax: cache_purge_background_queue 1 arg; · context: http
When enabled, wildcard and purge_all purge requests are enqueued and return 202 Accepted immediately; a per-worker background timer drains the queue in batches. Has no effect on exact-key purges, which are always synchronous. When disabled, all purges are processed synchronously in the request handler.
cache_purge_batch_size #
syntax: cache_purge_batch_size 1 arg (integer); · context: http
Number of queue entries processed per background timer tick. Values above 64 are clamped to 64 at startup (a warning is logged). Reduce this value if purge operations cause iowait spikes; increase it for faster queue drain on fast storage. Only meaningful when cache_purge_background_queue on.
cache_purge_legacy_status #
syntax: cache_purge_legacy_status 1 arg; · context: http
Controls the HTTP status code returned when a purge request targets an entry that is not in the cache: Default is on (412) for backwards compatibility with earlier releases. Set to off to return 404 Not Found, the correct HTTP status for a resource that does not exist (RFC 9110 §15.5.5).
cache_purge_queue_size #
syntax: cache_purge_queue_size 1 arg (integer); · context: http
Maximum number of entries the background queue can hold. Each slot occupies roughly 1–2 KB of shared memory (2048 slots ≈ 3 MB). When the queue is full, new wildcard / purge_all purge requests fall back to synchronous processing. Only meaningful when cache_purge_background_queue on.
cache_purge_response_type #
syntax: cache_purge_response_type 1 arg; · context: http, server, location
Sets the Content-Type and body format of purge responses. Has no effect on cache-miss responses (412 / 404), which are generated by nginx's built-in error-page renderer.
cache_purge_throttle_ms #
syntax: cache_purge_throttle_ms 1 arg (duration in ms); · context: http
Interval between background processing ticks. Accepts any nginx time value: 10ms, 500ms, 1s, 2s 500ms. Only meaningful when cache_purge_background_queue on. Increase on constrained or spinning-disk storage; decrease on NVMe. Time-unit note: a bare integer with no suffix (e.g. 10) is interpreted
cache_purge_vary_aware #
syntax: cache_purge_vary_aware 1 arg; · context: http
When on, an exact-key purge walks the cache directory after deleting the primary file and removes any remaining files that carry the same KEY: string. This covers all Vary and gzip_vary variants of a cached response, which are stored at different filesystem paths but share one logical key. The byte variant regardless. ---
fastcgi_cache_purge #
syntax: fastcgi_cache_purge 1+ args; · context: http, server, location
Equivalent to proxy_cache_purge but for FastCGI cache zones configured with fastcgi_cache / fastcgi_cache_path.
proxy_cache_purge #
syntax: proxy_cache_purge 1+ args; · context: http, server, location
Inline form (from …) — intercepts the named HTTP method on a proxy location and purges the matching cache entry. on is a shorthand for method PURGE; off disables purging. Optionally restrict to a list of CIDR ranges or use from all to allow from any address. Adding purge_all before from empties the entire cache zone regardless of the request URI.
scgi_cache_purge #
syntax: scgi_cache_purge 1+ args; · context: http, server, location
Equivalent to proxy_cache_purge but for SCGI cache zones configured with scgi_cache / scgi_cache_path.
uwsgi_cache_purge #
syntax: uwsgi_cache_purge 1+ args; · context: http, server, location
Equivalent to proxy_cache_purge but for uWSGI cache zones configured with uwsgi_cache / uwsgi_cache_path.
Example
http {
proxy_cache_path /var/cache/nginx keys_zone=main:10m;
cache_purge_background_queue on;
cache_purge_queue_size 2048;
cache_purge_batch_size 20;
cache_purge_throttle_ms 10ms;
server {
location / {
proxy_pass http://backend;
proxy_cache main;
proxy_cache_key "$host$uri$is_args$args";
proxy_cache_purge PURGE from 127.0.0.1;
}
}
}