Nginx proxy_cache_path: кешировать ответы бэкенда

proxy_cache_path задаёт каталог и зону разделяемой памяти для кеша ответов upstream. В связке с proxy_cache Nginx сохраняет ответы на диск и отдаёт повторные запросы без обращения к приложению. Это снижает нагрузку на бэкенд, но требует аккуратной настройки ключа и запрета кеширования персональных данных.

Включить кеш для API

upstream api_backend {
    server 127.0.0.1:9002;
}

proxy_cache_path /var/cache/nginx/api
    levels=1:2
    keys_zone=api_cache:10m
    max_size=1g
    inactive=10m
    use_temp_path=off;

server {
    listen 80;

    location /api/ {
        proxy_cache api_cache;
        proxy_cache_key "$scheme$request_method$host$request_uri";
        proxy_cache_valid 200 302 60s;
        proxy_cache_valid 404 10s;
        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
        proxy_cache_background_update on;
        proxy_cache_lock on;

        proxy_cache_bypass $http_authorization $cookie_session;
        proxy_no_cache $http_authorization $cookie_session;

        add_header X-Cache-Status $upstream_cache_status always;
        proxy_pass http://api_backend;
    }
}

proxy_cache_path должен находиться в контексте http. keys_zone хранит ключи и метаданные в памяти, max_size ограничивает диск, а inactive удаляет записи, к которым не обращались указанное время. levels=1:2 разбивает файлы по подкаталогам, чтобы не держать миллионы файлов в одной папке.

proxy_cache_valid задаёт время жизни для статусов, если upstream не прислал Cache-Control или Expires. proxy_cache_use_stale отдаёт устаревший ответ при ошибке или обновлении, а proxy_cache_lock не даёт толпе запросов одновременно обновлять одну запись. X-Cache-Status показывает MISS, HIT, EXPIRED, STALE, UPDATING или BYPASS.

Не кешируйте ответы с авторизацией, cookie и персональными данными: добавьте proxy_cache_bypass и proxy_no_cache, как в примере. Ключ должен учитывать всё, что влияет на ответ: хост, язык, версию API. Иначе пользователь получит чужой ответ. Для очистки кеша в open-source Nginx нет встроенной команды purge; используйте версионирование URL или сторонний модуль.

Каталог кеша должен быть доступен пользователю, от которого работает Nginx. После изменения конфигурации проверьте nginx -t и перезагрузите сервис. Следите за размером max_size и местом на диске: переполнение кеша может привести к ошибкам записи и 500.

Документация: ngx_http_proxy_module: proxy_cache_path, guide to caching.