Cloudflare Workers Sites на edge — пошаговое руководство

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

• Getting Started
• Creating a Site
• Previewing the Site
• Deploying the Site to Production
• Conclusion

Введение

За последние годы edge‑вычисления стали доступнее. Cloudflare Workers позволяют запускать серверный JavaScript непосредственно в точке присутствия сети рядом с пользователем. Workers устраняют cold‑starts и обеспечивают высокую производительность за меньшую цену по сравнению с традиционными serverless‑платформами.

Workers KV — это key‑value хранилище, интегрированное с Workers. Его можно использовать как базу данных и файловое хранилище, что делает возможным публикацию статических сайтов прямо с edge. В этом руководстве показано, как подготовить и развернуть простой статический сайт, обслуживаемый Cloudflare Workers и Workers KV.

Important: для использования Workers KV требуется план Workers Bundled.

Требования и план

Коротко о том, что понадобится:

• Аккаунт Cloudflare, привязанный к домену.
• План Workers Bundled (оплата минимум $5 в месяц, детали ниже).
• Установленный Wrangler (CLI для работы с Workers).
• Git (рекомендуется) и базовое знание командной строки.

Факты о плане Workers Bundled (перечислено исходя из общедоступной информации):

• Минимальная плата $5 и $0.50 за миллион запросов в месяц после 10 млн бесплатных запросов.
• До 30 сайтов на аккаунт.
• Бесплатный subdomain *.workers.dev.
• До 50 мс CPU на запрос (в бесплатном плане 10 мс).
• Доступ к Workers KV: до 100 пространств имён (namespaces).
• 1 ГБ хранения (дополнительно $0.50 за ГБ).
• Ограничения операций: 10 млн чтений, 1 млн записей/удалений/листинга (цены за превышение см. в панели).

Важно: не придумывайте и не публикуйте платёжные данные — проверяйте текущие условия в интерфейсе Cloudflare.

Установка Wrangler

Wrangler — официальный CLI для разработки и развёртывания Workers. Его можно установить через NPM (Node.js) или Cargo (Rust).

Установка через NPM

npm i @cloudflare/wrangler -g

Установка через Cargo

cargo install wrangler

Если вы предпочитаете использовать системную библиотеку OpenSSL вместо встроенной в Cargo, установите так для уменьшения размера пакета:

cargo install wrangler --features sys-openssl

Примечание: используйте совместимую версию Node/Cargo. В примерах использована Wrangler 1.11.0 и выше — в ней появилось упрощённое логирование.

Создание сайта

Теперь, когда Wrangler установлен и план Workers оплачен, можно создать проект сайта. В примерах использована версия Wrangler 1.11.0 и PowerShell, но команды подходят для любой оболочки, где установлен Wrangler.

Вход через Wrangler

Выполните команду логина, чтобы авторизовать Wrangler в вашем аккаунте Cloudflare. Команда откроет браузер для подтверждения прав, а Wrangler сохранит токен в конфигурации.

wrangler login

После успешного входа Wrangler создаст файл конфигурации (wrangler.toml) с токеном или ссылкой на токен. Не храните публично токены и не коммитьте их в открытые репозитории.

Генерация проекта

Создаём шаблон сайта. Команда создаст структуру проекта с публичной папкой и скриптами Workers.

wrangler generate --site worker-site

Рекомендуется перейти в созданную папку и инициализировать git:

cd worker-site
git init

Структура проекта

Типичная структура, которую создаёт Wrangler:

• public — статические файлы проекта: index.html, favicon.ico и т. п.
• workers-site — JavaScript, который отдаёт файлы из public (обычно index.js). Этот код управляет логикой отдачи статики на edge.
• wrangler.toml — конфигурация проекта: имя, тип сборки, account_id, route, zone_id и настройки site.

Wrangler может вывести предупреждение о том, что нужно обновить wrangler.toml. Как минимум укажите account_id.

Чтобы получить account_id, откройте Cloudflare dashboard → Workers и скопируйте Account ID.

Откройте wrangler.toml и заполните account_id:

Локальное превью

