바이브코더를 위한 Cloudflare막히는 순간을 푸는 1시간

원리

따라 하기

1. 설정 파일을 만듭니다. 프로젝트 폴더에서 npm create cloudflare@latest로 만들거나, 아래 파일을 직접 만들어도 됩니다. 꼭 있어야 하는 칸은 name과 compatibility_date 둘뿐입니다.

   wrangler.jsonc복사

   {
     "name": "ai-memo",
     "compatibility_date": "2026-09-30",
     "main": "./src/worker.ts",
     "assets": {
       "directory": "./dist",
       "not_found_handling": "single-page-application",
       "run_worker_first": ["/api/*"]
     },
     "observability": { "enabled": true }
   }

   directory는 빌드 결과 폴더(dist, build, out 등)입니다. not_found_handling은 화면 이동을 브라우저가 처리하는 앱(SPA)에서 새로고침 404를 막고, run_worker_first는 /api/* 요청을 항상 Worker가 받게 합니다. observability는 파트 5에서 볼 로그를 미리 켜 둡니다. API가 없는 정적 사이트라면 main과 run_worker_first를 뺍니다.

2. Cloudflare에 로그인합니다. 브라우저 창이 열리면 승인합니다.

   터미널복사

   npx wrangler login

3. 배포합니다. 끝나면 https://ai-memo.<내 계정>.workers.dev 같은 주소가 출력됩니다. 휴대폰으로 열어 보세요.

   터미널복사

   npx wrangler deploy

   "성공" 메시지만 믿지 말고 출력된 주소를 직접 열어 보세요. 같은 이름의 Pages 프로젝트가 있어서 성공이라고 떴는데 아무도 안 보는 주소로 올라간 사례가 있습니다.

4. (도메인이 있다면) 내 도메인을 붙입니다. 도메인의 네임서버가 Cloudflare로 옮겨져 있어야 합니다. 설정 파일에 아래 칸을 더하고 다시 배포하면, DNS 레코드와 HTTPS 인증서를 Cloudflare가 알아서 만듭니다. 대시보드의 Worker 설정에서 도메인을 추가해도 됩니다.

   wrangler.jsonc에 추가복사

   "routes": [{ "pattern": "memo.example.com", "custom_domain": true }]

   지금 보고 계신 이 페이지도 같은 방법으로 learn.daheyo.com에 올라가 있습니다.

막히면

AI에게 맡기기

원리

따라 하기

1. 프론트에서 키를 지웁니다. AI API를 직접 부르던 코드를 fetch('/api/summarize', ...)로 바꿉니다. AI에게 시키면 30초면 됩니다.

2. Worker에 대신 부르는 경로를 만듭니다. 키는 env에서만 읽습니다.

   src/worker.ts (뼈대)복사

   export default {
     async fetch(request: Request, env: Env): Promise<Response> {
       const url = new URL(request.url);
       if (url.pathname === '/api/summarize' && request.method === 'POST') {
         const { text } = await request.json<{ text: string }>();
         // callAi는 쓰는 AI 제공사에 맞게 AI에게 만들게 한다. 키는 env에서만 꺼낸다
         const summary = await callAi(text, env.AI_API_KEY);
         return Response.json({ summary });
       }
       return new Response('Not found', { status: 404 });
     },
   };

3. 키를 시크릿으로 등록합니다. 실행하면 값을 묻고, 새 버전을 만들어 바로 배포까지 합니다. 등록한 값은 Wrangler에서도 대시보드에서도 다시 볼 수 없습니다.

   터미널복사

   npx wrangler secret put AI_API_KEY

   대시보드에서 넣을 때는 Worker의 Settings → Variables and Secrets에서 유형을 Secret으로 고르고, Deploy를 눌러야 반영됩니다.

4. 로컬 개발용 키는 .dev.vars에 두고, 저장소에 안 올라가게 합니다. GitHub에서 키가 새는 경우 대부분이 여기서 생깁니다.

   .dev.vars (내 컴퓨터에만)복사

   AI_API_KEY=여기에-개발용-키

   .gitignore에 추가복사

   .dev.vars*
   .env*

   .dev.vars와 .env는 둘 중 하나만 쓰세요. .dev.vars가 있으면 .env의 값은 Worker에 들어가지 않습니다.

5. 레이트 리밋을 겁니다. 같은 사람이 너무 자주 부르면 429를 돌려줍니다. 기간(period)은 10초나 60초만 됩니다.

   wrangler.jsonc에 추가복사

   "ratelimits": [
     {
       "name": "LIMITER",
       "namespace_id": "1001",
       "simple": { "limit": 10, "period": 60 }
     }
   ]

   src/worker.ts, AI를 부르기 전에복사

   const ip = request.headers.get('cf-connecting-ip') ?? 'unknown';
   const { success } = await env.LIMITER.limit({ key: ip });
   if (!success) return new Response('잠시 후 다시 시도해 주세요', { status: 429 });

   namespace_id가 같으면 다른 Worker와 카운터를 같이 씁니다. 앱마다 다른 숫자를 쓰세요. Wrangler 4.36.0 이상이 필요하고, 이 바인딩은 대시보드에 나타나지 않습니다(429는 로그에서 확인).

6. 다시 배포하고 F12로 확인합니다. Sources 탭과 빌드 결과 폴더(dist) 어디에도 키가 없어야 합니다.

돈은 어디서 새는가

막히면

AI에게 맡기기

원리: 데이터마다 서랍이 다르다

따라 하기

1. 데이터베이스를 만듭니다. 출력된 바인딩 설정(d1_databases)을 wrangler.jsonc에 붙여 넣습니다.

   터미널복사

   npx wrangler d1 create memo-db

2. 테이블을 마이그레이션 파일로 만듭니다. 나중에 컬럼을 바꿀 때도 "새 파일 하나"로 끝납니다.

   터미널복사

   npx wrangler d1 migrations create memo-db create_notes

   migrations/0001_create_notes.sql복사

   CREATE TABLE notes (
     id         INTEGER PRIMARY KEY AUTOINCREMENT,
     content    TEXT NOT NULL,
     summary    TEXT NOT NULL DEFAULT '',
     created_at TEXT NOT NULL
   );

   터미널: 운영 DB에 적용복사

   npx wrangler d1 migrations apply memo-db --remote

   규칙은 하나입니다. 이미 적용한 파일은 고치지 않고, 바꿀 게 생기면 새 파일을 만듭니다.

3. Worker에 목록과 저장 경로를 만듭니다. SQL은 AI에게 맡기고, 구조만 확인하세요. 사용자 입력은 반드시 .bind()로 넘깁니다.

   src/worker.ts 중에서복사

   // GET /api/notes: 목록
   const { results } = await env.DB
     .prepare('SELECT id, content, summary, created_at FROM notes ORDER BY created_at DESC LIMIT 50')
     .all();
   
   // POST /api/notes: 저장. 입력은 문자열로 이어 붙이지 않고 bind()로 넘긴다
   await env.DB
     .prepare('INSERT INTO notes (content, summary, created_at) VALUES (?1, ?2, ?3)')
     .bind(content, summary, new Date().toISOString())
     .run();

4. 배포하고 확인합니다. 메모 작성 → 새로고침 → 휴대폰에서 열기. 둘 다 남아 있어야 합니다.

5. 대시보드의 D1 화면에서 실제 행을 봅니다. 내 데이터가 어디 있는지 눈으로 확인해 두면 다음에 덜 불안합니다. 같은 화면의 Metrics에서 읽은 행과 쓴 행 수도 볼 수 있습니다.

꼭 알아 둘 두 가지

막히면

npx wrangler d1 create memo-db --location apac

AI에게 맡기기

원리

따라 하기

1. Zero Trust를 켭니다. 계정에서 처음 쓰면 팀 이름을 정하는 활성화 절차가 먼저 나옵니다.

2. Worker에 Access를 겁니다. 대시보드 Workers & Pages → 내 Worker → Access 탭 → Protect this Worker behind Access → All traffic.

   Previews only를 고르면 미리보기 주소만 잠기고 실제 서비스는 열려 있습니다. 가장 흔한 착각입니다. All traffic이면 workers.dev 주소, 내 도메인, 미리보기 주소가 한 번에 보호되고, 나중에 도메인을 더 붙여도 유지됩니다. 옆의 "Protect all Workers"는 앞으로 만들 Worker까지 계정의 모든 Worker를 잠그니, 공개할 Worker가 있다면 누르지 마세요.

3. 누구를 들일지 정합니다. 간편 화면의 선택지는 두 가지입니다.

   • Cloudflare account: 내 Cloudflare 계정의 구성원. 나만 쓰는 도구라면 이걸로 충분합니다.
   • Email domain: 특정 도메인의 이메일. 회사 도메인이 있을 때 씁니다. gmail.com을 넣으면 전 세계 Gmail 사용자가 통과합니다.

   지인 몇 명처럼 특정 이메일만 들이려면 Zero Trust → Access에서 해당 앱의 정책을 편집해 이메일 주소를 넣으세요.

4. 시크릿 창으로 확인합니다. 로그인 화면 → 이메일 입력 → 메일로 온 코드 입력 → 앱 진입. 허용하지 않은 이메일로도 시도해 막히는지 봅니다.

5. 메모를 사용자별로 나눕니다. 새 마이그레이션으로 이메일 컬럼과 인덱스를 더하고, 저장과 조회를 로그인한 이메일 기준으로 바꿉니다.

   migrations/0002_add_user_email.sql복사

   ALTER TABLE notes ADD COLUMN user_email TEXT;
   CREATE INDEX notes_user ON notes (user_email, created_at);

6. 레이트 리밋 키를 IP에서 이메일로 바꿉니다. 파트 2에서 "익명 앱의 타협"이라고 했던 부분입니다.

함정: Worker에서 로그인한 이메일 읽기

import { createRemoteJWKSet, jwtVerify } from 'jose';

let jwks: ReturnType<typeof createRemoteJWKSet> | null = null;

export async function userEmail(request: Request, env: Env): Promise<string | null> {
  const token = request.headers.get('cf-access-jwt-assertion');
  if (!token) return null;
  // 공개키는 주기적으로 바뀐다. 코드에 고정하지 않고 certs 주소에서 받는다
  jwks ??= createRemoteJWKSet(new URL(`${env.TEAM_DOMAIN}/cdn-cgi/access/certs`));
  try {
    const { payload } = await jwtVerify(token, jwks, {
      issuer: env.TEAM_DOMAIN,   // https://팀이름.cloudflareaccess.com
      audience: env.POLICY_AUD,  // Access 앱의 AUD 태그
    });
    return typeof payload.email === 'string' ? payload.email.toLowerCase() : null;
  } catch {
    return null;
  }
}

TEAM_DOMAIN과 POLICY_AUD는 공식 예제가 쓰는 이름입니다. 둘 다 비밀이 아니라서 wrangler.jsonc의 vars에 둬도 됩니다. 이 자료를 만든 Daheyo Works의 내부 도구도 같은 구조(정적 자산 + Access + jose 검증)로 운영하고 있습니다.

Access가 맞는 경우와 아닌 경우

Access는 원래 직원과 협력사가 회사 내부 도구에 들어가도록 만든 문지기입니다. 회원가입, 프로필, 비밀번호 찾기가 필요해지면 전용 인증 서비스로 넘어가세요. 어느 쪽이든 인증 코드를 직접 짜지 않는 것이 원칙입니다.

막히면

AI에게 맡기기

습관 1. 로그 보기

습관 2. 되돌리기

npx wrangler rollback

# 1. 지금 시점의 북마크를 적어 둔다
npx wrangler d1 time-travel info memo-db
# 2. 원하는 시점으로 되돌린다
npx wrangler d1 time-travel restore memo-db --timestamp=2026-10-02T09:00:00+09:00

습관 3. 배포 전에 커밋하기

덤: 봇과 스팸 막기

AI에게 맡기기

실제로 있었던 일

• My deploy said Success. It went to a URL nobody visits.

  Workers와 Pages 프로젝트 이름이 같아, 성공이라고 떴는데 엉뚱한 곳에 배포됐다 (파트 1)

• Korean KT traffic routed to LAX instead of ICN

  한국 방문자가 서울 대신 LA 데이터센터로 간 커뮤니티 보고 (파트 1)

• Your Cloudflare Pages secret is set. Production cannot see it.

  시크릿을 넣었는데 프로덕션이 못 봤다 (파트 2)

• Designing a Guest AI Image Generation Flow Without Letting Free Usage Run Wild

  비회원에게 AI 기능을 열면서 무료 사용 폭주를 막는 설계. 구조 참고용 (파트 2)

• Why Cloudflare bills spike: 8 D1 and Durable Objects cases from 2026

  인덱스 누락 등으로 요금이 급증한 사례 모음 (파트 3)

• Crawlers burned my free Postgres hours in 22 days

  크롤러가 무료 데이터베이스 할당을 다 써 버린 사례 (파트 3)

• workerd #1346: 100,000 iterations of PBKDF2

  Workers의 PBKDF2 반복 횟수 상한. 직접 만든 로그인 코드가 운영에서 실패한 이유 (파트 4)

• What Cloudflare's free plan alerts you about, and what you check yourself

  무료 플랜이 알려 주는 것과 직접 확인해야 하는 것 (파트 5)

대부분 개인 경험담입니다. "이런 일이 있었다"는 참고로 읽어 주세요.