SvelteKit Monorepo + Cloudflare 원클릭 배포 및 자동 셋업 상세 설명서

detail-manual • 2026-07-06 PM7:23:44 (GMT+9) • 👀 1 •

#SvelteKit #Cloudflare #Wrangler #Deploy #Setup

🚀 SvelteKit Monorepo + Cloudflare 원클릭 배포 및 자동 셋업 상세 설명서

본 프로젝트는 스벨트킷(SvelteKit) 모노레포 환경을 기반으로 하며, 서버리스 데이터베이스인 Cloudflare D1과 KV Namespace, 그리고 Cloudflare Pages 배포 인프라를 유기적으로 사용합니다.

모노레포의 다중 애플리케이션 구조에서 발생할 수 있는 데이터베이스 연결 유실, 환경 변수 불일치, 수동 CLI 바인딩 설정 복잡성을 최소화하기 위해 원클릭 자동화 셋업 스크립트가 기본 내장되어 있습니다. 이 가이드는 스크립트 실행 전 준비해야 하는 로컬 환경 설정부터 실행 시 주어지는 터미널 선택 프롬프트의 의미와 모드별 활용법을 상세히 소개합니다.

📂 1. 스크립트 실행 전 사전 준비사항

셋업 스크립트는 실행 중 불필요한 오류로 작동이 멈추는 것을 방지하기 위해 Step 0 단계에서 필수 로컬 환경 변수(.dev.vars)가 올바르게 준비되었는지 사전 검증합니다. 스크립트를 구동하기 전에 반드시 아래의 조치를 완료해야 합니다.

🔑 1-1. `.dev.vars` 파일 생성 및 필수 값 설정

프로젝트 루트 기준, 블로그 앱과 어드민 앱 각각의 경로에 .dev.vars.example 파일을 복사하여 .dev.vars 파일을 생성하고 적절한 비밀값을 기입해 주세요.

블로그 서비스 환경 변수
- 위치: apps/blog/.dev.vars
- 필수 설정 항목:
```
BETTER_AUTH_SECRET="임의의_긴_비밀_문자열"
```
  (인증 세션 및 토큰을 암호화하기 위해 사용되는 유일하고 복잡한 비밀 문자열을 기입합니다. 비어있거나 따옴표만 존재하면 검증이 실패합니다.)
어드민 서비스 환경 변수
- 위치: apps/admin/.dev.vars
- 필수 설정 항목:
```
ADMIN_PASSWORD="어드민_접속_비밀번호"
```
  (어드민 대시보드 로그인 시 사용할 비밀번호를 기입합니다.)
- GA4 및 애드센스(AdSense) 더미 데이터 보기:
  어드민 대시보드 메인 화면에서 Google Analytics 4(GA4) 방문자 지표 및 Google AdSense 실적 리포트의 **더미 데이터(시뮬레이션 예시)**를 확인하여 화면 출력을 테스트하고 싶다면, 로컬 .dev.vars 파일 및 원격 Cloudflare Pages 설정에서 구글 연동 관련 환경변수들(GA4_PROPERTY_ID, ADSENSE_ACCOUNT_ID 등)을 **등록하지 않거나 완전히 삭제(혹은 주석 처리)**해야 합니다. 관련 필수 변수 중 하나라도 비어 있으면 시스템이 자동으로 더미 데이터를 생성해 출력합니다.

[!WARNING]
만약 파일이 없거나 필수 값이 비어 있다면 터미널에 아래와 같은 경고 메시지가 출력되며 셋업이 중단됩니다.
❌ apps/admin/.dev.vars 파일이 존재하지 않습니다.
   (apps/admin/.dev.vars.example 파일을 복사하여 생성하고 ADMIN_PASSWORD를 설정해주세요.)

🛠️ 2. 명령어 종류 및 실행 방법

명령어	실행 목적	특징
`npm run setup`	기본 전체 자동 설치 및 배포	초기 기본 언어만 설정하면 리소스 생성부터 최종 빌드/배포까지 논스톱으로 자동 진행됩니다.
`npm run setup:select`	사용자 지정 직접 선택 설정	배포 프로젝트명, 데이터 유지/삭제 여부, 리소스명 변경, CDN 캐시 퍼지 연동 등을 조율합니다.
`npm run restore`	백업 복원 및 보안 동기화	`wrangler.backup.json` 백업 파일을 참조하여 인프라를 안전하게 재정렬하고 배포합니다.

💬 3. 실행 단계별 터미널 선택 가이드 (Prompt Guide)

스크립트 실행 중 터미널 화면에 나타나는 실제 한글/영어 선택 프롬프트와 각 선택지가 인프라에 미치는 영향에 대한 가이드입니다.

🌐 3-1. 공통 초기 프롬프트 (npm run setup & setup:select 공통)

Q1. 기본 블로그 언어 선택 (기본 콘텐츠 언어 설정)

