[Cloudflare] Workers 설치방법 - 서버리스 엣지 컴퓨팅 시작하기 [1편]

 

안녕하세요!

재아군의 관찰인생입니다.

 

오늘은 웹 개발의 패러다임을 바꾸고 있는 Cloudflare Workers에 대해 이야기해보려고 합니다.

서버리스 엣지 컴퓨팅이라는 말, 한 번쯤 들어보셨을 텐데요.

직접 설치부터 배포까지 해보면서 그 매력을 느껴보겠습니다.

이 글은 시리즈 1편으로, Workers의 개념부터 설치 및 첫 배포까지를 다룹니다.

 

 

---

 

1. Cloudflare Workers란 무엇인가?

 

Cloudflare Workers는 Cloudflare의 글로벌 엣지 네트워크에서 JavaScript, TypeScript, Rust, Python 코드를 실행할 수 있는 서버리스 컴퓨팅 플랫폼입니다. 2017년에 처음 공개되었으며, 전 세계 300개 이상의 데이터센터에서 사용자와 가장 가까운 위치에서 코드가 실행됩니다.

 

기존의 서버 운영 방식에는 다음과 같은 문제가 있었습니다.

 

기존 서버 운영의 4가지 문제점:

 

1. 콜드 스타트 지연: AWS Lambda 같은 기존 서버리스 플랫폼은 함수가 일정 시간 호출되지 않으면 컨테이너가 내려가고, 다시 호출 시 수백 밀리초에서 수 초까지 콜드 스타트가 발생합니다. 사용자 경험에 직접적인 영향을 줍니다.
2. 리전 종속성: 전통적인 클라우드 서비스는 특정 리전(us-east-1, ap-northeast-2 등)에 서버를 배치합니다. 한국에 서버를 두면 북미 사용자는 느리고, 미국에 두면 아시아 사용자가 느립니다. 글로벌 서비스를 위해 멀티 리전을 구성하면 비용과 복잡도가 기하급수적으로 증가합니다.
3. 인프라 관리 부담: EC2 인스턴스의 OS 패치, 보안 업데이트, 오토스케일링 설정, 로드밸런서 구성 등 애플리케이션 로직과 무관한 인프라 작업에 개발 시간의 상당 부분을 소비하게 됩니다.
4. 확장 비용 비효율: 트래픽이 갑자기 10배 증가하면 서버를 미리 프로비저닝해야 하고, 트래픽이 줄면 유휴 리소스 비용이 발생합니다. 예측 불가능한 트래픽 패턴을 가진 서비스에서 비용 최적화가 매우 어렵습니다.

 

Cloudflare Workers는 이 모든 문제를 V8 아이솔레이트(Isolate) 기반의 엣지 컴퓨팅으로 해결합니다.

컨테이너가 아닌 V8 엔진의 경량 아이솔레이트를 사용하기 때문에 콜드 스타트가 사실상 0ms이며, 전 세계 모든 엣지 노드에 자동 배포됩니다.

 

 

---

 

2. 핵심 특징 & 기능 분석

 

Cloudflare Workers가 주목받는 이유를 5가지 핵심 특징으로 살펴보겠습니다.

 

2-1. 제로 콜드 스타트 (0ms Cold Start)

 

기존 서버리스 플랫폼이 컨테이너 기반으로 동작하는 반면, Workers는 Chrome V8 엔진의 아이솔레이트를 사용합니다.

아이솔레이트는 컨테이너보다 약 100배 가벼우며, 새로운 실행 환경을 5ms 이내에 생성합니다.

AWS Lambda의 평균 콜드 스타트가 100~500ms인 것과 비교하면 극적인 차이입니다.

이는 API 게이트웨이, 인증 미들웨어 등 지연에 민감한 워크로드에 특히 유리합니다.

 

2-2. 글로벌 엣지 배포 (300+ 도시)

 

Workers에 코드를 배포하면 전 세계 300개 이상 도시의 Cloudflare 데이터센터에 자동으로 복제됩니다.

별도의 멀티 리전 구성 없이도 한국 사용자는 서울 엣지에서, 미국 사용자는 가장 가까운 미국 엣지에서 응답을 받습니다.

이를 통해 글로벌 사용자 모두에게 50ms 이내의 응답 시간을 제공할 수 있습니다.

 

2-3. Web Standards API 호환

 

