Точечная очистка кэша Nginx: URL, regex и автоматизация | AdminWiki
Logo

Точечная очистка кэша Nginx: URL, regex и автоматизация

20 августа 2026 9 мин. чтения
Содержание статьи

Точечная очистка кэша Nginx решает задачу обновления отдельных страниц без полного сброса. Вы отправляете PURGE-запрос на конкретный URL или группу URL, и Nginx удаляет только эти записи из зоны кэша. Остальной кэш продолжает работать, нагрузка на бэкенд не возрастает.

Для этого используется модуль ngx_cache_purge. Он добавляет директиву proxy_cache_purge, которая принимает зону кэша и ключ. Ключ должен точно совпадать с тем, что сформировал proxy_cache_key при сохранении ответа. Если ключи разойдутся, очистка пройдёт, но запись останется в кэше.

В этой статье разберём установку модуля, настройку ключей с переменными, очистку по одному URL и регулярным выражениям, автоматизацию скриптами на Python и PHP, а также диагностику типичных ошибок.

Зачем нужна точечная очистка кэша Nginx

Полный сброс кэша приводит к тому, что все страницы одновременно запрашиваются с бэкенда. Для интернет-магазина с 50 000 карточек товаров это означает резкий скачок нагрузки на базу данных и приложение. Точечная инвалидация обновляет только изменённый ресурс: одна карточка товара, одна новость, одна ветка форума. Остальные страницы отдаются из кэша.

Nginx из коробки не предоставляет механизма выборочной очистки. Стандартные методы - ручное удаление файлов из директории кэша или полный сброс через proxy_cache_bypass - неудобны для точечных задач. Модуль ngx_cache_purge закрывает этот пробел.

Типичные сценарии, где нужна точечная очистка:

  • Обновление цены или остатков на карточке товара.
  • Публикация новой статьи в разделе новостного портала.
  • Добавление нового сообщения в ветку форума.
  • Изменение шаблона страницы без изменения остального сайта.

Если вы ещё не настраивали базовое кэширование, начните с полной настройки proxy_cache в Nginx. Там разобраны TTL, зоны памяти и мониторинг хитрейта.

Установка и настройка модуля ngx_cache_purge

Модуль ngx_cache_purge не входит в стандартную поставку Nginx. Есть два пути: собрать Nginx из исходников с параметром --add-module или установить готовый пакет из репозитория.

Компиляция Nginx с модулем ngx_cache_purge

Для сборки из исходников скачайте исходники Nginx и модуль, затем выполните configure с указанием пути к модулю:

# Скачиваем исходники Nginx
wget http://nginx.org/download/nginx-1.26.2.tar.gz
tar -xzf nginx-1.26.2.tar.gz

# Скачиваем модуль ngx_cache_purge
git clone https://github.com/nginx-modules/ngx_cache_purge.git

# Конфигурируем сборку
cd nginx-1.26.2
./configure --add-module=../ngx_cache_purge --with-http_ssl_module --with-http_realip_module

# Собираем и устанавливаем
make
sudo make install

После установки проверьте, что модуль подключён:

nginx -V 2>&1 | grep -o cache_purge

Если команда вывела cache_purge, модуль активен. Перезапустите Nginx:

sudo systemctl restart nginx

Для Debian и Ubuntu можно установить пакет nginx-extras, который включает ngx_cache_purge:

sudo apt update
sudo apt install nginx-extras

После установки проверьте версию и наличие модуля той же командой nginx -V.

Базовая конфигурация для очистки кэша

