Розробка кастомних 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/

Варіанти за типом пристрою

Якщо мобільна версія подається з того ж 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 {
    # Додаємо debug заголовки (видалити на проді або обмежити за 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

# Live лог з фільтрацією за 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 днів.