배포 가이드

본 사이트는 순수 정적 사이트로, 빌드 산출물을 아무 정적 호스팅 플랫폼에 배포할 수 있습니다.

빌드

bash

npm run docs:build:all

출력 디렉터리는 docs/.vitepress/dist입니다.

참고: npm run docs:build는 기본적으로 중국어 간체만 빌드합니다(빌드 시 다국어 버전 빌드 여부를 묻습니다). 전체 다국어 사이트를 배포하려면 npm run docs:build:all을 사용하고, 일상 개발에는 npm run docs:dev를 사용하세요.

방법 1: GitHub Pages

저장소 Settings → Pages에서 배포 브랜치와 디렉터리를 선택합니다;
또는 GitHub Actions로 자동 빌드합니다:

yaml

name: Deploy Docs

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run docs:build:all
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

방법 2: Vercel / Netlify

Vercel을 예로 들면:

저장소를 가져옵니다;
빌드 명령: npm run docs:build:all;
출력 디렉터리: docs/.vitepress/dist;
배포 버튼을 누르면 되며, 푸시할 때마다 자동 배포와 미리보기 브랜치를 지원합니다.

방법 3: Nginx

bash

# 빌드 산출물을 서버에 업로드한 후
scp -r docs/.vitepress/dist user@server:/var/www/docs

Nginx 설정 예시:

nginx

server {
  listen 80;
  server_name docs.example.com;

  root /var/www/docs;
  index index.html;

  # 프론트엔드 라우팅 폴백
  location / {
    try_files $uri $uri/ /index.html;
  }
}

커스텀 도메인과 HTTPS

호스팅 플랫폼에 커스텀 도메인을 연결합니다;
CNAME 레코드를 플랫폼으로 설정합니다;
플랫폼이 HTTPS 인증서를 자동 발급·갱신합니다.

방법 4: 텐센트 클라우드 COS + CDN

국내 접속 체감이 가장 좋은 저비용 방안 중 하나로, 객체 스토리지 + CDN 가속을 결합하여 중국 본토 사용자를 대상으로 한 사이트에 적합합니다.

1. 준비

텐센트 클라우드 계정(신규 사용자는 무료 할당량을 받을 수 있으며, 보통 표준 스토리지 10GB와 일부 트래픽이 포함되고 유효 기간은 수개월입니다);
ICP 비안(备案) 완료 도메인(중국 본토 CDN 가속 도메인 사용 시 반드시 ICP 비안을 완료해야 하며, 심사 기간은 약 1-3주, 무료입니다).

비안 절차 상세(텐센트 클라우드 ICP 비안)

선행 조건

도메인이 실명 인증을 완료해야 합니다(도메인 등록 기관에서, 보통 1-3일 후 적용);
텐센트 클라우드 계정의 실명 인증이 완료되었고, 텐센트 클라우드 서버/라이트웨이트 서버 등 비안용 클라우드 리소스를 보유해야 합니다(비안은 반드시 클라우드 리소스에 연동되어야 함);
사이트 내용은 《비영리 인터넷 정보 서비스 비안 관리 방법》을 준수해야 하며, 개인 비안은 영리성 콘텐츠를 포함할 수 없습니다.

단계	작업	필요 서류	예상 시간
1. 도메인 검증	텐센트 클라우드 비안 콘솔에 로그인해 도메인을 입력하면 시스템이 비안 유형(최초 비안/이전 비안 등)을 자동 인식합니다	비안할 도메인	즉시
2. 정보 작성	주체 정보(개인 성명/기업명, 증서 번호)와 서비스 정보(사이트 이름, 도메인, 사이트 책임자, 서비스 내용)를 작성하고, 신분증 사진과 확인서를 업로드합니다	신분증 앞뒷면, 손에 든 사진(App 얼굴 인증), 사이트 책임자 정보, 확인서(자동 생성)	준비 상황에 따라
3. 텐센트 클라우드 1차 심사	텐센트 클라우드가 서류의 진위성과 완전성을 심사합니다	—	영업일 기준 1-2일
4. SMS 인증	공업정보화부가 인증번호를 발송하며, 24시간 내에 공업정보화부 비안 시스템에 로그인해 인증을 완료합니다	받은 SMS 인증번호	24시간 내
5. 관리국 심사	지역 통신 관리국이 최종 심사합니다	—	최대 영업일 기준 20일
6. 비안 완료	SMS/이메일 알림을 받고 비안 번호를 획득합니다	—	알림 기준

