Caching Layers

Last updated


This page explains the cache key, lifetime, and invalidation of each of the four layers an image passes through: browser, Cloudflare Worker, Nginx, and local cache files.

The Four Layers


LayerCache keyLifetimeConfigured in
BrowserFull URL7 days (Cache-Control: public, max-age=604800 plus Expires)GetFromPath headers; Nginx adds the same value
Cloudflare WorkerOrigin URL plus full query string7 days (max-age=604800)worker/index.js
NginxDefault proxy_cache key (includes query)7 days for 200 / 301 / 302 / 304, 1 minute otherwise; evicted after 30 days without access; 2 GB capconfig/nginx/nodes.conf
Local cache fileFilename built from parameters (below)No expiry, never cleaned automaticallyGetFileCachePath()

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}_{b}_{B}.{t}
w and h{name}_{w}_{h}_{q}_{b}_{B}.{t}
Only w{name}_{w}_auto_{q}_{b}_{B}.{t}
Only h{name}_auto_{h}_{q}_{b}_{B}.{t}
None{name}_auto_auto_{q}_{b}_{B}.{t}

Each segment except t uses the raw request string, unnormalized (t is normalized first: jpeg becomes jpg, empty or unsupported becomes webp): ?s=480&t=avif yields {name}_480___1.avif (q and b are empty, B defaults to 1), while ?s=480&t=avif&q=50 produces identical output but a separate cache file.

Lookup Order


graph LR
    Req[Request] --> B{Browser fresh?}
    B -- No --> W{Worker hit?}
    W -- No --> N{Nginx hit?}
    N -- No --> L{Local cache file exists?}
    L -- No --> V[libvips transform and write cache file]
  1. graph LR
  2. Req[Request] --> B{Browser fresh?}
  3. B -- No --> W{Worker hit?}
  4. W -- No --> N{Nginx hit?}
  5. N -- No --> L{Local cache file exists?}
  6. L -- No --> V[libvips transform and write cache file]

Requests that bypass the Worker go from the browser straight to Nginx. .pdf, .svg, and o=1 never write a local cache file and are cached only by the first three layers.

Invalidation


The code has no cache purge. Deleting an original only moves the file in upload/ to the trash; transformed results in cache/ remain, and GetFromPath checks the cache file before the original, so existing size variants of a deleted image keep being served. To take an image down immediately, delete the matching files under storage/image/cache/ and purge both the Nginx cache at /var/cache/nginx/images and the Cloudflare cache.
中文