Workers 런타임은 Service Workers API를 기반으로 합니다. fetch, Request, Response, Headers, URL, crypto, TextEncoder/Decoder 등 웹 표준 API를 그대로 사용할 수 있어, 브라우저에서 동작하던 코드를 최소한의 수정으로 서버사이드에서 실행할 수 있습니다.

Node.js 호환 API도 지속적으로 추가되고 있어 Buffer, AsyncLocalStorage, EventEmitter 등을 사용할 수 있습니다.

 

2-4. 통합 스토리지 에코시스템

 

Workers는 다양한 스토리지 솔루션과 네이티브로 통합됩니다:

• KV (Key-Value): 글로벌하게 분산된 키-밸류 스토어. 읽기에 최적화되어 설정값, 캐시 데이터 저장에 적합합니다.
• R2: S3 호환 오브젝트 스토리지. 이그레스(egress) 비용이 무료입니다.
• D1: SQLite 기반 서버리스 데이터베이스. Workers에서 SQL 쿼리를 직접 실행할 수 있습니다.
• Durable Objects: 강한 일관성이 필요한 상태 관리에 사용합니다. 실시간 협업, 게임 서버 등에 활용됩니다.
• Queues: 메시지 큐 서비스로, 비동기 작업 처리에 사용합니다.

 

2-5. 넉넉한 무료 티어

 

Free 플랜에서 일일 100,000 요청까지 무료로 사용할 수 있습니다.

요청당 CPU 실행 시간은 10ms로 제한되지만, 대부분의 API 라우팅, 리다이렉션, 간단한 데이터 처리에는 충분합니다.

Paid 플랜($5/월)은 1,000만 요청 포함이며, 요청당 CPU 시간이 30ms로 늘어나고 Cron Triggers, Durable Objects 등 고급 기능을 사용할 수 있습니다.

 

 

---

 

3. 기술 아키텍처 & 동작 원리

 

Cloudflare Workers의 내부 구조를 이해하면 성능 최적화와 디버깅에 큰 도움이 됩니다.

 

핵심 구성 요소

 

구성 요소	역할	특징
V8 Isolate	코드 실행 환경	프로세스당 수천 개 생성 가능, 메모리 128MB 제한
Runtime API	웹 표준 + Workers 전용 API	fetch, KV, R2, D1 바인딩 제공
Wrangler CLI	개발/배포 도구	로컬 개발 서버, 배포, 시크릿 관리
Edge Network	글로벌 실행 인프라	300+ 도시, Anycast 라우팅
Miniflare	로컬 시뮬레이터	Wrangler v3에 내장, 로컬에서 Workers 환경 재현

 

요청 처리 흐름

 

클라이언트의 요청이 Workers에 도달하기까지의 흐름을 코드로 표현하면 다음과 같습니다.

 

// Workers의 요청 처리 라이프사이클
export default {
  // 1. HTTP 요청 핸들러 — 모든 요청의 진입점
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext
  ): Promise<Response> {
    const url = new URL(request.url);

    // 2. 라우팅 — URL 경로에 따라 분기
    if (url.pathname === '/api/hello') {
      return new Response(
        JSON.stringify({
          message: 'Hello from Cloudflare Workers!',
          timestamp: new Date().toISOString(),
          colo: request.cf?.colo,        // 처리한 데이터센터 코드 (예: ICN)
          country: request.cf?.country,  // 클라이언트 국가 코드
        }),
        {
          headers: { 'Content-Type': 'application/json' },
        }
      );
    }

    // 3. KV 스토어 연동 예시
    if (url.pathname.startsWith('/api/config/')) {
      const key = url.pathname.replace('/api/config/', '');
      const value = await env.MY_KV_NAMESPACE.get(key);

      if (!value) {
        return new Response('Not Found', { status: 404 });
      }
      return new Response(value, {
        headers: { 'Content-Type': 'application/json' },
      });
    }

    // 4. 정적 자산 또는 기본 응답
    return new Response('Cloudflare Workers is running!', { status: 200 });
  },

  // 5. 스케줄 트리거 — Cron으로 주기적 작업 실행
  async scheduled(
    controller: ScheduledController,
    env: Env,
    ctx: ExecutionContext
  ): Promise<void> {
    ctx.waitUntil(doScheduledTask(env));
  },
};

// 환경 변수 및 바인딩 타입 정의
interface Env {
  MY_KV_NAMESPACE: KVNamespace;
  DB: D1Database;
  BUCKET: R2Bucket;
  API_SECRET: string;
}

 

설계 원칙 4가지

 