D1 데이터베이스에 최초로 주입될 초기 가이드 게시글 및 기본 데이터의 언어를 결정합니다.

  [EN] Select default blog language:
  [KO] 기본 블로그 언어를 선택하세요:
  1) Korean / 한국어 (ko) [Default]
  2) English / 영어 (en)
  3) Japanese / 日本語 (ja)
  [EN] Choose option (1/2/3) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2/3) [기본값: 1]
  >

가이드: 기본값인 1을 선택하면 한국어로 구성된 기본 시드 데이터가 생성되며, 2 또는 3 입력 시 각각 영어/일본어로 번역된 초기 가이드 데이터가 주입됩니다.

Q2. 진행 방식 모드 선택

남은 셋업 과정을 자동으로 완전히 실행할지, 아니면 하나씩 커스텀하여 입력할지 결정합니다.

  [EN] Choose setup mode for the remaining steps:
  [KO] 나머지 설정의 진행 방식을 선택하세요:
  1) Full Auto Setup & Deploy / 풀 자동 설정 및 배포 [Default]
  2) Custom Interactive Setup / 사용자 지정 직접 선택 설정
  [EN] Choose option (1/2) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2) [기본값: 1]
  >

1) Full Auto Setup & Deploy (기본값): 블로그 및 어드민 배포명을 기본 규격에 맞춰 생성하고, Cloudflare 로그인 상태만 검증한 뒤 모든 리소스 바인딩과 마이그레이션, 배포를 일사천리로 마칩니다.
2) Custom Interactive Setup: 상세 커스텀 설정 모드로 전환되며, 아래의 추가 질문들(Q3 ~ Q8)이 연이어 제공됩니다. (npm run setup:select 명령어 실행 시 이 모드로 바로 진입합니다.)

🎨 3-2. 상세 커스텀 설정 프롬프트 (`npm run setup:select` 전용)

[!TIP]
상세 커스텀 설정 과정에서 나타나는 모든 질문 프롬프트는 값을 별도로 기입하지 않고 그냥 엔터(Enter)만 쳐서 넘어가도 대괄호 [Default: ...] 안에 적힌 안전한 기본값으로 자동 설정되므로 간편하게 진행할 수 있습니다.

Q3. 배포 프로젝트명 커스텀

