shipwords로 키워드 중심 AI 사이트 포트폴리오 구축 및 출시

shipwords의 기능

shipwords는 Cloudflare에서 AI 이미지 및 동영상 사이트를 여러 개 운영하기 위한 MIT 라이선스 오픈 소스 프레임워크이며, 각 키워드마다 하나의 사이트를 전용으로 제공합니다. 계정, 결제, 크레딧, AI 생성과 같은 공통 기능은 프레임워크에 한 번만 구현하고, 각 사이트는 고유한 페이지, 시각적 정체성, 도메인, 데이터베이스, 스토리지, 결제 계정을 사용할 수 있습니다.

각 사이트는 자체 Cloudflare Worker에서 실행되는 TanStack Start 및 React 19 애플리케이션이며, D1, R2, Workflows를 사용합니다. 이렇게 분리하면 사이트를 독립적으로 출시, 업데이트 또는 폐기하면서도 이후 배포에서 공유 코어의 개선 사항을 계속 적용할 수 있습니다.

주요 기능

• 계정 페이지를 포함한 Google 및 이메일 로그인.
• 크레딧 팩, 구독, 주문, 환불, 분쟁을 포함한 Stripe 및 PayPal 지원.
• 이메일 알림 및 reCAPTCHA v3 악용 제한이 적용된 게스트 무료 사용.
• 개인정보 보호, 이용 약관, 환불, DMCA 페이지.
• sitemap.xml, robots.txt, llms.txt를 포함한 SEO 및 GEO 도우미.
• 단방향 작업 상태와 실패한 작업의 자동 환불을 지원하는 워크플로 기반 생성 런타임.
• GPT Image, Nano Banana, Seedream, FLUX, Seedance, Veo, Kling, Wan 등의 모델을 위한 Yir API 통합.
• 모델 API 키 없이 로컬 개발에 사용할 수 있는 모의 업스트림.
• ffmpeg 컨테이너를 사용한 선택적 동영상 합성.

사전 요구 사항

시작하기 전에 저장소의 .nvmrc에 지정된 Node 24를 설치하고, 필요한 pnpm 버전을 사용할 수 있도록 Corepack을 활성화하세요:

corepack enable

Windows에서는 Git Bash 또는 WSL을 사용하세요. 배포하고 결제를 받을 준비가 되었을 때는 Cloudflare 계정과 Stripe 또는 PayPal 계정이 필요합니다. 기본적인 로컬 설정에는 필요하지 않습니다.

저장소 설치

저장소를 포크하거나 클론한 다음 종속 항목을 설치하세요:

pnpm install

새 사이트 스캐폴딩

사이트 생성기를 사용해 완전한 AI 사이트 템플릿으로 사이트를 만드세요. 첫 번째 인수는 sites/ 아래의 디렉터리가 되며, 도메인은 사이트 구성에 기록됩니다:

pnpm new-site my-tool --domain my-tool.com
pnpm install

생성된 사이트에는 홈 페이지, 가격 페이지, 계정 및 로그인 흐름, 정책 페이지와 표준 sitemap.xml, robots.txt, llms.txt 파일이 포함됩니다. 새 사이트의 종속 항목을 설치하려면 pnpm install을 다시 실행하세요.

로컬 시크릿 구성

로컬 시크릿은 저장소 외부에 보관하세요. 구성 디렉터리를 만들고, 생성된 사이트의 예시 변수 파일을 복사한 다음 worktree 구성을 연결하세요:

mkdir -p ~/.config/shipwords
cp sites/my-tool/.dev.vars.example ~/.config/shipwords/my-tool.dev.vars
pnpm setup:worktree

예시 구성은 로컬 개발에서 즉시 작동하도록 설계되었습니다. 이메일 로그인 코드는 개발 서버의 터미널에 출력되고, 새 계정에는 가입 크레딧이 지급되며, UPSTREAM_MOCK=1일 때 생성에는 모의 업스트림이 사용됩니다. 따라서 모델 API 키 없이도 애플리케이션을 테스트할 수 있습니다.

실제 생성 추가

실제 모델 요청을 사용하려면 Yir API 키를 추가하고 UPSTREAM_MOCK을 변경하여 모의 업스트림을 끄세요.

결제 테스트

크레딧 구매를 테스트하려면 sk_test_로 시작하는 Stripe 테스트 키를 추가하세요. 사이트 디렉터리에서 저장소의 웹훅 포워딩 유틸리티를 실행하면 로컬 개발 환경에서 Stripe 이벤트를 받을 수 있습니다:

node ../../tools/stripe-listen.mjs

공유 결제 코드는 반복되거나 순서가 뒤바뀐 결제 이벤트, 이중 청구, 실패한 작업의 환불을 처리하도록 설계되었습니다.

선택적 로그인 및 게스트 액세스 구성

게스트 무료 사용에는 reCAPTCHA 키가 필요합니다. 키가 없으면 방문자는 첫 번째 생성을 시작하기 전에 로그인해야 합니다. Google 로그인은 선택 사항입니다. 활성화하려면 Google OAuth 클라이언트를 만들고 http://localhost:<port>를 허용된 출처로 사용하세요. 이메일 로그인은 Google OAuth 없이도 작동합니다.

