Communitygithub.com

tenshowinnovation/tenshow-se-skills

Volcengine(火山引擎)에 이중 언어(중국어/영어) 정적 회사 마케팅 사이트를 출시하는 확고한 종단 간 워크플로우: Astro 6 + React 19 아일랜드 + Tailwind 4, TOS + CDN에 배포, HTTPS, 강제 리디렉션, HSTS, HTTP/2 지원, 전적으로 `ve` CLI 및 Node SDK를 통해 구현.

tenshow-se-skills란 무엇인가요?

이 스킬은 Volcengine(火山引擎) 클라우드 인프라에 이중 언어(중국어/영어) 정적 회사 마케팅 사이트를 구축하고 배포하기 위한 매우 구체적이고 확고한 워크플로우입니다. Astro 6 + React 19(모바일 메뉴 전용) + Tailwind 4 스택을 활용하여 모든 이미지를 인라인 SVG로 처리하고 단일 `src/content/site.ts` 파일을 콘텐츠의 단일 진실 공급원(source of truth)으로 사용합니다. 배포는 `ve` CLI와 Node 기반 스크립트를 통해 TOS(객체 스토리지) 버킷, CDN, 무료 DV 인증서, HTTPS 강화를 자동으로 프로비저닝하며, 각 인프라 단계는 멱등성 스크립트로 버전 관리됩니다. 이 워크플로우는 또한 Astro 에이전트 스킬을 종속성 설치 후 로드하여 향후 세션에서 프레임워크별 지침을 제공합니다. 사용자가 회사/브랜드 웹사이트, 특히 중국 본토 배포, ICP 비안(备案) 또는 Volcengine 서비스와 관련된 내용을 언급할 때 이 스킬을 사용하는 것을 선호합니다. 스킬의 SKILL.md 파일은 대체 시나리오(예: GitHub Pages, Vercel)에 대한 명확한 의사 결정 트리를 제공하므로, 사용자가 실제로 필요하지 않은 복잡한 Volcengine 워크플로우에 빠지지 않도록 합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tenshowinnovation/tenshow-se-skills/tree/HEAD/marketing-site-dev

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

마케팅 사이트 개발 (Volcengine)

Volcengine에 이중 언어 정적 회사 마케팅 사이트를 구축하고 출시하기 위한 종단 간 스킬입니다. 두 단계로 구성됩니다:

  1. 빌드 — Astro 6 + React 19 아일랜드(모바일 메뉴만) + Tailwind 4. 모든 곳에서 인라인 SVG 사용. 단일 콘텐츠 파일(src/content/site.ts)이 진실의 근원(source of truth)입니다.
  2. 배포 — TOS 버킷 + CDN + 무료 DV 인증서 + HTTPS 강화, 모두 ve CLI 및 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을 원하는 경우VercelVercel의 미리보기 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진수 색상, 아이콘 열거형이 필요합니다.
5ICP 기록 번호바닥글MIIT가 발급한 비안하오(备案号).
6작업 디렉토리프로젝트 루트그린필드(비어 있음)여야 하며, 그렇지 않으면 기존 파일과 조정해야 합니다.

선택 사항:

  • 공안 비안 번호(公安备案号) — 일반적으로 스캐폴딩 시 자리 표시자입니다. README에서 사용자가 출시 전에 교체해야 함을 강조하세요.
  • 브랜드 강조 색상 — 로고 SVG의 16진수 값에서 추출합니다. 결정할 수 없는 경우 지배적인 중립 색상이 아닌 색상을 기본값으로 사용하세요.

2단계: 정적 사이트 구축