Cloudflare Pages 상에 고유하게 생성될 배포 프로젝트 이름을 지정합니다. (기본 도메인은 https://[프로젝트명].pages.dev 형태로 자동 설정됩니다.)

  [EN] Enter Blog project name [Default: svelteblog]
  [KO] 블로그 배포명을 입력하세요
  > 

  [EN] Enter Admin project name [Default: svelteadmin]
  [KO] 어드민 배포명을 입력하세요
  >

가이드: 공백 상태로 엔터를 누르면 대괄호 내의 기본 이름이 사용됩니다. 본인의 Cloudflare 계정 내 타 프로젝트와 명칭이 충돌되지 않는 고유한 이름을 사용하고 싶다면 수동으로 기입합니다. (입력 시 package.json의 deploy:blog, deploy:admin 스크립트도 해당 프로젝트 명으로 동적 자동 수정됩니다.)

Q4. Cloudflare 계정 로그인 진행 여부

Cloudflare API 제어를 위한 인증 과정을 실행합니다.

  [EN] Run wrangler login?
  [KO] Wrangler 로그인을 진행할까요?
  [EN] (Y/n) [Default: Y]
  [KO] (Y/n) [기본값: Y]
  >

가이드: 로그인이 되어 있지 않다면 브라우저를 띄워 Cloudflare 계정 연동을 진행합니다. 이미 유효한 로그인이 감지된 상태라면 스크립트가 알아서 해당 세션을 파악하고 넘어가지만, 다른 계정으로 다시 로그인하고 싶다면 Y를 입력할 수 있습니다.

Q5. 데이터 초기화 모드 설정 (Fresh vs Keep)

기존에 구축하여 사용 중이던 Cloudflare 리소스(D1, KV)의 보존 여부를 묻습니다.

  [EN] Select Initialization Mode:
    1: Fresh Install (DELETE existing Cloudflare D1/KV databases and start clean)
    2: Keep Existing Data (Use existing Cloudflare databases to preserve your posts/data)
  [KO] 초기화 모드 선택:
    1: 완전 초기화 (기존 클라우드플레어의 D1/KV 데이터베이스를 모두 삭제하고 새로 생성합니다. 데이터 유실 주의!)
    2: 기존 데이터 유지 (기존에 구축된 클라우드플레어 리소스를 그대로 유지하고 연동합니다.)

  [EN] Choose an option (1/2) [Default: 2]
  [KO] 옵션을 선택하세요 (1/2) [기본값: 2]
  >

Fresh Install (1): 기존 Cloudflare에 올라간 D1 DB와 KV Namespace 데이터를 완전히 영구 삭제하고 새로 설치합니다. 테스트 중 완전히 빈 상태로 되돌리고 싶을 때만 선택해야 합니다.
Keep Existing Data (2, 권장/기본값): 이미 데이터베이스에 등록된 게시글, 회원 등의 데이터를 유지한 채로 새 배포 환경 정보 바인딩만 연결합니다.

Q6. Cloudflare 리소스명 직접 지정

Cloudflare 대시보드에 실제로 표시될 D1 및 KV 인스턴스의 이름을 지정합니다.

  [EN] Enter Blog DB name [Default: blog-db-xxxxxx]
  [KO] 블로그 DB 이름을 입력하세요
  > 

  [EN] Enter User DB name [Default: user-db-xxxxxx]
  [KO] 유저 DB 이름을 입력하세요
  > 

  [EN] Enter Images KV name [Default: blog-images-kv-xxxxxx]
  [KO] 이미지 KV 이름을 입력하세요
  >

가이드: 별도로 고정하여 관리하고자 하는 DB 명칭이 있다면 입력해 주시고, 그렇지 않다면 그대로 엔터를 눌러 랜덤 서픽스(xxxxxx)가 부여된 고유 이름으로 자동 생성되도록 합니다.

Q7. Cloudflare CDN 캐시 퍼지 등록

블로그 게시글 수정/삭제 시 배포 도메인의 에지(Edge) 캐시를 즉시 무효화하여 독자에게 최신 본문을 즉시 서빙하기 위한 CDN 동기화 인증 수단을 등록합니다.

  [EN] Configure Cloudflare CDN cache purge credentials?
  [KO] CDN 캐시 퍼지 설정을 등록하시겠습니까?
  [EN] (y/N) [Default: N]
  [KO] (y/N) [기본값: N]
  >

가이드: y를 누르면 Cloudflare 대시보드 화면 우측 하단에서 획득 가능한 Zone ID와 API Token 입력 단계가 시작됩니다. 입력 시 로컬 .dev.vars 파일에 해당 키값이 안전하게 주입되고 Cloudflare Pages의 환경변수로도 벌크 자동 등록됩니다.

Q8. 빌드 및 즉시 배포 여부

인프라 설정 완료 후 즉시 프로젝트 빌드 및 Cloudflare Pages 서버로 배포 전송을 수행할지 결정합니다.

  [EN] Deploy directly?
  [KO] 지금 바로 배포하시겠습니까?
  [EN] (Y/n) [Default: Y]
  [KO] (Y/n) [기본값: Y]
  >

가이드: 로컬 설정을 완료하고 즉시 실 배포 사이트에 반영하고 싶다면 Y를 누릅니다. 빌드가 진행된 뒤 최종 서비스 도메인 URL이 화면에 출력됩니다. 만약 리소스 바인딩 파일(wrangler.json)만 세팅하고 싶다면 n을 입력합니다.

🔒 3-3. 배포 동기화 시 조건별 추가 프롬프트 (IP 및 다국어 사전)

빌드 및 원격 배포 단계(sync-secrets.js)에 진입하면 추가적으로 관리 환경 보안과 번역 사전 동기화를 위한 판단을 요청받게 됩니다.

Q9. 어드민 접속 IP 불일치 감지 및 처리

어드민 서비스는 외부 공격을 차단하기 위해 화이트리스트 기반의 IP 접근 제어(ALLOWED_IP)를 사용합니다. 스크립트가 로컬 PC의 외부 퍼블릭 IP 주소를 실시간 자동 추적하여 기존 설정값과 비교하고 불일치 시 아래의 질문을 던집니다.

  1) Keep existing allowed IPs / 기존 목록 유지 (현재 기기 미등록) [Default]
  2) Add current machine IP to list / 현재 기기 IP를 목록에 추가 (복수 허용)
  3) Replace with current machine IP / 현재 기기 IP로만 갱신 (기존 목록 제거)

  [EN] Select option (1/2/3) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2/3) [기본값: 1]
  >

1) Keep existing allowed IPs (기본값): 현재 배포 기기의 IP를 어드민 접속 허용 목록에 추가하지 않고 기존 설정대로 둡니다. (만약 현재 사용 중인 인터넷망이 다른 곳이라면 배포 후 어드민 접속이 차단될 수 있습니다.)
2) Add current machine IP to list: 기존에 입력되어 있던 다른 주소들을 콤마(,) 구분자로 남겨둔 채, 현재 배포 기기의 퍼블릭 IP를 허용 목록에 추가합니다. 여러 장소(예: 집, 사무실)에서 동시에 접근하고자 할 때 최적의 옵션입니다.
3) Replace with current machine IP: 기존에 등록되었던 허용 목록을 싹 지우고, 오직 현재 접속 중인 이 기기의 외부 IP 주소로만 화이트리스트를 갱신합니다. 단일 환경 보안을 극대화할 때 유용합니다.

