🚀 CMD 원클릭 설치 및 클라우드플레어 배포 가이드

본 가이드는 터미널(CMD 또는 PowerShell) 환경에서 자동화 명령어 한 줄(npm run setup)을 실행하여 Cloudflare 에지 인프라를 구축하고, 어드민과 블로그 앱을 동시에 배포 및 동기화하는 가장 쉽고 안전한 방법을 안내합니다.

---

🛠️ 1. 원클릭 배포 자동화 소개

스벨트킷 블로그 엔진은 복잡한 서버 리소스 생성과 설정 파일 편집 과정을 터미널의 대화형 설치 도구를 통해 완전히 자동화했습니다.

블로그 소스 코드의 압축을 풀거나 git clone으로 컴퓨터에 저장한 후, 터미널을 열어 프로젝트 루트 폴더로 이동한 뒤 아래 명령어를 차례대로 실행하기만 하면 됩니다.

# 필수 패키지 설치
npm install

• 의존성 라이브러리 설치: 터미널에 npm install을 입력하여 필요한 패키지를 모두 설치합니다. 설치가 완료된 후 터미널 창에 보안 경고(vulnerabilities) 메시지가 나타난다면, npm audit fix 명령어를 입력해 안전하게 최신 보안 패치를 적용해 주는 것을 권장합니다.

패키지 설치가 끝난 후 npm run setup을 실행하면, 터미널 창 안내에 따라 아래 과정이 자동으로 처리됩니다.

• Cloudflare 계정 간편 인증: 클릭 한 번으로 배포 계정 연동 완료
• DB 및 저장 리소스 생성: 블로그 전용 D1 데이터베이스 2개와 이미지 보관용 KV 저장소 자동 신규 생성
• 설정 파일 실시간 갱신: 생성된 데이터베이스 고유 ID를 감지하여 모노레포 설정 파일(wrangler.json)에 자동으로 주입
• 데이터베이스 기본 데이터 주입: 테이블을 생성하고, 선택한 기본 언어에 맞춰 샘플 게시글과 기초 환경설정 정보를 자동 등록
• 비밀 보안 변수 및 접속 허용 IP 업로드: 어드민 접속을 위해 배포자의 현재 공인 IP 주소(ALLOWED_IP)와 비밀번호 환경변수를 클라우드에 자동 전송
• 통합 빌드 및 웹 서비스 배포: 블로그 및 어드민 SvelteKit 프로젝트를 통합 빌드하여 Cloudflare Pages에 즉시 업로드 배포

---

📋 2. 배포 전 확인사항

안전한 설치를 시작하기 전에 아래 사항이 모두 준비되어 있는지 확인해 주세요.

1. Node.js 설치: 컴퓨터에 Node.js(버전 22 이상)가 작동하고 있어야 합니다.
2. Cloudflare 계정: 블로그 사이트와 데이터베이스가 호스팅될 클라우드플레어 계정(무료 제공 수준으로 충분)이 필요합니다.
3. 비밀 환경변수 파일(.dev.vars) 생성 (필수):
   • 배포 시작 전에 apps/admin/ 폴더와 apps/blog/ 폴더 밑에 각각 .dev.vars 파일을 직접 생성해 주어야 합니다.
   • apps/admin/.dev.vars 파일에는 ADMIN_PASSWORD=어드민로그인비밀번호를 작성합니다.
   • apps/blog/.dev.vars 파일에는 BETTER_AUTH_SECRET=임의의작성문자열을 작성합니다.

   • [!WARNING]
     이 환경변수 설정이 되어 있지 않으면 npm run setup 실행 즉시 정상적 작동을 위해 설치 도구가 중단됩니다.

---

⚙️ 3. npm run setup 단계별 설명

터미널을 열고 블로그 프로젝트 루트 경로에서 npm run setup을 입력한 뒤 엔터를 누릅니다.

Step 0. 비밀 환경변수 사전 검사 (Pre-Validation)

• 실행 즉시 어드민과 블로그 폴더 안의 .dev.vars 파일 및 필수 비밀 변수(ADMIN_PASSWORD, BETTER_AUTH_SECRET)가 입력되었는지 검사합니다.
• 값 설정이 누락되었다면 가이드 로그를 띄운 뒤 종료되니, 사전에 꼭 기재해 주시기 바랍니다.

Step 1. 배포 프로젝트명(도메인 주소) 설정

