Редиректы через Cloudflare Workers

TL;DR

Cloudflare Workers позволяют перенаправлять запросы прямо на edge, снижая задержки и нагрузку на origin. В статье показано, как настроить рабочую среду, реализовать и улучшить скрипт редиректов, развернуть воркер для домена и какие практики учитывать при эксплуатации.

Быстрые ссылки

Конфигурация Cloudflare Worker
Разработка кода для редиректов
Улучшение скрипта редиректов
Развёртывание
Будущие возможности
Заключение

Архитектура Cloudflare Workers: исполнение кода на edge, близко к пользователю

Чем ближе к edge выполняется логика и возвращается ответ посетителю, тем быстрее получается пользовательский опыт. Cloudflare Workers дают возможность запускать JavaScript прямо на edge-серверах: перехватить запрос, обработать его и вернуть ответ, часто без обращения к origin.

Это открывает не только прирост производительности, но и новые архитектурные возможности — сервисы и приложения, которые почти полностью работают на edge с минимальным backend. В статье показан практический случай: реализация перенаправлений (redirects) на уровне Cloudflare Workers.

Конфигурация Cloudflare Worker

Предположим, что домен уже проксируется через Cloudflare. В панели Cloudflare есть раздел для Workers, где можно создать рабочую среду и протестировать код до продакшн-развёртывания. Это удобная песочница для отладки.

Кнопка создания воркера в панели Cloudflare — интерфейс «Create a Worker»

Нажмите «Create a Worker» для генерации среды разработки: Cloudflare создаст тестовый поддомен для проверки скрипта.

Среда разработки воркера: редактор кода слева, HTTP-клиент и превью справа

Среда делится на три области: редактор кода слева, справа — вкладка HTTP для формирования запросов и вкладка Preview для визуализации ответа. Это позволяет быстро проверять поведение воркера без развёртывания на реальный домен.

Теперь создадим базовый редирект и усложним его по необходимости.

Разработка кода редиректа

Базовый шаблон воркера следующий. Событие fetch перехватывает входящий запрос и передаёт его в функцию обработки.

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

/**
 * Обработать запрос
 * @param {Request} request
 */
async function handleRequest(request) {
  // Логика редиректа здесь
}

Идея простая: считать pathname из URL запроса и принять решение о перенаправлении. Пример с оператором switch (исправленная и рабочая версия):

addEventListener('fetch', async event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  const requestURL = new URL(request.url)
  const path = requestURL.pathname.split('/redirect')[1]
  let location = null

  switch (path) {
    case '/test1':
      location = 'https://mysite.com/newlocation1'
      break
    case '/test2':
      location = 'https://mysite.com/newlocation2'
      break
    default:
      break
  }

  if (location) {
    return Response.redirect(location, 301)
  }

  return fetch(request)
}

Такой подход работает, но становится неудобным для большого количества правил. Далее — как сделать карту редиректов более управляемой.

Улучшение скрипта: Map и KV

Для упрощения поддержки редиректов вместо громоздкого switch удобно использовать Map или извлекать правила из KV-хранилища.

Пример с Map в коде (подходит для небольшого количества статических правил):

const redirectMap = new Map([
  ['/test1', 'https://mysite.com/newlocation1'],
  ['/test2', 'https://mysite.com/newlocation2'],
  ['/test3', 'https://mysite.com/newlocation3'],
  ['/test4', 'https://mysite.com/newlocation4'],
])

addEventListener('fetch', async event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  const requestURL = new URL(request.url)
  const path = requestURL.pathname.split('/redirect')[1]
  const location = redirectMap.get(path)

  if (location) {
    return Response.redirect(location, 301)
  }

  return fetch(request)
}

При большом числе записей лучше хранить правила в Workers KV. Тогда правила можно менять без развёртывания нового скрипта. Пример обращения к KV (предполагается, что namespace привязан как REDIRECTS):

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  const requestURL = new URL(request.url)
  const path = requestURL.pathname.split('/redirect')[1]

  // Получаем значение из KV: REDIRECTS.get возвращает строку или null
  const location = await REDIRECTS.get(path)

  if (location) {
    return Response.redirect(location, 301)
  }

  return fetch(request)
}

Важно: при использовании KV нужно связать namespace в настройках скрипта (Bindings). KV обеспечивает eventual consistency — изменения распространяются по краю не мгновенно.

Полезные улучшения в коде

Сохранение query string при редиректе, если это требуется.
Поддержка временных (302) и постоянных (301) редиректов по ключу.
Логирование ошибок и метрик (wrangler dev/напрямую интеграция с логами Cloudflare).
Защита от циклических редиректов — лимит числа редиректов в цепочке.

Развёртывание