Q10. 데이터베이스 다국어 번역 사전(ui_dictionary) 갱신 여부

어드민 앱 배포 시, 로컬 공유 모듈(packages/shared/src/i18n/index.ts)에 개발자가 정의한 다국어 기본 사전 개체(fallbackDictionary)를 원격 D1 데이터베이스의 blog_settings 테이블에 덮어쓸지 확인합니다.

[EN] Force sync remote D1 ui_dictionary with local index.ts? (Web changes will be lost)
[KO] D1 DB의 ui_dictionary를 로컬 index.ts 기준으로 강제 덮어쓰시겠습니까? (웹 수정본 유실 주의)
  [EN] Select option (y/N) [Default: N]
  [KO] 옵션을 선택하세요 (y/N) [기본값: N]
  >

가이드: 웹 어드민 화면 내의 '설정 대시보드' 등에서 사용자가 직접 번역 문구를 수정한 이력이 있다면, 로컬 소스코드로 덮어쓰는 순간 웹 수정본이 유실될 수 있으므로 N을 권장합니다. 로컬 소스코드의 번역 데이터 수정본을 강제로 원격 서버에 동기화하고자 할 때만 y를 누릅니다. (단, npm run setup 초기 실행 단계에서는 데이터 정합성을 위해 자동 동기화 처리됩니다.)

🔄 4. 백업 및 복원 메커니즘 (`npm run restore`)

셋업이 성공적으로 끝나면 프로젝트 루트에 wrangler.backup.json 파일이 자동 생성됩니다.

{
    "d1": {
        "BLOG_DB": { "name": "blog-db-xxxxxx", "id": "d1-uuid-value" },
        "USER_DB": { "name": "user-db-xxxxxx", "id": "d1-uuid-value" }
    },
    "kv": {
        "IMAGES_KV": "kv-namespace-id"
    },
    "blogProjectName": "svelteblog",
    "adminProjectName": "svelteadmin"
}

이 백업 파일이 존재하면 향후 코드 수정이나 기기 변경 시 npm run restore 명령어를 사용해 복구 모드를 진행할 수 있습니다.

복원 모드에서는 휴먼 에러 방지를 위해 프로젝트 배포명과 리소스 ID 바인딩이 완전 자동 고정되어 즉각 연동됩니다.
또한 기존 데이터를 절대 건드리지 않도록 초기 시드 주입(Seeding) 단계를 자동으로 안전하게 생략하므로 기존 운영 중인 블로그 데이터 유실 없이 인프라 관계만 재생성해냅니다.

❓ 5. 자주 겪는 문제 및 문제 해결 (Troubleshooting)

🚨 1. Wrangler Whoami 세션 및 권한 오류

현상: 스크립트 실행 중 Authentication Error 혹은 D1/KV 리소스 생성 명령어 시점에 세션 없음 에러가 표시되는 경우.
해결: npm run setup:select를 구동하고 Q4. Wrangler 로그인 단계에서 Y를 입력해 브라우저를 통해 재인증을 마쳐야 합니다. 스크립트는 계정 보안을 위해 오직 최소 권한(account:read, user:read, workers:write, pages:write, d1:write, workers_kv:write)만을 요구하므로 안심하고 승인하시면 됩니다.

🚨 2. Windows 환경의 스크립트 실행 권한 차단

현상: 윈도우 파워쉘(PowerShell) 등에서 스크립트 무단 실행 정책 오류가 표시되는 경우.
해결: 셋업 스크립트는 윈도우 OS 감지 시 자동으로 npx 대신 npx.cmd를 호출하고 쉘 제어 플래그를 변환하도록 자체 예외 설계되어 있습니다. 가급적이면 파워쉘보다 Git Bash 혹은 CMD 터미널을 사용하여 실행하는 것을 권장합니다.

Share this post on social networks

0 Comments

This post is written in English.

SvelteKit Monorepo + Cloudflare 원클릭 배포 및 자동 셋업 상세 설명서

detail-manual • 2026-07-06 PM7:23:44 (GMT+9) • 👀 1 •

#SvelteKit #Cloudflare #Wrangler #Deploy #Setup

🚀 SvelteKit Monorepo + Cloudflare 원클릭 배포 및 자동 셋업 상세 설명서

📂 1. 스크립트 실행 전 사전 준비사항

🔑 1-1. `.dev.vars` 파일 생성 및 필수 값 설정

블로그 서비스 환경 변수
- 위치: apps/blog/.dev.vars
- 필수 설정 항목:
```
BETTER_AUTH_SECRET="임의의_긴_비밀_문자열"
```
  (인증 세션 및 토큰을 암호화하기 위해 사용되는 유일하고 복잡한 비밀 문자열을 기입합니다. 비어있거나 따옴표만 존재하면 검증이 실패합니다.)
