Разработка кастомных VCL-правил Varnish

Разработка кастомных VCL-правил Varnish

Varnish Cache без кастомного VCL — это молоток, которым пытаются закручивать шурупы. Дефолтная конфигурация кэширует всё подряд или не кэширует ничего, игнорирует заголовки авторизации, не умеет работать с мобильными версиями сайта и падает на первом же edge-кейсе с cookies.

Кастомные VCL-правила решают конкретные задачи: управление кэшем по условиям, нормализация запросов, обход CDN для определённых маршрутов, маршрутизация на разные бэкенды, grace-режим при падении origin.

Архитектура VCL и точки входа

VCL (Varnish Configuration Language) — это domain-specific язык с конечным автоматом из состояний: vcl_recv, vcl_hash, vcl_hit, vcl_miss, vcl_pass, vcl_fetch (в Varnish 4+ это vcl_backend_fetch/vcl_backend_response), vcl_deliver.

Типичная точка старта для кастомизации — vcl_recv. Здесь решается, что кэшировать, что пропустить напрямую, что отдать из кэша без обращения к бэкенду.

vcl 4.1;

import std;
import directors;

backend default {
    .host = "127.0.0.1";
    .port = "8080";
    .connect_timeout = 2s;
    .first_byte_timeout = 60s;
    .between_bytes_timeout = 10s;
    .probe = {
        .url = "/healthz";
        .timeout = 1s;
        .interval = 5s;
        .window = 5;
        .threshold = 3;
    }
}

backend api {
    .host = "127.0.0.1";
    .port = "8081";
    .connect_timeout = 1s;
    .first_byte_timeout = 30s;
}

Нормализация запросов

Без нормализации один и тот же ресурс хранится под десятками ключей: /?utm_source=google, /?utm_source=facebook, /?fbclid=abc123 — это разные записи в кэше, хотя контент идентичен.

sub vcl_recv {
    # Удаляем маркетинговые параметры из URL до построения cache key
    if (req.url ~ "(\?|&)(utm_source|utm_medium|utm_campaign|utm_term|utm_content|fbclid|gclid|yclid|_ga|mc_eid)=") {
        set req.url = regsuball(req.url, "&(utm_source|utm_medium|utm_campaign|utm_term|utm_content|fbclid|gclid|yclid|_ga|mc_eid)=[^&]*", "");
        set req.url = regsuball(req.url, "\?(utm_source|utm_medium|utm_campaign|utm_term|utm_content|fbclid|gclid|yclid|_ga|mc_eid)=[^&]*&?", "?");
        set req.url = regsub(req.url, "\?$", "");
    }

    # Нормализуем Accept-Encoding — Varnish хранит отдельные объекты для gzip/br/identity
    if (req.http.Accept-Encoding) {
        if (req.url ~ "\.(jpg|jpeg|png|gif|webp|gz|tgz|bz2|tbz|mp3|ogg|swf|flv|mp4|woff2?)$") {
            unset req.http.Accept-Encoding;
        } elsif (req.http.Accept-Encoding ~ "br") {
            set req.http.Accept-Encoding = "br";
        } elsif (req.http.Accept-Encoding ~ "gzip") {
            set req.http.Accept-Encoding = "gzip";
        } else {
            unset req.http.Accept-Encoding;
        }
    }

    # Нормализуем cookies — оставляем только нужные для аутентификации
    if (req.http.Cookie) {
        set req.http.Cookie = ";" + req.http.Cookie;
        set req.http.Cookie = regsuball(req.http.Cookie, "; +", ";");
        set req.http.Cookie = regsuball(req.http.Cookie, ";(session|auth_token|XSRF-TOKEN)=", "; \1=");
        set req.http.Cookie = regsuball(req.http.Cookie, ";[^ ][^;]*", "");
        set req.http.Cookie = regsuball(req.http.Cookie, "^[; ]+|[; ]+$", "");
        if (req.http.Cookie == "") {
            unset req.http.Cookie;
        }
    }
}

Маршрутизация по типу запроса

API-запросы и статика требуют разной логики. API — короткий TTL или pass, статика — долгий TTL с нормализацией.

sub vcl_recv {
    # API — не кэшируем, пропускаем напрямую
    if (req.url ~ "^/api/") {
        return(pass);
    }

    # Маршрутизация на отдельный бэкенд для API
    if (req.url ~ "^/api/v[0-9]+/") {
        set req.backend_hint = api;
        return(pass);
    }

    # Авторизованные пользователи — персональный контент, не кэшируем
    if (req.http.Authorization || req.http.Cookie ~ "auth_token=") {
        return(pass);
    }

    # POST, PUT, DELETE, PATCH — не кэшируем
    if (req.method != "GET" && req.method != "HEAD") {
        return(pass);
    }

    # Статика — кэшируем агрессивно, убираем cookies
    if (req.url ~ "\.(css|js|jpg|jpeg|png|gif|ico|svg|woff|woff2|ttf|eot|webp|avif)(\?.*)?$") {
        unset req.http.Cookie;
        return(hash);
    }

    return(hash);
}

