Source: Dev.to

5가지 치명적인 실수와 회피 방법

Cloudflare Workers를 프로덕션에 배포하면서 내가 저지른 실수들

Cloudflare Workers는 서버리스 환경을 손쉽게 활용할 수 있게 해 주지만, 처음 배포할 때는 생각보다 많은 함정에 빠지기 쉽습니다. 아래에서는 제가 직접 겪은 5가지 실수와 이를 방지하기 위한 실전 팁을 공유합니다.

---

1️⃣ 비밀키와 환경 변수를 하드코딩했다

실수

// ❌ 잘못된 예시
const API_KEY = "12345-abcdef-67890";

코드에 직접 API 키, 토큰, 비밀번호 등을 넣어두면 버전 관리 시스템에 노출될 위험이 있습니다. 또한, 다른 환경(스테이징, 프로덕션)에서 같은 코드를 재사용하기가 어렵습니다.

해결책

• wrangler.toml에 vars 혹은 kv_namespaces를 사용해 환경 변수를 선언합니다.
• 실제 비밀값은 Cloudflare Dashboard → Workers → Settings → Secrets에 저장하고, wrangler secret put <NAME> 명령어로 주입합니다.

# 비밀값 추가 (예시)
wrangler secret put API_KEY

Tip: CI/CD 파이프라인에서 wrangler secret 명령을 자동화하면, 배포마다 비밀값을 안전하게 주입할 수 있습니다.

---

2️⃣ 에러 처리를 무시했다

실수

// ❌ 에러를 잡지 않음
fetch(request).then(res => res.json()).then(data => {
  // do something
});

예외가 발생하면 워커가 즉시 종료되고, 클라이언트는 500 에러를 받게 됩니다. 또한, 로그를 통해 원인을 파악하기가 어렵습니다.

해결책

• try / catch 블록과 fetch의 catch를 적극 활용합니다.
• Cloudflare의 Workers KV 혹은 Durable Objects에 에러 로그를 저장하거나, Logpush를 통해 외부 로그 시스템(예: Datadog, Splunk)으로 전송합니다.

// ✅ 안전한 예시
async function handleRequest(request) {
  try {
    const response = await fetch(request);
    const data = await response.json();
    return new Response(JSON.stringify(data), { status: 200 });
  } catch (err) {
    console.error("Fetch error:", err);
    return new Response("Internal Server Error", { status: 500 });
  }
}

---

3️⃣ 라우팅을 제대로 설정하지 않았다

실수

wrangler.toml에 라우트를 지정하지 않으면 워커가 전체 트래픽을 가로채거나, 의도한 경로에서 동작하지 않을 수 있습니다.

# ❌ 라우트 누락
name = "my-worker"
type = "javascript"

해결책

• 정확한 라우트 패턴을 명시합니다.
• 여러 도메인·서브도메인에 배포할 경우, routes 배열을 활용합니다.

# ✅ 올바른 라우트 설정
name = "my-worker"
type = "javascript"

routes = [
  "example.com/api/*",
  "api.example.com/*"
]

Tip: wrangler dev 로컬 서버를 사용할 때도 동일한 라우트 패턴을 적용해 테스트하면, 프로덕션 배포 시 실수를 크게 줄일 수 있습니다.

---

4️⃣ 로컬 테스트를 건너뛰었다

실수

코드를 바로 wrangler publish 로 배포하고, 문제를 실제 트래픽에서 발견하는 경우가 많습니다.

해결책

• wrangler dev 로 로컬에서 실제 Cloudflare 환경과 동일하게 실행합니다.
• Unit test와 Integration test를 작성하고, CI 파이프라인에 포함시킵니다.

# 로컬 개발 서버 실행
wrangler dev

Tip: wrangler dev --local 옵션을 사용하면, 외부 API 호출을 모킹(mock)하여 비용을 절감하면서도 로직을 검증할 수 있습니다.

---

5️⃣ 모니터링과 로깅을 무시했다

실수

배포 후 성능 지표나 오류 로그를 확인하지 않으면, 문제 발생 시 원인 파악이 어려워집니다.

해결책

• Cloudflare Dashboard의 Analytics 탭을 활용해 요청 수, 지연 시간, 오류 비율을 모니터링합니다.
• console.log, console.error 로 출력된 로그를 Logpush와 연동해 외부 로그 수집 서비스로 전송합니다.

