Директивы кеширования Nginx: полная шпаргалка для proxy_cache и fastcgi_cache

Эта шпаргалка предоставляет DevOps инженерам и системным администраторам готовые, проверенные конфигурации и полное понимание логики работы кеша в Nginx. Вы получите конкретные блоки кода для модулей ngx_http_proxy_module и ngx_http_fastcgi_module, которые можно сразу внедрить в production. Мы детально разберем каждую ключевую директиву, от создания хранилища до управления сроком жизни и инвалидации кеша. Материал структурирован так, чтобы вы быстро находили ответы на вопросы: почему запрос не кешируется, как очистить кеш для конкретной страницы и как избежать перегрузки бэкенда при высокой нагрузке.

Все примеры основаны на практике работы с высоконагруженными проектами и учитывают актуальные особенности Nginx. Вы научитесь не только настраивать кеш, но и диагностировать его работу, понимая внутренние алгоритмы принятия решений.

Основы и подготовка: создание и настройка кеша

Кеширование в Nginx реализуется через два основных модуля: proxy_cache для проксированных запросов (например, к API или другому веб-серверу) и fastcgi_cache для приложений, работающих через FastCGI (например, PHP-FPM). Разница заключается в точке применения: proxy_cache работает с ответами от upstream-сервера, а fastcgi_cache - с ответами от FastCGI-процесса. Конфигурационные директивы для них аналогичны, но имеют разные префиксы (proxy_ и fastcgi_).

Базовый пример: кеширование проксированных запросов (proxy_cache)

Этот шаблон позволяет быстро настроить кеширование ответов от бэкенда. Конфигурация задается в контексте http для определения зоны кеша и в location для его применения.

http {
    # Определение зоны кеша и его хранилища на диске
    proxy_cache_path /var/cache/nginx/proxy levels=1:2 keys_zone=backend_cache:10m max_size=1g inactive=60m use_temp_path=off;

    server {
        listen 80;
        server_name example.com;

        location /api/ {
            proxy_pass http://backend_server;
            # Использование созданной зоны кеша
            proxy_cache backend_cache;
            # Формирование ключа кеша на основе метода, URI и заголовка Authorization
            proxy_cache_key "$scheme$request_method$uri$http_authorization";
            # Кеширование успешных ответов (200, 302) на 10 минут
            proxy_cache_valid 200 302 10m;
            # Добавление заголовка для диагностики статуса кеша
            add_header X-Cache-Status $upstream_cache_status;
        }
    }
}

Ключевые директивы в этом примере:

• proxy_cache_path: задает физический путь на диске, структуру каталогов (levels), имя и размер зоны в памяти (keys_zone), максимальный размер кеша (max_size) и время, после которого неиспользуемый файл удаляется (inactive).
• proxy_cache: указывает, какая зона кеша используется для этого location.
• proxy_cache_key: определяет уникальный ключ для каждого кешируемого ответа. Ключ формируется из переменных запроса.
• proxy_cache_valid: устанавливает время жизни кеша для разных кодов ответа.

Базовый пример: кеширование FastCGI (например, PHP через php-fpm)

Конфигурация для кеширования ответов от PHP или других FastCGI приложений структурно похожа на proxy_cache, но использует соответствующий набор директив.

http {
    fastcgi_cache_path /var/cache/nginx/fastcgi levels=1:2 keys_zone=php_cache:10m max_size=1g inactive=60m use_temp_path=off;

    server {
        listen 80;
        server_name example.com;

        location ~ \.php$ {
            fastcgi_pass php_fpm_backend;
            fastcgi_cache php_cache;
            fastcgi_cache_key "$scheme$request_method$uri$query_string";
            fastcgi_cache_valid 200 10m;
            add_header X-Cache-Status $upstream_cache_status;
        }
    }
}

Основное отличие - использование fastcgi_cache_key, где часто включается $query_string, чтобы кешировать ответы для разных GET-параметров. Для тонкой настройки кеширования динамического контента, например, AJAX-запросов, можно использовать готовые конфигурации из нашего руководства по динамической загрузке контента и кешированию в Nginx.

Директива proxy_cache_path / fastcgi_cache_path: тонкая настройка хранилища

Эта директива определяет, как кеш хранится на диске. Правильная настройка параметров критична для производительности и управления пространством.

Для проектов с очень интенсивным чтением кеша можно рассмотреть двухуровневую архитектуру с RAM-диском, как описано в статье о тонкой настройке кеша Nginx для высоких нагрузок.

