Коли бекенд nginx перестає відповідати або повертає помилку 502 чи 504, найгрубіший результат для відвідувача — сторінка помилки замість сайту. Директива proxy_cache_use_stale дозволяє nginx у такій ситуації віддати застарілу версію сторінки з кешу замість помилки, поки бекенд не відновиться. Це не усуває причину збою, а лише продовжує життя сайту на час, поки причина усувається.
Що означає stale і чим це відрізняється від звичайного кешу
Звичайний кеш у nginx, налаштований директивами proxy_cache_valid, живе до закінчення терміну, а потім запит знову йде на бекенд за свіжою відповіддю. Якщо бекенд у цей момент недоступний, то без додаткових директив запит просто завершиться помилкою — кеш для цієї конкретної відповіді вже застарів і не використовується автоматично.
Базове налаштування зони кешу і часу життя описане у статті про proxy_cache і fastcgi_cache. proxy_cache_use_stale додається до цього налаштування і каже nginx: за перелічених умов помилки віддавай саме застарілий запис, а не код помилки.
Налаштування proxy_cache_use_stale
Директива приймає список умов, за яких використовується застарілий кеш: error — бекенд недоступний або обірвав з'єднання, timeout — не відповів за proxy_read_timeout, updating — запис уже оновлюється іншим запитом, а також конкретні коди відповіді http_500, http_502, http_503, http_504.
Умова updating особливо корисна разом з proxy_cache_lock: поки перший запит оновлює кеш, решта отримують стару версію сторінки замість того, щоб чекати у черзі чи одночасно бити по бекенду. Сам location, куди це додається, зазвичай уже існує у server-блоці, налаштованому за статтею про налаштування Nginx для сайту на VDS.
proxy_cache_path /var/cache/nginx/proxy levels=1:2 keys_zone=proxy_cache:10m max_size=1g inactive=60m use_temp_path=off;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_cache proxy_cache;
proxy_cache_valid 200 10m;
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_background_update on;
proxy_cache_lock on;
add_header X-Cache-Status $upstream_cache_status;
}
proxy_cache_background_update і фонове оновлення
Кілька директив тут працюють разом, і їх легко сплутати за назвою.
| Директива | Що робить |
|---|---|
| proxy_cache_use_stale | дозволяє віддати застарілий запис за перелічених помилок бекенду |
| proxy_cache_background_update | оновлює застарілий запис у фоні, поки клієнт отримує стару версію |
| proxy_cache_lock | не дає кільком запитам одночасно йти на бекенд за одним і тим самим записом |
| inactive | час, після якого невикористаний запис видаляється з кешу на диску |
Якщо потрібно діагностувати саме факт падіння бекенду, а не розбиратися у показаннях X-Cache-Status, то конкретні причини 502 і 504 розібрані у статті про діагностику 502 і 504.
Обмеження: скільки живе застаріла копія
proxy_cache_use_stale не продовжує життя запису нескінченно — він усе одно видаляється за директивою inactive, якщо до нього не звертаються. Якщо бекенд упав надовго, а трафіку на цю сторінку немає, застаріла копія може зникнути з кешу раніше, ніж бекенд відновиться.
Контент, що оновлюється при кожному запиті — залишок товару на складі, баланс особистого кабінету — не варто віддавати як застарілий без явного попередження користувачу: для таких сторінок надійніше взагалі не кешувати їх, ніж показувати неправильні цифри під час збою.
Чек-лист перед включенням stale-кешу
Перш ніж включати proxy_cache_use_stale у продакшені, варто звірити наступні пункти.
- Зона кешу і proxy_cache_valid уже налаштовані і перевірені у звичному режимі, без помилок бекенду.
- Для статичних і слабо змінюваних сторінок задані тривалі значення inactive, щоб застаріла копія не зникала з кешу занадто швидко.
- Включений proxy_cache_lock, щоб відновлення бекенду не зустріло лавину одночасних запитів на одну і ту саму сторінку.
- Сторінки з персональними даними і актуальними цінами виключені з цього кешу через proxy_no_cache.
- Моніторинг перевіряє значення X-Cache-Status на STALE окремо від HIT, щоб бачити, коли сайт працює на старих даних.
Часті питання
Чи бачить відвідувач, що йому показали застарілу сторінку?
Nginx не додає видимого попередження на саму сторінку — відрізнити STALE від звичного HIT можна лише за заголовком X-Cache-Status у відповіді. Якщо важливо показати користувачу попередження, його додають на рівні застосунку або через окремий банер, що перевіряє цей заголовок.
Що якщо бекенд узагалі ніколи не відповідав для цієї сторінки?
Якщо запису в кеші ще не було, proxy_cache_use_stale не допоможе — віддавати нічого. Директива працює лише з уже наявною, хоча б раз закешованою копією відповіді.
Чи потрібен proxy_cache_background_update, якщо вже включений proxy_cache_lock?
Так, це різні механізми: proxy_cache_lock обмежує кількість одночасних запитів на бекенд, а proxy_cache_background_update вирішує, хто оновлює запис — поточний клієнт, що чекає відповіді, чи окремий фоновий запит, поки решта отримують стару версію без очікування.