[4/7] Cloudflare Workers로 Docusaurus 자동 배포하기

이 글은 실제 Abulafium 구축 이력(2026-10-09 기준)을 바탕으로 다시 작성한 공개용 실습 매뉴얼입니다. [실제 검증]은 구축 과정에서 성공을 확인한 상태, [재현 절차]는 이를 일반화한 실행 순서, [확인 필요]는 실제 소스·대시보드를 추가 확인해야 하는 사항입니다. 명령어의 <USER>, <REPO_URL> 등은 자신의 환경으로 변경하세요.

완성 목표

GitHub main에 Push한 소스가 Cloudflare Workers Builds를 통해 빌드·배포되어 사용자 도메인에서 열리도록 한다. 초기 설계의 Cloudflare Pages가 아니라 Workers라는 점이 핵심이다.

1. 현재 운영 중인 배포 경로 [실제 검증]

GitHub Private repo (main)
    ↓ Push
Cloudflare Workers Builds
  Production root: abulafium-site
  Build command: npm run build
  Deploy command: npx wrangler deploy
    ↓
사용자 지정 도메인 (실제 운영: abulafium.com)

저장소 내부에는 abulafium-site/wrangler.jsonc, worker/, schema.sql 등이 있다. D1은 프로덕션과 프리뷰를 별도로 구성했다. 비밀키와 데이터베이스 ID는 실제 대시보드에서 확인해야 한다.

2. 배포 전 확인 [재현 절차]

1. GitHub 저장소를 준비하고 권한을 확인한다.
2. 로컬 abulafium-site/에서 npm ci && npm run build가 성공하는지 확인한다.
3. Cloudflare 계정에서 Workers Builds의 GitHub 연결을 구성한다.
4. 빌드·배포 루트와 명령을 현재 프로젝트 구조와 일치시킨다.
5. Wrangler 설정의 Worker entrypoint, D1 바인딩과 필요한 환경 변수를 점검한다.

Set-Location C:\works\abulafium\abulafium-site
npm ci
npm run build
Get-Content .\wrangler.jsonc

중요: Cloudflare UI와 Wrangler 옵션은 개정될 수 있다. 따라서 이 문서에서 실제로 검증된 것은 위 프로젝트 설정값이며, 화면의 메뉴 이름·권한 인증 동작은 현재 Cloudflare 콘솔에서 재확인해야 한다.

3. Production과 Preview를 나눴던 이유

실제 구축 당시 Production은 루트를 abulafium-site로 사용했다. 반면 별도 Preview 브랜치 환경은 루트 /가 사용되어 다음과 같이 명시적 경로 이동이 필요했다.

cd abulafium-site && npm ci && npm run build

Preview 배포 명령도 별도 Wrangler 실행 구성이 사용됐다. 정확한 현재 Preview 명령과 리소스 바인딩은 대시보드에서 확인해야 한다. 특히 Preview·Production D1은 독립된 데이터베이스를 사용해야 테스트가 운영 자료를 수정하지 않는다.

4. 커밋 후 배포 검증 [실제 검증 + 재현 절차]

Set-Location C:\works\abulafium
git status -sb
git add garden/blog/tech-notes/your-post.md
git commit -m "docs: publish technical note"
git push origin main

Cloudflare Workers Builds에서 성공 로그를 확인하고 사이트의 해당 글이 열리는지 확인한다. 도메인과 TLS가 정상인지 브라우저에서 확인한다. 실제로 Private 폴더의 테스트 파일만 Push했는데도 빌드가 트리거된 사례가 있었다. 그러므로 '빌드가 시작됐다'는 사실이 '그 문서가 공개됐다'와 동일하지 않다.

5. 반드시 해야 하는 보안·공개 검증

• garden/inbox, ideas, memos 파일이 정적 산출물 또는 공개 URL에 포함되지 않는가?
• 공개 강의노트만 노출되는가? URL 직접 입력으로도 점검했는가?
• Worker에서 인증이 필요하다면 서버 측 접근 통제가 실제 작동하는가?
• Preview 빌드가 Production D1을 참조하지 않는가?
• API 키·비밀번호가 빌드 로그나 클라이언트 번들에 들어가지 않는가?
• description 등 front matter가 빌드를 실패시키지 않는가?

[확인 필요] 강의별 암호, 단계 공개, 실제 Worker 코드의 접근 통제는 현재 확보한 구축 기록만으로 완료를 확정할 수 없다.

6. 실패할 때 확인할 곳

증상	진단 순서
빌드 시작 안 함	GitHub 연결 → 브랜치 트리거 → 권한
의존성 오류	빌드 루트 → lockfile → Node 버전 → npm ci
문서 경로 누락	커스텀 플러그인 → ../garden 상대경로
배포 명령 오류	wrangler.jsonc → Worker 엔트리 → 계정·바인딩
Preview 데이터 변경	Preview·Production D1 분리 확인