• 독자들이 블로그에 접속할 때 사용하게 될 주소(예: [입력한프로젝트명].pages.dev)를 정하는 단계입니다.
• 배포 타겟인 블로그와 어드민의 이름 2가지를 입력받습니다. 복구 모드(--restore)로 실행하는 경우 기존 백업 정보 파일(wrangler.backup.json)로부터 기존 이름을 자동으로 읽어와 세팅합니다.

Step 2. Cloudflare 계정 로그인 인증

• 클라우드플레어 인증을 확인합니다. 기존에 로그인한 이력이 있다면 자동으로 세션을 감지하여 스킵합니다.
• 로그인되어 있지 않다면 브라우저 창이 열리며 인증 요청 화면이 나타납니다. **[Allow / 허용]**을 클릭해 계정 연동을 승인해 주시면 됩니다.
• 보안 정보: 본 자동화 도구는 인프라 생성 및 배포에 필요한 최소한의 계정 API 권한만을 요청하므로 안심하고 진행하셔도 됩니다.

Step 3. 리소스 생성 및 환경설정 연동

• 실제 서비스 작동을 위한 데이터베이스와 미디어 저장소를 클라우드에 생성하는 단계입니다. 터미널의 안내 문구를 보고 알맞은 번호를 입력하세요.
  1. 1 (완전 초기화 / Fresh Install): 이전에 만들어진 데이터베이스와 저장소를 완전히 삭제하고 새롭게 다시 만듭니다. 기존 데이터가 모두 지워지므로 유의해야 합니다.
  2. 2 (기존 데이터 유지 / Keep Existing Data) [권장]: 이미 생성된 리소스가 있다면 데이터를 안전하게 지키면서 연결 정보만 매칭시켜 줍니다.
• 연동 완료 즉시 새롭게 발급된 DB 및 KV 고유 ID가 모노레포의 각 설정 파일(wrangler.json)에 자동으로 업데이트됩니다.

Step 4. 웹 프로젝트 사전 생성

• 배포의 완성도를 높이기 위해, 클라우드플레어 에지에 비어 있는 웹 프로젝트를 선제적으로 등록 및 선점합니다.
• 이미 같은 이름의 주소가 점유되어 있다면 기존 주소를 재활용하여 안전하게 다음 단계로 자동 전환됩니다.

Step 5. 비밀 환경변수 원격 동기화

• 앞서 로컬에 작성했던 .dev.vars 안의 마스터 비밀번호 등 비밀 값들을 클라우드로 안전하게 업로드하여 동기화합니다.
• 접속 IP 자동 등록: 특히 이 단계에서 배포를 가동 중인 관리자 컴퓨터의 공인 IP 주소를 실시간 감지하여 ALLOWED_IP 변수로 자동 주입해 줍니다. 덕분에 배포 직후 로그인 창에 처음 들어갈 때 IP가 차단되어 접근하지 못하는 일을 원천 예방합니다.

Step 6. 데이터베이스 테이블 구성 및 기본 테마 구축

• 블로그 기능 동작에 필요한 DB 테이블을 구성하고 초기 설정값을 이식합니다.
• 화면 안내에 따라 주로 사용할 기본 언어(한국어, 영어, 일본어)를 선택하면 번역 시스템이 구축되고 샘플 카테고리와 헤더 메뉴 뼈대, 기본 환영 게시글이 자동으로 세팅됩니다.

Step 7. 웹 서비스 빌드 및 최종 배포

• 전체 모노레포 앱의 통합 빌드를 진행하고, Cloudflare 서버에 배포 명령을 자동 실행하여 설치 프로세스를 마칩니다. 배포가 완료되면 블로그와 어드민의 Pages 접속 주소가 표시됩니다.

---

[!TIP]

💡 비밀 값 자동 설정과 즉시 접속 지원

본 프로젝트의 설치 프로세스는 리소스 생성, 웹 프로젝트 확보, 비밀 환경변수 전송까지 유기적으로 이어서 처리합니다.
배포 완료와 동시에 로그인 비밀번호 및 IP 허용 설정이 원격 서버에 완벽하게 세팅되므로, 별도의 추가 수동 조작 없이도 즉시 작동합니다.

---

🔄 4. 블로그 업데이트 및 데이터 복원 배포 (npm run restore)

블로그를 운영하던 중 새로운 패치 버전이나 버그가 수정된 최신 릴리즈 코드가 배포되었을 때, 기존에 써왔던 게시글 데이터와 주소를 유실 없이 안전하게 승계하며 새 코드로 화면을 교체하는 방법입니다.

