Изграждане на безсървърна контактна форма с Cloudflare Pages Functions и KV Store

Cloudflare Pages Functions и KV Store предоставят мощно безсървърно решение за изграждане на контактни форми без традиционна backend инфраструктура. Тази публикация описва подробно как да имплементирате сигурна, scalable контактна форма, използвайки тези технологии.

Съдържание

• Съдържание
• Защо Cloudflare Pages Functions и KV Store?
• Преглед на архитектурата
• Ръководство за имплементация
• Deployment
• Анализ на разходите
• API endpoints
• Най-добри практики за сигурност
• Заключение

Защо Cloudflare Pages Functions и KV Store?

Традиционните решения за контактни форми често изискват:

• Специализирани backend сървъри
• Инфраструктура за бази данни
• Конфигурация на имейл сървър
• Сложни deployment процеси

Безсървърният стек на Cloudflare елиминира тези изисквания, като предоставя:

• Нулево управление на инфраструктура: Няма сървъри за поддръжка или скалиране
• Глобална Edge мрежа: Кодът се изпълнява близо до потребителите навсякъде по света
• Вградена сигурност: DDoS защита, rate limiting и CAPTCHA поддръжка
• Ефективност на разходите: Ценообразуване според използването с щедър безплатен план

Преглед на архитектурата

Решението се състои от четири основни компонента:

1. Статичен frontend: HTML форма, хоствана на Cloudflare Pages
2. Pages Function: Безсървърен handler, обработващ данните от формата
3. KV Store: Разпределено key-value хранилище за данните от съобщенията
4. Turnstile CAPTCHA: Защита от ботове и спам

Ръководство за имплементация

Пълният работещ примерен код е наличен в GitHub: ivandachev-examples/cloudflare-contact-form

Стъпка 1: Настройка на Cloudflare Pages

Първо, създайте нов проект в Cloudflare Pages:

# Създаване на директория за проекта
mkdir contact-form-app
cd contact-form-app

# Инициализация на npm проект
npm init -y

# Инсталиране на зависимости
npm install -D wrangler

Стъпка 2: Създаване на контактната форма

Създайте проста HTML форма в public/index.html:

Loading code...

Вижте в GitHub: index.html

Стъпка 3: Имплементиране на Pages Function

Създайте безсървърния handler в functions/api/contact.js. Тази имплементация включва:

• CORS поддръжка за заявки от различни източници
• Rate limiting (5 заявки на минута на IP)
• Конфигурируема валидация с environment variables
• API endpoints - POST за изпращане, GET за извличане
• Turnstile CAPTCHA верификация за защита от ботове

Loading code...

Вижте в GitHub: contact.js

Ключови функции в кода:

• Конфигурация на CORS headers с allowed origins
• Rate limiting използвайки KV с автоматично изтриване
• Валидация на входните данни с конфигурируеми min/max дължини
• API key автентикация, поддържаща както query parameter, така и header
• Turnstile token верификация със server-side валидация
• Изчерпателна обработка на грешки с подходящи HTTP status codes

Стъпка 4: Конфигуриране на KV Store

Създайте конфигурационен файл wrangler.jsonc с KV namespace binding и environment variables:

Loading code...

Вижте в GitHub: wrangler.jsonc

Конфигурацията включва:

• KV namespace binding за съхраняване на съобщенията
• Allowed origins за CORS
• Конфигурируеми validation limits
• Коментари за настройка на secret API key

Създайте KV namespace и настройте автентикация:

# Създаване на KV namespace чрез npm скрипт
npm run kv:create
# Копирайте генерираното ID в wrangler.jsonc

# Генериране на сигурен API key
openssl rand -hex 32

# Задаване на API key като secret
npx wrangler pages secret put API_KEY --project-name contact-form-app
# Въведете генерирания ключ при подкана

# Проверка дали е качен
npx wrangler pages secret list --project-name contact-form-app

Стъпка 5: Конфигуриране на Cloudflare Turnstile

Turnstile предоставя CAPTCHA защита за предотвратяване на спам и ботове:

1. Създайте Turnstile site във вашия Cloudflare dashboard:
   • Навигирайте до Turnstile в страничната лента
   • Кликнете Add Site
   • Конфигурирайте вашия сайт с вашите домейни
   • Изберете widget mode (Managed или Invisible)
   • Копирайте Site Key и Secret Key