Для проверки работы сайта используйте команду preview. Параметр –watch автоматически обновляет превью при изменении файлов.

wrangler preview --watch

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

Чтобы опубликовать сайт под собственным доменом, откройте wrangler.toml и настройте несколько ключевых параметров:

• zone_id — идентификатор зоны (ваш домен) в Cloudflare.
• route — шаблон URL, на который будет применяться Worker (например example.com/ или sub.example.com/).
• workers_dev — выставьте в false, если развертываете на собственный домен.

zone_id можно найти в панели Cloudflare: выберите сайт → Overview → Zone ID.

Пример финальной конфигурации wrangler.toml:

name = "worker-site"
type = "webpack"
account_id = "my-account-id"
workers_dev = false
route = "example.com/*"
zone_id = "my-zone-id"

[site]
  bucket = "./public"

Наконец, командой publish опубликуйте сайт:

wrangler publish

Что важно проверять после публикации

• Работает ли сайт по URL из route.
• Возвращаются ли корректные Content-Type и заголовки кеширования.
• Нет ли утечек токенов или секретов в публичных файлах.
• Логи ошибок (через панель Cloudflare или внешние лог‑сервисы).

Когда Workers Sites не подходят

• Если у вас сложная серверная логика с активной базой данных и длительными вычислениями. Workers ограничены по CPU и по времени выполнения.
• Если вы храните большие бинарные файлы; KV не предназначено для огромных объектов (лучше объектные хранилища типа R2 или S3).
• Если нужна сильная согласованность записей: KV даёт eventual consistency для реплик, что иногда неприемлемо.

Counterexample: приложение с транзакциями и сложными запросами в реальном времени — лучше использовать традиционную бэкенд‑архитектуру.

Альтернативные подходы

• Cloudflare Pages — полностью статические сайты с интеграцией CI/CD, хорошо подходит для JAMstack.
• S3 + CloudFront — классика для хранения и доставки статических файлов с возможностью кастомной логики на origin.
• Netlify / Vercel — предлагаются функции edge и serverless, удобны для фронтенд‑разработчиков.

Выбор зависит от требований к latency, цене, интеграциям и модели разработки.

Ментальные модели и эвристики

• Edge = близость к пользователю. Используйте edge, если критична задержка.
• KV = ключ/значение + скорость чтения. Не используйте KV как замену реляционной БД.
• Workers = короткие, быстрые функции. Длинные фоновые задачи выносите в очереди или фоновые задачи.

Факто‑бокс: ключевые числа

• CPU на запрос: до 50 мс в Bundled плане.
• Storage в KV: 1 ГБ включён, доплата за ГБ.
• Операции в KV: 10 млн чтений и 1 млн записей/удалений/листинга в базовом пакете.

(Проверьте актуальные лимиты в интерфейсе Cloudflare перед закупкой.)

Чек‑листы по ролям

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

• Инициализировать проект wrangler generate.
• Поместить статические файлы в public.
• Локально протестировать wrangler preview –watch.
• Настроить wrangler.toml и заполнить account_id.

DevOps / Системный администратор:

• Подключить домен и получить zone_id.
• Убедиться в правильных DNS записях.
• Обновить route и workers_dev=false.
• Настроить CI/CD для автоматического publish.

Security / Compliance:

• Убедиться, что секреты не попадают в public.
• Настроить заголовки безопасности (CSP, HSTS).
• Настроить политику логирования и ретенции.

Product Owner:

• Проверить требования к SLA и latency.
• Оценить соответствие требованиям GDPR/конфиденциальности.

Пошаговый SOP: от шаблона до продакшна

