🚀 새 릴리즈 코드를 가장 안전하게 올리는 법: Cloudflare Pages 다계정 배포 자동화

깃허브 저장소에 새로운 릴리즈 버전이 올라왔을 때, 최신 코드를 내려받아 내 블로그에 배포하다 보면 한 가지 조심스러운 고민이 생깁니다.

"새 릴리즈의 엔진 코어와 데이터베이스 마이그레이션이 실제 운영 중인 내 본 계정 블로그에 문제없이 잘 적용될까?"

스벨트킷 블로그 엔진은 레이아웃, 컬러, 폰트 같은 디자인 설정과 작성한 글이 모두 D1 데이터베이스에 안전하게 보존되므로, 코드를 업데이트하더라도 어드민에서 꾸며둔 블로그 UI가 초기화되지는 않습니다.

하지만 새 버전에서 추가된 코어 기능이나 D1 스키마 변경, 배포 스크립트가 내 Cloudflare 환경에 정상적으로 잘 배포되는지 사전에 확인해보고 싶을 때가 있습니다. 이때 가장 안전한 방법은 무료 Cloudflare 보조 계정(테스트 인스턴스)에 먼저 배포해 본 뒤, 정상 가동을 확인하고 본 계정에 올리는 것입니다.

기존에는 Cloudflare 기본 도구(Wrangler)로 여러 계정을 오가려면 매번 브라우저 로그인을 다시 하거나 D1/KV ID를 일일이 수동 교체해야 했고, 로컬 캐시가 엉켜 배포가 꼬이기도 했습니다. 이번 글에서는 이러한 번거로움 없이 **새 릴리즈 코드를 테스트 계정에서 먼저 검증하고 본 계정으로 안전하게 배포하는 '다계정 원클릭 배포 파이프라인'**을 정리해 보았습니다.

---

🔄 1. 실전 안전 배포 워크플로우

다계정 배포 시스템을 활용하면 다음과 같이 안전한 배포 사이클을 구축할 수 있습니다:

---

🔑 2. 준비물: Cloudflare API 토큰 발급 (계정당 최초 1회)

브라우저 로그인 팝업 없이 터미널에서 백그라운드로 안전하게 배포하기 위해, 각 Cloudflare 계정에서 API 토큰을 딱 한 번만 발급받아 둡니다.

2-1. 안전한 최소 권한 API 토큰 만들기

1. Cloudflare 대시보드 로그인 ➔ 우측 상단 [내 프로필(My Profile)] ➔ [API 토큰(API Tokens)] 메뉴로 이동합니다.
2. **[토큰 만들기(Create Token)]**를 누르고, 목록에서 Cloudflare Pages 편집(Edit Cloudflare Pages) 템플릿의 **[템플릿 사용]**을 클릭합니다.
3. 권한(Permissions) 섹션 하단의 **+ 더 추가(+ Add more)**를 눌러 다음 2가지 권한을 추가합니다:
   • 계정(Account) - D1 - 편집(Edit) (D1 데이터베이스 스키마 자동 동기화용)
   • 계정(Account) - Workers KV Storage - 편집(Edit) (이미지 저장소 바인딩용)

💡 보안 팁: 모든 권한을 다 주는 전역 키 대신, 블로그 빌드와 배포에 꼭 필요한 **Pages, D1, KV 3개 리소스만 권한을 주는 방식(최소 권한 원칙)**이 가장 안전합니다.

4. **계정 리소스(Account Resources)**에서 해당 계정을 선택하고, **[계속해서 요약 보기] ➔ [토큰 만들기]**를 누릅니다.
5. 발급된 API 토큰 문자열을 복사해 둡니다.

2-2. 32자리 계정 ID 확인

대시보드 접속 후 브라우저 주소창(URL)에서 32자리 문자열을 복사합니다:

https://dash.cloudflare.com/1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d/workers-and-pages
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                             (이 부분이 Account ID입니다)

---

📦 3. 백업 파일로 1초 만에 계정 등록하기 (deploy:sync)

새 계정의 D1 ID, KV ID, 프로젝트명을 복잡하게 손으로 적을 필요 없이, 어드민의 기본 기능인 '배포 설정 백업' 파일을 이용해 한 번에 등록합니다.

1. 배포 대상 블로그의 어드민 페이지 ➔ **[환경설정] ➔ [데이터 관리]**에서 **[배포 설정 다운로드]**를 클릭합니다.
2. 다운로드된 파일 이름을 계정 식별자로 변경하여 프로젝트 루트 폴더에 넣습니다:
   • 예: 테스트 계정 백업 파일 ➔ wrangler.backup.test.json
   • 예: 본 계정 백업 파일 ➔ wrangler.backup.main.json
3. 터미널에서 동기화 명령을 실행합니다:

npm run deploy:sync