비안 통과 후에도 두 가지를 더 해야 합니다:

사이트 하단에 비안 번호를 표시하고 공업정보화부 비안 시스템 https://beian.miit.gov.cn에 하이퍼링크를 걸어야 합니다. 예: 「粤ICP备2026000000号」;
동시에 **공안 비안(公安备案)**을 신청할 것을 권장합니다(비안 통과 후 30일 이내), 일부 성(省)은 강제로 요구합니다.

비안 팁

개인 최초 비안은 보통 1-2주면 완료되며, 지역 관리국마다 처리 속도가 다릅니다;
비안 기간에는 COS 기본 도메인이나 해외 노드로 먼저 배포해 서비스를 시작하고, 비안 통과 후 커스텀 도메인으로 전환할 수 있습니다;
비안은 무료 서비스로, 유료 대행(대행은 자료 정리 안내만 제공)에 주의하세요.

2. 스토리지 버킷 생성

콘솔에서 객체 스토리지 COS로 들어가 스토리지 버킷을 생성합니다;
지역은 가까운 곳을 선택합니다(예: 광저우 ap-guangzhou);
접근 권한은 공개 읽기, 비공개 쓰기를 선택합니다;
「정적 사이트」 기능을 켜고, 인덱스 문서는 index.html, 오류 문서는 404.html로 설정합니다.

3. 빌드 산출물 업로드

빌드 후 docs/.vitepress/dist 디렉터리를 업로드합니다:

bash

npm run docs:build:all

# 방법 1: 콘솔 업로드(객체 → 폴더 업로드, dist 아래 모든 파일 선택)
# 방법 2: COSCLI 명령줄 도구 사용
pip install coscmd
coscmd config -a <SecretId> -s <SecretKey> -b <bucket-name>-<appid> -r ap-guangzhou
coscmd upload -rs ./docs/.vitepress/dist/ /
coscmd list -r /

4. CDN 가속 연동

콘솔에서 콘텐츠 전송 네트워크 CDN으로 들어가 가속 도메인을 추가합니다;
가속 지역은 중국 본토를 선택합니다(비안 전이라면 중국 홍콩/해외를 선택하며, 속도는 보통입니다);
원본 서버 유형은 객체 스토리지 COS를 선택하고 방금 생성한 스토리지 버킷을 선택합니다;
도메인 연동 방식은 CNAME을 선택하고, 안내에 따라 도메인 서비스 업체에 CNAME 레코드를 추가합니다;
CNAME 적용을 기다립니다(약 10분), 「원본 추적 301/302」와 「Range 원본 추적」을 켭니다.

5. HTTPS 설정

5.1 무료 인증서 신청

콘솔에서 SSL 인증서로 들어가 「무료 인증서 신청」을 선택합니다;
인증서 유형은 DV(도메인형)를 선택하고 가속 도메인을 연결합니다;
검증 방식은 자동 DNS 검증을 선택합니다(도메인이 텐센트 클라우드/이관된 파싱 환경이면 원클릭 완료), 발급을 기다립니다(몇 분에서 몇 시간).

5.2 CDN에서 활성화

CDN 「도메인 관리 → HTTPS 설정」에서 발급된 인증서를 선택합니다;
「HTTP 강제 HTTPS 점프」를 켭니다(권장, 점프 상태 코드는 301 선택);
활성화 후 첫 접속 전에 「새로고침·프리히팅」에서 홈페이지 URL 프리히팅을 실행해 첫 접속 속도를 높일 수 있습니다.

요금 안내

