한국 사주 웹앱 소스, Cloudflare D1 배포 전 로컬에서 시작하기

한국 사주 웹앱 소스를 살펴보고 있다면 원격 DB부터 만들기보다 로컬 실행부터 확인하는 편이 좋습니다. 제공 패키지는 Node.js 22.13 이상에서 npm ci와 npm run dev로 시작하며, 로컬에서는 격리된 Miniflare D1 바인딩을 사용합니다. 공개 배포는 별도 작업입니다. 구매자 소유 Cloudflare D1, DB 바인딩, 데이터베이스 ID, Worker 설정, DNS 결정을 직접 준비해야 합니다.

먼저 답하면: 로컬에서 패키지의 흐름을 확인한 뒤 원격 리소스를 만드세요. 체크인된 Drizzle 마이그레이션과 로컬 D1 경로는 들어 있지만, 제공된 wrangler.jsonc의 d1_databases 배열은 비어 있습니다. 로컬 화면이 열렸다는 사실만으로 구매자 계정이나 운영 도메인 설정이 끝났다고 볼 수 없습니다.

이 패키지에는 무엇이 들어 있나요?

이 소스 패키지는 한국 전통사주 네 기둥 웹앱의 출발점입니다. README에는 한국어 생년월일 입력, 양력·음력 변환, 절입과 진태양시 보정, 사주 네 기둥, 오행 균형, 십성과 지장간 풀이, 한국 이름 연구용 한자 선택, 익명 공유 링크, 선택적 D1 저장이 문서화돼 있습니다. 유료 AI API 의존성은 없습니다.

$99 상품은 구매자 1명과 프로젝트 1개를 대상으로 하는 소스 라이선스입니다. 한 개의 최종 제품을 리브랜딩·수정·운영하고 그 제품의 사용자에게 요금을 받을 수 있습니다. 원본 소스를 다시 판매하거나 배포할 권리는 포함되지 않습니다. 실제 운영 전에 포함된 LICENSE.md와 THIRD_PARTY_NOTICES.md를 읽으세요.

로컬에서 어떻게 시작하나요?

패키지 루트에서 지원되는 Node 버전을 확인한 뒤 실행합니다.

npm ci
npm run dev

Vite가 출력하는 정확한 주소를 브라우저에서 여세요. 패키지의 predev 스크립트는 wrangler.local.jsonc를 통해 체크인된 Drizzle 마이그레이션을 saju-source-local이라는 로컬 DB에 적용합니다. DB 바인딩은 로컬용이며 폐기할 수 있습니다. 첫 실행 때 생기는 .wrangler/도 재생성 가능한 로컬 상태입니다. 이 흐름에는 Cloudflare 계정, 원격 DB, 도메인, 유료 AI 서비스가 필요하지 않습니다.

페이지가 열리면 다음 점검 명령이 README에 적혀 있습니다.

npm run build
npm test
npm run selftest
npm run lint

selftest는 격리된 로컬 서버를 시작해 페이지, 로컬 D1 조회수, 익명 공유 API를 확인한 뒤 종료합니다. 이 명령은 패키지의 점검 절차일 뿐, 모든 구매자 환경이 통과했다는 결과를 뜻하지 않습니다.

Cloudflare D1 배포에서는 무엇이 달라지나요?

운영 DB는 구매자가 소유합니다. 먼저 Wrangler로 DB를 만든 뒤 반환된 이름과 UUID를 프로젝트의 D1 설정에 넣어야 합니다. Cloudflare는 wrangler d1 create가 설정에 넣을 바인딩과 UUID를 제공한다고 설명합니다. 자세한 내용은 Cloudflare 공식 D1 Wrangler 명령 문서에서 확인하세요.

먼저 구매자 소유 DB를 만듭니다.

npx wrangler d1 create your-saju-db

