# Turnstile을 이용한 Nuxt 폼 스팸 방지 > Turnstile을 쓰는 Nitro 서버 라우트, Nitro 스토리지의 IP별 제한, runtimeConfig 시크릿, routeRules로 설정한 CSP로 Nuxt 폼을 스팸으로부터 보호하세요. 2026-10-25 게시 · https://ikiform.com/ko/guides/spam-protection/nuxt `$fetch`로 폼을 서버 라우트에 POST하세요. 서버 라우트는 Nitro 스토리지에서 클라이언트 IP별 시도를 세고, siteverify로 Turnstile 토큰을 검증한 뒤, 허니팟과 함께 필드를 전달합니다. 시크릿은 런타임에 `NUXT_` 환경 변수로 설정되는 비공개 `runtimeConfig`에 두세요. 문의 페이지의 CSP는 `routeRules`에서 보내고, 스크립트와 프레임에 `challenges.cloudflare.com`을 허용하세요. ## Nuxt에서 다른 점 Nuxt의 서버는 Nitro이며, Nitro는 스팸 검사에 필요한 두 가지를 제공합니다. `server/api`의 서버 라우트는 `$fetch`가 이미 연결된 평범한 엔드포인트이고, `useStorage()`는 환경마다 백엔드를 고를 수 있는 키-값 저장소를 줍니다. 개발 환경에서는 메모리, 프로덕션에서는 Redis나 다른 드라이버입니다. 그래서 레이트 리밋은 의존성이 아니라 설정 변경이 됩니다. 여기서 문제를 일으키는 Nuxt 습관이 두 가지 있습니다. `getRequestIP(event, { xForwardedFor: true })`는 첫 번째 `X-Forwarded-For` 항목을 반환하는데, h3 문서조차 이를 클라이언트 입력이라고 부릅니다. 그리고 `.env` 파일은 프로덕션에서 읽히지 않으므로 시크릿은 플랫폼 환경 변수로 설정해야 합니다. 다이어그램: Nuxt 서버 라우트와 Nitro 스토리지를 거치는 문의 POST 1. 컴포넌트가 $fetch로 필드와 Turnstile 토큰을 /api/contact에 POST합니다. 2. 서버 라우트가 runtimeConfig에 지정된 헤더에서 클라이언트 IP를 읽습니다. 3. Nitro 스토리지에서 현재 1분 동안 해당 IP의 POST 수를 셉니다. 5건을 넘으면 남은 초와 함께 429를 던집니다. 4. 제한 이내라면 siteverify로 토큰을 검증하며 action과 호스트를 확인합니다. 5. 그런 다음 필드를 Ikiform으로 전달하고, Ikiform이 저장하고 허니팟 점수를 매깁니다. 개발 환경에서는 스토리지 마운트가 메모리에 있습니다. 프로덕션에서는 nuxt.config가 다른 드라이버를 마운트하므로 같은 코드가 Redis와 통신합니다. ## 프로젝트 설정 `파일`: ```text app/ components/ ContactForm.vue composables/ useTurnstile.ts server/ api/ contact.post.ts utils/ spam.ts nuxt.config.ts .env ``` `.env`: ```bash NUXT_PUBLIC_TURNSTILE_SITE_KEY=1x00000000000000000000AA NUXT_TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA NUXT_IKIFORM_SECRET_KEY=ik_sk_your_secret_key NUXT_CLIENT_IP_HEADER=x-forwarded-for ``` `nuxt.config.ts`: ```ts const policy = [ "default-src 'self'", "script-src 'self' 'unsafe-inline' https://challenges.cloudflare.com", "frame-src https://challenges.cloudflare.com", "object-src 'none'", "base-uri 'self'", ].join("; "); export default defineNuxtConfig({ runtimeConfig: { turnstileSecretKey: "", ikiformSecretKey: "", clientIpHeader: "x-forwarded-for", public: { turnstileSiteKey: "", }, }, routeRules: { "/contact": { headers: { "Content-Security-Policy": policy } }, }, $production: { nitro: { storage: { ratelimit: { driver: "upstash" }, }, }, }, }); ``` - 모든 `runtimeConfig` 키는 런타임에 `NUXT_` 변수로 덮어쓸 수 있습니다. `turnstileSecretKey`는 `NUXT_TURNSTILE_SECRET_KEY`로, `public.turnstileSiteKey`는 `NUXT_PUBLIC_TURNSTILE_SITE_KEY`로 덮어씁니다. `public` 밖의 키는 브라우저에 절대 전달되지 않습니다. - `routeRules`는 `/contact`에서만 CSP를 보냅니다. Nuxt는 페이로드와 하이드레이션 스크립트를 인라인하므로 이 정책은 `'unsafe-inline'`을 유지합니다. 더 엄격한 정책이 필요하다면 커뮤니티 모듈 `nuxt-security`가 nonce를 생성해 줍니다. - `upstash` 드라이버는 프로덕션에서만 마운트되며 환경에서 `UPSTASH_REDIS_REST_URL`과 `UPSTASH_REDIS_REST_TOKEN`을 읽습니다. `@upstash/redis` 패키지가 필요하므로 `npm install @upstash/redis`로 설치하세요. ## 서버 유틸리티 `server/utils`의 파일은 모든 서버 라우트에 자동으로 import됩니다. `server/utils/spam.ts`: ```ts import type { H3Event } from "h3"; const WINDOW_SECONDS = 60; const LIMIT = 5; export function clientIp(event: H3Event) { const header = useRuntimeConfig(event).clientIpHeader; return getRequestHeader(event, header)?.split(",")[0]?.trim() || "unknown"; } export async function secondsToWait(ip: string) { const storage = useStorage("ratelimit"); const window = Math.floor(Date.now() / 1000 / WINDOW_SECONDS); const key = `contact:${ip}:${window}`; const count = ((await storage.getItem(key)) ?? 0) + 1; await storage.setItem(key, count); if (count <= LIMIT) return 0; return (window + 1) * WINDOW_SECONDS - Math.floor(Date.now() / 1000); } export async function isHuman(event: H3Event, token: string, ip: string) { if (!token || token.length > 2048) return false; try { const verdict = await $fetch<{ success: boolean; hostname?: string; action?: string }>("https://challenges.cloudflare.com/turnstile/v0/siteverify", { method: "POST", body: { secret: useRuntimeConfig(event).turnstileSecretKey, response: token, remoteip: ip }, }); return verdict.success && verdict.action === "contact" && (import.meta.dev || verdict.hostname === getRequestHost(event)); } catch { return false; } } ``` - `clientIp`는 호스트가 덮어쓰는 헤더 딱 하나만 읽습니다. `NUXT_CLIENT_IP_HEADER`를 Vercel은 `x-forwarded-for`, Netlify는 `x-nf-client-connection-ip`, Cloudflare는 `cf-connecting-ip`로 설정하세요. - 카운터는 Nitro 스토리지의 고정 구간입니다. 읽은 뒤 쓰는 방식은 원자적이지 않으므로, 같은 순간에 온 두 POST가 모두 제한 아래로 빠져나갈 수 있습니다. 문의 폼에는 허용할 만합니다. 키는 저절로 만료되지 않으므로 Redis 데이터베이스에 축출 정책을 지정하세요. - `$fetch`는 siteverify 본문을 JSON으로 보내며, siteverify는 이를 받습니다. 호스트 검사는 `getRequestHost`를 쓰며, 테스트 토큰에는 더미 호스트 이름이 있으므로 개발 환경에서는 건너뜁니다. ## 서버 라우트 `server/api/contact.post.ts`: ```ts interface ContactBody { name?: string; email?: string; company?: string; message?: string; _gotcha?: string; "cf-turnstile-response"?: string; } export default defineEventHandler(async (event) => { const ip = clientIp(event); const wait = await secondsToWait(ip); if (wait) throw createError({ status: 429, message: `Too many messages. Try again in ${wait} seconds.` }); const body = await readBody(event); const fields = { name: body.name?.trim().slice(0, 120) ?? "", email: body.email?.trim() ?? "", company: body.company?.trim().slice(0, 120) ?? "", message: body.message?.trim().slice(0, 5000) ?? "", _gotcha: body._gotcha ?? "", }; if (!fields.email.includes("@")) throw createError({ status: 400, message: "Enter an address we can reply to." }); if (!(await isHuman(event, body["cf-turnstile-response"] ?? "", ip))) { throw createError({ status: 403, message: "We couldn't confirm you're human. Try again." }); } const origin = getRequestHeader(event, "origin"); await $fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", { method: "POST", headers: { Accept: "application/json", Authorization: `Bearer ${useRuntimeConfig(event).ikiformSecretKey}`, ...(origin ? { Origin: origin } : {}), }, body: fields, }).catch((failure) => { throw createError({ status: failure.status ?? 502, message: failure.data?.error?.message ?? "Your message didn't send. Try again.", }); }); return { sent: true }; }); ``` - `.post.ts` 접미사는 Nitro가 `POST`에만 응답하게 합니다. 그 밖의 요청은 `405`를 받습니다. - 제한은 `readBody`보다 먼저 실행되므로, 폭주가 본문 파싱이나 siteverify 호출 비용을 쓰지 않습니다. - 실패할 때마다 `createError`를 던집니다. JSON 본문에는 컴포넌트가 표시하는 `message`가 담깁니다. - 서버 측 fetch는 `Origin`을 보내지 않으므로 방문자의 이 헤더를 넘기며, Ikiform은 이를 읽어 무료 `localhost` 테스트를 알아봅니다. - 허니팟 `_gotcha`는 그대로 함께 전달되므로, Ikiform은 채워진 허니팟을 버리지 않고 스팸으로 저장합니다. > 서버 측 버전은 시크릿 키로 POST하므로 Ikiform은 **Allowed domains**와 자체 사람 확인을 건너뜁니다. 그러면 모든 POST가 서버의 IP에서 오고, 방문자당 분당 5건인 Standard 제한이 모든 방문자를 합쳐서 셉니다. 서버를 거쳐 POST하는 폼에는 Relaxed 또는 Custom [레이트 리밋](https://ikiform.com/ko/docs/rate-limits.md)을 고르고, `IKIFORM_SECRET_KEY`는 서버 전용 환경 변수에 두세요. ## 컴포저블과 폼 `app/composables/useTurnstile.ts`: ```ts interface TurnstileApi { render( container: HTMLElement, options: { sitekey: string; action: string; callback: (token: string) => void; "expired-callback": () => void }, ): string; reset(widgetId: string): void; remove(widgetId: string): void; } let loading: Promise | undefined; function load() { loading ??= new Promise((resolve, reject) => { const script = document.createElement("script"); script.src = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"; script.async = true; script.onload = () => { const api = (window as Window & { turnstile?: TurnstileApi }).turnstile; if (api) resolve(api); else reject(new Error("Turnstile did not load")); }; script.onerror = () => reject(new Error("Turnstile did not load")); document.head.append(script); }); return loading; } export function useTurnstile(action: string) { const { turnstileSiteKey } = useRuntimeConfig().public; const box = ref(); const token = ref(""); let api: TurnstileApi | undefined; let widgetId: string | undefined; onMounted(async () => { api = await load(); if (!box.value) return; widgetId = api.render(box.value, { sitekey: turnstileSiteKey, action, callback: (value) => (token.value = value), "expired-callback": () => (token.value = ""), }); }); onBeforeUnmount(() => { if (widgetId) api?.remove(widgetId); }); function reset() { token.value = ""; if (widgetId) api?.reset(widgetId); } return { box, token, reset }; } ``` `app/components/ContactForm.vue`: ```vue