DV 인증서는 무료이며 갱신 비용이 없습니다(만료 전 시스템이 알림을 주고 다시 신청 가능);
주의: CDN의 HTTPS 요청 수는 부가 서비스로 0.04원/만회로 과금됩니다 — 문서 사이트는 요청량이 적고(월 평균 수십만 회) 약 몇 원이므로 무시할 수 있습니다; 완전히 비용을 피하고 싶다면 「부가 서비스」에서 HTTPS 요금 항목을 끌 수 있습니다(비추천, 암호화를 잃게 됩니다).

5.3 배포 결과 검증

bash

curl -I https://docs.example.com
# 기대 응답: HTTP/2 200
# 응답 헤더에 strict-transport-security 등 보안 헤더 포함(추후 CDN 응답 헤더 설정에서 커스터마이징 가능)

5.4 CNAME 설정 설명

CDN을 연동하면 가속 도메인에 .cdn.dnsv1.com으로 끝나는 CNAME 레코드가 할당되며, 도메인 파싱 서비스 업체에 추가해야 합니다:

레코드 유형	호스트 레코드	레코드 값	TTL
CNAME	`docs`	`docs.example.com.cdn.dnsv1.com`	600

적용 시간은 보통 10분에서 1시간입니다(TTL에 따라 다름);
설정 오류(예: A 레코드로 잘못 설정)는 도메인이 CDN으로 파싱되지 않아 접속 오류가 발생합니다;
검증: nslookup docs.example.com, CNAME 대상을 반환하면 성공입니다.

6. 캐시 설정

정적 문서 사이트는 리소스에 긴 캐시를 설정하는 것을 권장합니다(CDN 적중률 99%+ 도달 가능, 원본 추적 트래픽이 거의 없음). CDN 콘솔 「도메인 관리 → 캐시 설정」에서 작업합니다.

6.1 권장 캐시 규칙

우선순위	매칭 유형	내용	캐시 시간	설명
1	파일 확장자	`.html`	10분	콘텐츠 업데이트 후 빠르게 적용
2	파일 확장자	`.js` `.css`	30일	VitePress 빌드 산출물에 hash가 포함되어 안심하고 긴 캐시 사용
3	파일 확장자	`.png` `.jpg` `.svg` `.webp` `.ico`	30일	이미지 정적 리소스
4	파일 확장자	`.woff` `.woff2` `.ttf`	30일	폰트 파일
5	모든 파일	`*`	30일	폴백 규칙

6.2 캐시 적중과 적중률

캐시 적중 후 CDN은 엣지 노드 콘텐츠를 직접 반환하며, 원본 추적 트래픽이 발생하지 않습니다(0.15원/GB의 원본 추적 비용 절약);
적중률은 콘솔 「통계 분석 → 적중률」에서 확인할 수 있으며, 문서 사이트는 보통 99% 이상으로 안정적입니다;
적중률이 낮다면 「쿼리 문자열 무시」가 켜져 있는지 확인하세요: 켜면 page.html?ref=a와 page.html?ref=b가 같은 캐시에 적중합니다.

6.3 캐시 새로고침과 프리히팅

새로고침: 콘텐츠 업데이트 후 실행하여 엣지 노드 캐시를 제거합니다(URL 새로고침은 실시간 적용, 디렉터리 새로고침은 약 5분);
프리히팅: 리소스를 미리 엣지 노드에 캐시하여 신규 버전 출시나 대규모 프로모션 시 첫 접속이 원본 추적하지 않게 합니다;
콘솔 경로: 「새로고침·프리히팅」 → URL/디렉터리 입력 → 제출;
자동화 방법: 배포 스크립트에서 coscmd upload 후 CDN 새로고침 API(DescribeCdnHosts / URL 새로고침 인터페이스)를 호출하거나 COS 이벤트 알림으로 트리거합니다.

6.4 브라우저 캐시(2차 캐시)

CDN 노드 캐시 외에도 브라우저 자체가 리소스를 캐시하며, COS 또는 CDN의 「HTTP 응답 헤더 설정」에서 정적 리소스에 다음을 추가할 수 있습니다:

http

Cache-Control: public, max-age=2592000   # 30일, hash가 있는 정적 리소스용
Cache-Control: no-cache                   # HTML은 매번 원본 검증(10분 노드 캐시와 함께)