Минимальная рабочая конфигурация выглядит так:

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

    server {
        listen 80;
        server_name example.com;

        location / {
            proxy_pass http://backend;
            proxy_cache my_cache;
            proxy_cache_key "$scheme$host$request_uri";
            proxy_cache_valid 200 10m;
        }

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

Разберём ключевые директивы:

  • proxy_cache_path определяет зону кэша my_cache с размером 10 МБ для хранения ключей.
  • proxy_cache_key задаёт шаблон ключа. Здесь это схема, хост и URI запроса.
  • location ~ /purge(/.*) перехватывает запросы на очистку. Регулярное выражение захватывает часть после /purge/ в переменную $1.
  • proxy_cache_purge my_cache $scheme$host$1 удаляет запись с ключом, собранным из схемы, хоста и захваченного URI.
  • allow 127.0.0.1; deny all; ограничивает доступ к очистке только с localhost.

Для очистки страницы /product/123 отправьте запрос:

curl -X PURGE http://example.com/purge/product/123

Модуль сформирует ключ http://example.com/product/123 и удалит соответствующую запись из зоны my_cache.

Настройка ключей кэширования с переменными

Ключ кэша определяет, под каким идентификатором хранится ответ. По умолчанию Nginx использует строку вида $scheme$proxy_host$request_uri. Директива proxy_cache_key позволяет изменить состав ключа, добавив переменные.

Правильный ключ критичен для точечной очистки. Если при сохранении ответа ключ был $scheme$host$request_uri$args, а при очистке вы передадите только $scheme$host$request_uri, запись не удалится. Ключи должны совпадать байт в байт.

Примеры proxy_cache_key для разных сценариев

Кэширование страниц с пагинацией и параметрами запроса:

proxy_cache_key "$scheme$host$request_uri$args";

Кэширование с учётом куки пользователя, например для персонализированных страниц:

proxy_cache_key "$scheme$host$request_uri$cookie_user";

Кэширование отдельно для мобильных и десктопных устройств:

set $is_mobile "";
if ($http_user_agent ~* "(android|iphone|ipad)") {
    set $is_mobile "mobile";
}
proxy_cache_key "$scheme$host$request_uri$is_mobile";

При изменении proxy_cache_key нужно обновить и location для очистки. Если ключ включает $args, запрос на очистку должен передавать те же параметры:

location ~ /purge(/.*) {
    allow 127.0.0.1;
    deny all;
    proxy_cache_purge my_cache $scheme$host$1$args;
}

Теперь очистка /product/123?color=red удалит только кэш для этого варианта страницы, а не для всех вариантов товара.

Очистка кэша по URL и регулярным выражениям

Модуль ngx_cache_purge поддерживает два режима: очистку одного URL и массовую очистку по шаблону. Выбор зависит от задачи.

Очистка одного URL

Для одиночной страницы используйте простой location с захватом URI:

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

Запрос на очистку:

curl -X PURGE http://example.com/purge/product/123

Ответ 200 с заголовком X-Cache-Purge: 1 означает, что запись удалена. Ответ 404 означает, что записи с таким ключом не было в кэше.

Очистка по регулярному выражению

Для массовой очистки раздела используйте регулярное выражение в location. Пример для новостного портала, где нужно сбросить все страницы раздела /news/:

location ~ ^/purge(/news/.*) {
    allow 127.0.0.1;
    deny all;
    proxy_cache_purge my_cache $scheme$host$1;
}

Запрос:

curl -X PURGE http://example.com/purge/news/

Этот запрос удалит все записи, ключи которых начинаются с http://example.com/news/. Обратите внимание: регулярное выражение должно точно соответствовать структуре ключа. Если ключ содержит $args, в шаблоне очистки нужно учесть и параметры.

Риски широких регулярных выражений: шаблон /purge(/.*) удалит весь кэш сайта, если отправить запрос на /purge/. Ограничивайте доступ к location очистки и проверяйте шаблоны перед применением в production.

Автоматизация очистки кэша скриптами

Ручная очистка через curl подходит для разовых задач. В production очистку встраивают в процессы обновления контента: сработал хук в CMS, обновился товар в админке, прошёл деплой. Для этого пишут скрипты на Python или PHP.

Скрипт на Python для очистки кэша

Python-скрипт с использованием библиотеки requests:

import requests

def purge_url(host, path):
    """Отправляет PURGE-запрос на очистку кэша."""
    url = f"http://{host}/purge{path}"
    try:
        response = requests.request("PURGE", url, timeout=5)
        if response.status_code == 200:
            print(f"OK: {path} очищен")
            return True
        elif response.status_code == 404:
            print(f"SKIP: {path} не найден в кэше")
            return False
        else:
            print(f"ERROR: {path} код {response.status_code}")
            return False
    except requests.exceptions.RequestException as e:
        print(f"FAIL: {path} ошибка {e}")
        return False

# Пример: очистка списка URL
urls = [
    "/product/123",
    "/product/456",
    "/category/electronics",
]

for path in urls:
    purge_url("example.com", path)

Скрипт принимает хост и путь, отправляет PURGE-запрос и обрабатывает ответ. Для списка URL просто перебираете массив. Интеграция с CI/CD: вызывайте скрипт после деплоя, передавая пути изменённых страниц.

Скрипт на PHP для очистки кэша

PHP-скрипт с использованием cURL:

<?php
function purgeCache($host, $path) {
    $url = "http://{$host}/purge{$path}";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PURGE");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 5);
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode == 200) {
        echo "OK: {$path} очищен\n";
        return true;
    } elseif ($httpCode == 404) {
        echo "SKIP: {$path} не найден в кэше\n";
        return false;
    } else {
        echo "ERROR: {$path} код {$httpCode}\n";
        return false;
    }
}

// Вызов из CMS при обновлении записи
purgeCache("example.com", "/product/123");
?>

Этот скрипт можно вызвать из хука CMS: после сохранения товара или статьи передайте URL изменённой страницы. Для WordPress, например, хук save_post формирует путь и вызывает purgeCache.

Если вам нужна автоматизация очистки по расписанию, посмотрите руководство по настройке cron-задач для очистки кэша Nginx.

Примеры для интернет-магазинов, новостных порталов и форумов

Три типовых сценария покрывают большинство задач точечной инвалидации.

Очистка карточки товара в интернет-магазине

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

Конфигурация Nginx:

location / {
    proxy_pass http://backend;
    proxy_cache my_cache;
    proxy_cache_key "$scheme$host$request_uri";
    proxy_cache_valid 200 30m;
}

location ~ /purge(/product/.*) {
    allow 127.0.0.1;
    deny all;
    proxy_cache_purge my_cache $scheme$host$1;
}

Очистка:

curl -X PURGE http://shop.example.com/purge/product/123

Автоматизация: в админке магазина после сохранения товара вызывайте скрипт purge_url("shop.example.com", "/product/123"). Кэш карточки обновится, каталог и корзина продолжат отдаваться из кэша.

Сброс кэша раздела новостного портала

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

Конфигурация с регулярным выражением для раздела:

location ~ ^/purge(/news/.*) {
    allow 127.0.0.1;
    deny all;
    proxy_cache_purge my_cache $scheme$host$1;
}

location ~ ^/purge(/$) {
    allow 127.0.0.1;
    deny all;
    proxy_cache_purge my_cache $scheme$host/;
}

Очистка раздела и главной:

curl -X PURGE http://news.example.com/purge/news/
curl -X PURGE http://news.example.com/purge/

Первый запрос удалит все URL, начинающиеся с /news/. Второй сбросит главную страницу. Новая статья сразу появится в списках, остальные разделы останутся в кэше.

Инвалидация ветки форума

Задача: при добавлении нового сообщения обновить все страницы ветки, где отображается список сообщений.

Конфигурация:

location ~ ^/purge(/forum/topic/.*) {
    allow 127.0.0.1;
    deny all;
    proxy_cache_purge my_cache $scheme$host$1;
}

Очистка ветки:

curl -X PURGE http://forum.example.com/purge/forum/topic/456

Регулярное выражение захватывает все URL ветки, включая страницы пагинации /forum/topic/456?page=2, если ключ кэша включает $args. При добавлении сообщения вызывайте скрипт с путём ветки.

Для управления кэшем статики и изображений в этих сценариях пригодится руководство по кэшу Nginx для статики и изображений.

Частые ошибки и методы диагностики

Точечная очистка не срабатывает по трём основным причинам: несовпадение ключей, некорректные регулярные выражения, проблемы с зонами памяти.

Несовпадение ключей возникает, когда proxy_cache_key при сохранении и proxy_cache_purge при очистке формируют разные строки. Пример: ключ сохранения $scheme$host$request_uri$args, а в location очистки указан $scheme$host$1 без $args. Запись останется в кэше, хотя модуль вернёт 200.

Некорректные регулярные выражения: шаблон /purge(/.*) захватывает пустую строку, если запрос пришёл на /purge/. Это удалит весь кэш. Или шаблон /purge(/product/.*) не сработает для URL /product/123, потому что в location указан полный путь с /purge/, а в запросе его нет.

Проблемы с зонами памяти: если keys_zone слишком мала, Nginx не может хранить все ключи. При очистке запись может отсутствовать в зоне, хотя файл кэша существует. Увеличьте размер зоны и проверьте, что proxy_cache_path и proxy_cache_purge ссылаются на одну и ту же зону.

Проверка очистки с помощью curl

Быстрая проверка, сработала ли очистка:

curl -X PURGE -I http://example.com/purge/product/123

Анализируйте код ответа и заголовки:

  • 200 и заголовок X-Cache-Purge: 1 - запись удалена.
  • 404 - записи с таким ключом не было.
  • 403 - доступ запрещён, проверьте allow/deny в location.
  • 405 - метод PURGE не разрешён, проверьте, что модуль активен.

Для проверки, отдаётся ли страница из кэша, используйте заголовки X-Cache:

curl -I http://example.com/product/123 | grep X-Cache

X-Cache: HIT означает, что страница в кэше. После очистки должен появиться MISS, а затем снова HIT после повторного сохранения.

Анализ логов Nginx

Включите debug-логирование для модуля кэша:

error_log /var/log/nginx/error.log debug;

После отправки PURGE-запроса ищите в логе строки с cache purge:

grep -i "cache purge" /var/log/nginx/error.log

Типичные сообщения:

  • cache purge: key not found - ключ не совпал, проверьте proxy_cache_key и proxy_cache_purge.
  • cache purge: zone "my_cache" not found - зона не определена, проверьте proxy_cache_path.
  • cache purge: invalid key - ключ содержит недопустимые символы, проверьте экранирование.

Если очистка не сработала, а в логах нет сообщений, проверьте, что запрос вообще попадает в location /purge/. Добавьте временный access_log для этого location и посмотрите, какие запросы приходят.

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

Заключение

Точечная очистка кэша Nginx с модулем ngx_cache_purge решает задачу обновления отдельных страниц без потери производительности. Ключевые шаги: установите модуль, настройте proxy_cache_key с нужными переменными, создайте location для очистки с ограничением доступа, автоматизируйте PURGE-запросы скриптами.

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

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

Поделиться:
Сохранить гайд? В закладки браузера