2. Актуализирайте вашата конфигурация:
   • Задайте TURNSTILE_SITE_KEY в wrangler.jsonc
   • Актуализирайте site key във вашата HTML форма

3. Задайте secret key:

   npx wrangler pages secret put TURNSTILE_SECRET_KEY --project-name contact-form-app
   # Въведете вашия Turnstile secret key при подкана
   

4. Опции за персонализация на widget:

   <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY" data-theme="light" data-size="normal"></div>
   

За подробни инструкции за настройка на Turnstile, вижте TURNSTILE_SETUP.md в примерното repository.

Deployment

Deploy на вашето приложение за контактна форма:

# Вход в Cloudflare
wrangler login

# Deploy в Cloudflare Pages
npm run deploy

За локална разработка:

# Стартиране на сървър за разработка на http://localhost:8788
npm run dev

Примерното repository също включва инструменти за разработка за качество на кода:

# Форматиране на код с Prettier
npm run format

# Стартиране на ESLint за JavaScript linting
npm run lint

# Стартиране на Stylelint за CSS linting
npm run lint:css

Анализ на разходите

Ценовият модел на Cloudflare за това решение:

• Pages: Безплатно за неограничени заявки
• Functions: 100,000 заявки/ден безплатно, след това $0.50/милион
• KV Storage: 100,000 reads/ден безплатно, 1,000 writes/ден безплатно
• KV операции: $0.50/милион reads, $5.00/милион writes след free tier

За типична контактна форма, получаваща 1,000 submissions на месец:

• Месечна цена: $0 (в рамките на free tier)
• Капацитет за скалиране: Може да обработва милиони submissions без промени в инфраструктурата

API endpoints

Контактната форма предоставя следните API endpoints:

Изпращане на контактна форма

• POST /api/contact
• Body: JSON с полета name, email, message и cf-turnstile-response
• Изисква валиден Cloudflare Turnstile token
• Rate limited до 5 съобщения на минута на IP

Получаване на съобщения (изисква API ключ)

• GET /api/contact?api_key=YOUR_API_KEY
• GET /api/contact с header X-API-Key: YOUR_API_KEY
• Query параметри:
  • limit: Брой резултати на страница (1-1000, по подразбиране: 100)
  • cursor: Pagination cursor за следващата страница
• Връща JSON отговор с:
  • submissions: Array от submission обекти
  • list_complete: Boolean, указващ дали има още резултати
  • cursor: Cursor за следващата страница (null ако няма повече резултати)
  • count: Брой съобщения в текущата страница

Проверка на API статус

• GET /api/contact
• Връща API статус (не се изисква автентикация)

Най-добри практики за сигурност

1. CAPTCHA защита: Cloudflare Turnstile предотвратява изпращания от ботове
2. Валидация на входните данни: Винаги валидирайте и почиствайте потребителските данни
3. Rate limiting: Имплементирайте per-IP rate limiting (5 заявки/минута)
4. CORS: Конфигурирайте подходящи CORS headers за allowed domains
5. API сигурност: Използвайте API keys за endpoints за достъп до данни
6. Криптиране: Използвайте HTTPS за всички комуникации
7. Съхранение на данни: Имплементирайте политики за автоматично изтриване на данни
8. Token сигурност: Turnstile tokens изтичат след 5 минути и са за еднократна употреба

Заключение

Cloudflare Pages Functions и KV Store предоставят стабилно, скалиращо решение за контактни форми, което елиминира сложността на традиционната инфраструктура. Този безсървърен подход предлага:

• Глобална производителност: Edge deployment осигурява ниска latency в световен мащаб
• Автоматично скалиране: Справяне с пикове в трафика без конфигурация
• Ефективност на разходите: Плащате само за това, което използвате
• Developer Experience: Прост deployment и поддръжка

Комбинацията от Pages Functions за изчисления и KV Store за персистентност създава цялостно backend решение, което е идеално за контактни форми и подобни приложения, изискващи просто събиране и съхранение на данни.

Изграждали ли сте безсървърни приложения с Cloudflare? Споделете вашия опит и съвети в коментарите по-долу!