Grace-режим и stale-while-revalidate

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

sub vcl_backend_response {
    # Устанавливаем grace-период: 24 часа после истечения TTL
    set beresp.grace = 24h;

    # Если бэкенд вернул 5xx — сохраняем объект для grace
    if (beresp.status >= 500) {
        set beresp.ttl = 0s;
        set beresp.grace = 60s;
        return(deliver);
    }

    # Кастомный TTL по типу контента
    if (bereq.url ~ "^/news/") {
        set beresp.ttl = 10m;
    } elsif (bereq.url ~ "^/static/") {
        set beresp.ttl = 30d;
        unset beresp.http.Set-Cookie;
    } elsif (bereq.url ~ "^/product/") {
        set beresp.ttl = 1h;
    } else {
        set beresp.ttl = 5m;
    }

    # Не кэшируем если бэкенд явно запрещает
    if (beresp.http.Cache-Control ~ "no-store|private") {
        set beresp.uncacheable = true;
        return(deliver);
    }
}

sub vcl_hit {
    # Если объект устарел, но grace позволяет — отдаём и фоново обновляем
    if (obj.ttl >= 0s) {
        return(deliver);
    }
    if (obj.ttl + obj.grace > 0s) {
        return(deliver);
    }
    return(restart);
}

Инвалидация кэша

Purge по тегам (через xkey/surrogate keys) — правильный подход для CMS с зависимостями между объектами.

import xkey;

sub vcl_recv {
    # Purge по URL (простой случай)
    if (req.method == "PURGE") {
        if (!client.ip ~ purge_acl) {
            return(synth(405, "Not allowed"));
        }
        return(purge);
    }

    # Soft-purge по тегу (xkey)
    if (req.method == "XKEY-PURGE") {
        if (!client.ip ~ purge_acl) {
            return(synth(405, "Not allowed"));
        }
        set req.http.n-gone = xkey.softpurge(req.http.xkey-purge);
        return(synth(200, "Purged " + req.http.n-gone + " objects"));
    }
}

sub vcl_backend_response {
    # Бэкенд передаёт surrogate keys в заголовке
    if (beresp.http.Surrogate-Key) {
        set beresp.http.xkey = beresp.http.Surrogate-Key;
    }
}

Вызов инвалидации со стороны приложения:

# Purge конкретной страницы
curl -X PURGE https://example.com/news/article-123

# Purge по тегу (все страницы, связанные с категорией)
curl -X XKEY-PURGE -H "xkey-purge: category:5" https://example.com/

Варианты по устройству (Device Detection)

Если мобильная версия отдаётся с того же URL, нужно хранить отдельные объекты для desktop и mobile.

sub vcl_hash {
    hash_data(req.url);
    if (req.http.host) {
        hash_data(req.http.host);
    } else {
        hash_data(server.ip);
    }
    # Добавляем тип устройства в cache key
    if (req.http.X-Device-Type) {
        hash_data(req.http.X-Device-Type);
    }
    return(lookup);
}

sub vcl_recv {
    # Определяем тип устройства по User-Agent
    if (req.http.User-Agent ~ "(?i)mobile|android|iphone|ipod|blackberry|opera mini|iemobile") {
        set req.http.X-Device-Type = "mobile";
    } else {
        set req.http.X-Device-Type = "desktop";
    }
}

Отладка и метрики

sub vcl_deliver {
    # Добавляем отладочные заголовки (убрать на проде или ограничить по IP)
    if (obj.hits > 0) {
        set resp.http.X-Cache = "HIT";
        set resp.http.X-Cache-Hits = obj.hits;
    } else {
        set resp.http.X-Cache = "MISS";
    }
    set resp.http.X-Served-By = server.hostname;
    # Удаляем внутренние заголовки
    unset resp.http.X-Powered-By;
    unset resp.http.Server;
    unset resp.http.X-Varnish;
    unset resp.http.Via;
}

Мониторинг через varnishstat и varnishlog:

# Текущий hit rate
varnishstat -f MAIN.cache_hit,MAIN.cache_miss

# Живой лог с фильтрацией по URL
varnishlog -q 'ReqURL ~ "^/news/"' -g request

# Топ cache miss по URL
varnishtop -i ReqURL -q 'VCL_call eq "MISS"'

Типичный таймлайн проекта

День 1–2 — аудит текущего трафика, анализ заголовков ответов бэкенда, выявление некэшируемых паттернов (cookies, Cache-Control: private).

День 3–4 — написание базового VCL: нормализация URL, strip маркетинговых параметров, разделение статики и динамики.

День 5 — настройка grace, health checks, тестирование на стейджинге с varnishtest.

День 6 — внедрение инвалидации через PURGE/xkey, интеграция с CMS или деплой-пайплайном.

День 7 — нагрузочное тестирование, настройка мониторинга hit rate, финальный деплой.

Сложные кейсы (A/B тестирование через Varnish, ESI-включения, многоуровневое кэширование с Nginx) добавляют 3–5 дней.