어드민 서비스 환경 변수
- 위치: apps/admin/.dev.vars
- 필수 설정 항목:
```
ADMIN_PASSWORD="어드민_접속_비밀번호"
```
  (어드민 대시보드 로그인 시 사용할 비밀번호를 기입합니다.)
- GA4 및 애드센스(AdSense) 더미 데이터 보기:
  어드민 대시보드 메인 화면에서 Google Analytics 4(GA4) 방문자 지표 및 Google AdSense 실적 리포트의 **더미 데이터(시뮬레이션 예시)**를 확인하여 화면 출력을 테스트하고 싶다면, 로컬 .dev.vars 파일 및 원격 Cloudflare Pages 설정에서 구글 연동 관련 환경변수들(GA4_PROPERTY_ID, ADSENSE_ACCOUNT_ID 등)을 **등록하지 않거나 완전히 삭제(혹은 주석 처리)**해야 합니다. 관련 필수 변수 중 하나라도 비어 있으면 시스템이 자동으로 더미 데이터를 생성해 출력합니다.

[!WARNING]
만약 파일이 없거나 필수 값이 비어 있다면 터미널에 아래와 같은 경고 메시지가 출력되며 셋업이 중단됩니다.
❌ apps/admin/.dev.vars 파일이 존재하지 않습니다.
   (apps/admin/.dev.vars.example 파일을 복사하여 생성하고 ADMIN_PASSWORD를 설정해주세요.)

🛠️ 2. 명령어 종류 및 실행 방법

명령어	실행 목적	특징
`npm run setup`	기본 전체 자동 설치 및 배포	초기 기본 언어만 설정하면 리소스 생성부터 최종 빌드/배포까지 논스톱으로 자동 진행됩니다.
`npm run setup:select`	사용자 지정 직접 선택 설정	배포 프로젝트명, 데이터 유지/삭제 여부, 리소스명 변경, CDN 캐시 퍼지 연동 등을 조율합니다.
`npm run restore`	백업 복원 및 보안 동기화	`wrangler.backup.json` 백업 파일을 참조하여 인프라를 안전하게 재정렬하고 배포합니다.

💬 3. 실행 단계별 터미널 선택 가이드 (Prompt Guide)

스크립트 실행 중 터미널 화면에 나타나는 실제 한글/영어 선택 프롬프트와 각 선택지가 인프라에 미치는 영향에 대한 가이드입니다.

🌐 3-1. 공통 초기 프롬프트 (npm run setup & setup:select 공통)

Q1. 기본 블로그 언어 선택 (기본 콘텐츠 언어 설정)

D1 데이터베이스에 최초로 주입될 초기 가이드 게시글 및 기본 데이터의 언어를 결정합니다.

  [EN] Select default blog language:
  [KO] 기본 블로그 언어를 선택하세요:
  1) Korean / 한국어 (ko) [Default]
  2) English / 영어 (en)
  3) Japanese / 日本語 (ja)
  [EN] Choose option (1/2/3) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2/3) [기본값: 1]
  >

가이드: 기본값인 1을 선택하면 한국어로 구성된 기본 시드 데이터가 생성되며, 2 또는 3 입력 시 각각 영어/일본어로 번역된 초기 가이드 데이터가 주입됩니다.

Q2. 진행 방식 모드 선택

남은 셋업 과정을 자동으로 완전히 실행할지, 아니면 하나씩 커스텀하여 입력할지 결정합니다.

  [EN] Choose setup mode for the remaining steps:
  [KO] 나머지 설정의 진행 방식을 선택하세요:
  1) Full Auto Setup & Deploy / 풀 자동 설정 및 배포 [Default]
  2) Custom Interactive Setup / 사용자 지정 직접 선택 설정
  [EN] Choose option (1/2) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2) [기본값: 1]
  >

1) Full Auto Setup & Deploy (기본값): 블로그 및 어드민 배포명을 기본 규격에 맞춰 생성하고, Cloudflare 로그인 상태만 검증한 뒤 모든 리소스 바인딩과 마이그레이션, 배포를 일사천리로 마칩니다.
2) Custom Interactive Setup: 상세 커스텀 설정 모드로 전환되며, 아래의 추가 질문들(Q3 ~ Q8)이 연이어 제공됩니다. (npm run setup:select 명령어 실행 시 이 모드로 바로 진입합니다.)

🎨 3-2. 상세 커스텀 설정 프롬프트 (`npm run setup:select` 전용)

[!TIP]
상세 커스텀 설정 과정에서 나타나는 모든 질문 프롬프트는 값을 별도로 기입하지 않고 그냥 엔터(Enter)만 쳐서 넘어가도 대괄호 [Default: ...] 안에 적힌 안전한 기본값으로 자동 설정되므로 간편하게 진행할 수 있습니다.

Q3. 배포 프로젝트명 커스텀

