Перейти к содержанию

cache-purge: модуль NGINX для очистки кэша и инвалидации по тегам

Требуется тарифный план Pro (или выше) подписки GetPageSpeed NGINX Extras.

Установка

Вы можете установить этот модуль в любом дистрибутиве на основе RHEL, включая, но не ограничиваясь:

  • RedHat Enterprise Linux 7, 8, 9 и 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 и Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-cache-purge

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-cache-purge

Включите модуль, добавив следующую строку в начало файла /etc/nginx/nginx.conf:

load_module modules/ngx_http_cache_purge_module.so;

В этом документе описывается nginx-module-cache-purge v2.6.0, выпущенный 23 августа 2026 года.

Выборочная очистка содержимого кэшей FastCGI, proxy, SCGI и uWSGI в NGINX с помощью HTTP-запросов PURGE — без взлома файловой системы и проблем с правами доступа.

Эта функция присутствует в NGINX Plus, но ngx_cache_purge добавляет её в открытую версию NGINX.

Ключевые возможности

  • Очистка в том же location — добавьте поддержку PURGE непосредственно в существующие location с кэшем, без дополнительных блоков location
  • Очистка по шаблону — очистка нескольких записей кэша одним запросом с помощью *
  • Теги кэша / суррогатные ключи — инвалидация только тех объектов, чьи теги в кэшированном ответе соответствуют доверенному шаблону PURGE
  • Массовая очистка — полная очистка всего кэшированного содержимого с помощью purge_all
  • Контроль доступа на основе IP — ограничение круга лиц, которые могут отправлять запросы на очистку
  • Подстановка метода в ключе кэша — очистка GET-кэшированного содержимого, даже если $request_method присутствует в вашем ключе кэша
  • Настраиваемый формат ответа — получение результатов очистки в HTML, JSON, XML или обычном тексте
  • Все типы кэша — работает с FastCGI, proxy, SCGI и uWSGI

Быстрый старт

Добавьте поддержку PURGE в любой location с кэшем:

http {
    proxy_cache_path /var/cache/nginx keys_zone=my_cache:10m max_size=1g;

    server {
        location / {
            proxy_pass        http://127.0.0.1:8000;
            proxy_cache       my_cache;
            proxy_cache_key   "$scheme$host$request_uri";
            proxy_cache_purge PURGE from 127.0.0.1;
        }
    }
}

Очистите кэшированную страницу:

curl -X PURGE https://example.com/page-to-purge

Вот и всё. Никакого отдельного location /purge, никаких прав на файловую систему.

Директивы конфигурации

Синтаксис в том же location (рекомендуется)

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

fastcgi_cache_purge

  • синтаксис: fastcgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • по умолчанию: none
  • контекст: http, server, location

proxy_cache_purge

  • синтаксис: proxy_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • по умолчанию: none
  • контекст: http, server, location

scgi_cache_purge

  • синтаксис: scgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • по умолчанию: none
  • контекст: http, server, location

uwsgi_cache_purge

  • синтаксис: uwsgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]
  • по умолчанию: none
  • контекст: http, server, location

Синтаксис с отдельным location

Используйте выделенный location для запросов на очистку. Полезно, когда для очистки требуются другие правила доступа.

fastcgi_cache_purge

  • синтаксис: fastcgi_cache_purge zone_name key
  • контекст: location

proxy_cache_purge

  • синтаксис: proxy_cache_purge zone_name key
  • контекст: location

scgi_cache_purge

  • синтаксис: scgi_cache_purge zone_name key
  • контекст: location

uwsgi_cache_purge

  • синтаксис: uwsgi_cache_purge zone_name key
  • контекст: location

Формат ответа

cache_purge_response_type

  • синтаксис: cache_purge_response_type html|json|xml|text
  • по умолчанию: html
  • контекст: http, server, location

Пример с JSON-ответами:

location / {
    proxy_pass        http://backend;
    proxy_cache       my_cache;
    proxy_cache_key   "$uri$is_args$args";
    proxy_cache_purge PURGE from 127.0.0.1;

    cache_purge_response_type json;
}

{"Key": "httplocalhost/"}

Подстановка метода в ключе кэша

Когда $request_method является частью вашего ключа кэша, запросы на очистку генерируют другой ключ (PURGE вместо GET) и не находят кэшированную запись. Эти директивы решают эту проблему:

*_cache_purge_key_method

  • синтаксис: fastcgi_cache_purge_key_method <method> [<method> ...]
  • контекст: http, server, location

Доступно для всех типов кэша: fastcgi_cache_purge_key_method, proxy_cache_purge_key_method, scgi_cache_purge_key_method, uwsgi_cache_purge_key_method.

location ~ \.php$ {
    fastcgi_cache           WORDPRESS;
    fastcgi_cache_key       "$scheme$request_method$host$request_uri";
    fastcgi_cache_purge     PURGE from 127.0.0.1;
    fastcgi_cache_purge_key_method GET;  # Подставляет GET вместо PURGE при поиске ключа
}

Вы можете указать несколько методов:

fastcgi_cache_purge_key_method GET HEAD;

Интеграция с WordPress

FastCGI Cache + Purge

Полная настройка WordPress с кэшированием и автоматической очисткой:

http {
    fastcgi_cache_path /var/cache/nginx levels=1:2
        keys_zone=WORDPRESS:100m max_size=1g
        inactive=60m use_temp_path=off;
    fastcgi_cache_key "$scheme$host$request_uri";

    server {
        listen 80;
        server_name example.com;
        root /var/www/wordpress;
        index index.php;

        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot|webp|avif)$ {
            expires max;
            log_not_found off;
        }

        location / {
            try_files $uri $uri/ /index.php?$args;
            fastcgi_cache_purge PURGE from 127.0.0.1;
        }

        location ~ \.php$ {
            try_files $uri =404;
            fastcgi_pass unix:/run/php-fpm/www.sock;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include fastcgi_params;

            fastcgi_cache WORDPRESS;
            fastcgi_cache_valid 200 60m;
            fastcgi_cache_use_stale error timeout updating;
            fastcgi_cache_lock on;
            fastcgi_cache_purge PURGE from 127.0.0.1;

            add_header X-Cache-Status $upstream_cache_status always;
        }
    }
}

Почему fastcgi_cache_purge в обоих location? Корневой URL / — это особый случай. Когда try_files проверяет $uri/, он находит корневой каталог документа. Для GET-запросов директива index направляет запрос на index.php — но для PURGE-запросов index не применяется, и NGINX останавливается на location /. Добавление fastcgi_cache_purge туда гарантирует, что PURGE / будет работать.

Плагин очистки прокси-кэша

Установите плагин Proxy Cache Purge для автоматической очистки кэша при обновлении содержимого:

wp plugin install varnish-http-purge --activate
wp option update vhp_varnish_ip '127.0.0.1'

Плагин отправляет запросы PURGE в NGINX при изменении записей, комментариев или страниц — ручное управление кэшем не требуется.

Рекомендации по ключам кэша

Держите ключи простыми — избегайте $request_method в ключах

## Рекомендуется
fastcgi_cache_key "$scheme$host$request_uri";

## Избегайте — запросы на очистку не совпадут с кэшированными GET-записями
fastcgi_cache_key "$scheme$request_method$host$request_uri";

Если вам обязательно нужно включить $request_method, используйте *_cache_purge_key_method GET, чтобы исправить поиск ключей при очистке.

Очистка по шаблону

Очистите несколько записей, соответствующих шаблону, добавив *:

curl -X PURGE https://example.com/blog/*

Звёздочка должна быть последним символом. Для работы этой функции $uri должен находиться в конце вашего ключа кэша.

Теги кэша / суррогатные ключи

cache_purge_tags связывает заголовок тега, хранящийся в кэшированных ответах вышестоящего сервера, с регулярным выражением из заголовка авторизованного PURGE-запроса:

location / {
    proxy_pass         http://backend;
    proxy_cache        app_cache;
    proxy_cache_key    "$scheme$host$request_uri";

    proxy_cache_purge  PURGE from 127.0.0.1;
    cache_purge_tags   X-Magento-Tags X-Magento-Tags-Pattern;
}
  • синтаксис: cache_purge_tags <cached-response-header> <purge-pattern-header>
  • по умолчанию: off
  • контекст: http, server, location

Для Magento Open Source и Adobe Commerce не требуется изменений в приложении. Magento уже добавляет X-Magento-Tags в кэшируемые ответы и отправляет доверенные локальные PURGE-запросы с X-Magento-Tags-Pattern. Модуль сканирует ту же зону кэша и удаляет только соответствующие объекты. Шаблон тега имеет приоритет над поведением точного ключа, шаблона и purge_all для этого запроса.

Заголовок тега ответа может быть скрыт от клиентов с помощью proxy_hide_header. Он остаётся доступным в метаданных кэша NGINX на диске для инвалидации. Некорректное регулярное выражение возвращает HTTP 400; корректный шаблон без совпадений возвращает HTTP 200, что соответствует сгенерированному VCL Varnish от Magento.

Инвалидация по тегам сканирует метаданные заголовков кэша только при поступлении PURGE-запроса. Обычные попадания в кэш не несут накладных расходов на индекс тегов, но время очистки растёт с количеством файлов в зоне кэша. Это заменяет постоянный список запретов Varnish немедленным удалением соответствующих объектов NGINX.

Интеграции тегов кэша WordPress могут использовать ту же директиву со своими именами заголовков:

cache_purge_tags X-Cache-Tags X-Cache-Tags-Pattern;

Массовая очистка

Очистите все кэшированные файлы сразу:

proxy_cache_purge PURGE purge_all from 127.0.0.1;

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

Контроль доступа на основе IP

Ограничьте запросы на очистку доверенными источниками:

fastcgi_cache_purge PURGE from 127.0.0.1 192.168.1.0/24;

Устранение неполадок

Ответ Причина Исправление
405 Not Allowed PURGE попал в location без *_cache_purge Добавьте *_cache_purge во все соответствующие location
412 Precondition Failed Запись кэша не найдена (никогда не кэшировалась, уже истекла или несовпадение ключа) Проверьте ключ кэша — обратите внимание на проблемы с $request_method
403 Forbidden IP-адрес клиента отсутствует в списке from Добавьте свой IP в from
200 OK, но кэш сохраняется $request_method в ключе кэша создаёт несовпадающие ключи Удалите $request_method из ключа или добавьте *_cache_purge_key_method GET

Взаимодействие с gzip_vary: Включение gzip_vary может мешать очистке кэша. Если вы испытываете нестабильное поведение очистки, отключите gzip_vary внутри location с кэшем.

Тестирование

ngx_cache_purge включает набор тестов на основе Test::Nginx:

prove

См. также