1. 아이솔레이션 우선: 각 Workers는 독립된 V8 아이솔레이트에서 실행되어, 하나의 Worker 오류가 다른 Worker에 영향을 주지 않습니다.
2. 이벤트 드리븐: 요청(fetch), 스케줄(scheduled), 큐(queue), 이메일(email) 등 이벤트에 반응하는 구조로 설계되었습니다.
3. 제로 트러스트 보안: Workers는 기본적으로 외부 네트워크 접근만 가능하며, 내부 리소스 접근은 바인딩을 통해서만 허용됩니다.
4. 엣지 퍼스트: 모든 연산은 사용자에게 가장 가까운 엣지에서 우선 처리되고, 오리진 서버로의 요청은 최소화합니다.

 

---

 

4. 실무 활용 가이드

 

Workers 설치 및 첫 프로젝트 만들기

 

Workers 개발 환경을 구축하는 과정을 단계별로 진행하겠습니다.

 

# 1단계: Node.js 확인 (v16.17 이상 필요)
node --version
# v20.11.0

# 2단계: Wrangler CLI 설치 (Workers 전용 개발 도구)
npm install -g wrangler@latest

# 설치 확인
wrangler --version
# ⛅️ wrangler 3.91.0

# 3단계: Cloudflare 계정 인증
wrangler login
# 브라우저가 열리면 Cloudflare 계정으로 로그인 → 권한 허용

# 4단계: 새 프로젝트 생성
npm create cloudflare@latest my-first-worker
# 프롬프트:
#   What would you like to start with? → Hello World example
#   Which template? → Hello World Worker
#   Which language? → TypeScript
#   Do you want to deploy? → No

# 5단계: 프로젝트 디렉토리 진입 및 의존성 설치
cd my-first-worker
npm install

# 6단계: 로컬 개발 서버 실행
wrangler dev
# ⎔ Starting local server...
# Ready on http://localhost:8787

# 7단계: 배포 (Cloudflare 엣지 네트워크에 전 세계 배포)
wrangler deploy
# Published my-first-worker (0.20 sec)
# https://my-first-worker.<your-subdomain>.workers.dev

 

프로젝트가 생성되면 wrangler.toml 설정 파일이 핵심입니다:

 

# wrangler.toml — Workers 프로젝트 설정 파일
name = "my-first-worker"
main = "src/index.ts"
compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]

# KV 네임스페이스 바인딩
[[kv_namespaces]]
binding = "MY_KV"
id = "abc123def456"

# D1 데이터베이스 바인딩
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxxx-yyyy-zzzz"

# R2 버킷 바인딩
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-assets"

# 환경별 설정
[env.production]
routes = [
  { pattern = "api.example.com/*", zone_name = "example.com" }
]

# Cron 트리거 설정
[triggers]
crons = ["0 */6 * * *"]  # 6시간마다 실행

 

기존 환경에 Workers 도입하기

 

단계	작업	구체적인 방법	예상 소요 시간
1단계	기존 API 분석	지연에 민감한 엔드포인트 식별, 캐싱 가능 여부 판단	1~2일
2단계	엣지 미들웨어 적용	인증 토큰 검증, CORS 처리, 요청 헤더 가공을 Workers로 이전	2~3일
3단계	API 라우팅 전환	Workers에서 라우팅 후 오리진 서버로 프록시, 점진적으로 Workers 네이티브 핸들러 추가	1~2주
4단계	스토리지 마이그레이션	정적 자산을 R2로 이전, 설정값을 KV로, 사용자 데이터를 D1으로 마이그레이션	2~4주

 

팀 활용 팁

 

• 시크릿 관리: wrangler secret put API_KEY 명령으로 환경 변수를 안전하게 등록합니다. .dev.vars 파일은 로컬 개발 전용이며, .gitignore에 반드시 추가합니다.
• 프리뷰 배포: wrangler deploy --env preview로 별도 환경에 배포한 뒤 QA를 진행합니다. 프로덕션에 영향 없이 테스트가 가능합니다.
• 로그 확인: wrangler tail로 실시간 로그를 확인합니다. --format json 플래그를 추가하면 구조화된 로그를 확인할 수 있습니다.
• 로컬 개발: wrangler dev --remote는 실제 Cloudflare 환경에 연결하여 KV, D1 등 실제 데이터를 사용한 개발이 가능합니다.

 

---

 

5. 경쟁 기술 비교 분석

 

Cloudflare Workers와 경쟁 서버리스 엣지 플랫폼을 실질적으로 비교해보겠습니다.

 