Cloudflare Pages 상에 고유하게 생성될 배포 프로젝트 이름을 지정합니다. (기본 도메인은 https://[프로젝트명].pages.dev 형태로 자동 설정됩니다.)

  [EN] Enter Blog project name [Default: svelteblog]
  [KO] 블로그 배포명을 입력하세요
  > 

  [EN] Enter Admin project name [Default: svelteadmin]
  [KO] 어드민 배포명을 입력하세요
  >

가이드: 공백 상태로 엔터를 누르면 대괄호 내의 기본 이름이 사용됩니다. 본인의 Cloudflare 계정 내 타 프로젝트와 명칭이 충돌되지 않는 고유한 이름을 사용하고 싶다면 수동으로 기입합니다. (입력 시 package.json의 deploy:blog, deploy:admin 스크립트도 해당 프로젝트 명으로 동적 자동 수정됩니다.)

Q4. Cloudflare 계정 로그인 진행 여부

Cloudflare API 제어를 위한 인증 과정을 실행합니다.

  [EN] Run wrangler login?
  [KO] Wrangler 로그인을 진행할까요?
  [EN] (Y/n) [Default: Y]
  [KO] (Y/n) [기본값: Y]
  >

가이드: 로그인이 되어 있지 않다면 브라우저를 띄워 Cloudflare 계정 연동을 진행합니다. 이미 유효한 로그인이 감지된 상태라면 스크립트가 알아서 해당 세션을 파악하고 넘어가지만, 다른 계정으로 다시 로그인하고 싶다면 Y를 입력할 수 있습니다.

Q5. 데이터 초기화 모드 설정 (Fresh vs Keep)

기존에 구축하여 사용 중이던 Cloudflare 리소스(D1, KV)의 보존 여부를 묻습니다.

  [EN] Select Initialization Mode:
    1: Fresh Install (DELETE existing Cloudflare D1/KV databases and start clean)
    2: Keep Existing Data (Use existing Cloudflare databases to preserve your posts/data)
  [KO] 초기화 모드 선택:
    1: 완전 초기화 (기존 클라우드플레어의 D1/KV 데이터베이스를 모두 삭제하고 새로 생성합니다. 데이터 유실 주의!)
    2: 기존 데이터 유지 (기존에 구축된 클라우드플레어 리소스를 그대로 유지하고 연동합니다.)

  [EN] Choose an option (1/2) [Default: 2]
  [KO] 옵션을 선택하세요 (1/2) [기본값: 2]
  >

Fresh Install (1): 기존 Cloudflare에 올라간 D1 DB와 KV Namespace 데이터를 완전히 영구 삭제하고 새로 설치합니다. 테스트 중 완전히 빈 상태로 되돌리고 싶을 때만 선택해야 합니다.
Keep Existing Data (2, 권장/기본값): 이미 데이터베이스에 등록된 게시글, 회원 등의 데이터를 유지한 채로 새 배포 환경 정보 바인딩만 연결합니다.

Q6. Cloudflare 리소스명 직접 지정

Cloudflare 대시보드에 실제로 표시될 D1 및 KV 인스턴스의 이름을 지정합니다.

  [EN] Enter Blog DB name [Default: blog-db-xxxxxx]
  [KO] 블로그 DB 이름을 입력하세요
  > 

  [EN] Enter User DB name [Default: user-db-xxxxxx]
  [KO] 유저 DB 이름을 입력하세요
  > 

  [EN] Enter Images KV name [Default: blog-images-kv-xxxxxx]
  [KO] 이미지 KV 이름을 입력하세요
  >

가이드: 별도로 고정하여 관리하고자 하는 DB 명칭이 있다면 입력해 주시고, 그렇지 않다면 그대로 엔터를 눌러 랜덤 서픽스(xxxxxx)가 부여된 고유 이름으로 자동 생성되도록 합니다.

Q7. Cloudflare CDN 캐시 퍼지 등록

  [EN] Configure Cloudflare CDN cache purge credentials?
  [KO] CDN 캐시 퍼지 설정을 등록하시겠습니까?
  [EN] (y/N) [Default: N]
  [KO] (y/N) [기본값: N]
  >

가이드: y를 누르면 Cloudflare 대시보드 화면 우측 하단에서 획득 가능한 Zone ID와 API Token 입력 단계가 시작됩니다. 입력 시 로컬 .dev.vars 파일에 해당 키값이 안전하게 주입되고 Cloudflare Pages의 환경변수로도 벌크 자동 등록됩니다.

Q8. 빌드 및 즉시 배포 여부

인프라 설정 완료 후 즉시 프로젝트 빌드 및 Cloudflare Pages 서버로 배포 전송을 수행할지 결정합니다.

  [EN] Deploy directly?
  [KO] 지금 바로 배포하시겠습니까?
  [EN] (Y/n) [Default: Y]
  [KO] (Y/n) [기본값: Y]
  >

가이드: 로컬 설정을 완료하고 즉시 실 배포 사이트에 반영하고 싶다면 Y를 누릅니다. 빌드가 진행된 뒤 최종 서비스 도메인 URL이 화면에 출력됩니다. 만약 리소스 바인딩 파일(wrangler.json)만 세팅하고 싶다면 n을 입력합니다.

🔒 3-3. 배포 동기화 시 조건별 추가 프롬프트 (IP 및 다국어 사전)

빌드 및 원격 배포 단계(sync-secrets.js)에 진입하면 추가적으로 관리 환경 보안과 번역 사전 동기화를 위한 판단을 요청받게 됩니다.

Q9. 어드민 접속 IP 불일치 감지 및 처리

  1) Keep existing allowed IPs / 기존 목록 유지 (현재 기기 미등록) [Default]
  2) Add current machine IP to list / 현재 기기 IP를 목록에 추가 (복수 허용)
  3) Replace with current machine IP / 현재 기기 IP로만 갱신 (기존 목록 제거)

  [EN] Select option (1/2/3) [Default: 1]
  [KO] 옵션을 선택하세요 (1/2/3) [기본값: 1]
  >

