EmDash CMS Cloudflare 무료 플랜 프로덕션 플레이북

게시일 2026-04-08 작성자 Emdash Cms Everything

요약

핵심 CMS 워크플로에 한해 Cloudflare 무료 플랜에서 EmDash를 프로덕션으로 운영할 수 있습니다.
반드시 받아들여야 할 점: 샌드박스 플러그인 실행은 사용할 수 없으므로 설정에서 worker_loaders를 제거해야 합니다.

이 가이드는 최대 기능 범위가 아니라 안정성을 우선합니다.

무료 플랜에서의 기능 경계

사용 가능

• EmDash 코어 사이트 및 관리자 흐름
• D1 기반 콘텐츠 데이터
• R2 기반 미디어 저장소(무료 사용량 내)
• Workers 배포 및 라우팅

사용 불가

• 샌드박스 플러그인용 Dynamic Workers
• 마켓플레이스 스타일의 신뢰할 수 없는 런타임 실행

런치가 샌드박스된 서드파티 플러그인 실행에 의존한다면 무료 플랜으로는 부족합니다.

배포 전 체크리스트

배포 명령을 실행하기 전에 다음을 모두 확인하세요.

• Wrangler 인증 완료(wrangler login 완료)
• 프로젝트가 클라우드 전용 가정 없이 로컬에서 빌드됨
• wrangler.jsonc의 D1·R2 바인딩이 런타임 설정과 일치
• 무료 플랜용으로 worker_loaders 항목 제거
• 패키지 매니저 선택 일관(npm 또는 pnpm, 혼용 금지)

리소스 프로비저닝 순서

바인딩 churn을 줄이려면 정확히 이 순서로 프로비저닝하세요.

1. D1 데이터베이스 생성
2. R2를 생성하거나 활성화한 뒤 버킷 생성
3. wrangler.jsonc를 정확한 이름과 ID로 업데이트
4. Worker 빌드 및 배포

이유: D1 ID와 버킷 이름이 환경 바인딩의 단일 진실 소스가 됩니다.

# 먼저 D1 프로비저닝
npx wrangler d1 create your-db-name

# 그다음 R2 버킷 프로비저닝
npx wrangler r2 bucket create your-media-bucket

무료 플랜용 최소 wrangler.jsonc 형태

다음 스켈레톤은 의도적으로 작게 유지했습니다.

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "your-site-name",
  "main": "./src/worker.ts",
  "compatibility_date": "2026-04-08",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "your-db-name",
      "database_id": "replace-with-d1-id"
    }
  ],
  "r2_buckets": [
    {
      "binding": "MEDIA",
      "bucket_name": "your-media-bucket"
    }
  ]
}

무료 플랜에서는 worker_loaders 섹션이 없습니다.

빌드 및 배포 흐름

EmDash 프로젝트 루트에서 명령을 실행합니다.

# 패키지 매니저 하나를 고르고 그대로 유지
npm run build
npm run deploy

프로젝트가 pnpm 기반이면:

pnpm build
pnpm deploy

락파일을 의도적으로 동기화하지 않는 한 같은 배포 세션에서 npm과 pnpm을 섞어 쓰지 마세요.

배포 후 검증 체크리스트

다음 순서로 검증하세요.

1. 프런트엔드 URL이 해석되고 예상 콘텐츠를 반환하는지
2. 관리자 URL(/_emdash/admin)에 도달 가능한지
3. 첫 관리자 설정이 성공적으로 완료되는지
4. 테스트 항목 하나를 만들어 게시하는지
5. 미디어 파일 하나를 업로드하고 조회가 되는지

라우트 도달만이 아니라 데이터 쓰기 경로까지 확인해야 배포가 완료된 것입니다.

자주 나오는 실패 모드와 가장 짧은 수정

실패: 배포는 성공했으나 관리자 초기화 실패

가능한 원인: 런타임 통합과 wrangler.jsonc 사이의 바인딩 불일치.

수정 경로:

1. 바인딩 이름(DB, MEDIA)이 모든 곳에서 동일한지 확인
2. 설정 수정 후 재배포
3. 관리자 초기화 재시도

실패: R2 명령이 계정 안내로 막힘

가능한 원인: 대시보드에서 아직 R2를 켜지 않음.

수정 경로:

1. Cloudflare 대시보드에서 R2 활성화
2. 결제 약관 수락(무료 사용량은 그대로 적용)
3. 버킷 생성 명령 재실행

실패: 무료 플랜에서 플러그인 관련 런타임 오류

가능한 원인: 남아 있는 샌드박스 설정.

수정 경로:

1. worker_loaders 제거
2. 샌드박스 전용 플러그인 설정 비활성화
3. 재배포 후 재테스트

롤백 전략

보수적인 롤백 정책을 사용하세요.

• 마지막으로 알려진 정상 배포 커밋에 태그 유지
• 프로덕션 회귀가 보이면 태그된 이전 커밋 재배포
• 트래픽이 안정될 때까지 스키마 또는 플러그인 변경 연기

운영상 인시던트 구간에서는 깊은 핫픽스보다 빠른 롤백이 낫습니다.

무료에서 유료로 올릴 때

다음 중 하나가 참일 때만 업그레이드하세요.

• 샌드박스된 신뢰할 수 없는 플러그인 실행이 필요할 때
• 트래픽 또는 저장소가 무료 한도를 정기적으로 초과할 때
• 거버넌스상 더 강한 플러그인 런타임 격리가 필요할 때

결제 화면의 모호한 문구만 보고 업그레이드하지 마세요. 구체적인 기능 요구가 있을 때만 업그레이드하세요.