Nginx Proxy Cache Internals: Key-Value Design, Configuration & Cache Locking Strategies

What Is Nginx Proxy Cache?

Nginx Proxy Cache stores backend responses (HTML, images, JSON, etc.) on local disk or memory. On subsequent identical requests, Nginx serves the cached content directly without forwarding to the upstream server.

Problems Solved

Reduces backend load: hot static resources, list pages, detail pages no longer repeatedly hit Java/Node/PHP services.

Lowers response latency: Nginx returns from local disk, avoiding network round-trips, application computation, and database queries.

Improves availability: during brief backend failures or timeouts, stale cache can still be served, preventing complete outage.

Core Principle

Nginx caching is fundamentally a local file-system key-value store.

Request processing flow:

Compute Cache Key : Generate cache identifier from request method, host, URI, query parameters.

Lookup Cache : Search cache zone; if valid, return cached content directly.

Request Upstream : If cache missing, expired, or bypassed, forward request to upstream server.

Store Response : When response meets caching criteria, write to cache with configured TTL.

Expiration & Update : On expiry, Nginx can re-fetch from upstream and update; during update, old content continues to serve, preventing thundering herd.

Configuration Walkthrough

The following configuration demonstrates a production-ready setup:

http {
    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:100m max_size=20g inactive=7d use_temp_path=off;

    upstream backend {
        server 127.0.0.1:8080;
        keepalive 64;
    }

    server {
        listen 80;
        server_name example.com;

        location /api/ {
            proxy_pass http://backend;

            proxy_cache api_cache;
            proxy_cache_key "$scheme$request_method$host$request_uri";

            proxy_cache_valid 200 301 302 10m;
            proxy_cache_valid 404 1m;
            proxy_cache_valid any 30s;

            # Prevent cache stampede: only one request per key goes to origin
            proxy_cache_lock on;
            proxy_cache_lock_timeout 5s;
            proxy_cache_lock_age 10s;

            # Serve stale cache on backend errors
            proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;

            # Background update after expiry, stale content continues serving
            proxy_cache_background_update on;

            # Expose cache status for monitoring
            add_header X-Cache-Status $upstream_cache_status;

            proxy_http_version 1.1;
            proxy_set_header Connection "";
        }
    }
}

Key Directives Explained

proxy_cache_path

: Defines cache directory, index memory zone (keys_zone), max size, inactive timeout, and disables temporary path. proxy_cache: Enables the named cache zone in a location. proxy_cache_key: Builds the cache key from scheme, method, host, and full URI. proxy_cache_valid: Sets TTL per status code: 10 minutes for 200/301/302, 1 minute for 404, 30 seconds for any other. proxy_cache_lock: Ensures only one request populates a missing key (prevents cache stampede). proxy_cache_lock_timeout and proxy_cache_lock_age control lock wait and fallback. proxy_cache_use_stale: Allows serving expired cache when upstream returns errors, times out, or is updating. proxy_cache_background_update: Triggers asynchronous revalidation after expiry while continuing to serve stale content. add_header X-Cache-Status: Exposes cache hit/miss status for observability. proxy_http_version 1.1 and proxy_set_header Connection "": Enable HTTP/1.1 keepalive to upstream.