항목	Cloudflare Workers	AWS Lambda@Edge	Vercel Edge Functions	Deno Deploy
런타임	V8 Isolate	Node.js Container	V8 (Edge Runtime)	V8 (Deno)
콜드 스타트	~0ms	100~500ms	~0ms	~0ms
글로벌 엣지 노드	300+ 도시	13개 리전 (CloudFront POP은 400+이나 Lambda 실행은 리전 한정)	~20개 리전 (Vercel Edge Network)	35+ 리전
무료 티어	10만 요청/일	100만 요청/월 (Lambda 기준)	10만 실행/월	10만 요청/일
최대 실행 시간	30초 (Paid)	30초 (Lambda@Edge), 5분 (Lambda)	25초	50ms CPU (Free)
번들 크기 제한	10MB (압축 후)	50MB (Lambda)	4MB (Edge)	제한 없음
스토리지 통합	KV, R2, D1, Durable Objects, Queues	DynamoDB, S3, SQS 등 AWS 생태계 전체	KV (beta), Blob (beta)	Deno KV
가격 (유료)	$5/월 + $0.50/백만 요청	$0.60/백만 요청 + 컴퓨팅 시간	$20/월 (Pro)	$10/월
로컬 개발	Wrangler dev (Miniflare)	SAM CLI / LocalStack	vercel dev	deno serve

 

선택 가이드

 

• Cloudflare Workers: 글로벌 엣지 성능이 최우선이고, KV/R2/D1 등 통합 스토리지를 활용하려는 경우. 특히 CDN과 컴퓨팅을 하나의 플랫폼에서 관리하고 싶을 때 최적입니다.
• AWS Lambda: 이미 AWS 생태계(RDS, SQS, SNS 등)에 깊이 투자한 조직에서 기존 인프라와의 긴밀한 통합이 필요한 경우.
• Vercel Edge Functions: Next.js 기반 프로젝트에서 프론트엔드 배포와 엣지 함수를 하나의 워크플로우로 관리하고 싶은 경우.
• Deno Deploy: Deno 런타임을 선호하거나, TypeScript 네이티브 환경에서 심플한 엣지 함수를 빠르게 배포하고 싶은 경우.

 

---

 

6. 도입 시 베스트 프랙티스

 

5가지 핵심 원칙

 

1. 작게 시작하기: 처음부터 전체 API를 Workers로 옮기지 마세요. 인증 미들웨어, A/B 테스트 라우팅, 헤더 변환 같은 단일 기능부터 시작합니다. 하나의 Worker가 하나의 역할만 담당하도록 설계하면 디버깅과 유지보수가 쉬워집니다.
2. 바인딩 기반 아키텍처 설계: Workers의 강점은 KV, R2, D1, Durable Objects 등과의 네이티브 바인딩입니다. 외부 HTTP 호출보다 바인딩을 통한 접근이 훨씬 빠르고 안정적입니다. wrangler.toml에 필요한 바인딩을 선언하고, Env 타입으로 타입 안전성을 확보하세요.
3. 에러 핸들링 표준화: 엣지에서 발생하는 에러는 즉시 감지하기 어렵습니다. 모든 Worker에 표준화된 에러 핸들링을 적용하고, ctx.waitUntil()을 사용해 에러 로그를 외부 서비스(Sentry, Datadog 등)로 비동기 전송합니다.
4. 캐싱 전략 수립: Workers는 Cache API를 직접 제어할 수 있습니다. caches.default를 활용하여 오리진 응답을 엣지에 캐싱하면 오리진 서버 부하를 극적으로 줄일 수 있습니다. Cache-Control 헤더와 함께 cf.cacheTtl 옵션을 적절히 설정하세요.
5. 모니터링 체계 구축: Cloudflare 대시보드의 Workers Analytics로 요청 수, CPU 시간, 에러율을 모니터링합니다. 일일 CPU 시간 사용량이 한도의 80%에 도달하면 알림을 설정하여 예기치 않은 비용 증가를 방지하세요.

 

흔한 실수와 해결 방법

 