반환된 DB 이름과 ID를 wrangler.jsonc에 넣으세요. 제공된 원격 배열은 비어 있고, 현재 마이그레이션 디렉터리를 가진 설정은 로컬 설정입니다. 아래처럼 구매자 값으로 바인딩을 추가하고 모든 placeholder를 배포 전에 바꾸세요.

"d1_databases": [
  {
    "binding": "DB",
    "database_name": "your-saju-db",
    "database_id": "<returned-database-id>",
    "migrations_dir": "./drizzle"
  }
]

그 다음 마이그레이션을 적용하고 빌드한 뒤 배포합니다.

npx wrangler d1 migrations apply your-saju-db --remote
npm run build
npx wrangler deploy

DB 바인딩 이름은 정확히 DB여야 하며, database_name은 구매자 DB 이름, database_id는 반환된 ID, migrations_dir는 이 패키지의 ./drizzle이어야 합니다. Cloudflare 공식 D1 마이그레이션 문서는 선택한 DB에 마이그레이션을 적용하는 방식과 바인딩별 마이그레이션 디렉터리를 설명합니다. 추가 마이그레이션을 만들기 전 제공 패키지의 Drizzle 구조와 현재 Wrangler 동작을 확인해야 합니다.

Cloudflare의 D1 시작하기 문서는 로컬 작업과 원격 작업을 구분합니다. 원격 DB는 계정 권한, 데이터, 발생 가능한 비용이 연결된 실제 리소스입니다. Worker 이름과 계정, 지역·관할 요구사항, 커스텀 도메인이나 라우트를 구매자 상황에 맞게 정한 뒤 DNS를 연결하세요.

런타임

로컬: Node.js 22.13 이상, Vite 개발 서버.

운영: Node, Wrangler, 계정, 배포 권한 확인.

DB

로컬: 로컬 Miniflare D1, DB 바인딩.

운영: 구매자 소유 D1 생성, database_id 입력.

마이그레이션

로컬: predev가 체크인된 SQL 적용.

운영: 선택한 원격 DB에 적용.

주소

로컬: 개발 중 http://localhost:5173.

운영: 구매자 HTTPS origin과 메타데이터·공유 origin 설정.

도메인

로컬: 필요 없음.

운영: 구매자 소유 라우트·커스텀 도메인·DNS 구성.

개인정보

로컬: 로컬 실행 안에서만 샘플 사용.

운영: 운영 데이터와 고지 문구를 사람과 검토.

공개 전에는 무엇을 사람이 확인해야 하나요?

브랜드와 문구는 app/page.tsx, 메타데이터와 공유 origin은 app/layout.tsx, 디자인 토큰은 app/globals.css에서 바꿉니다. 실제 사용자를 받기 전 개인정보처리방침, 한국어 법률 고지, 제3자 라이선스, 운영 설정을 사람이 검토해야 합니다. README에 따르면 차트 계산은 브라우저에서 이뤄지고, 공유 API는 파생 결과만 저장하며 생년월일·출생시간·출생지 보정·한자 이름·글자별 획수는 저장하지 않습니다. 실제 서비스의 구현과 고지는 구매자가 다시 확인해야 합니다.

학습이나 프로토타입만 필요하다면 공개 데모와 Cloudflare 문서를 이용해 처음부터 만들어도 됩니다. 한국 사주 소스팩은 패키지화된 출발점, 문서화된 소스, 프로젝트 1개에 한정된 권리를 원하는 구매자를 위한 선택지입니다. 맞춤 설치, 리브랜딩 대행, DNS, 호스팅, 법률 검토, 지속 운영은 포함되지 않습니다. 이런 조건이 목적에 맞는다면 라이선스와 구매자 소유 배포 단계를 확인한 뒤 소스팩을 선택하세요.

참고 자료

이 글은 Cloudflare 공식 D1 Wrangler 명령 문서, D1 마이그레이션 문서, D1 시작하기 문서와 제공 패키지의 README.md, docs/KO_QUICKSTART.md, package.json, wrangler.jsonc, 체크인된 마이그레이션 파일을 기준으로 작성했습니다.