Логика принятия решений: когда кешировать, отдавать или обходить

Nginx выполняет последовательность проверок для каждого запроса, чтобы определить действие с кешем. Понимание этого алгоритма позволяет диагностировать проблемы и точно конфигурировать поведение.

Алгоритм кеширования Nginx: от запроса до ответа

Для каждого запроса, попадающего в location с активным кешем, Nginx выполняет следующие шаги:

1. Проверка обхода (bypass): вычисляются условия директив proxy_cache_bypass или fastcgi_cache_bypass. Если условие истинно, кеш игнорируется, запрос отправляется к бэкенду, но ответ может быть кеширован.
2. Проверка запрета кеширования (no_cache): вычисляются условия директив proxy_no_cache или fastcgi_no_cache. Если условие истинно, ответ от бэкенда не будет сохранен в кеш.
3. Проверка методов запроса: если метод запроса не включен в список proxy_cache_methods (по умолчанию GET и HEAD), кеширование не происходит.
4. Генерация ключа кеша: вычисляется значение по директиве proxy_cache_key или fastcgi_cache_key.
5. Поиск в кеше: Nginx проверяет, существует ли в зоне кеша объект с этим ключом.
6. Если MISS (нет в кеше): запрос передается бэкенду. После получения ответа проверяется, можно его кешировать (код ответа, наличие заголовка Cache-Control: no-store и т.д.). Если условия соблюдены, ответ сохраняется.
7. Если HIT (кеш найден): проверяется срок жизни объекта. Если кеш свежий, он отдается клиенту. Если устарел, проверяется директива proxy_cache_use_stale. Если она разрешает отдавать устаревший кеш (например, при ошибке бэкенда), он отдается. Если не разрешает, запрос идет к бэкенду для обновления.
8. Если UPDATING (кеш обновляется): когда другой запрос уже начал обновлять устаревший кеш, текущий запрос может получить устаревший кеш, если proxy_cache_use_stale updating установлено.

Директивы условного обхода (bypass) и запрета кеширования (no_cache)

Директивы proxy_cache_bypass и proxy_no_cache принимают строку параметров, которая может содержать переменные. Если хотя бы один параметр не пустой и не равен «0», условие считается истинным.

location /api/ {
    proxy_pass http://backend;
    proxy_cache backend_cache;
    # Обойти кеш, если в запросе есть параметр edit или установлена сессия
    proxy_cache_bypass $cookie_session $arg_edit;
    # Не кешировать ответы, если запрос содержит заголовок Authorization
    proxy_no_cache $http_authorization;
}

Разница между директивами важна:

• proxy_cache_bypass: запрос всегда отправляется к бэкенду, минуя проверку кеша. Однако ответ от бэкенда может быть кеширован для будущих запросов.
• proxy_no_cache: ответ от бэкенда никогда не сохраняется в кеш, независимо от других условий. Но если в кеше уже есть свежий ответ для этого ключа, он может быть отдан клиенту.

Это позволяет, например, отправлять запросы авторизованных пользователей напрямую к бэкенду, но все же кешировать публичные ответы.

Директивы использования устаревшего кеша (use_stale)

Директива proxy_cache_use_stale повышает отказоустойчивость сервиса, разрешая отдавать устаревший кеш при определенных проблемах с бэкендом.

proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;

Параметры директивы:

• error: использовать устаревший кеш при любой ошибке связи с бэкендом.
• timeout: использовать при timeout запроса к бэкенду.
• updating: использовать устаревший кеш, когда другой запрос уже обновляет его.
• http_500, http_502, ...: использовать устаревший кеш, если бэкенд вернул указанный код ошибки.

Аналогичная директива для FastCGI - fastcgi_cache_use_stale. Эта настройка позволяет сервису оставаться доступным даже при временной недоступности или высокой нагрузке на backend-серверы.

Контроль жизненного цикла кеша и инвалидация

Управление сроком жизни кешированных объектов и их принудительное удаление - ключевые задачи для поддержания актуальности данных.

Управление сроком жизни: proxy_cache_valid и заголовки ответа

Директива proxy_cache_valid задает время жизни кеша для разных кодов ответа в конфигурации Nginx.

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
proxy_cache_valid any 5m;

Приоритет управления TTL (Time To Live):