После того как скрипт протестирован и сохранён, его нужно привязать к домену и маршруту. В панели Cloudflare для нужной зоны откройте вкладку Workers, нажмите «Add Route» и укажите шаблон маршрута. Обычный пример:

*.mysite.com/*

Такой маршрут будет перехватывать все запросы к зоне и позволять скрипту анализировать путь и перенаправлять при совпадениях.

Добавление маршрута для воркера через интерфейс Cloudflare

Настройка маршрута и выбор скрипта для привязки к зоне

Важное: привязка воркера к маршруту вступает в силу сразу. Любые изменения скрипта или ошибки начнут действовать мгновенно, поэтому тестируйте в dev окружении перед продом.

Будущие возможности и интеграции

Cloudflare предоставляет дополнительные инструменты вокруг Workers:

Workers KV — для масштабируемого хранения правил и контента.
Wrangler — CLI для разработки, публикации и управления скриптами и привязками.
Возможность отдавать статические сайты из KV через Worker (полезно для простых SPA или landing pages).
Интеграция с Durable Objects для согласованного состояния на edge, если нужно хранить небольшие наборы данных с сильной согласованностью.

Эти возможности расширяют сценарии использования: A/B-тесты на edge, мультирегиональные фичи, быстрые ответные страницы при отказе origin.

Когда такой подход не подходит

Сложная логика маршрутизации, требующая доступа к актуальным реляционным данным: если для решения нужны транзакции или сложные JOIN, лучше держать логику на backend.
Очень чувствительные к консистентности данные: Workers KV — eventual consistent; для сильной согласованности разумнее origin или Durable Objects.
Ограничения по времени выполнения или ресурсам в Workers: для тяжёлых вычислений edge не всегда подходит.

Альтернативы

Перенаправления на уровне веб-сервера (nginx/Apache) — централизованное управление, подходит для больших, стабильных сайтов.
CDN rewrite/redirect правила — если CDN предоставляет встроенные правила, их можно использовать без скриптов.
Контейнер/функции в облаке (Cloud Functions, AWS Lambda@Edge) — когда требуется интеграция с экосистемой провайдера.

Методология развёртывания (мини-SOP)

Разработать и протестировать воркер в среде Cloudflare Workers (dev).
Настроить набор тестовых правил в Map или KV и покрыть автоматическими тестами.
Проверить поведение через HTTP-инструменты (curl, Postman) и preview в панели.
Привязать Worker к тестовой зоне или поддомену, провести интеграционные тесты.
Перенести на прод-зону, установить мониторинг и оповещения на ошибки.
Документировать правила редиректов и процесс отката.

Критерии приёмки

Для заданных тестовых путей редиректы возвращают корректный код и Location.
Запросы, не попадающие под правила, передаются на origin без изменения.
Метрики ошибок и латентности в пределах допустимых порогов.
Возможность отката до предыдущей версии воркера за одну операцию.

Тестовые сценарии

Прямой матч: /redirect/test1 → 301 к новой локации.
Нет совпадения: /redirect/unknown → проксирование на origin.
Сохранение query: /redirect/test1?utm=1 → перенаправление с query.
Неправильный формат: некорректный путь → 400 или проксирование по соглашению.
Симуляция ошибки в скрипте → проверка алертов и корректного логирования.

Ролевые чеклисты

Разработчик:

Покрыл код тестами и локально отладил.
Обновил документацию и changelog.

Оператор (SRE):

Настроил мониторинг ошибок и latency.
Подготовил план отката и проверил его на тестовой зоне.

Информационная безопасность:

Проверил, что воркер не раскрывает внутренние заголовки.
Проверил доступ к KV и права привязки.

Безопасность и конфиденциальность

Не храните в KV чувствительные персональные данные без шифрования и прав доступа.
Ограничьте количество прав для воркера: привязывайте только необходимые namespace и bindings.
Логи могут содержать пользовательские параметры — не логируйте PII без необходимости.
Учитывайте GDPR/локальные требования при обработке данных пользователей.

Справочник: 1‑строчные определения

Worker — скрипт, выполняющийся на edge для обработки HTTP-запросов.
KV — ключ‑значение хранилище Cloudflare, eventual readonly/modify модель.
Route (маршрут) — шаблон URL, на который привязывается воркер.
Edge — распределённая сеть точек присутствия ближе к пользователю.

Заключение

Cloudflare Workers предоставляют простой и мощный путь для переноса части логики на edge. Для задач типа массовых редиректов это часто оптимальный выбор: низкая латентность, облегчённая нагрузка на origin и гибкость управления правилами через Map или KV. При этом важно понимать ограничения по консистентности и ресурсам, тестировать изменения в dev и иметь план отката.