Caching Layers

Last updated


This page explains the cache key, lifetime, and invalidation of each of the four cache layers an image passes through.

The Four Layers


LayerCache keyLifetimeConfigured in
BrowserFull URL7 days (Cache-Control: public, max-age=604800)Nginx /c/img/ block and the Cloudflare Worker; Express itself does not send this header
Cloudflare WorkerOrigin URL plus query string, with an X-Custom-Cache-Key header7 daysworker/index.js
NginxDefault proxy_cache key (includes query)7 days for 200 / 301 / 302 / 304, 1 minute otherwise; evicted after 30 idle days; 2 GB capconfig/nginx/nodejs.conf
Local cache fileFilename built from parameters (below)No expiryGetFromPath.ts

Local Cache File Naming


Cache files live in storage/image/cache/, mirroring upload/. The original extension is stripped and the parameters are appended:
ParametersFilename pattern
s present{name}_{s}_{q}.{t}
w and h{name}_{w}_{h}_{q}.{t}
Only w{name}_{w}_auto_{q}.{t}
Only h{name}_auto_{h}_{q}.{t}
None{name}_auto_auto_{q}.{t}

?w=800 yields {name}_800_auto_.webp (quality is empty when not given). {t} is the normalized format (jpeg → jpg, invalid values → webp).

Lookup Order


graph TB
    A[Request /c/img/...] --> B{.pdf / .svg?}
    B -->|Yes| C[Stream original, no cache]
    B -->|No| D{o = 1?}
    D -->|Yes| E[Stream original, no cache]
    D -->|No| F{Cache file exists?}
    F -->|Yes| G[Return cache file]
    F -->|No| H[sharp convert → respond → write cache file]
  1. graph TB
  2. A[Request /c/img/...] --> B{.pdf / .svg?}
  3. B -->|Yes| C[Stream original, no cache]
  4. B -->|No| D{o = 1?}
  5. D -->|Yes| E[Stream original, no cache]
  6. D -->|No| F{Cache file exists?}
  7. F -->|Yes| G[Return cache file]
  8. F -->|No| H[sharp convert → respond → write cache file]

Invalidation and Purging


SituationResult
An original is overwritten under the same nameCannot happen: upload filenames are a random string plus timestamp
Purge the local cacheDelete the matching directory under storage/image/cache/
Purge the Nginx cacheDelete /var/cache/nginx/images in the container and reload Nginx
Purge the Cloudflare cachePurge from the Cloudflare Dashboard


中文