Очистка кэша Nginx: диагностика и устранение типичных ошибок

Очистка кэша Nginx чаще всего ломается из-за ошибки прав доступа, неверно указанного пути или невыполненной перезагрузки. Если после удаления файлов вы видите старый контент, ошибку 404 или 502, причина почти всегда в одном из этих трёх узлов. Ниже разобраны конкретные сценарии с командами для диагностики и исправления.

Материал ориентирован на системных администраторов и DevOps-инженеров, которые уже используют Nginx как проксирующий или кэширующий сервер. Если вы только настраиваете кэширование, начните с полного руководства по настройке proxy_cache. Здесь же разбираем именно отказные сценарии после того, как кэш уже работает.

Как правильно очистить кэш Nginx

Кэш Nginx хранится на диске в директории, указанной в директиве proxy_cache_path, fastcgi_cache_path или аналогичной. Очистка сводится к удалению файлов из этой директории и последующей перезагрузке Nginx. Пропуск любого из этих шагов приводит к типовым ошибкам.

Определение пути к кэшу

Путь к кэшу задаётся в конфигурационном файле, обычно /etc/nginx/nginx.conf или в файлах виртуальных хостов в /etc/nginx/sites-enabled/. Найдите директиву:

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

Значение после proxy_cache_path и есть директория кэша. В примере это /var/cache/nginx. У вас путь может отличаться, например /tmp/nginx_cache или /data/nginx/cache. Проверить текущее значение можно командой:

grep -R "proxy_cache_path\|fastcgi_cache_path" /etc/nginx/

Если вы используете контейнерные среды, путь может быть смонтирован как volume. В Docker проверьте маппинг через docker inspect <container_name>, в Kubernetes - через описание PersistentVolumeClaim. Подробнее этот сценарий разобран в руководстве по очистке кэша Nginx.

Очистка кэша вручную

Для полной очистки используйте удаление содержимого директории:

sudo rm -rf /var/cache/nginx/*

Команда удаляет все файлы и поддиректории внутри кэша, но сохраняет саму корневую директорию. Это важно: Nginx должен иметь возможность писать в неё дальше. Альтернативный вариант с find:

sudo find /var/cache/nginx -type f -delete

Будьте точны с путём. Ошибка в одну букву может привести к удалению не той директории. Перед выполнением проверьте, что путь действительно указывает на кэш:

ls -la /var/cache/nginx

Внутри вы должны увидеть каталоги вида 0/, 1/, a/, b/ и файлы без расширений. Если видите что-то другое, остановитесь и перепроверьте конфигурацию.

Перезагрузка Nginx после очистки

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

sudo nginx -s reload

Перезагрузка заставляет Nginx перечитать конфигурацию и сбросить внутренние указатели на удалённые файлы. В некоторых случаях, особенно при использовании open_file_cache, может потребоваться полный рестарт:

sudo systemctl restart nginx

Разница в том, что reload выполняется без разрыва активных соединений, а restart кратковременно прерывает обработку запросов. Для production-сред предпочтителен reload.

Ошибка Permission denied при очистке кэша

Ошибка Permission denied возникает, когда пользователь, выполняющий команду очистки, не имеет прав на запись в директорию кэша. Nginx обычно работает от пользователя nginx или www-data, и директория кэша принадлежит ему же.

Проверка прав доступа

Посмотрите владельца и права на директорию кэша:

ls -ld /var/cache/nginx

Типичный вывод:

drwxr-xr-x 2 nginx nginx 4096 Aug 20 10:00 /var/cache/nginx

Права drwxr-xr-x означают, что писать может только владелец nginx. Если вы работаете под пользователем admin или deploy, запись запрещена. Дополнительно проверьте, к каким группам принадлежит ваш пользователь:

groups $USER

Если группы nginx или www-data в списке нет, прямое удаление без sudo не сработает.

Исправление прав доступа

Самый безопасный способ - выполнить очистку с повышенными привилегиями:

sudo rm -rf /var/cache/nginx/*

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

sudo usermod -aG nginx $USER

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

groups $USER

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

После очистки кэша отдаётся устаревший контент

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

Проверка заголовков ответа

Запросите страницу и посмотрите заголовки:

curl -I https://example.com/page

Ищите заголовки X-Cache, X-Proxy-Cache или Age. Значение HIT означает, что ответ пришёл из кэша Nginx. Значение MISS - кэш не используется, контент отдан бэкендом. Заголовок Age показывает возраст закэшированного ответа в секундах. Если Age больше нуля, а вы только что очистили кэш, перезагрузка не была выполнена или файлы удалены не из той директории.

Очистка кэша браузера и CDN

Браузер кэширует ответы на основе заголовков Cache-Control и Expires. Проверьте страницу в режиме инкогнито или очистите кэш браузера. Если используете CDN, например Cloudflare, очистите кэш в панели управления CDN. CDN может отдавать устаревший контент независимо от состояния вашего Nginx. Для статики и изображений этот сценарий разобран в руководстве по кэшу статики в Nginx.

Если заголовки показывают MISS, но контент старый, проблема на стороне бэкенда. Проверьте, отдаёт ли бэкенд актуальные данные напрямую, минуя Nginx.

Ошибки 404 и 502 после очистки кэша

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

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

Откройте error.log в реальном времени:

sudo tail -f /var/log/nginx/error.log

Записи вида:

connect() failed (111: Connection refused) while connecting to upstream

указывают на недоступный бэкенд. Записи вида:

open() failed (2: No such file or directory)

указывают на отсутствие файла. Логи дают точный адрес upstream и путь к файлу, что ускоряет диагностику.

Проверка бэкенда и upstream

Убедитесь, что бэкенд запущен. Для PHP-FPM:

systemctl status php-fpm

Для Node.js:

systemctl status node-app

Проверьте конфигурацию upstream в Nginx:

upstream backend {
    server 127.0.0.1:9000;
}

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

sudo nginx -s reload

Ошибка 404 часто связана с тем, что бэкенд отдаёт 404 на запрос, который раньше обслуживался из кэша. Проверьте, существует ли ресурс на бэкенде. Если ресурс удалён намеренно, настройте отдачу 404 или 410 напрямую, без попыток кэширования.

Проверка конфигурации Nginx перед очисткой кэша

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

Использование nginx -t

Выполните проверку:

sudo nginx -t

Успешный вывод:

nginx: configuration file /etc/nginx/nginx.conf test is successful

При ошибке Nginx укажет файл и строку с проблемой. Исправьте ошибку и повторите проверку. Только после успешной проверки выполняйте перезагрузку. Это правило предотвращает большинство отказов, связанных с опечатками в директивах proxy_cache_path или upstream.

Диагностика проблем с кэшем через логи Nginx

Логи Nginx - основной источник информации о состоянии кэша. Access.log показывает статусы ответов и попадания в кэш, error.log - ошибки соединений и файловой системы.

Анализ access.log

Чтобы видеть статус кэша в access.log, добавьте переменную $upstream_cache_status в формат лога:

log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" "$upstream_cache_status"';

Пример строки:

127.0.0.1 - - [20/Aug/2026:14:00:00 +0000] "GET /page HTTP/1.1" 200 1234 "-" "curl/7.68.0" "HIT"

Последнее поле показывает HIT, MISS, EXPIRED или BYPASS. HIT - ответ из кэша, MISS - кэш не использовался, EXPIRED - кэш устарел, BYPASS - кэш обойдён намеренно. Эта информация помогает понять, работает ли кэш вообще и очищается ли он корректно.

Включение отладочного уровня логирования через error_log /var/log/nginx/error.log debug; даёт больше деталей, но в production не рекомендуется из-за объёма записей. Используйте debug только на тестовых стендах.

Как работает кэширование в Nginx

Nginx кэширует ответы от бэкенда на диске. Директивы proxy_cache_path и fastcgi_cache_path определяют место хранения и зону разделяемой памяти. Зона памяти хранит метаданные: какие ключи кэша существуют, когда они устаревают, какие файлы им соответствуют. Сами данные лежат на диске в виде файлов.

При запросе Nginx сначала проверяет зону памяти. Если ключ найден и не устарел, Nginx отдаёт файл с диска. Если ключа нет или он устарел, Nginx обращается к бэкенду, сохраняет ответ в кэш и обновляет метаданные. При ручном удалении файлов метаданные в памяти остаются. Поэтому после очистки необходима перезагрузка: она синхронизирует состояние памяти с фактическим состоянием диска.

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

Безопасная очистка кэша без простоя сервиса

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

Использование ngx_cache_purge

Модуль ngx_cache_purge позволяет очищать кэш для конкретного URL без удаления всего кэша. Пример конфигурации:

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

Запрос к /purge/page удалит из кэша только запись для /page. Остальной кэш останется нетронутым. Это снижает нагрузку на бэкенд и предотвращает простой. Модуль требует сборки Nginx с поддержкой ngx_cache_purge. Проверить наличие модуля можно командой:

nginx -V 2>&1 | grep cache_purge

Если модуля нет, используйте атомарное переименование директории кэша:

sudo mv /var/cache/nginx /var/cache/nginx_old
sudo mkdir /var/cache/nginx
sudo chown nginx:nginx /var/cache/nginx
sudo nginx -s reload
sudo rm -rf /var/cache/nginx_old

Этот способ позволяет мгновенно освободить кэш без длительного удаления файлов. Старая директория удаляется в фоне, не блокируя работу Nginx. Для контейнерных сред и Kubernetes аналогичные подходы описаны в руководстве по очистке кэша в Docker и Kubernetes.

Если вы ищете готовую облачную инфраструктуру для размещения Nginx и управления кэшем, Timeweb Cloud предоставляет VDS/VPS с гибким масштабированием ресурсов. Это удобно для проектов, где кэширование критично для производительности.