// 로그 예시
console.log("Request received:", request.url);

• Alert를 설정해 특정 오류율이 초과될 경우 Slack, Email 등으로 알림을 받도록 합니다.

---

📌 요약

이 다섯 가지 실수를 피하면 Cloudflare Workers를 보다 안전하고 안정적으로 프로덕션에 배포할 수 있습니다. Happy coding! 🚀

개요

저는 50개가 넘는 Cloudflare Workers를 프로덕션에 배포했습니다. 솔직히 말해서, 저는 책에 나오는 모든 실수를 저질렀습니다.

• 일부는 사소한 불편함에 불과했습니다.
• 다른 일부는 큰 비용을 초래했습니다. 한 실수 때문에 우리 회사는 한 아침 전체가 다운됐고, 또 다른 실수는 사용자가 보고하기 전까지 놓친 보안 취약점을 노출시켰습니다.

각 실수는 저에게 교훈을 주었습니다. 오랜 시간(고통스럽게) 배우고 난 뒤, 이제는 제대로 작동하는 시스템을 갖추게 되었습니다.

오늘은 제가 저지른 실수들과, 여러분이 그것을 피할 수 있는 방법을 공유하고자 합니다.

Source: …

실수 #1: 보안 체크리스트 없이 배포하기

내가 한 일

Worker를 만들고, 로컬에서 테스트한 뒤 배포했습니다. 괜찮아 보였죠.

놓친 점

• CORS 설정이 없음 (브라우저가 요청을 차단)
• 속도 제한이 없음 (요청이 폭주)
• 보안 헤더가 없음 (XSS 공격에 노출)
• 비밀 키를 환경 변수에 하드코딩 (Cloudflare Secrets를 사용했지만 입력 검증을 하지 않음)

결과

내 API가 대량의 요청에 휩싸였습니다. 속도 제한이 없어서 서버가 다운됐고, 한 사용자가 악성 데이터를 주입할 수 있다고 보고했습니다.

예방 방법

배포 전 보안 체크리스트를 작성하세요:

• ✅ 도메인 전용으로 CORS 설정 (와일드카드 금지)
• ✅ 속도 제한 활성화
• ✅ 모든 엔드포인트에 입력 검증 적용
• ✅ 보안 헤더 설정 (HSTS, CSP 등)
• ✅ 비밀은 코드가 아닌 Cloudflare에 저장
• ✅ JWT 토큰에 만료 시간 부여
• ✅ 오류 메시지가 시스템 정보를 유출하지 않도록 처리

이제 저는 모든 배포마다 체크리스트를 사용합니다. 10분이면 충분하고, 수많은 골칫거리를 예방할 수 있습니다.

이것이 바로 제가 Workers를 안전하게 배포하기 위해 7‑체크리스트 시스템(및 프로덕션‑레디 코드 템플릿)을 만든 이유입니다. 보안은 그 중 하나에 불과합니다.
전체 가이드를 $29에 구매하기 →

Source: …

실수 #2: 프로덕션 전에 성능 테스트를 하지 않음

내가 한 일

로컬에서 빌드하고, 스테이징에서 테스트한 뒤, 프로덕션에 배포했습니다.

놓친 점

• 느린 데이터베이스 쿼리
• 캐시 설정 누락
• 일부 엔드포인트가 2 초 이상 응답

결과

사용자들이 속도 저하를 불평했습니다. 불필요한 데이터베이스 호출 때문에 CF Workers 비용이 예상보다 높아졌습니다. 롤백하고 최적화해야 했습니다.

방지 방법

• 로드 상황에서 응답 시간을 테스트하기 (로컬만이 아니라)
• P95 레이턴시 확인하기 (평균만 보는 것이 아니라)
• 데이터베이스 쿼리 프로파일링하기
• 반복 요청에 대한 캐시 구현하기
• 번들 크기가 1 MB 이하인지 확인하기

개발 중에 간단한 console.time()을 사용했다면 즉시 문제를 발견했을 것입니다:

console.time('db-query');
const users = await env.DB.prepare('SELECT * FROM users').all();
console.timeEnd('db-query'); // Output: db-query: 145ms

