Наш сайт работает на Next.js и Payload CMS. Страницы, которые редко меняются, nginx отдаёт из своего кеша, не трогая приложение. Чтобы правка в админке была видна сразу, а не через пять минут, Payload при сохранении сам сбрасывает нужные страницы в кеше nginx. Рассказываем, как это устроено и где мы ошиблись.

Зачем кешировать в nginx, а не в Next.js

У Next.js есть свой кеш страниц (ISR). Мы оставили кеш в nginx, и вот что это даёт:

  1. Кеш nginx не зависит от приложения. Если контейнер перезапускается или база на секунду недоступна, nginx продолжает отдавать последнюю удачную версию страницы (proxy_cache_use_stale).
  2. Его видно и им легко управлять. Заголовок X-Cache-Status в ответе показывает, откуда пришла страница. Сбросить её можно одним HTTP-запросом.

Данные из базы Next.js при этом всё равно кеширует у себя (Data Cache). Так что слоёв кеша два, и сбрасывать нужно оба.

Как это работает

Посетитель получает страницу из кеша nginx. Редактор сохраняет кейс → хук Payload сбрасывает данные в Next.js и отправляет PURGE в nginx → следующий посетитель получает свежую страницу
Посетитель получает страницу из кеша nginx. Редактор сохраняет кейс → хук Payload сбрасывает данные в Next.js и отправляет PURGE в nginx → следующий посетитель получает свежую страницу
  1. Посетитель открывает страницу. Если она есть в кеше nginx — получает её сразу (HIT). Если нет — nginx идёт в Next.js, отдаёт ответ и кладёт его в кеш на 5 минут (MISS).
  2. Редактор сохраняет кейс в админке.
  3. Хук Payload afterChange сбрасывает данные кейса в Next.js и отправляет в nginx запрос PURGE для каждой затронутой страницы: главной, портфолио, самого кейса — на обоих языках.
  4. Следующий посетитель получает 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 дней и не сбрасывает: файл с тем же адресом не меняется.

Как проверить у себя

X-Cache-Status во вкладке Network: MISS при первом открытии, HIT при повторном, снова MISS после сохранения в админке
X-Cache-Status во вкладке Network: MISS при первом открытии, HIT при повторном, снова MISS после сохранения в админке

Откройте DevTools → Network, выберите документ страницы и посмотрите заголовок X-Cache-Status:

  1. Первая загрузка — MISS, обновление страницы — HIT.
  2. Сохраните эту страницу в админке, обновите — один раз MISS, потом снова HIT.
  3. Войдите в админку и откройте сайт — BYPASS: редактор видит живую версию.