Mastering Nginx Caching: Configuration, Management, and Optimization

Basic Idea of Nginx Caching

By leveraging request locality, Nginx stores a local copy of a response so subsequent requests can be served directly from disk without contacting the upstream server.

When Nginx starts, it scans the cache directory, builds an in‑memory index, and runs dedicated processes to handle expiration and updates.

Typical Cache Questions

Where are cache files stored?

Can the cache size be limited?

How to select which requests are cached?

What is the cache lifetime?

How to bypass the cache for specific requests?

Enabling Cache

Use the proxy_cache_path directive in the http context, then enable proxy_cache in the desired server or location block.

http {
    # …
    proxy_cache_path /data/nginx/cache keys_zone=one:10m;
    server {
        proxy_cache one;
        location / {
            proxy_pass http://localhost:8000;
        }
    }
}

The first argument of proxy_cache_path is the cache directory; keys_zone defines the cache name and the size of the in‑memory metadata (e.g., 10m). To limit total cache size, use the max_size parameter.

Cache Management Processes

Nginx runs two auxiliary processes:

Cache manager – periodically checks total cache usage and evicts the least‑used items when limits are exceeded.

Cache loader – runs once after startup to load metadata into memory. Loading can be throttled with loader_threshold, loader_files, and loader_sleeps to avoid long startup delays.

Example:

proxy_cache_path /data/nginx/cache keys_zone=one:10m \
    loader_threshold=300 loader_files=200;

Specifying Which Requests Are Cached

By default Nginx caches responses to GET and HEAD requests using the request URI as the cache key.

Custom key: proxy_cache_key "$host$request_uri$cookie_user"; Cache only after a request has been seen a minimum number of times: proxy_cache_min_uses 5; Choose cached methods:

proxy_cache_methods GET HEAD POST;

Cache Validity

Without explicit settings, cached content lives indefinitely unless the cache size limit is reached. You can set expiration per status code:

proxy_cache_valid 200 302 10m;   # 10 minutes for 200/302 responses
proxy_cache_valid any 5m;       # 5 minutes for any status

Bypassing the Cache

Use proxy_cache_bypass with variables; if any variable is non‑empty or non‑zero, Nginx skips the cache and proxies directly.

proxy_cache_bypass $cookie_nocache $arg_nocache $arg_comment;

Comprehensive Example

http {
    # Cache directory: /data/nginx/cache
    # Cache name: one
    # In‑memory zone: 10m
    # Loader: max 300 ms per iteration, up to 200 files
    # Max disk usage: 200m
    proxy_cache_path /data/nginx/cache keys_zone=one:10m \
        loader_threshold=300 loader_files=200 max_size=200m;

    server {
        listen 8080;

        # Use cache named "one"
        proxy_cache one;

        location / {
            proxy_pass http://backend1;
        }

        location /some/path {
            proxy_pass http://backend2;
            # Cache validity: 1 minute
            proxy_cache_valid any 1m;
            # Cache after 3 hits
            proxy_cache_min_uses 3;
            # Bypass cache when specific parameters are present
            proxy_cache_bypass $cookie_nocache $arg_nocache $arg_comment;
        }
    }
}