Наш сайт работает на Next.js и Payload CMS. Страницы, которые редко меняются, nginx отдаёт из своего кеша, не трогая приложение. Чтобы правка в админке была видна сразу, а не через пять минут, Payload при сохранении сам сбрасывает нужные страницы в кеше nginx. Рассказываем, как это устроено и где мы ошиблись.
Зачем кешировать в nginx, а не в Next.js
У Next.js есть свой кеш страниц (ISR). Мы оставили кеш в nginx, и вот что это даёт:
- Кеш nginx не зависит от приложения. Если контейнер перезапускается или база на секунду недоступна, nginx продолжает отдавать последнюю удачную версию страницы (
proxy_cache_use_stale). - Его видно и им легко управлять. Заголовок
X-Cache-Statusв ответе показывает, откуда пришла страница. Сбросить её можно одним HTTP-запросом.
Данные из базы Next.js при этом всё равно кеширует у себя (Data Cache). Так что слоёв кеша два, и сбрасывать нужно оба.
Как это работает

- Посетитель открывает страницу. Если она есть в кеше nginx — получает её сразу (
HIT). Если нет — nginx идёт в Next.js, отдаёт ответ и кладёт его в кеш на 5 минут (MISS). - Редактор сохраняет кейс в админке.
- Хук Payload
afterChangeсбрасывает данные кейса в Next.js и отправляет в nginx запросPURGEдля каждой затронутой страницы: главной, портфолио, самого кейса — на обоих языках. - Следующий посетитель получает
MISSи уже свежую страницу. Все последующие снова получаютHIT.
Пять минут — это запасной срок. Если сброс почему-то не дошёл, страница всё равно обновится сама.
Конфигурация nginx
Нужен модуль ngx_cache_purge. В Ubuntu он ставится пакетом libnginx-mod-http-cache-purge.
proxy_cache_path /var/cache/nginx/site levels=1:2 keys_zone=SITE_CACHE:20m
max_size=1g inactive=24h use_temp_path=off;
# Не кешируем для вошедших редакторов и для клиентской навигации Next.js
map $http_cookie $site_editor {
"~*(^|;\s*)payload-token=" 1;
default "";
}
map "$site_editor$http_rsc$http_next_router_prefetch$http_next_router_state_tree" $site_skip {
"" 0;
default 1;
}
location / {
proxy_cache SITE_CACHE;
proxy_cache_key "$scheme$host$request_uri";
proxy_cache_valid 200 301 302 5m;
proxy_cache_valid 404 1m;
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_background_update on;
proxy_cache_lock on;
proxy_cache_bypass $site_skip;
proxy_ignore_headers Cache-Control Expires;
proxy_no_cache $site_skip;
add_header X-Cache-Status $upstream_cache_status always;
proxy_pass http://app;
}
# Отдельный сервер для PURGE — только на внутренних адресах
server {
listen 127.0.0.1:8088;
listen 172.21.0.1:8088; # шлюз docker-сети, откуда стучится контейнер
location / {
proxy_cache SITE_CACHE;
proxy_cache_key "https$host$request_uri";
proxy_cache_purge PURGE from all;
proxy_pass http://app;
}
}Что здесь важно:
proxy_ignore_headers Cache-Control. Next.js помечает динамические страницы какno-store. Без этой строки nginx ничего бы не кешировал.$http_rscи соседние заголовки. При переходе по ссылке Next.js запрашивает тот же адрес, но получает не HTML, а данные для React. Если их закешировать, следующий посетитель вместо страницы увидит текст из скобок и кавычек.- Ключ в PURGE-сервере. Он должен совпадать с ключом страницы побайтно. Сброс идёт по HTTP, поэтому
$schemeтам будетhttp, а страница закеширована сhttps. Пишемhttpsруками.
Код хука в Payload
import http from 'http';
const purge = (path: string) =>
new Promise<void>((resolve) => {
const req = http.request({
host: process.env.HOST_NGINX_PURGE_IP || '172.21.0.1',
port: 8088,
path,
method: 'PURGE',
headers: { Host: 'double.systems' },
timeout: 2000,
}, () => resolve());
req.on('error', () => resolve()); // сброс кеша не должен ломать сохранение
req.on('timeout', () => { req.destroy(); resolve(); });
req.end();
});
// в коллекции cases
hooks: {
afterChange: [({ doc, previousDoc }) => {
const paths = ['/', '/portfolio', `/portfolio/${doc.slug}`];
if (previousDoc?.slug && previousDoc.slug !== doc.slug) {
paths.push(`/portfolio/${previousDoc.slug}`); // старый адрес тоже
}
revalidateTag('cases', { expire: 0 }); // сначала данные в Next.js
for (const p of paths) { purge(p); purge(`/ru${p === '/' ? '' : p}`); }
}],
},Порядок важен: сначала сбрасываем данные в Next.js, потом страницу в nginx. Иначе nginx сразу закеширует страницу, собранную из старых данных.
Две ошибки, на которых мы обожглись
Сбрасывались только списки
Хуки сбрасывали главную и портфолио, а страницу самого кейса — нет. Редактор правил текст кейса, а на сайте видел старый, пока не истекали пять минут. Теперь сбрасывается и страница кейса, и его старый адрес, если поменяли slug.
Картинки без хуков
У коллекции media хуков сброса не было вовсе. Редактор заменял обложку, а закешированные страницы продолжали ссылаться на старую. Теперь любое изменение в медиатеке сбрасывает кеш страниц. Сами файлы картинок nginx хранит 30 дней и не сбрасывает: файл с тем же адресом не меняется.
Как проверить у себя

Откройте DevTools → Network, выберите документ страницы и посмотрите заголовок X-Cache-Status:
- Первая загрузка —
MISS, обновление страницы —HIT. - Сохраните эту страницу в админке, обновите — один раз
MISS, потом сноваHIT. - Войдите в админку и откройте сайт —
BYPASS: редактор видит живую версию.
8 927 874 48 31