1) Keep existing allowed IPs (기본값): 현재 배포 기기의 IP를 어드민 접속 허용 목록에 추가하지 않고 기존 설정대로 둡니다. (만약 현재 사용 중인 인터넷망이 다른 곳이라면 배포 후 어드민 접속이 차단될 수 있습니다.)
2) Add current machine IP to list: 기존에 입력되어 있던 다른 주소들을 콤마(,) 구분자로 남겨둔 채, 현재 배포 기기의 퍼블릭 IP를 허용 목록에 추가합니다. 여러 장소(예: 집, 사무실)에서 동시에 접근하고자 할 때 최적의 옵션입니다.
3) Replace with current machine IP: 기존에 등록되었던 허용 목록을 싹 지우고, 오직 현재 접속 중인 이 기기의 외부 IP 주소로만 화이트리스트를 갱신합니다. 단일 환경 보안을 극대화할 때 유용합니다.

Q10. 데이터베이스 다국어 번역 사전(ui_dictionary) 갱신 여부

[EN] Force sync remote D1 ui_dictionary with local index.ts? (Web changes will be lost)
[KO] D1 DB의 ui_dictionary를 로컬 index.ts 기준으로 강제 덮어쓰시겠습니까? (웹 수정본 유실 주의)
  [EN] Select option (y/N) [Default: N]
  [KO] 옵션을 선택하세요 (y/N) [기본값: N]
  >

가이드: 웹 어드민 화면 내의 '설정 대시보드' 등에서 사용자가 직접 번역 문구를 수정한 이력이 있다면, 로컬 소스코드로 덮어쓰는 순간 웹 수정본이 유실될 수 있으므로 N을 권장합니다. 로컬 소스코드의 번역 데이터 수정본을 강제로 원격 서버에 동기화하고자 할 때만 y를 누릅니다. (단, npm run setup 초기 실행 단계에서는 데이터 정합성을 위해 자동 동기화 처리됩니다.)

🔄 4. 백업 및 복원 메커니즘 (`npm run restore`)

셋업이 성공적으로 끝나면 프로젝트 루트에 wrangler.backup.json 파일이 자동 생성됩니다.

{
    "d1": {
        "BLOG_DB": { "name": "blog-db-xxxxxx", "id": "d1-uuid-value" },
        "USER_DB": { "name": "user-db-xxxxxx", "id": "d1-uuid-value" }
    },
    "kv": {
        "IMAGES_KV": "kv-namespace-id"
    },
    "blogProjectName": "svelteblog",
    "adminProjectName": "svelteadmin"
}

이 백업 파일이 존재하면 향후 코드 수정이나 기기 변경 시 npm run restore 명령어를 사용해 복구 모드를 진행할 수 있습니다.

복원 모드에서는 휴먼 에러 방지를 위해 프로젝트 배포명과 리소스 ID 바인딩이 완전 자동 고정되어 즉각 연동됩니다.
또한 기존 데이터를 절대 건드리지 않도록 초기 시드 주입(Seeding) 단계를 자동으로 안전하게 생략하므로 기존 운영 중인 블로그 데이터 유실 없이 인프라 관계만 재생성해냅니다.

❓ 5. 자주 겪는 문제 및 문제 해결 (Troubleshooting)

🚨 1. Wrangler Whoami 세션 및 권한 오류

현상: 스크립트 실행 중 Authentication Error 혹은 D1/KV 리소스 생성 명령어 시점에 세션 없음 에러가 표시되는 경우.
해결: npm run setup:select를 구동하고 Q4. Wrangler 로그인 단계에서 Y를 입력해 브라우저를 통해 재인증을 마쳐야 합니다. 스크립트는 계정 보안을 위해 오직 최소 권한(account:read, user:read, workers:write, pages:write, d1:write, workers_kv:write)만을 요구하므로 안심하고 승인하시면 됩니다.