1. Оплатите Workers Bundled и подтвердите доступ к Workers KV.
2. Установите Wrangler (NPM или Cargo).
3. Выполните wrangler login и подтвердите доступ через браузер.
4. Сгенерируйте проект: wrangler generate –site worker-site.
5. Поместите все статические файлы в public.
6. Инициализируйте git и создайте CI pipeline (опционально).
7. Получите account_id и zone_id из панели Cloudflare и обновите wrangler.toml.
8. Локально протестируйте: wrangler preview –watch.
9. Приготовьте route (example.com/*) и установите workers_dev = false.
10. Разверните: wrangler publish.
11. Мониторьте логи и ошибки, проверяйте метрики производительности.

Примеры конфигураций и сниппеты

wrangler.toml шаблон:

name = "worker-site"
type = "webpack"
account_id = "REPLACE_WITH_ACCOUNT_ID"
workers_dev = false
route = "example.com/*"
zone_id = "REPLACE_WITH_ZONE_ID"

[site]
  bucket = "./public"

Основные команды:

# Вход
wrangler login

# Сгенерировать проект
wrangler generate --site worker-site

# Просмотр с автообновлением
wrangler preview --watch

# Публикация в production
wrangler publish

Короткая подсказка: не добавляйте в git файл с реальным API-токеном. Используйте переменные окружения или secrets в CI.

Советы по безопасности

• Храните секреты и API‑ключи в секрете: используйте секреты CI или Cloudflare Secrets.
• Минимизируйте данные, хранящиеся в KV; избегайте PII без шифрования.
• Настройте политики кеширования и заголовки: Cache-Control, Content-Security-Policy, Strict‑Transport‑Security.
• Включите Firewall Rules и WAF для защиты от атак.
• Ограничьте доступ к административным маршрутам по IP или по токену.

Конфиденциальность и соответствие требованиям (GDPR)

• KV может реплицироваться географически. Если политика данных требует локального хранения, проверьте правила репликации и локализацию данных.
• Минимизируйте хранение персональных данных в KV. Храните только минимум идентификаторов и используйте ссылку на PII в безопасном BaaS.
• Обеспечьте право на удаление: реализуйте механизмы удаления данных и проверьте, как быстро реплики KV удаляют данные.

Important: проконсультируйтесь с юристом или специалистом по GDPR для критичных случаев.

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

• Сайт доступен по заданному route (example.com/*).
• Статические файлы отдаются корректно с Content-Type и ожидаемыми кодами ответа.
• Страницы проходят базовую проверку производительности (latency, время ответа).
• Нет утечек секретов в публичных исходниках.
• Логи не содержат PII в открытом виде.

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

• Smoke test: доступ к / и проверка кода 200.
• Cache test: заголовки Cache-Control присутствуют и соблюдаются.
• KV read/write: записать тестовое значение в KV и прочитать его.
• Route test: проверить, что запросы к другим поддоменам не обрабатываются (если не настроены).

Совместимость и миграция

• Wrangler v1.x использует разные подходы к аутентификации по сравнению с более старыми версиями. Обновите CI и локальные машины.
• Workers runtime поддерживает модульный (ES Modules) и Service Worker API; проверяйте код на совместимость.
• При миграции с других решений (S3, Netlify) проверьте разницу в заголовках и поведении кэша.

Примеры ошибок и пути их решения

Ошибка: 403 при publish — проверьте токен и account_id.

Ошибка: 404 для статического файла — убедитесь, что файл лежит в public и правильный путь указан в запросе.

Ошибка: несоответствие MIME — проверьте конфигурацию сервера/webpack и расширения файлов.

Краткое резюме

Cloudflare Workers Sites — удобный и быстрый способ развернуть статический сайт на edge. Он отлично подходит для сайтов с высокими требованиями к latency и низкой интерактивностью. Не подходит для тяжёлой серверной логики и больших бинарных хранилищ. Следуйте SOP, защищайте секреты и проверяйте соответствие требованиям конфиденциальности.

Короткий глоссарий

• Worker — код, выполняющийся на edge.
• KV — key‑value хранилище, быстрое чтение, eventual consistency.
• zone_id — идентификатор зоны (домена) в Cloudflare.
• route — шаблон URL для применения Worker.
• wrangler.toml — конфигурационный файл проекта.

Заключение

Cloudflare Workers Sites даёт простую и быструю платформу для публикации статических сайтов с преимуществами edge‑платформы: низкая задержка, масштабируемость и простота использования. Для сложных серверных задач комбинируйте Workers с другими сервисами (R2, Functions, внешними БД). Если вам важна скорость доставки и простота развёртывания — это отличный выбор.