💡 새 버전 마이그레이션 4단계 절차

어드민의 데이터 백업과 npm run restore 명령어를 사용하면 데이터 유실 없이 안전하게 업그레이드를 완료할 수 있습니다.

1. [1단계] 기존 데이터 및 배포 설정 백업:
   • 운영 중인 어드민의 콘텐츠 백업 메뉴 및 디자인 에디터 메뉴 하단 백업 섹션에 접속해 포스트 본문 데이터와 테마 디자인 설정을 각각 컴퓨터로 내려받습니다.
   • 또한 콘텐츠 백업 메뉴의 설정 백업 다운로드 단추를 눌러 [wrangler.backup.json] 파일을 PC에 저장해 둡니다. (이는 기존 상용 서버의 데이터베이스 고유 ID 연동을 유지하는 가장 중요한 파일입니다.)
2. [2단계] 새 코드 격리 테스트:
   • 새로 내려받은 신버전 코드 폴더 안에서 npm run setup을 가동해 테스트용 임시 DB와 테스트용 Pages 임시 배포명을 입력해 별도 배포합니다.
   • 임시 배포된 새 어드민에 로그인하여 1단계에서 저장해 두었던 백업 데이터 파일들을 가져오기(Import)하여 데이터가 무사히 불려오는지 사전 확인합니다.
3. [3단계] 기존 상용 서버로 바인딩 복원 (npm run restore):
   • 검증이 끝났다면, 신버전 프로젝트 폴더의 루트 디렉터리에 1단계에서 따로 내려받아 두었던 wrangler.backup.json 파일을 복사해 붙여넣습니다.
   • 터미널에서 npm run restore 명령을 기동하면, 도구 스크립트가 해당 백업 내용에 기재된 기존의 상용 DB와 KV의 고유 ID 정보를 읽어와 새 코드 설정 파일에 덮어쓰기 방식으로 자동 연결해 줍니다.
4. [4단계] 스키마 동기화 및 덮어쓰기 배포:
   • 복원 스크립트는 기존 상용 DB의 테이블 구조 뼈대만 최신 사양으로 안전하게 갱신하므로, 이미 적재되어 있던 실제 게시글이나 데이터는 훼손되거나 지워지지 않고 완벽히 보존됩니다.
   • 이어서 npm run deploy:blog 와 npm run deploy:admin을 각각 실행하면, 사용 중이던 주소 그대로 최신 업그레이드된 블로그 시스템만 안전하게 덮어쓰기 배포됩니다.

---

📦 5. 백업 파일의 종류와 기능

어드민 백업 메뉴에서 안전하게 가져오고 내보낼 수 있는 개별 파일들의 역할은 아래 표를 참고해 주세요.

백업 유형	추출 경로	권장 파일명 예시	상세 기능 및 보존 내용
1. 콘텐츠 DB 데이터	콘텐츠 백업 메뉴	blog-content-backup-[날짜].json	작성된 모든 블로그 포스트 본문, 생성된 카테고리 정보, 태그 목록 및 기본 시스템 설정값 보존
2. 배포 설정 백업	콘텐츠 백업 메뉴	wrangler.backup.json	Cloudflare D1 DB 및 KV 저장소 연동에 필요한 배포명과 고유 UUID 정보를 안전하게 보존 (서버 마이그레이션 시 필수)
3. 미디어 파일 백업	콘텐츠 백업 메뉴의 미디어 백업 및 복원 섹션 또는 미디어 라이브러리 메뉴 우측 상단 [백업 / 복원] 단추	[스토리지이름]-images-backup-[날짜].zip (예: kv-images-backup-[날짜].zip)	활성화된 이미지 저장소(KV, R2, Supabase, ImageKit)에 업로드된 전체 이미지 미디어 파일을 ZIP 형식으로 압축 다운로드하여 보존
4. 디자인 설정 백업	디자인 에디터 메뉴 하단	blog-design-backup-[날짜].json	디자인 에디터에서 설정한 블로그 테마 컬러 정보, 배경 타입 및 기기별(데스크톱/모바일) 위젯 배치 구조 보존
5. 시스템 전체 백업	사이트 설정 메뉴 하단	full-system-backup-[날짜].json	두 개 데이터베이스(BLOG_DB, USER_DB) 내 모든 테이블의 원천 데이터를 하나의 JSON 파일로 모아 전체 백업 및 복원