마케팅 사이트 개발 (Volcengine)
Volcengine에 이중 언어 정적 회사 마케팅 사이트를 구축하고 출시하기 위한 종단 간 스킬입니다. 두 단계로 구성됩니다:
- 빌드 — Astro 6 + React 19 아일랜드(모바일 메뉴만) + Tailwind 4. 모든 곳에서 인라인 SVG 사용. 단일 콘텐츠 파일(
src/content/site.ts)이 진실의 근원(source of truth)입니다. - 배포 — TOS 버킷 + CDN + 무료 DV 인증서 + HTTPS 강화, 모두
veCLI 및 Volcengine OpenAPI(ve가 제공하지 않는 작업을 위해volc-api.mjs를 통해 SigV4 서명)를 통해 멱등성 Node 스크립트로 스크립팅되었습니다.
성공의 기준: 사용자가 종단 간 약 6개의 명령어를 실행하고 https://<their-domain>/에서 HTTPS, HTTPS 강제 리디렉션, HSTS, HTTP/2, 에지 캐싱 및 자동 캐시 무효화를 갖춘 프로덕션 품질의 이중 언어 사이트를 제공받는 것입니다. 모든 인프라 단계는 멱등성 스크립트로 버전 관리됩니다.
이 스킬이 적합한가요?
이는 의도적으로 확고한 워크플로우로, 하나의 특정 시나리오에 최적화되어 있습니다. 깊이 들어가기 전에 해당 시나리오가 사용자의 상황과 실제로 일치하는지 확인하세요. 일치하지 않는다면, 사용자에게 더 무거운 경로를 강요하는 대신 더 나은 대안을 제시하세요.
다음과 같은 경우 이 스킬을 사용하세요:
- 사이트가 중국 회사 또는 중국 본토 사용자를 대상으로 하는 제품을 위한 것입니다. — 중국 본토에서 중국 외 CDN까지의 지연 시간이 충분히 나쁘기(200-400ms, 피크 시간에는 종종 더 심함) 때문에 방문자가 알아차리고 이탈합니다.
- ICP 비안(备案)이 필요하거나 이미 보유하고 있는 경우 — 중국에서 합법적으로 배포하려면 중국 클라우드에 호스팅된 도메인에 연결된 신고가 필요합니다. Volcengine은 비안 지원을 제공하며 여기에 배포하는 도메인에 대해 제공합니다.
- 사용자가 이미 Volcengine 생태계(다른 Volcengine 서비스, 기존 TOS 버킷 등)에 있으며 통합이 중요한 경우.
- 이중 언어(중국어/영어) 패턴이 필요한 경우 — 콘텐츠 계층(
site.ts)이 이를 중심으로 설계되었습니다.
다음과 같은 경우 더 간단한 대안을 사용하세요:
| 시나리오 | 권장 대안 | 이유 |
|---|---|---|
| 개인 사이트/포트폴리오/사이드 프로젝트, 중국어 청중 요구 사항 없음 | GitHub Pages | 무료, 자동 HTTPS, git push 시 배포, 관리할 인프라 없음. Volcengine의 함정이 전혀 적용되지 않습니다. |
| 국제 전용 청중(미국/유럽/동남아), 중국 진출 계획 없음 | Vercel(또는 Cloudflare Pages / Netlify) | 무료 티어, git에서 즉시 배포, PR별 미리보기 URL, 자동 HTTPS, 글로벌 에지 네트워크. ve CLI + ICP 워크플로우 전체를 건너뜁니다. |
| 사이트에 서버리스 함수(양식, 인증, 동적 콘텐츠)가 필요한 경우 | Vercel 또는 Cloudflare Pages(에지 함수 사용) | 이 스킬은 순수 정적 파일만 제공합니다. Volcengine에는 서버리스 제품이 있지만, 이 워크플로우는 이를 다루지 않습니다. |
| 브랜치/PR 기반 검토를 위한 미리보기 URL을 원하는 경우 | Vercel | Vercel의 미리보기 URL UX는 최고 수준입니다. 이 스킬은 푸시당 하나의 프로덕션 배포를 생성하며, 브랜치 미리보기는 없습니다. |
사용자의 상황이 "더 간단한 대안 사용" 열과 일치한다면, 스캐폴딩하기 전에 명시적으로 알려주세요. 사용자가 Volcengine이 제공하는 것이 필요하지 않을 때 30분짜리 Volcengine 부트스트랩보다 2분짜리 Vercel 배포가 더 나은 경험입니다. 이 스킬을 호출했다고 해서 잘못된 스택에 빠지게 하지 마세요.
확실하지 않다면 다음 질문을 하세요: "중국 본토 사용자가 귀하의 청중 중 의미 있는 부분을 차지할 것이며, 해당 도메인에 대한 ICP 비안(备案)이 있거나 (또는 신청할 계획이) 있습니까?" 두 질문에 대한 답변이 모두 '아니오'라면 Vercel / GitHub Pages를 추천하고 중단하세요.
1단계: 의도 파악 (항상 먼저 질문하세요)
사용자로부터 다음 여섯 가지 입력을 받기 전에는 코드를 작성하지 마세요. 프롬프트에 없으면 AskUserQuestion을 통해 질문하세요. 대부분의 팀은 공안 비안 번호를 제외한 모든 것을 가지고 있을 것입니다. 이 번호는 자리 표시자로 괜찮습니다.
| # | 입력 | 사용처 | 참고 |
|---|---|---|---|
| 1 | 회사명 (중국어 + 영어) | site.ts의 COMPANY.nameZh / COMPANY.nameEn; 바닥글; SEO | |
| 2 | 도메인 (예: example.com) | 모든 곳 — 버킷 바인딩, CDN, DNS, 인증서 SAN | 반드시 이미 ICP 신고가 완료되어 있어야 하며 이상적으로는 Volcengine DNS에서 호스팅되어야 합니다. 다른 곳에서 호스팅하는 경우 사용자가 수동으로 CNAME + TXT 레코드를 추가해야 합니다. |
| 3 | 브랜드 자산 디렉토리 (SVG 로고 파일 경로) | 인라인 BrandMark.astro 추출 (짧은 로고 SVG의 마지막 3개 경로) | 일반적으로 assets/logo/svg/Tenshow_short1.svg와 같은 — 짧은/아이콘 전용 변형. |
| 4 | 제품 목록 | site.ts의 PRODUCTS[] | 각 제품에는 이중 언어 이름 + 설명, URL, 악센트 16진수 색상, 아이콘 열거형이 필요합니다. |
| 5 | ICP 기록 번호 | 바닥글 | MIIT가 발급한 비안하오(备案号). |
| 6 | 작업 디렉토리 | 프로젝트 루트 | 그린필드(비어 있음)여야 하며, 그렇지 않으면 기존 파일과 조정해야 합니다. |
선택 사항:
- 공안 비안 번호(公安备案号) — 일반적으로 스캐폴딩 시 자리 표시자입니다. README에서 사용자가 출시 전에 교체해야 함을 강조하세요.
- 브랜드 강조 색상 — 로고 SVG의 16진수 값에서 추출합니다. 결정할 수 없는 경우 지배적인 중립 색상이 아닌 색상을 기본값으로 사용하세요.
2단계: 정적 사이트 구축
자세한 내용은 references/phase-1-static-site.md에 있습니다. 요약:
- 스캐폴드 —
assets/templates/package.json및assets/templates/astro.config.mjs를 프로젝트 루트에 복사합니다.package.json의name과astro.config.mjs의site를 업데이트합니다. - 패키지 설치 —
pnpm install. - Astro 에이전트 스킬 설치 —
pnpm install이 성공한 후에만:
스킬 설치가 실패하면 사이트 빌드를 계속하고 실패를 기록하여 사용자가 나중에 다시 시도할 수 있도록 합니다. 워크플로우를 차단하지 마세요.npx skills add https://github.com/astrolicious/agent-skills --skill astro - phase-1-static-site.md의 레이아웃과 일치하는 소스 트리를 만듭니다(
src/content/site.ts,src/components/,src/layouts/BaseLayout.astro,src/pages/index.astro,src/pages/en/index.astro,src/styles/global.css). - 사용자의 SVG에서 브랜드 마크를 추출합니다 —
assets/templates/BrandMark.astro를 시작점으로 사용합니다. 짧은 로고 SVG의 마지막 3개<path>요소가 마크입니다. 그대로 복사하고 브랜드 팔레트에서 채우기 색상을 선택합니다. - 섹션 구축 — 히어로(phase-1-static-site.md의 정확한 레시피 사용 — 그리드 배경 + 방사형 광선 + 그라데이션 제목 + 상태 알약 + 2개의 CTA), 소개, 제품, 초점, 업데이트, 연락처, 바닥글. 헤더 고정, 모바일 메뉴 = 유일한 React 아일랜드.
- 로컬에서 확인 —
pnpm dev로 개발,pnpm build && pnpm preview로 인프라를 건드리기 전에 정적 출력을 점검합니다.
스택 고정 (이탈하지 마세요)
Astro 6, React 19(모바일 메뉴만), Tailwind 4(via @tailwindcss/vite), pnpm 10, Node 22+, TypeScript strict, 제로 외부 이미지, 제로 UI 라이브러리, 제로 폰트 서비스, 시스템 폰트 스택. 근거 및 자세한 내용은 phase-1-static-site.md에 있습니다.
3단계: 배포 인프라 설정
자세한 내용은 references/phase-2-volcengine-deploy.md에 있습니다. 먼저 references/landmines.md를 읽으세요 — 이 단계에서 시간의 절반은 명령어를 실행하는 것이 아니라 함정을 피하는 데 사용됩니다.
- 스크립트 복사 —
assets/scripts/디렉토리 전체와assets/cdn-payloads/를 각각 사용자의scripts/및scripts/cdn-payloads/에 복사합니다.assets/templates/deploy.config.mjs를 프로젝트 루트에 복사하고bucket,region,endpoint,cdnDomains를 입력합니다. - 페이로드의 자리 표시자 교체 —
scripts/cdn-payloads/apex.json및www.json의{{DOMAIN}},{{BUCKET}},{{REGION}}.OriginHost는 도메인 자체여야 하며 비어 있으면 안 됩니다 — 템플릿은 기본적으로 올바르게 설정되어 있습니다. 편집하는 경우OriginHost를 유지하세요. landmines.md #3 참조. .env생성 프로젝트 루트에 (gitignore에 추가됨):
Volcengine AK/SK에는VOLC_ACCESS_KEY=AK... VOLC_SECRET_KEY=...TOSFullAccess,CDNFullAccess,DNSFullAccess,CertificateFullAccess(또는 최소 권한 등가) 권한이 필요합니다.ve설치 확인:ve version— 1.0.x 이상 필요. 없으면 Volcengine 공식 문서를 통해 설치하세요.
4단계: 첫 번째 배포 실행
pnpm install # 아직 안 했다면
npx skills add https://github.com/astrolicious/agent-skills --skill astro # 아직 안 했다면
pnpm build # 로컬 빌드가 작동하는지 확인
pnpm run setup:bucket # 멱등성: 버킷 + 웹사이트 라우팅 + 사용자 정의 도메인 바인딩
pnpm run deploy:upload # dist/ → 버킷 동기화
# 이 시점에서: https://<bucket>.tos-<region>.volces.com/index.html 가 200을 반환해야 함
pnpm run setup:cdn # 확인 → CDN 추가 → CNAME → 인증서 → HTTPS 강화
# DNS 전파를 위해 1-3분 대기
pnpm run cdn:refresh # 첫 번째 방문 시 버킷 목록 JSON을 반환하지 않도록 에지 캐시 제거
초기 실행 후, 일일 반복은 하나의 명령어가 됩니다:
pnpm run deploy && pnpm run cdn:refresh
항상 pnpm run을 사용하고, pnpm 단독으로 사용하지 마세요
pnpm deploy는 pnpm 내장 워크스페이스 명령어입니다. 워크스페이스 외부에서 실행하면 ERR_PNPM_CANNOT_DEPLOY 오류가 발생합니다. pnpm run deploy 및 **pnpm run cdn:refresh**를 사용하세요. 프로젝트의 README에 이를 문서화하세요. landmines.md #6 참조.
5단계: 확인
references/verification.md의 curl + openssl 체크리스트를 실행하세요. 예상 결과: 주요 경로에서 5× HTTP 200, HTTP → HTTPS에서 1× 301, apex + www를 포함하는 SAN이 있는 유효한 인증서, HTTP/2 + HSTS 확인, deploy.config.mjs 규칙과 일치하는 캐시 제어 헤더.
확인에 실패하면 verification.md에서 각 실패 모드를 근본 원인 및 해결 방법에 매핑합니다.
실행 전에 반드시 알아야 할 중요한 함정
전체 목록은 landmines.md에 있습니다. 읽지 않으면 부딪힐 함정들:
HTTPS_PROXY오염 — TOS SDK + 로컬 HTTP 프록시 =Protocol "http:" not supported.assets/scripts/의 모든 스크립트는 상단에서 프록시 환경 변수를 이미 삭제합니다. 복사/수정하는 경우 해당 전문을 유지하세요.- TOS SDK 특이점 —
headBucket(string)는headBucket({bucket})가 아닙니다.listObjectsType2서명은 입력에continuationToken: undefined가 있을 때 깨집니다.putObject는 public-read 버킷에서도 기본적으로 비공개입니다. 항상acl: 'public-read'를 설정하세요. - TOS에는 별도의 웹사이트 엔드포인트 호스트 이름이 없습니다 — 동일한
<bucket>.tos-<region>.volces.com은Host헤더에 따라 버킷 목록 JSON 또는index.html을 반환합니다. 반드시 (a) apex/www 도메인당putBucketCustomDomain을 호출하고, (b) CDNAddCdnDomain페이로드에서OriginHost를 사용자의 도메인(비어 있지 않음)으로 설정해야 합니다. - 확인을 위한 CDN ≠ DCDN — CDN(内容分发网络)은 TXT 호스트
volccdnauth와cdn:CheckCdnDomain(veCLI에 없음 —volc-api.mjs사용)을 원합니다. DCDN(全站加速)은_dnsauth와ve dcdn VerifyDomainOwnership을 사용합니다. 혼동하면 무한 확인 루프에 빠집니다. - TXT 변경 사항이 Volcengine 검증기로 전파되는 데 약 10분이 걸립니다. 첫 번째 쓰기에서 값을 올바르게 가져오세요. 불필요하게 변경하지 마세요.
pnpm deploy는 내장 명령어입니다.pnpm run deploy를 사용하세요.- 무료 DV 인증서 신청은 콘솔 전용입니다. 영구 AK/SK로 API 발급이 차단됩니다(
OperationDenied.RequestFreeInstance). 그러나 이미 발급된 인증서 나열은 문제없이 작동합니다 — 무료 DV 인증서는 도메인 등록 시 자동으로 발급되는 경우가 많습니다. 항상CertificateGetInstanceList를 먼저 호출하세요.San이 apex + www를 모두 포함하는 인증서를Result.Instances[](InstanceList또는Data아님)에서 찾으세요.
동작 규칙
- 먼저 계획하고, 파괴적인 작업 전에 확인하세요.
createBucket,AddCdnDomain, 기존 TXT에 대한DeleteRecord, 또는BatchDeployCert전에 무엇이 발생할지 요약하고 사용자에게 확인을 요청하세요. - 쓰기 전에 기존 상태를 읽으세요. 항상
ListRecords/ListCdnDomains/CertificateGetInstanceList를 먼저 실행하세요. 무료 인증서는 종종 사전 발급되고, CDN 도메인이 이미 존재할 수 있으며, DNS 레코드가 이미 올바른 위치를 가리키고 있을 수 있습니다. 멱등성이 핵심입니다. ve에 작업이 없는 경우 사용자에게ve를 업그레이드하거나 콘솔을 사용하라고 말하는 대신volc-api.mjs를 사용하세요. 유일한 콘솔 전용 경로는 무료 DV 인증서 발급입니다(landmines.md #4).- DNS 레코드를 불필요하게 변경하지 마세요. 각 TXT 수정은 약 10분의 캐시를 추가합니다. 호스트/값을 처음에 올바르게 가져오세요. CDN의 경우
volccdnauth, DCDN의 경우_dnsauth이며, 서로 바꿔 사용할 수 없습니다. - 모든 구성 결정을
deploy.config.mjs에 표시하고 절대 스크립트에 하드코딩하지 마세요. 버킷, 리전, 엔드포인트, CDN 도메인, 캐시 규칙 — 모두 구성 파일에 있어 사용자가 하나의 파일을 편집하여 모든 것을 변경할 수 있습니다. /usr/bin/curl은 동일한 셸에서 긴 명령어 실행 후 검사를 실행할 때curl단독보다 더 안정적입니다. bash PATH 조회가 때때로 이상해질 수 있기 때문입니다. CI 스크립트의 테스트에도 동일하게 적용됩니다.
번들된 자산 및 참조
assets/scripts/ (사용자의 scripts/에 그대로 복사)
lib/volc-api.mjs— SigV4 서명기, 종속성 제로.veCLI에서 누락된 모든 작업에 사용합니다.setup-bucket.mjs— 멱등성 버킷 + 웹사이트 + 사용자 정의 도메인 바인딩.deploy.mjs— 접두사별Cache-Control및 고아 파일 삭제가 포함된 TOS 동기화 업로더.cdn-setup.mjs— CDN 오케스트레이션: 소유권 확인 → AddCdnDomain → CNAME → 인증서 → HTTPS 강화.cdn-refresh.mjs—cdn:SubmitRefreshTask를 통한 캐시 무효화(volc-api.mjs로 서명,ve없이 CI에서 작동).
assets/cdn-payloads/ (scripts/cdn-payloads/에 복사)
...
[번역을 위해 잘림]