로컬에서 사이트 실행

생성된 사이트로 이동해 로컬 데이터베이스 아티팩트를 만들고, 로컬 마이그레이션을 적용한 다음 개발 서버를 시작하세요:

cd sites/my-tool
pnpm db:generate && pnpm db:migrate:local
pnpm dev

개발 서버에 출력된 로컬 URL을 여세요. 예시 구성을 사용해 이메일 인증, 계정 생성, 크레딧 및 모의 생성을 테스트할 수 있습니다.

저장소 명령 사용

대부분의 명령은 특정 사이트에 적용하거나 저장소 전체 검사에 사용할 수 있습니다:

pnpm new-site <dir> --domain <domain>
pnpm list-sites
pnpm setup:worktree
pnpm --filter "./sites/<site>" dev
pnpm --filter "./sites/<site>" check
pnpm check:packages
pnpm check:template
pnpm lint && pnpm test:tools

list-sites 명령은 각 사이트의 코드와 README를 바탕으로 사이트 목록을 만듭니다. 사이트의 check 명령은 타입 검사, 빌드 및 실행 확인을 수행합니다. 패키지 검사는 공유 코어와 jobs 패키지를 대상으로 하며, 템플릿 및 도구 검사는 출시 전에 문제를 발견하는 데 도움을 줍니다.

AI 코딩 에이전트로 사이트 구축

대상으로 삼을 키워드를 이미 알고 있다면 저장소는 에이전트 기반 워크플로를 지원합니다. Claude Code, Codex 또는 Cursor에서 저장소의 에이전트 지침을 제공하고 사이트를 구축하도록 요청하세요:

Read shipwords.dev/llms.txt and build a site for "<your keyword>"

에이전트는 저장소를 복제하고 사이트를 생성한 뒤 로컬에서 실행할 수 있습니다. AI 코딩 에이전트에 대한 규칙은 AGENTS.md에 문서화되어 있습니다. 새롭게 등장하는 키워드에 대한 아이디어가 필요하다면 별도의 new-term-radar 프로젝트를 참고하세요. 이 프로젝트는 X, Hugging Face, GitHub 및 사이트맵에서 새로운 AI 용어를 모니터링합니다.

고급 사이트 동작 사용자 지정

공유 생성 런타임 사용

packages/jobs 패키지는 워크플로 기반 런타임, 업스트림 어댑터 인터페이스, Yir 어댑터, 로컬 모의 업스트림, 선택적 ffmpeg 합성을 제공합니다. 사이트별 생성 동작은 사이트 구성에 유지하고, 작업 처리와 환불 처리는 공유 런타임을 사용하세요.

생성 비용 한도 설정

Yir를 통한 모델 호출은 요청 단위로 청구됩니다. 각 작업의 최대 비용은 site.models.ts에서 설정합니다. 실제 생성을 활성화하기 전에 이 한도를 검토하여 사이트의 가격 및 크레딧 동작이 최대 업스트림 비용과 일치하는지 확인하세요.

동영상 예제 살펴보기

동영상 중심 사이트를 만들 때는 sites/tinydeskai-example을 살펴보세요. 이 디렉터리는 Tiny Desk AI의 전체 소스이며 사진 슬롯, 단일 단계 동영상 편집, 출력 확인, ffmpeg 합성 및 콘텐츠 페이지를 보여 줍니다. 이 워크플로는 바이럴 클립을 방문자가 업로드한 사진과 함께 사용할 수 있는 템플릿으로 변환합니다.

사이트 독립성 유지

각 사이트는 자체 데이터베이스, 스토리지 및 결제 계정을 사용하여 독립적으로 배포됩니다. 이 아키텍처를 사용하면 공유 코어를 한 번 개선한 후, 사이트의 출시 또는 종료를 서로 결합하지 않고 선택한 사이트에 업데이트를 배포할 수 있습니다.

프로덕션 준비

로컬 사이트가 정상적으로 작동하면 사이트 출시 핸드북에 따라 프로덕션 절차를 진행하세요. 도메인 비용, Cloudflare 사용료, 결제 처리 수수료 및 Yir 모델 요청 비용을 계획해야 합니다. 클립을 이어 붙이는 동영상 사이트는 Cloudflare Containers를 사용하며 Workers Paid 플랜이 필요합니다.

출시 전에 사이트의 인증, 결제 웹훅, 크레딧 동작, 생성 실패, 환불, 정책 페이지, SEO 파일 및 분석 구성을 확인하세요. 저장소에는 더 자세한 구성 정보를 위한 아키텍처 및 로컬 개발 문서도 포함되어 있습니다.

결론

shipwords는 각 프로젝트마다 인증, 결제, 크레딧, 생성 워크플로 및 SEO 지원을 다시 구축하지 않고도 여러 키워드 중심 AI 사이트를 출시할 수 있는 실용적인 기반을 제공합니다. 템플릿으로 시작하고, 로컬 테스트에는 모의 업스트림을 사용하며, 준비가 되면 실제 제공자를 추가한 뒤, 완성된 각 사이트를 Cloudflare에 독립적으로 배포하세요.