이 경험을 통해 배운 교훈이며, 그래서 배포 가이드에 완전한 성능 체크리스트와 캐시 템플릿을 포함했습니다.
Check it out → $29

실수 #3: 적절한 로깅 설정을 잊음

내가 한 일

배포했지만 작동할 거라 생각하고 모니터링을 전혀 설정하지 않았습니다.

놓친 점

무언가가 깨졌을 때 무슨 일이 일어났는지 전혀 알 수 없었습니다. 로그도 없고, 오류 추적도 없습니다. 그냥… 아무것도 없었습니다.

결과

눈을 가리고 2시간을 디버깅하는 데 보냈습니다. 적절한 로그가 있었다면 5분 안에 문제를 찾을 수 있었을 것입니다.

이를 방지하는 방법

• ✅ wrangler.toml에서 Workers 로그 활성화
• ✅ 구조화된 로깅 (JSON 형식)
• ✅ 추적을 위한 RequestID 포함
• ✅ 다양한 레벨 로그 (DEBUG, INFO, WARN, ERROR)
• ✅ 높은 오류 비율에 대한 알림 설정

Example:

const logger = new Logger({
  requestId: crypto.randomUUID(),
  path: url.pathname,
  method: request.method,
});

logger.info('Request received', { endpoint: '/api/users' });
// Output:
// {"timestamp":"2025-12-25T...","level":"INFO","message":"Request received","requestId":"...","path":"/api/users","method":"GET"}

저는 이후에 구조화된 로깅 템플릿을 만들고 가이드에 포함시켰으며, 모니터링, 헬스 체크 및 필요한 모든 것을 포함했습니다.
Get $29 access →

실수 #4: 롤백 계획이 없음

내가 한 일

깨진 버전을 배포했고, 프로덕션이 중단되자 당황했습니다.

놓친 점

이전 버전으로 빠르게 되돌리는 방법을 전혀 몰랐습니다. 급히 작업하느라 수정에 30 분이 걸렸습니다.

결과

사용자에게 30 분의 다운타임이 발생했습니다. 신뢰를 잃었습니다. 롤백 절차를 연습했다면 2 분이면 충분했을 것입니다.

방지 방법

1. 롤백 명령을 암기하세요:

   wrangler rollback DEPLOYMENT_ID

2. 먼저 스테이징 환경에서 테스트하세요.

3. 팀 런북에 문서화하세요.

4. 연습하세요 (진지하게 테스트 롤백을 수행하세요).

5분짜리 연습 세션이 나중에 30 분의 당황을 방지합니다.

실수 #5: 수행한 작업을 문서화하지 않음

내가 한 일

중요한 업데이트를 배포했지만 변경 사항을 문서화하지 않았고 팀에도 알리지 않았다.

내가 놓친 점

동료가 한 시간 뒤에 배포했지만 내 변경 사항을 몰랐다. 충돌이 발생했다.

결과

구성 파일이 혼란스러워지고 배포가 망가졌으며, 내 변경을 롤백하고 다음 날 다시 배포해야 했다.

예방 방법

팀을 위한 배포 체크리스트를 만들자:

• 무엇이 변경되었나요?
• 왜 변경되었나요?
• 주의할 점은?
• 롤백 방법은?
• 누가 배포했나요?
• 언제 배포했나요?

5분짜리 배포 로그가 나중에 몇 시간의 혼란을 예방해 줍니다.

작동하는 시스템

배포 전

• 배포 전 체크리스트 (구성, 비밀키, 데이터베이스)
• 보안 체크리스트 (인증, CORS, 헤더, 검증)
• 성능 체크리스트 (캐싱, 쿼리, 번들 크기)
• 테스트 체크리스트 (단위, 통합, 스테이징)

배포 중

• 배포일 체크리스트 (헬스 체크, 메트릭, 알림)
• 지속적인 모니터링 (로그, 알림, 헬스 엔드포인트)

준비된 체크리스트, 템플릿, 그리고 Cloudflare Workers를 안전하게 배포하기 위한 단계별 가이드를 원하시면 $29에 전체 패키지를 받아보세요.

전체 가이드 받기 →

24시간 동안 슬리

• 오류 비율과 응답 시간을 모니터링하세요

배포 후

