Nginx Caching Mastery: Proxy Cache Keys, Hit Rates & Cache-Control Matrix
This article provides a comprehensive guide to Nginx caching, covering browser vs proxy cache distinctions, Cache-Control directives, fingerprint-based static asset strategies, proxy_cache key design, stale-while-revalidate patterns, production configurations for static sites and API caching, source-code-level cache internals, cache hit rate measurement, purge strategies, and security hardening.
Three Incidents, Three Lessons
The article opens with three production incidents that frame the entire discussion:
User sees another user's order: An API endpoint /api/order was cached with the default proxy_cache_key ( $scheme$proxy_host$request_uri). The endpoint relied on the Authorization header to identify users, but the key did not include it. The first user's response was cached and served to all subsequent users.
Mass white-screen after deploy: A frontend deploy changed app.js to a fingerprinted filename (e.g., app.a3f9c2.js), but index.html had expires 1h. Browsers kept the old HTML referencing the old JS file, which had been deleted by the deploy script, causing 404s and a blank page for 40 minutes.
Cache directory fills the disk: A proxy cache for images was configured without max_size or inactive. After three months the disk hit 100%, Nginx failed to write temporary cache files, all proxied requests returned 500, and the log disk on the same machine was also affected.
The lessons: (1) Authenticated endpoints must either disable caching or include identity in the key; (2) HTML entry points must be no-cache while fingerprinted static assets get long-term caching; (3) Proxy caches must have a capacity ceiling ( max_size) and an idle-time eviction ( inactive).
Technical Analysis: Two Independent Cache Lines
1.1 Browser Cache vs Proxy Cache
expiresand add_header Cache-Control control the browser/CDN (client-side storage duration). proxy_cache controls Nginx itself (whether to re-fetch from upstream). They are completely independent and can be combined: a single location can have "browser cache 10 minutes + proxy cache 1 hour". The most common misconception is treating proxy_cache_valid as a browser cache directive — it only affects the Nginx-to-upstream segment; the browser never sees it.
1.2 Cache-Control Directive Matrix
Five essential values:
no-store — no storage at any layer (only correct choice for sensitive data).
no-cache — may store but must revalidate on every request (304); standard for HTML entry points.
max-age=N — browser caches locally for N seconds, no request sent during that window.
s-maxage=N — applies only to shared caches (CDN/proxy), overrides max-age.
private/public — private forbids shared caches from storing (mandatory for personalized responses with cookies).
Key semantic distinction: no-cache means "ask every time", not "don't cache"; no-store means "never store". The most frequent accidents are swapping these two: writing no-cache as no-store kills performance, writing no-store as no-cache leaks sensitive data into CDNs.
1.3 Fingerprint Strategy: Correct Deploy Posture
The fix for Incident 2 is the industry-standard fingerprint approach, three rules:
Hashed resources (e.g., app.a3f9c2.js) get Cache-Control: max-age=31536000, immutable — one year plus immutable tells the browser not to send even conditional requests. index.html and route entry points get no-cache — every request revalidates; if content changed the new URL is fetched, if not a 304 is returned instantly.
Old fingerprinted files are retained for one deploy cycle (to avoid 404s during canary windows), then deleted.
Combined: deploys take effect immediately, rollback is zero-cost, cache hit rate is maximized. A quick litmus test: "Which cache is longer, the entry file or the fingerprinted file?" If the entry file's cache is longer, Incident 2's white-screen is guaranteed.
1.4 proxy_cache Key Design
Incident 1's root cause. proxy_cache_key determines which requests share a cached response; default is $scheme$proxy_host$request_uri — no request headers, no cookies . Four design principles:
Public data (product details, config) — use default key for highest hit rate.
Authenticated endpoints — either proxy_cache off or hash the Authorization / Cookie into the key (key includes identity = one cache entry per user, hit rate drops to near zero, usually not worth it).
Device/language variants — include relevant parts of $http_user_agent or $http_accept_language in the key.
Compression variants — gzipped and non-gzipped responses must never share a key; add $gzip_ratio variables or enforce uniform compression upstream.
Always ask "For whom is this response identical?" before writing the key — key design errors are the #1 source of proxy cache accidents.
1.5 proxy_cache_valid and Stale Strategies
Two-layer validity: proxy_cache_valid 200 10m; sets TTL by status code.
If upstream sends Cache-Control / Expires, Nginx honors those by default ( proxy_ignore_headers can explicitly ignore them).
More valuable is the stale strategy — "what if the cached entry is expired but upstream is down?": proxy_cache_use_stale error timeout http_500 http_503 allows serving stale content when upstream fails; proxy_cache_background_update on makes Nginx "serve old value to user, silently refresh in background". This is a lifesaver during flash sales: users get slightly stale but usable data instead of error pages. Trade-off: data is briefly stale; enable per business tolerance.
1.6 Three Static-Serving Optimizations
Biggest gains for pure static serving: sendfile on — kernel copies file data from page cache directly to socket, bypassing user-space copies (covered in Episode 01, mandatory for static serving). tcp_nopush on — works with sendfile to accumulate response header + first data chunk into one MSS, reducing small packets. open_file_cache — caches file metadata (existence, size, permissions), avoiding a stat() per request; significant CPU reduction when static directories contain many files. Caveat (expanded in Source Segment 4): metadata has a cache window — after a file is deleted, Nginx may still "find" it for a short period; deploy flows that delete files must account for this window.
Core Flows & Production-Grade Configurations
2.1 Production Config 1: Frontend Static Site
First complete config — standard SPA caching strategy embodying the fingerprint rules from 1.3:
# /etc/nginx/conf.d/frontend.conf
server {
listen 443 ssl http2;
server_name www.example.com;
root /data/web/current;
# Fingerprinted assets: 1 year + immutable
location ^~ /assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
access_log off;
}
# Entry & routes: revalidate every time
location / {
try_files $uri $uri/ /index.html;
add_header Cache-Control "no-cache, must-revalidate";
}
# Static serving trio
sendfile on;
tcp_nopush on;
open_file_cache max=10000 inactive=30s;
open_file_cache_valid 60s;
open_file_cache_min_uses 2;
open_file_cache_errors on;
}Three details worth emphasizing: /assets/ uses ^~ prefix match (previous episode's knowledge: skips regex, deterministic routing).
When expires 1y and Cache-Control are both present, the latter wins ( expires is legacy; modern standard is Cache-Control). open_file_cache_min_uses 2 — only cache after two accesses, preventing one-off files (e.g., captcha images) from polluting the cache. Deploy flow: new version published to /data/web/版本号/, then current symlink atomically switched; rollback is just switching the symlink back — instant, reversible, no cache pollution.
2.2 Production Config 2: Proxy Cache
Second complete config — proxy cache for public data APIs, covering all parameters from Incident 3:
# http block: cache zone definition
proxy_cache_path /data/nginx/cache
levels=1:2
keys_zone=api_cache:100m
max_size=10g
inactive=7d
use_temp_path=off;
server {
location /api/public/ {
proxy_pass http://api_pool;
proxy_cache api_cache;
proxy_cache_key $scheme$host$uri$is_args$args;
proxy_cache_valid 200 10m;
proxy_cache_valid 404 1m;
proxy_cache_valid any 0;
proxy_cache_use_stale error timeout http_500 http_503;
proxy_cache_background_update on;
proxy_cache_lock on;
add_header X-Cache-Status $upstream_cache_status;
proxy_set_header Host $host;
}
}Parameter breakdown: levels=1:2 — cache files split into two directory levels by key hash (avoids single directory with millions of files killing inode performance). keys_zone=api_cache:100m — shared memory index; 100 MB supports roughly one million entries. max_size=10g — disk ceiling; when exceeded the manager process evicts LRU (Incident 3's lifeline). inactive=7d — delete entries untouched for 7 days (regardless of expiry). use_temp_path=off — write temp files directly in the cache directory (same disk), avoiding cross-disk rename penalty. proxy_cache_lock on — concurrent requests for the same key: only one goes upstream, others wait (cache stampede protection; same mutex idea as Redis Episode 07, but native). X-Cache-Status — first debugging header; tells you whether the request hit or missed.
2.3 Cache Hit State Machine & Bypass Conditions
X-Cache-Statusvalues are the cache's lifecycle:
MISS — not in cache, fetch upstream and store.
HIT — fresh hit, return directly.
EXPIRED — present but stale, re-fetch upstream.
STALE — stale and upstream failed, serve old value ( use_stale active).
UPDATING — background update in progress, serving old value.
BYPASS — rule skipped cache (e.g., request carries cookie).
REVALIDATED — conditional request got 304, old entry refreshed.
Common bypass mechanism: proxy_cache_bypass $http_authorization — requests with auth header skip cache entirely (safety valve for "public API occasionally carries identity"). Companion proxy_no_cache decides whether to store the response (e.g., don't store if response has Set-Cookie).
2.4 Complete Timeline of a Cached Request
T1 Request enters, compute cache key, lookup index.
T2 Hit and not expired → read disk file, return ( HIT , never touches upstream).
T3 Miss → if proxy_cache_lock on, check if another request for same key is already fetching upstream; if yes, wait.
T4 First request fetches upstream, response written to cache (levels directories + atomic rename) per status-code TTL.
T5 Subsequent same-key requests → HIT .
T6 After expiry, request re-fetches upstream; if upstream down and use_stale configured → STALE returns old value + background update.
T7 Manager process periodically cleans per max_size / inactive.
T3's lock is the standard cache stampede solution: at the moment a hot key expires, 100 concurrent requests result in only one upstream call — isomorphic to the Redis mutex pattern from Episode 07.
2.5 Symlink Deploy: Standard Static Site Release Flow
Turn the root /data/web/current from 2.1 into a full release pipeline:
Publish new version to /data/web/版本号/ (full directory copy). ln -sfn switch current symlink (atomic, instant).
Retain old version directory for one cycle, then delete.
Three quality determinants: ln -sfn is atomic — no "half-new half-old" window; this is the fundamental difference from overwriting files in place.
Use reload not restart — after symlink switch, Nginx may have worker-level caches for static files; safe practice is nginx -s reload once.
Verify before deleting old version — confirm no edge nodes are still requesting old fingerprinted files (observe CDN side for 24h before deletion). The whole flow turns "deploy" from a high-risk operation into a three-line script: copy dir, flip symlink, reload; rollback is just flipping the symlink back.
Core Source Code: Four Critical Logic Segments
Segment 1: Cache Key to Disk Path
// 1. cache key's on-disk path
hash = md5(cache_key)
// levels=1:2:
path = cache_dir /
hash[-1] / // level 1: 1 char
hash[-3:-1] / // level 2: 2 chars
hash // filename
// Why tiered: ext4 single directory
// file count >10k causes lookup & fsck
// performance cliff; tiering spreads directory pressure
// index lives in shared memory keys_zone
// disk file contains response headers + body + metadataExplains levels purpose: cache files are not flat but distributed by MD5 tail characters — a filesystem-level "hash bucketing" sharing the same encoding philosophy as Redis Episode 02: data structure choice always serves scale. Troubleshooting tip: to locate a specific URL's cache file, compute its MD5 ( echo -n "key" | md5sum) and reconstruct the path per levels — a little-known but practical proxy cache debugging technique.
Segment 2: Hit Decision Chain
// 2. hit decision chain
on_request(key):
if cache_bypass_flag:
return BYPASS // skip without lookup
entry = zone.lookup(key)
if entry is null:
return MISS // fetch + store
if entry.expired:
if stale_ok and upstream_down:
return STALE
if bg_update and in_flight:
return UPDATING
return EXPIRED // re-fetch upstream
return HITLays out every branch of X-Cache-Status. The decision chain order is the troubleshooting order: see BYPASS → check bypass conditions; see MISS → verify key correctness; see STALE → upstream had an outage; see UPDATING → background_update is working. In production, add this header to access_log ( $upstream_cache_status variable); hit-rate dashboards aggregate from it — more accurate than any external probe.
Segment 3: proxy_cache_lock Stampede Protection
// 3. proxy_cache_lock stampede protection
on_miss(key):
if lock.try_acquire(key):
resp = fetch_upstream()
store(key, resp)
lock.release(key)
notify_all_waiters()
else:
wait(timeout=proxy_cache_lock_timeout, default 5s)
if store_done:
return HIT
else:
return fetch_upstream()
// wait timeout falls back to self-fetchHot key expiry moment concurrency protection. Difference from Redis mutex: Nginx's lock is in-process, naturally single-point, no "lock expiry" problem; waiters time out then fall back to self-fetch — a classic case where native component stampede protection is more stable than application-layer DIY. proxy_cache_lock_timeout defaults to 5s; timed-out waiters fetch themselves, so the lock doesn't guarantee "only one upstream call" but guarantees "vast majority of concurrent calls only one upstream call".
Segment 4: open_file_cache Lifecycle
// 4. open_file_cache lifecycle
on_stat(path):
e = cache.get(path)
if e and e.valid_until > now:
return e.meta // no stat
meta = stat(path)
cache.put(path, meta,
valid=60s)
// Pitfall: within valid window after file deletion
// Nginx still thinks file exists --
// whether it returns old content or 404 depends on
// open_file_cache_errors
// deploy-and-delete flows must avoid this windowSource-level explanation of the side-effect mentioned in 2.1: open_file_cache_valid 60s means file metadata can be stale for up to 60 seconds. "Deploy then delete old files" collides with this window (old HTML references deleted file, but Nginx metadata cache still thinks it exists). Fix is exactly Rule 1.3: retain old fingerprinted files for one deploy cycle, or reload after deploy (some metadata rebuilt with worker recycle). Every "valid" in cache config is a consistency window; before wiring it, ask: if a change happens inside this window, can the business tolerate it?
Advanced Topics: Five Accounts to Settle Upfront
4.1 Hit Rate Measurement & Interpretation
Proxy cache hit rate in one command: aggregate $upstream_cache_status from access_log, HIT / (HIT+MISS+EXPIRED+STALE). Interpretation matters more than calculation: a 60% hit rate cache may be worse than no cache — MISS requests pay both upstream latency and disk write, more expensive than direct proxy; 90%+ hit rate with MISS concentrated on new keys is healthy. Healthy profile: HIT dominant, EXPIRED stable/predictable (equals baseline upstream traffic), STALE near zero (appearance = upstream fault), BYPASS proportion matches business rules. Hit rate sudden drop: three main causes — key contains randomness (timestamp/traceId in key), upstream added Cache-Control: no-cache, traffic mix changed (new endpoints not cached).
4.2 Cache Purge: Open Source Reality
Open source Nginx has no native purge (active URL-based deletion is commercial feature). Four practical workarounds:
Versioned key — key includes a global version variable (controlled via map config file); bump version = entire cache expires naturally; preferred for deploy-time invalidation.
proxy_cache_bypass toggle — variable from file or map; emergency global cache bypass.
Third-party module ( ngx_cache_purge) — precise per-URL deletion; requires compiling into Nginx; suitable for low-frequency precise invalidation.
Shorten TTL and endure — compress expiry to within business-tolerable staleness window; trade "accept higher miss rate" for "deletion simplicity".
Selection rule: if invalidation is routine, use versioned key; if invalidation is rare emergency, use bypass toggle — don't incur long-term module compilation cost for rare needs.
4.3 Large Files & Range Requests
Video/large file scenario has a structural problem: default cache granularity is the whole file — user watches 30 seconds, Nginx must pull entire 2 GB before storing; Range requests (resume) are not cached by default. Solution is the slice module: add $slice_range to proxy_cache_key, slice 8m splits file into 8 MB chunks, each chunk cached independently, Range requests fetch only the needed chunk . Cost: chunk boundary header handling complexity, "full hit" becomes harder (multiple chunks must hit simultaneously), so slice only recommended for "large file + guaranteed Range access" video scenarios; ordinary downloads better served by proxy_buffering off streaming pass-through.
4.4 Static Site Security Checklist
Static serving isn't just performance; five mandatory checks: autoindex off (default off, but often enabled for debugging and forgotten — directory listing exposes all site files).
Block dotfiles — location ~ /\.. { deny all; } stops .git, .env leaks (classic source code/secret exposure).
Disable symlink escape — disable_symlinks on controls symlink targets.
Physically isolate upload directory from static directory — upload directory never configured as static, prevents uploaded executables from being parsed. Content-Type + X-Content-Type-Options: nosniff — stops browser from executing uploaded files in image directories as scripts.
Together these form the minimum security waterline for static directories.
4.5 Three High-Frequency Operational Pitfalls
Set-Cookie pollution — upstream response with Set-Cookie causes Nginx to not cache that response (good), but reverse accident: logged-in user visits public page, response carries personalized cookie, that page's cache becomes permanently invalid. Fix: on confirmed identity-independent public pages, use proxy_ignore_headers Set-Cookie selectively (with bypass conditions to prevent leakage).
Dual-header conflict — expires directive and add_header Cache-Control both present; modern browsers obey Cache-Control (HTTP/1.1) but legacy proxies may read Expires (HTTP/1.0); keep both values consistent. Production recommendation: write only Cache-Control, keep expires solely for compatibility.
gzip-cache interaction — cached gzipped version served to non-gzip client causes garbled output; either include $http_accept_encoding in cache key, or adopt simpler rule: "cache stores uncompressed version, egress compresses uniformly" — one rule eliminates a whole class of bugs.
Learning Path: From Usage to Battle-Ready
Step 1, land both configs: run 2.1/2.2 locally in Docker, use curl -I to verify Cache-Control and X-Cache-Status field by field. Step 2, reproduce the three incidents: cache an auth-required endpoint and watch leakage; delete fingerprinted file and trace white-screen chain; remove max_size and fill a small disk to observe manager behavior — pits you've personally reproduced become your pits. Step 3, read the docs: ngx_http_proxy_module cache directives and ngx_http_headers_module line by line; focus on semantic differences of bypass, no_cache, lock variables. Step 4, put up two dashboards: hit-rate report (aggregated by $upstream_cache_status) and cache disk usage (alert at 80% of max_size), turning 4.1's healthy profile into daily patrol items. After four steps, cache-related incident triage path solidifies: first check X-Cache-Status, then verify key and bypass conditions, finally inspect upstream headers ( Cache-Control / Set-Cookie / Vary) and open_file_cache window.
High-Frequency Interview Questions (with Answers)
The article includes 20 Q&A pairs covering: browser vs proxy cache difference, no-cache vs no-store, frontend deploy cache strategy, immutable purpose, why authenticated endpoints can't use proxy_cache directly, proxy_cache_path parameters, X-Cache-Status values, proxy_cache_lock problem solved, proxy_cache_use_stale value/cost, levels=1:2 design rationale, open_file_cache role/side-effect, expires vs Cache-Control conflict resolution, hit rate calculation/interpretation, open source purge methods, slice module use case, static directory security checks, Set-Cookie impact on proxy cache, gzip caching viability, 304 conditional cache mechanism, standard cache fault triage path.
One-Page Cheat Sheet
Two lines: expires / Cache-Control govern browser; proxy_cache governs Nginx; they don't substitute each other.
Semantics: no-cache =revalidate every time; no-store =never store; immutable =skip even conditional requests within max-age.
Deploy: entry no-cache + fingerprinted 1yr immutable + retain old files one cycle.
Key: ask "same for whom?" then write key; auth endpoints off or bypass; gzip versions separate keys.
Lifelines: max_size + inactive mandatory; proxy_cache_lock prevents stampede; use_stale + background_update absorbs upstream jitter.
Debug: X-Cache-Status into logs, hit-rate dashboard from it; STALE appearance = upstream fault.
Summary & Next Episode Preview
Caching's two lines each have iron laws: browser cache core is "entry short, fingerprint long"; proxy cache core is "key matches whom + has ceiling + self-heals" . Two complete configs cover all lifeline parameters from static site to proxy cache — max_size and lock seem valueless day-to-day, but when incidents strike they are the line between system and disaster. Next episode enters the final layer of traffic protection: rate limiting — limit_req and limit_conn leaky bucket algorithms, burst configuration for traffic spikes, and "how to divide responsibilities between gateway rate limiting and business rate limiting".
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