6.5 상태 코드 캐시

상태 코드	권장 캐시 시간	설명
`200`	캐시 규칙 따름	정상 응답
`404`	10초	오류 페이지의 영구 캐시를 방지하여 수정 후에도 404가 나오는 문제 차단
`403/500/502`	0	서버 오류는 캐시하지 않아 빠른 복구에 유리

7. 배포 스크립트 자동화(업로드 + 자동 새로고침)

본 프로젝트는 원클릭 배포 스크립트 scripts/deploy.mjs를 내장하여 「빌드 → 증분 업로드 → CDN 캐시 자동 새로고침」의 전체 과정을 처리합니다.

7.1 환경 준비

의존성 설치: npm i -D cos-nodejs-sdk-v5 tencentcloud-sdk-nodejs-cdn;
접근 관리 CAM에서 API 키를 생성합니다;
.env.example을 복사해 .env로 만들고 작성합니다:

bash

TENCENTCLOUD_SECRET_ID=your-secret-id
TENCENTCLOUD_SECRET_KEY=your-secret-key
COS_BUCKET=your-bucket-1250000000    # appid 접미사 포함
COS_REGION=ap-guangzhou              # 스토리지 버킷 지역과 일치
CDN_DOMAIN=docs.example.com          # 가속 도메인, 설정 시 CDN 자동 새로고침

7.2 사용법

bash

npm run deploy                  # 정식 배포: 빌드 + 백업 + 업로드 + CDN 새로고침
npm run deploy -- --dry-run     # 시뮬레이션: 실행 계획만 출력하고 실제 변경 없음
npm run deploy -- --refresh-all # 전체 사이트 디렉터리 새로고침으로 변경(기본은 .html만 새로고침)
npm run deploy -- --skip-build  # 빌드 건너뛰고 기존 산출물 직접 업로드
npm run deploy -- --no-backup   # 배포 전 버전 백업 건너뛰기

7.3 스크립트 실행 과정

단계	작업	설명
1	`npm run docs:build:all`	정적 사이트 빌드
2	로컬 파일 수집	각 파일의 MD5 계산
3	원격 객체 나열	COS 기존 파일을 페이지 단위로 조회(MD5는 커스텀 헤더에 저장)
4	차이 계산	MD5 동일 시 건너뜀, 로컬에서 삭제된 원격 파일은 자동 정리
5	현재 버전 백업	배포 전 온라인 콘텐츠를 `__backup/<타임스탬프>/`로 스냅샷(COS 동일 버킷 복사, 트래픽 0), 최근 10개 버전 유지
6	증분 업로드	변경된 파일만 업로드, HTML에는 `Cache-Control: no-cache`, 정적 리소스는 30일
7	CDN 새로고침	기본적으로 모든 `.html` URL 정밀 새로고침(할당량 충분); `--refresh-all`로 전체 사이트 디렉터리 새로고침 전환

왜 HTML만 새로고침하나요? 정적 리소스 파일명에는 hash가 포함되어 콘텐츠가 바뀌면 파일명도 바뀌므로 새로고침이 필요 없습니다. HTML 캐시는 10분이므로 새로고침 후 바로 적용됩니다. 이렇게 매 배포마다 새로고침 할당량 10개만 사용합니다.

7.4 CI/CD 연동(GitHub Actions 예시)

yaml

name: Deploy Docs

on:
  push:
    branches: [main]
    paths: ['docs/**', 'package.json']

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 docs:build:all
      - name: COS 배포 + CDN 새로고침
        run: node scripts/deploy.mjs --skip-build
        env:
          TENCENTCLOUD_SECRET_ID: ${{ secrets.TENCENTCLOUD_SECRET_ID }}
          TENCENTCLOUD_SECRET_KEY: ${{ secrets.TENCENTCLOUD_SECRET_KEY }}
          COS_BUCKET: ${{ secrets.COS_BUCKET }}
          COS_REGION: ap-guangzhou
          CDN_DOMAIN: ${{ secrets.CDN_DOMAIN }}