======================================================
✅ [.deploy-accounts.json] 계정 설정 동기화 완료!
======================================================
📋 [현재 등록된 계정 목록]
  - main (Main Blog Account): 🟢 준비 완료
  - test (Test Blog Account): 🟡 token/accountId 입력 필요

4. 생성된 .deploy-accounts.json 파일을 열고, 발급받은 token과 accountId를 입력해 줍니다:

{
  "test": {
    "name": "Test Staging Account",
    "token": "실제_발급받은_API_토큰",
    "accountId": "실제_32자리_계정_ID",
    "blogProject": "test-blog-web",
    "adminProject": "test-blog-admin",
    "d1": {
      "BLOG_DB": { "name": "test-blog-db", "id": "11111111-2222-3333-4444-555555555555" },
      "USER_DB": { "name": "test-user-db", "id": "66666666-7777-8888-9999-000000000000" }
    },
    "kv": {
      "IMAGES_KV": "aaaaaaaaaabbbbbbbbbbccccccccccdd"
    }
  }
}

안전 보장: deploy:sync는 이미 입력해 둔 토큰과 계정 ID를 절대 지우지 않고 안전하게 보존(Merge)합니다.

---

🚀 4. 릴리즈 업데이트 실전 배포 시나리오

이제 새 릴리즈가 떴을 때 터미널에서 명령어 한 줄로 안전하게 배포할 수 있습니다.

시나리오 A. 릴리즈 테스트 계정에 먼저 쏴보기 (권장)

새 버전의 엔진 코어와 마이그레이션을 테스트 계정에 먼저 올려서 Blog(웹)와 Admin(관리자)이 정상 가동되는지 확인합니다.

npm run deploy:multi -- test

시나리오 B. 검증 완료 후 본 계정에 안전 배포

테스트 인스턴스에서 새 기능과 글 작성 등이 정상 작동하는 것을 확인했다면 본 계정에 배포합니다.

npm run deploy:multi -- main

시나리오 C. 여러 개의 블로그를 한 번에 일괄 판올림

메인 블로그 외에 서브 블로그를 함께 운영하고 있다면, 새 릴리즈 코드를 등록된 모든 계정에 한 번에 일괄 배포할 수 있습니다.

npm run deploy:multi -- --all

시나리오 D. 블로그 웹 또는 관리자 앱만 선별 배포

블로그 프론트엔드 코드만 수정되었거나 어드민 기능만 수정되었을 때는 필요한 앱만 골라서 배포할 수 있습니다.

# test 계정의 Blog(웹)만 배포
npm run deploy:multi -- test --blog-only

# test 계정의 Admin(관리자)만 배포
npm run deploy:multi -- test --admin-only

---

🛡️ 5. 계정 간 충돌을 원천 차단하는 3단계 샌드박스 설계

여러 Cloudflare 계정을 오가며 배포할 때 가장 위험한 문제는 로컬 캐시 엉킴으로 인해 엉뚱한 계정에 사이트가 배포되는 사고입니다. Wrangler는 로컬 PC에 이전 계정 세션을 캐시해 두는 습성이 있기 때문입니다.

이를 원천 차단하기 위해 배포 러너에는 3단계 샌드박스 격리 시스템이 적용되어 있습니다:

1. 임시 세션 샌드박스: 배포가 진행되는 동안 APPDATA를 임시 디렉토리로 격리하여, 내 컴퓨터의 기존 브라우저 로그인 세션에 영향을 주지 않습니다.
2. 원자적(In-Memory) 설정 복구: 배포 순간에만 해당 계정의 wrangler.json을 적용하고, 배포가 끝나면 finally 블록에서 기존 파일로 100% 원래대로 복구합니다.
3. 로컬 캐시 자동 청소: 배포 직후 로컬 캐시를 비워주므로, 평소에 쓰시던 단일 배포(npm run deploy:blog, deploy:admin)와 다계정 배포를 번갈아 실행해도 세션이 꼬이지 않습니다.

---

📋 6. 주요 명령어 요약

용도	명령어
계정 설정 자동 동기화	npm run deploy:sync
특정 계정 배포 (Blog + Admin)	npm run deploy:multi -- <계정명>
특정 계정 Blog만 선별 배포	npm run deploy:multi -- <계정명> --blog-only
특정 계정 Admin만 선별 배포	npm run deploy:multi -- <계정명> --admin-only
등록된 모든 계정 일괄 판올림	npm run deploy:multi -- --all

---

💡 7. 마치며

어드민에서 직접 꾸며둔 디자인 설정과 소중한 글 데이터는 D1 데이터베이스에 그대로 보존되면서, 새로운 엔진 릴리즈 버전이 나올 때마다 테스트 인스턴스를 통해 안심하고 업데이트할 수 있는 배포 파이프라인이 완성되었습니다.

테스트 계정을 활용한 안전 배포 워크플로우로 나만의 블로그를 더욱 안정적이고 편안하게 운영해 보시기 바랍니다.