마이그레이션 가이드

Turnstile에서 CaptchaLa로 마이그레이션

10분 이내에 끝나는 즉시 교체. 폼은 그대로 두고 Cloudflare 의존성을 제거하면서, 챌린지 폴백과 중국 본토 엔드포인트를 얻으세요.

TTurnstileCurrent setup~10 minCaptchaLaDrop-in target

코드 변경 예시

Before — Turnstile
<div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
After — CaptchaLa
<button id="login-btn">Sign in</button>
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>
<script>
  loadCaptchala(() => Captchala.init({ appKey: 'YOUR_APP_KEY', action: 'login' })
    .onSuccess(res => onToken(res.token))
    .bindTo('#login-btn'));
</script>
Before — Turnstile server verify (Node)
const res = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    secret: process.env.TURNSTILE_SECRET,
    response: req.body['cf-turnstile-response'],
  }),
})
const data = await res.json()
if (!data.success) return res.status(400).json({ error: 'bot' })
After — CaptchaLa server verify (Node)
const res = await fetch('https://apiv1.captcha.la/v1/validate', {
  method: 'POST',
  headers: {
    'X-App-Key': process.env.CAPTCHALA_APP_KEY,
    'X-App-Secret': process.env.CAPTCHALA_APP_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ pass_token: req.body['captchala-token'] }),
})
const { data } = await res.json()
if (!data || !data.valid) return res.status(400).json({ error: 'bot' })

마이그레이션 단계

  1. 1

    가입하고 App Key + Secret 받기

    무료 CaptchaLa 계정을 만들고 사이트를 추가한 뒤, App Key(공개)와 App Secret(서버용)을 복사하세요. Cloudflare 계정은 필요 없습니다.

  2. 2

    위젯 태그 교체

    cf-turnstile를 captchala로, data-sitekey를 data-app-key로 바꾸세요. script src를 당사 CDN으로 변경합니다. 위젯 형태(div 자리표시자 + script 태그)는 동일합니다.

  3. 3

    숨김 필드명 변경

    Turnstile은 cf-turnstile-response를, CaptchaLa는 captchala-token을 삽입합니다. 대부분의 폼 핸들러는 필드를 이름으로 읽지 않지만, 만약 그렇다면 한 곳에서 상수만 변경하세요.

  4. 4

    서버 검증 호출 업데이트

    엔드포인트를 apiv1.captcha.la/v1/validate로 변경하세요. 당사는 JSON을 받으므로(Turnstile은 form-urlencoded 사용), Content-Type과 본문 형식을 업데이트하세요. 응답은 여전히 분기 코드용 valid 플래그(data.valid)를 반환합니다.

  5. 5

    점진적으로 배포

    대부분의 폼은 Turnstile을 유지하고, 트래픽이 적은 폼 하나에 먼저 CaptchaLa를 적용하세요. 하루 동안 전환율과 챌린지 비율을 지켜보세요. 만족스러우면 확대하면 됩니다. 최소 사용량도 계약도 없습니다.

자주 묻는 질문

Cloudflare CDN을 유지하면서 CaptchaLa를 쓸 수 있나요?

네. CaptchaLa는 어떤 CDN과도 독립적입니다. 고객 대부분은 CDN으로 Cloudflare를 유지하고 검증에 CaptchaLa를 사용합니다. 두 레이어는 충돌하지 않습니다.

Cloudflare 봇 탐지 규칙은 계속 적용되나요?

네. 그것들은 Turnstile과 별개인 Cloudflare WAF / Bot Management 기능입니다. Turnstile 위젯을 제거해도 Cloudflare 영역 설정에는 아무 영향이 없습니다.

Cloudflare Workers를 통해 Turnstile을 사용 중이라면?

Worker 쪽 마이그레이션도 동일합니다. Turnstile fetch를 CaptchaLa fetch로 교체하세요. Workers 런타임과 호환되는 스니펫이 문서에 있습니다.