실수	증상	해결 방법
동기식 무거운 연산	CPU 시간 초과로 Worker 강제 종료	무거운 연산은 Queues로 분리하고, Worker는 요청 접수만 담당
전역 변수에 상태 저장	요청마다 다른 결과 반환, 메모리 누수	Workers는 요청 간 상태를 공유하지 않는다고 가정. 상태는 KV 또는 Durable Objects에 저장
await 누락	비동기 작업 결과가 Promise 객체로 반환	모든 바인딩 호출(env.KV.get(), env.DB.prepare())에 await 필수
wrangler.toml에 시크릿 기입	깃 히스토리에 API 키 노출	시크릿은 반드시 wrangler secret put 명령 사용, .dev.vars는 .gitignore에 추가
과도한 서브리퀘스트	50개 서브리퀘스트 제한 초과 에러	Promise.all()로 병렬 처리하되, 필요 최소한의 호출로 설계. 캐싱 적극 활용

 

---

 

7. 향후 전망 & 발전 방향

 

Cloudflare Workers의 4가지 발전 방향

 

1. AI 추론 엣지 실행: Cloudflare는 이미 Workers AI를 통해 LLM, 이미지 생성, 음성 인식 등의 AI 모델을 엣지에서 직접 실행할 수 있는 기능을 제공하고 있습니다. GPU 인프라가 전 세계 엣지에 확대 배치되면서, 사용자에게 가장 가까운 위치에서 AI 추론이 실행되는 시대가 열리고 있습니다. AI 에이전트의 백엔드로 Workers가 자리잡을 가능성이 높습니다.
2. Python 런타임 정식 지원: 현재 베타 상태인 Python Workers가 정식 출시를 앞두고 있습니다. NumPy, Pandas 같은 데이터 과학 라이브러리를 엣지에서 실행할 수 있게 되면, 데이터 전처리와 ML 파이프라인의 엣지 실행이 현실화됩니다.
3. 풀스택 엣지 플랫폼 완성: D1(데이터베이스), R2(오브젝트 스토리지), KV(키-밸류), Queues(메시지 큐), Hyperdrive(데이터베이스 커넥션 풀링), Vectorize(벡터 DB)까지 갖춰지면서, Cloudflare만으로 백엔드 인프라 전체를 구성할 수 있게 되고 있습니다. 별도의 AWS나 GCP 없이 엣지 네이티브 풀스택 아키텍처가 가능해집니다.
4. RPC 기반 Worker 간 통신: Service Bindings와 RPC를 통해 마이크로서비스 아키텍처를 엣지에서 구현할 수 있습니다. Workers 간 HTTP 오버헤드 없이 직접 함수를 호출할 수 있어, 복잡한 비즈니스 로직도 엣지에서 처리하는 방향으로 발전하고 있습니다.

 

개발자에게 주는 시사점

 

• 엣지 퍼스트 사고방식: "서버를 어디에 둘까?"가 아닌 "서버가 어디에나 있다"는 관점의 전환이 필요합니다.
• V8 아이솔레이트 이해: Workers의 특성을 이해하면 Node.js와의 차이(전역 상태 비공유, 제한된 API 등)를 자연스럽게 활용할 수 있습니다.
• 점진적 도입 전략: 당장 전체 마이그레이션이 아닌, CDN 커스터마이징, API 게이트웨이, 인증 미들웨어 등 확실한 성과를 낼 수 있는 영역부터 적용하는 것이 현실적입니다.
• 생태계 성장에 주목: Cloudflare의 스토리지, AI, 네트워킹 서비스가 빠르게 확장되고 있으므로, Workers를 익혀두면 향후 다양한 워크로드에 활용 범위가 넓어질 것입니다.

 

---

 

마무리

 

오늘은 Cloudflare Workers의 개념부터 설치, 그리고 실무 활용까지 살펴보았습니다.

 

핵심을 정리하면:

• Cloudflare Workers는 V8 아이솔레이트 기반으로 콜드 스타트 없이 전 세계 300개 이상의 엣지에서 코드를 실행합니다.
• Wrangler CLI로 설치부터 배포까지 5분 이내에 완료할 수 있으며, 무료 티어로 일 10만 요청까지 지원합니다.
• KV, R2, D1, Durable Objects 등 통합 스토리지와 네이티브 바인딩으로 별도 인프라 없이 풀스택 엣지 애플리케이션을 구축할 수 있습니다.
• 기존 서버에 엣지 미들웨어부터 점진적으로 도입하는 것이 가장 효과적인 전략입니다.

 

다음 2편에서는 Workers에서 KV와 D1을 활용한 실제 API 구축을 다룰 예정입니다.

Cloudflare Workers로 여러분의 서비스를 글로벌 엣지로 확장해보세요!

 

궁금한 점이나 경험을 공유하고 싶으시다면, 댓글로 남겨주세요.

좋아요와 공유는 큰 힘이 됩니다.

감사합니다!