자세한 내용은 references/phase-1-static-site.md에 있습니다. 요약:

  1. 스캐폴드 — assets/templates/package.json 및 assets/templates/astro.config.mjs를 프로젝트 루트에 복사합니다. package.json의 name과 astro.config.mjs의 site를 업데이트합니다.
  2. 패키지 설치 — pnpm install.
  3. Astro 에이전트 스킬 설치 — pnpm install이 성공한 후에만:
    npx skills add https://github.com/astrolicious/agent-skills --skill astro
    
    스킬 설치가 실패하면 사이트 빌드를 계속하고 실패를 기록하여 사용자가 나중에 다시 시도할 수 있도록 합니다. 워크플로우를 차단하지 마세요.
  4. 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).
  5. 사용자의 SVG에서 브랜드 마크를 추출합니다 — assets/templates/BrandMark.astro를 시작점으로 사용합니다. 짧은 로고 SVG의 마지막 3개 <path> 요소가 마크입니다. 그대로 복사하고 브랜드 팔레트에서 채우기 색상을 선택합니다.
  6. 섹션 구축 — 히어로(phase-1-static-site.md의 정확한 레시피 사용 — 그리드 배경 + 방사형 광선 + 그라데이션 제목 + 상태 알약 + 2개의 CTA), 소개, 제품, 초점, 업데이트, 연락처, 바닥글. 헤더 고정, 모바일 메뉴 = 유일한 React 아일랜드.
  7. 로컬에서 확인 — 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를 읽으세요 — 이 단계에서 시간의 절반은 명령어를 실행하는 것이 아니라 함정을 피하는 데 사용됩니다.

  1. 스크립트 복사 — assets/scripts/ 디렉토리 전체와 assets/cdn-payloads/를 각각 사용자의 scripts/ 및 scripts/cdn-payloads/에 복사합니다. assets/templates/deploy.config.mjs를 프로젝트 루트에 복사하고 bucket, region, endpoint, cdnDomains를 입력합니다.
  2. 페이로드의 자리 표시자 교체 — scripts/cdn-payloads/apex.json 및 www.json의 {{DOMAIN}}, {{BUCKET}}, {{REGION}}. OriginHost는 도메인 자체여야 하며 비어 있으면 안 됩니다 — 템플릿은 기본적으로 올바르게 설정되어 있습니다. 편집하는 경우 OriginHost를 유지하세요. landmines.md #3 참조.
  3. .env 생성 프로젝트 루트에 (gitignore에 추가됨):
    VOLC_ACCESS_KEY=AK...
    VOLC_SECRET_KEY=...
    
    Volcengine AK/SK에는 TOSFullAccess, CDNFullAccess, DNSFullAccess, CertificateFullAccess (또는 최소 권한 등가) 권한이 필요합니다.
  4. 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에 있습니다. 읽지 않으면 부딪힐 함정들:

  1. HTTPS_PROXY 오염 — TOS SDK + 로컬 HTTP 프록시 = Protocol "http:" not supported. assets/scripts/의 모든 스크립트는 상단에서 프록시 환경 변수를 이미 삭제합니다. 복사/수정하는 경우 해당 전문을 유지하세요.
  2. TOS SDK 특이점 — headBucket(string)는 headBucket({bucket})가 아닙니다. listObjectsType2 서명은 입력에 continuationToken: undefined가 있을 때 깨집니다. putObject는 public-read 버킷에서도 기본적으로 비공개입니다. 항상 acl: 'public-read'를 설정하세요.
  3. TOS에는 별도의 웹사이트 엔드포인트 호스트 이름이 없습니다 — 동일한 <bucket>.tos-<region>.volces.com은 Host 헤더에 따라 버킷 목록 JSON 또는 index.html을 반환합니다. 반드시 (a) apex/www 도메인당 putBucketCustomDomain을 호출하고, (b) CDN AddCdnDomain 페이로드에서 OriginHost를 사용자의 도메인(비어 있지 않음)으로 설정해야 합니다.
  4. 확인을 위한 CDN ≠ DCDN — CDN(内容分发网络)은 TXT 호스트 volccdnauth와 cdn:CheckCdnDomain(ve CLI에 없음 — volc-api.mjs 사용)을 원합니다. DCDN(全站加速)은 _dnsauth와 ve dcdn VerifyDomainOwnership을 사용합니다. 혼동하면 무한 확인 루프에 빠집니다.
  5. TXT 변경 사항이 Volcengine 검증기로 전파되는 데 약 10분이 걸립니다. 첫 번째 쓰기에서 값을 올바르게 가져오세요. 불필요하게 변경하지 마세요.
  6. pnpm deploy는 내장 명령어입니다. pnpm run deploy를 사용하세요.
  7. 무료 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 서명기, 종속성 제로. ve CLI에서 누락된 모든 작업에 사용합니다.
  • 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/에 복사)

...

[번역을 위해 잘림]

관련 스킬