• 배포 후 체크리스트 사용 (로그, 메트릭, 팀 알림)
• 변경된 내용 문서화
• 축하하기 (당신은 자격이 있습니다)

이 시스템은 내 프로덕션 이슈의 **95 %**를 제거했습니다. 이제 문제가 발생하면 즉시 포착되어 몇 분 안에 해결됩니다, 몇 시간 걸리지 않죠.

지루하지만 필요한 진실

배포는 화려하지 않다. 체크리스트는 흥미롭지 않다. 하지만 효과가 있다.

내가 일해 본 최고의 팀은 가장 똑똑한 팀이 아니라 가장 규율이 철저한 팀이었다.

• 체크리스트를 가지고 있었다.
• 그것을 따랐다.
• 사고가 거의 없었다.

그리고 무언가 잘못됐을 때? 그들은 계획을 가지고 있었고, 몇 분 안에 고쳐서 넘어갔다.

그래서 나는 이 모든 것을 하나의 가이드로 정리하는 데 시간을 투자했다. 당신에게 무언가를 팔기 위해서가 아니라, 진심으로 모든 개발자가 가져야 한다고 믿기 때문이다. 포함 내용:

• ✅ 25페이지 분량의 프로덕션 배포 가이드
• ✅ 프린트 가능한 체크리스트 7개(프린트해서 책상에 붙일 수 있음)
• ✅ 프로덕션 준비된 코드 템플릿 9개

Get it here → — $29

Source:

어디서 시작할까

이 글을 읽으며 “그래, 시스템을 갖춰야겠어…” 라고 생각한다면, 제가 권하는 방법은 다음과 같습니다:

1. 보안 체크리스트를 출력해서 모니터에 붙여두세요.
2. 팀을 위한 간단한 배포 체크리스트를 만들거나(제 가이드에서 하나 가져오세요).
3. Cloudflare에서 오류 비율이 높은 경우 알림 하나를 설정하세요.
4. 롤백을 한 번 테스트해 보세요.

약 1시간 정도면 끝나며, 6개월 동안 지속될 수 있는 보안 악몽을 예방할 수 있습니다.

또는 모든 것이 준비된 상태를 원한다면, 전체 가이드를 $29에 받아보세요 →.

최종 생각

나는 값비싼 실수를 통해 이 교훈들을 배웠다. 당신은 그럴 필요가 없다.

가장 현명한 선택은 첫 시도에 완벽한 코드를 작성하는 것이 아니다. 생산에 문제가 도달하기 전에 실수를 잡아내는 시스템을 만드는 것이다.

• 체크리스트
• 모니터링
• 로깅
• 롤백 절차

지루할까? 어쩌면 그렇다. 하지만 운영팀은 당신을 사랑하게 되고, 사용자들은 중단을 겪지 않으며, CEO는 당신에게 소리를 지르지 않을 것이다.

이러한 실수를 해본 적이 있나요? 무엇을 배웠나요? 댓글로 알려 주세요—배포 전쟁 이야기를 듣고 싶습니다.

If you’re looking for a complete system to avoid these issues, I’ve put everything together for $29 →

가이드에 포함된 내용

제가 계속 언급하는 만큼, 실제로 $29에 무엇을 받을 수 있는지 알려드립니다:

가이드

• 25페이지 분량의 프로덕션 배포 지식
• 사전 배포 설정부터 사후 배포 모니터링까지 전부 포함
• 실제 오류 사례와 해결 방법

코드 (프로덕션 준비가 된 TypeScript 템플릿 9개)

• JWT 인증
• CORS 핸들러
• 속도 제한
• 캐싱 전략
• 보안 헤더
• 구조화된 로깅
• 입력 검증
• 헬스 체크
• 완전한 워커 설정

체크리스트 (각 단계별 7개의 인쇄 가능한 체크리스트)

• 사전 배포
• 보안
• 성능
• 테스트
• 모니터링
• 배포일
• 사후 배포

추가 자료

• 구성 예시
• 완전한 트러블슈팅 가이드
• 20개 이상의 질문에 답한 FAQ

모두 바로 사용하고, 커스터마이즈하고, 확장할 수 있도록 준비되었습니다.

29달러에 구매하기 →

만족하지 못하시면 30일 환불 보장.