1. Заголовок X-Accel-Expires: отправленный бэкендом, имеет наивысший приоритет. Значение 0 означает «не кешировать», отрицательное - «кешировать бесконечно».
2. Заголовок Cache-Control с параметрами max-age или s-maxage: также переопределяет proxy_cache_valid.
3. Директива proxy_cache_valid: применяется, если заголовки от бэкенда не задают TTL.

Пример заголовка от бэкенда (например, PHP-приложения):

header('X-Accel-Expires: 3600'); // Кешировать на 1 час

Это дает бэкенду полный контроль над кешированием конкретных ответов. Для комплексной настройки кеширования в сложных сценариях, таких как REST или GraphQL API, обратитесь к нашему практическому руководству по кешированию GraphQL и REST API в Nginx.

Очистка кеша (Purge) и условная инвалидация

Стандартный Nginx не включает функцию принудительного удаления (purge) объектов из кеша. Для этого требуется дополнительный модуль, например, ngx_cache_purge, или сторонние решения.

location ~ /purge(/.*) {
    allow 127.0.0.1;
    allow 10.0.0.0/8;
    deny all;
    proxy_cache_purge backend_cache $scheme$request_method$host$1;
}

Запрос PURGE к URL, соответствующему этому location, удаляет объект из указанной зоны кеша. Ключ для удаления формируется аналогично proxy_cache_key.

Альтернативный метод без специального модуля - использование proxy_cache_bypass с уникальным ключом. Например, можно отправлять запрос с специальным параметром, который обходит кеш и вызывает обновление данных от бэкенда:

proxy_cache_bypass $arg_purge;

Запрос /api/data?purge=1 обойдет кеш и получит свежий ответ от бэкенда, который затем будет сохранен с новым TTL.

Оптимизация для высоких нагрузок и диагностика

Для production-сред с высокой частотой запросов существуют директивы, которые снижают нагрузку на бэкенд и повышают актуальность данных.

Директивы для снижения нагрузки и повышения актуальности

• proxy_cache_lock: при включении этой директивы (proxy_cache_lock on;) Nginx предотвращает одновременные запросы к бэкенду для одного ключа кеша, если кеш отсутствует или устарел. Первый запрос получает «lock» и идет к бэкенду, остальные ожидают его завершения или timeout. Это защищает бэкенд от «cache stampede» (лавины запросов при очистке кеша).
• proxy_cache_revalidate: директива (proxy_cache_revalidate on;) позволяет Nginx отправлять к бэкенду условные запросы (с заголовками If-Modified-Since или If-None-Match) для обновления устаревшего кеша, вместо полного повторного получения ресурса. Это экономит трафик и снижает нагрузку, если бэкенд поддерживает эти заголовки.
• fastcgi_cache_background_update: специфичная для FastCGI директива (fastcgi_cache_background_update on;) позволяет Nginx сразу отдать клиенту устаревший кеш, а затем в фоновом режиме обновить его новым ответом от бэкенда. Это улучшает воспринимаемую скорость ответа.

Эти оптимизации особенно важны для высоконагруженных API и веб-приложений. При работе с большими объемами данных также стоит учитывать настройки файловой системы и лимиты, подробно рассмотренные в статье о оптимизации загрузки больших файлов в Nginx.

Мониторинг и отладка: статус кеша в заголовках ответа

Самым простым способом диагностики работы кеша является добавление в ответ специального заголовка, показывающего его статус.

add_header X-Cache-Status $upstream_cache_status;

Значение переменной $upstream_cache_status раскрывает, что произошло с запросом:

Анализ этого заголовка в инструментах мониторинга или непосредственно в браузере позволяет оценить эффективность кеширования и выявить проблемы конфигурации.

Справочник: синтаксис, контекст и значения по умолчанию

Эта таблица служит кратким справочником по всем рассмотренным директивам. Она помогает быстро определить, где можно использовать директиву и каково ее поведение без явной настройки.

Эта шпаргалка охватывает ключевые директивы для эффективного управления кешем в Nginx. Для построения комплексной конфигурации сервера, включающей не только кеширование, но и балансировку, безопасность и обработку ошибок, используйте наш полный разбор структуры nginx.conf с практическими примерами настроек. Если вам требуется унифицированный доступ к множеству моделей искусственного интеллекта для автоматизации рабочих задач, рассмотрите сервис AiTunnel. Он агрегирует API более 200 нейросетей, включая GPT, Gemini и Claude, и позволяет интегрировать их без необходимости использования VPN, с оплатой в рублях и управлением бюджетами.