저장소 Settings → Secrets에서 위 키들을 설정하면, docs/ 변경이 푸시될 때마다 자동 배포됩니다.

7.5 버전 백업과 롤백

배포 전 스크립트가 자동으로 현재 온라인 콘텐츠를 __backup/<타임스탬프>/ 접두사로 스냅샷합니다(COS 동일 버킷 복사, 트래픽 비용 없음), 최근 10개 버전을 유지하므로 배포에 문제가 생기면 언제든 롤백할 수 있습니다.

bash

npm run rollback                            # 모든 백업 버전 나열(시간 + 파일 수)
npm run rollback -- --to 20260831103000     # 지정 버전으로 롤백
npm run rollback -- --to 20260831103000 --prune    # 롤백하고 해당 버전 외의 불필요한 파일 삭제
npm run rollback -- --to 20260831103000 --dry-run  # 시뮬레이션, 실행 계획만 출력
npm run rollback -- --to 20260831103000 --refresh-all  # 롤백 후 전체 사이트 새로고침(기본은 .html만)

롤백 원리: 백업 객체를 사이트 루트 디렉터리로 복사합니다(기존 캐시 헤더 유지), --prune 시 현재 온라인에 남은 불필요한 파일을 삭제하고, 이후 CDN 캐시를 자동 새로고침하여 사이트가 즉시 복구됩니다.

보안 설계

백업은 업로드 전에 완료되며, 백업 실패 시 배포 리스크로 간주해 먼저 해결한 후 계속합니다;
롤백은 백업에 있는 파일만 복구하며 다른 백업 버전에는 영향을 주지 않습니다(서로 독립);
--dry-run은 전 과정이 오프라인으로 진행되어 가짜 키로 먼저 시뮬레이션할 수 있습니다.

7.6 변경 로그 자동 생성

내장 scripts/changelog.mjs는 두 가지 모드를 지원합니다(git 저장소 자동 감지):

bash

npm run changelog                  # 최근 30일 변경 로그 출력
npm run changelog -- --days 7      # 최근 7일만 보기
npm run changelog -- --write       # CHANGELOG.md에 쓰기
npm run changelog -- --from <ref>  # git 모드: 지정 ref(tag/hash/HEAD~10)부터 시작
npm run changelog -- --files       # 파일 모드 강제(git 없이)

git 모드(권장): git log 기반, Conventional Commit에 따라 자동 분류(feat→추가, fix→수정, docs→문서, perf→성능 등);
파일 모드(자동 다운그레이드): git 저장소가 없으면 docs/ 아래 Markdown 파일의 수정 시간과 제목을 스캔해 날짜별로 그룹화하여 생성합니다.

배포 과정과 함께 쓰는 것을 권장합니다: 먼저 npm run changelog -- --write로 변경 로그를 갱신한 뒤 npm run deploy로 배포합니다.

7.7 가벼운 대안: coscli + tccli(코드 작성 불필요)

Node SDK를 도입하고 싶지 않다면 텐센트 클라우드 공식 명령줄 도구를 사용할 수도 있습니다:

bash

# 1. coscli 설치(증분 동기화 + 불필요한 파일 삭제)
curl -L https://github.com/tencentyun/coscli/releases/latest/download/coscli-darwin-amd64 -o /usr/local/bin/coscli
chmod +x /usr/local/bin/coscli
coscli config  # 안내에 따라 키 입력

npm run docs:build:all
coscli sync ./docs/.vitepress/dist/ cos://your-bucket/ -r --delete --include ".*"

# 2. tccli 설치 후 CDN 새로고침(텐센트 클라우드 공식 CLI)
pip install tccli
tccli configure  # 키 설정
tccli cdn PurgeUrlsCache --Urls '["https://docs.example.com/index.html"]' --Area mainland

비용 추정

전형적인 문서 사이트(사이트 100MB, 월 접속 1만 회, CDN 트래픽 약 2GB)를 예로 들면:

