웹 페이지 배포하기

웹 페이지 배포하기

ConnectBase 는 정적 사이트를 호스팅할 수 있는 웹 스토리지 기능을 제공합니다. 콘솔에서 웹 스토리지를 만들고, npx connectbase-client deploy 명령으로 빌드 결과물을 업로드하면 https://{storageId}.web.connectbase.world 로 즉시 게시됩니다. 1.8.0 부터 manifest 기반 증분 배포가 적용되어 변경된 파일만 업로드합니다.

이런 사이트를 배포할 수 있습니다

• React / Vue / Svelte 등 SPA (Single Page Application)
• Next.js / Nuxt 등의 정적 내보내기 (Static Export)
• 일반 HTML / CSS / JS 웹사이트
• 문서 사이트 (Docusaurus, VitePress 등)

1. 사전 준비

• ConnectBase 계정 + 앱 생성 (콘솔 퀵스타트)
• Node.js 18 이상
• 콘솔 → 스토리지 → 웹 스토리지 에서 새 웹 스토리지 생성 — storageId 확인
• 배포할 웹 프로젝트

2. 프로젝트 초기화

프로젝트 폴더에서 init 을 실행하면 Public Key, Secret Key, Storage ID 를 입력받아 .connectbaserc 가 생성됩니다.

cd my-web-project
npx connectbase-client init

대화형 프롬프트:

? Public Key (cb_pk_...): cb_pk_xxxxxxxxxxxx
? Secret Key (cb_sk_...): cb_sk_xxxxxxxxxxxx
? Web Storage ID: stg_xxxxxxxxxxxx
? Deploy directory (default: .): dist
✅ .connectbaserc 생성 완료

⚠️ Secret Key(cb_sk_*)는 배포에 필수입니다. Public Key 는 브라우저 번들에 실려 공개되는 값이라 배포 권한을 증명하지 못해, 서버가 Authorization: Bearer cb_sk_* 를 함께 요구합니다(Public Key 도 앱 식별을 위해 계속 함께 전송됩니다). init 이 .connectbaserc 에 저장해 두면 deploy / promote 가 자동으로 보냅니다. 이미 키가 있다면 CONNECTBASE_SECRET_KEY 환경변수로 지정해도 됩니다. 401 SECRET_KEY_REQUIRED 가 나면 CLI 가 구버전이라는 뜻이니 npm i -g connectbase-client@latest 로 업데이트하세요. Secret Key 와 .connectbaserc 는 저장소에 커밋하지 마세요.

3. 빌드 후 배포하기

CLI는 직접 빌드를 실행하지 않습니다. 먼저 프로젝트의 빌드 스크립트로 결과물을 만든 뒤 deploy 에 디렉터리를 전달합니다.

npm run build
npx connectbase-client deploy dist

CLI 가 자동으로:

1. dist/ 의 파일 목록을 manifest 와 비교 (1.8.0 증분 배포)
2. 변경된 파일만 업로드
3. URL 을 출력

🚀 배포 완료!

URL: https://stg_xxxxxxxxxxxx.web.connectbase.world
업로드: 4 / 18 files (재배포 67% 절약)
소요: 0.9초

💡 .connectbaserc 에 deployDir 가 저장돼 있으면 npx connectbase-client deploy 처럼 인자를 생략할 수 있습니다.

📦 파일 하나가 약 6 MiB 를 넘으면 413 으로 거부됩니다. 배포 파일은 DB 행 하나에 저장되고 바이너리는 base64 로 저장되어 원본의 약 1.33배가 되므로, 원본 기준 약 4.6 MB 가 실질 경계입니다. 초과하면 응답에 어떤 파일이 얼마나 초과했는지 목록이 담겨 옵니다. CLI 는 초과 바이너리(3D 모델, 큰 동영상, 폰트 등)를 자동으로 Object Storage 에 직접 업로드한 뒤 metadata 만 전송하므로 따로 할 일은 없습니다. 다만 큰 텍스트 번들(JS/CSS)은 자동 우회가 불가능하니 코드 스플리팅으로 나누세요.

4. 배포 URL 구조

배포가 끝나면 자동으로 URL이 생성됩니다:

5. 커스텀 도메인 연결

자신만의 도메인을 연결할 수 있습니다:

1. 콘솔 → 스토리지 → 해당 웹 스토리지 → 도메인 탭
2. 커스텀 도메인 추가 클릭, 도메인 입력 (예: www.mysite.com)
3. 표시되는 DNS 레코드 (CNAME) 를 도메인 관리자에서 추가
4. DNS 전파 완료 후 자동으로 Let's Encrypt SSL 인증서가 발급됩니다

6. QA → Production (릴리스 / promote)

신규 웹 스토리지는 manual 모드가 기본이라 deploy 는 QA 환경에만 반영되고, production 은 promote 로만 바뀝니다. promote 는 포인터만 전환하므로 QA 에서 검증한 바이트가 그대로 production 이 됩니다(재빌드/재업로드 없음).

npm run build
npx connectbase-client deploy dist   # manual 모드: QA 환경에 반영 + QA 링크 출력
npx connectbase-client releases      # 릴리스 이력 + production/QA 포인터
npx connectbase-client promote       # 최신 QA 릴리스를 production 으로 승격

QA 환경 URL 은 https://{slug|uuid}--qa.web.connectbase.world?cb_qa=<token> 형태로, 토큰 게이트 + noindex 입니다. --dev 플래그(deprecated)는 promote_mode 무관 QA 채널 배포 별칭입니다.

7. CI/CD 자동 배포

GitHub Actions 예시:

# .github/workflows/deploy.yml
name: Deploy to ConnectBase

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npm run build

      - name: Deploy
        run: npx connectbase-client deploy dist -k $PUBLIC_KEY -s $STORAGE_ID
        env:
          PUBLIC_KEY: ${{ secrets.CONNECTBASE_PUBLIC_KEY }}
          STORAGE_ID: ${{ secrets.CONNECTBASE_STORAGE_ID }}
          # 배포 인증에 필수 — 저장소에 평문으로 커밋하지 말고 저장소 시크릿으로 주입
          CONNECTBASE_SECRET_KEY: ${{ secrets.CONNECTBASE_SECRET_KEY }}

📌 -k / -s 옵션으로 .connectbaserc 없이 Public Key / 스토리지 ID 를 직접 전달할 수 있어 CI 환경에서 편합니다. Secret Key 는 명령줄 대신 CONNECTBASE_SECRET_KEY 환경변수로 넘기세요 — 프로세스 목록이나 CI 로그에 남지 않습니다. GitHub 저장소 Settings > Secrets and variables > Actions 에 CONNECTBASE_SECRET_KEY 를 등록해 위처럼 주입하면 됩니다.

8. 배포 관리

다음 단계

• React에서 ConnectBase 시작하기 — 배포한 앱에 데이터 연동
• 파일 업로드 시스템 만들기 — 이미지/파일 업로드 추가