🚨 2. Windows 환경의 스크립트 실행 권한 차단

현상: 윈도우 파워쉘(PowerShell) 등에서 스크립트 무단 실행 정책 오류가 표시되는 경우.
해결: 셋업 스크립트는 윈도우 OS 감지 시 자동으로 npx 대신 npx.cmd를 호출하고 쉘 제어 플래그를 변환하도록 자체 예외 설계되어 있습니다. 가급적이면 파워쉘보다 Git Bash 혹은 CMD 터미널을 사용하여 실행하는 것을 권장합니다.

Share this post on social networks

0 Comments

This post is written in English.

Categories

Popular Posts

Recent Posts

Tags

Buy me a Coffee

🚀 SvelteKit Monorepo + Cloudflare 원클릭 배포 및 자동 셋업 상세 설명서

📂 1. 스크립트 실행 전 사전 준비사항

🔑 1-1. .dev.vars 파일 생성 및 필수 값 설정

🛠️ 2. 명령어 종류 및 실행 방법

💬 3. 실행 단계별 터미널 선택 가이드 (Prompt Guide)

🌐 3-1. 공통 초기 프롬프트 (npm run setup & setup:select 공통)

Q1. 기본 블로그 언어 선택 (기본 콘텐츠 언어 설정)

Q2. 진행 방식 모드 선택

🎨 3-2. 상세 커스텀 설정 프롬프트 (npm run setup:select 전용)

Q3. 배포 프로젝트명 커스텀

Q4. Cloudflare 계정 로그인 진행 여부

Q5. 데이터 초기화 모드 설정 (Fresh vs Keep)

Q6. Cloudflare 리소스명 직접 지정

Q7. Cloudflare CDN 캐시 퍼지 등록

Q8. 빌드 및 즉시 배포 여부

🔒 3-3. 배포 동기화 시 조건별 추가 프롬프트 (IP 및 다국어 사전)

Q9. 어드민 접속 IP 불일치 감지 및 처리

Q10. 데이터베이스 다국어 번역 사전(ui_dictionary) 갱신 여부

🔄 4. 백업 및 복원 메커니즘 (npm run restore)

❓ 5. 자주 겪는 문제 및 문제 해결 (Troubleshooting)

🚨 1. Wrangler Whoami 세션 및 권한 오류

🚨 2. Windows 환경의 스크립트 실행 권한 차단

Share this post on social networks

0 Comments

Tags

🚀 SvelteKit Monorepo + Cloudflare 원클릭 배포 및 자동 셋업 상세 설명서

📂 1. 스크립트 실행 전 사전 준비사항

🔑 1-1. .dev.vars 파일 생성 및 필수 값 설정

🛠️ 2. 명령어 종류 및 실행 방법

💬 3. 실행 단계별 터미널 선택 가이드 (Prompt Guide)

🌐 3-1. 공통 초기 프롬프트 (npm run setup & setup:select 공통)

Q1. 기본 블로그 언어 선택 (기본 콘텐츠 언어 설정)

Q2. 진행 방식 모드 선택

🎨 3-2. 상세 커스텀 설정 프롬프트 (npm run setup:select 전용)

Q3. 배포 프로젝트명 커스텀

Q4. Cloudflare 계정 로그인 진행 여부

Q5. 데이터 초기화 모드 설정 (Fresh vs Keep)

Q6. Cloudflare 리소스명 직접 지정

Q7. Cloudflare CDN 캐시 퍼지 등록

Q8. 빌드 및 즉시 배포 여부

🔒 3-3. 배포 동기화 시 조건별 추가 프롬프트 (IP 및 다국어 사전)

Q9. 어드민 접속 IP 불일치 감지 및 처리

Q10. 데이터베이스 다국어 번역 사전(ui_dictionary) 갱신 여부

🔄 4. 백업 및 복원 메커니즘 (npm run restore)

❓ 5. 자주 겪는 문제 및 문제 해결 (Troubleshooting)

🚨 1. Wrangler Whoami 세션 및 권한 오류

🚨 2. Windows 환경의 스크립트 실행 권한 차단

Share this post on social networks

0 Comments

인기 포스트

태그

커피 한 잔 사주기

🔑 1-1. `.dev.vars` 파일 생성 및 필수 값 설정

🎨 3-2. 상세 커스텀 설정 프롬프트 (`npm run setup:select` 전용)

🔄 4. 백업 및 복원 메커니즘 (`npm run restore`)

🔑 1-1. `.dev.vars` 파일 생성 및 필수 값 설정

🎨 3-2. 상세 커스텀 설정 프롬프트 (`npm run setup:select` 전용)

🔄 4. 백업 및 복원 메커니즘 (`npm run restore`)