요금 항목	단가	월 비용 추정
COS 표준 스토리지	0.118원/GB/월	약 0.01원(신규 사용자 무료 할당량으로 충당)
COS 요청 비용	0.01원/만회	약 0.01원
CDN 트래픽(0-2TB 구간)	0.21원/GB	약 0.42원
CDN 원본 추적 트래픽	0.15원/GB	약 0원(캐시 적중률 99%+)
HTTPS 인증서	무료	0원
합계	—	월 약 0.5원

비용 안내

트래픽이 많을수록 CDN 단가가 낮아집니다: 2-10TB 구간 0.20원/GB, 10-50TB 구간 0.18원/GB;
CDN 트래픽 패키지를 구매하면 단가를 더 낮출 수 있습니다(프로모션 흔함);
유일한 추가 비용은 도메인입니다(일반 접미사 연 20-60원, 신규 사용자 1원 프로모션 흔함), 비안 자체는 무료;
비안을 하지 않았다면 COS 기본 접속 도메인을 직접 사용할 수도 있지만, 커스텀 도메인을 사용할 수 없고 외부 네트워크 다운로드는 0.5원/GB로 과금되므로, 비안 + CDN 조합을 권장합니다.

힌트

국내 환경에서는 텐센트 클라우드 COS + CDN 외에도 알리바바 클라우드 OSS + CDN, 치뉴 클라우드, 우파이 클라우드 등의 객체 스토리지로 정적 사이트를 호스팅할 수 있으며, 비용과 작업 방식은 유사합니다.

배포 가이드 ​

빌드 ​

방법 1: GitHub Pages ​

방법 2: Vercel / Netlify ​

방법 3: Nginx ​

커스텀 도메인과 HTTPS ​

방법 4: 텐센트 클라우드 COS + CDN ​

1. 준비 ​

비안 절차 상세(텐센트 클라우드 ICP 비안) ​

2. 스토리지 버킷 생성 ​

3. 빌드 산출물 업로드 ​

4. CDN 가속 연동 ​

5. HTTPS 설정 ​

5.1 무료 인증서 신청 ​

5.2 CDN에서 활성화 ​

5.3 배포 결과 검증 ​

5.4 CNAME 설정 설명 ​

6. 캐시 설정 ​

6.1 권장 캐시 규칙 ​

6.2 캐시 적중과 적중률 ​

6.3 캐시 새로고침과 프리히팅 ​

6.4 브라우저 캐시(2차 캐시) ​

6.5 상태 코드 캐시 ​

7. 배포 스크립트 자동화(업로드 + 자동 새로고침) ​

7.1 환경 준비 ​

7.2 사용법 ​

7.3 스크립트 실행 과정 ​

7.4 CI/CD 연동(GitHub Actions 예시) ​

7.5 버전 백업과 롤백 ​

7.6 변경 로그 자동 생성 ​

7.7 가벼운 대안: coscli + tccli(코드 작성 불필요) ​

비용 추정 ​

배포 가이드

빌드

방법 1: GitHub Pages

방법 2: Vercel / Netlify

방법 3: Nginx

커스텀 도메인과 HTTPS

방법 4: 텐센트 클라우드 COS + CDN

1. 준비

비안 절차 상세(텐센트 클라우드 ICP 비안)

2. 스토리지 버킷 생성

3. 빌드 산출물 업로드

4. CDN 가속 연동

5. HTTPS 설정

5.1 무료 인증서 신청

5.2 CDN에서 활성화

5.3 배포 결과 검증

5.4 CNAME 설정 설명

6. 캐시 설정

6.1 권장 캐시 규칙

6.2 캐시 적중과 적중률

6.3 캐시 새로고침과 프리히팅

6.4 브라우저 캐시(2차 캐시)

6.5 상태 코드 캐시

7. 배포 스크립트 자동화(업로드 + 자동 새로고침)

7.1 환경 준비

7.2 사용법

7.3 스크립트 실행 과정

7.4 CI/CD 연동(GitHub Actions 예시)

7.5 버전 백업과 롤백

7.6 변경 로그 자동 생성

7.7 가벼운 대안: coscli + tccli(코드 작성 불필요)

비용 추정