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

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.5.10, выпущенный 25 марта 2026 года.

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

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

Ключевые особенности

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

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

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

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

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

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

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

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

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

Синтаксис отдельного местоположения

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

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 в обоих местоположениях? Корневой 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 должен находиться в конце вашего ключа кэша.

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

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

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 попал в местоположение без *_cache_purge Добавьте *_cache_purge во все соответствующие местоположения
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 внутри кэшированного местоположения.

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

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

prove

См. также