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
| Layer | Cache key | Lifetime | Configured in |
|---|---|---|---|
| Browser | Full URL | 7 days (Cache-Control: public, max-age=604800 plus Expires) | GetFromPath headers; Nginx adds the same value |
| Cloudflare Worker | Origin URL plus full query string | 7 days (max-age=604800) | worker/index.js |
| Nginx | Default proxy_cache key (includes query) | 7 days for 200 / 301 / 302 / 304, 1 minute otherwise; evicted after 30 days without access; 2 GB cap | config/nginx/nodes.conf |
| Local cache file | Filename built from parameters (below) | No expiry, never cleaned automatically | GetFileCachePath() |
Local Cache File Naming
Cache files live in
storage/image/cache/, mirroring upload/. The original extension is stripped and the parameters are appended:| Parameters | Filename 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]- 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]
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.