Open-source template for "one photo → AI video that follows a viral template" SaaS sites, one site per trending keyword. Cloudflare Workers + D1/R2/KV/Queues, TanStack Start + Hono, Google sign-in, credit packs (Waffo/Dodo), fal.ai video generation, admin console.

ShrimpReel — 정의 및 작동 방식

ShrimpReel은 한 장의 사진을 AI 생성 비디오로 변환하여 바이럴 트렌드(예: 댄스 챌린지)를 따르는 SaaS 웹사이트를 구축하기 위한 오픈소스 템플릿입니다. 아이디어는 모든 트렌드 키워드에 전용 사이트를 만들고, 각 사이트를 이 동일한 템플릿에서 구축하는 것입니다. 리포지토리를 클론하고 구성, 카피, 미디어를 변경하면 새 사이트를 바로 시작할 수 있습니다.

모든 것은 Cloudflare의 인프라에서 실행됩니다 — Workers(서버리스 코드), D1(데이터베이스), R2(객체 스토리지), KV(키-값 저장소), Queues, Rate Limiting, Cron Triggers. 즉, 전체 스택이 Cloudflare에서 관리되므로 자체 서버가 필요 없습니다.

핵심 개념

사진 한 장 → AI 비디오: 사용자가 사진 한 장을 업로드하면 사이트는 사전 정의된 템플릿(예: 산타의 작업장에서 엘프로 춤추기)을 따르는 짧은 비디오를 생성합니다.
키워드별 사이트: 각 사이트는 특정 바이럴 키워드(예: "크리스마스 댄스 AI")를 대상으로 합니다. 이 템플릿에서 새 리포지토리를 만들고 키워드를 설정한 다음 출시합니다.
수익화: 사용자는 비디오를 생성하기 위해 크레딧(일회성 팩 또는 구독)을 지불합니다. 결제는 제3자 제공업체(Waffo Pancake, Dodo Payments 또는 Stripe)가 처리합니다.

기술 스택(간소화)

프론트엔드 및 서버 사이드 렌더링: TanStack Start (React 19) + Tailwind CSS 4. 사이트는 이중 언어입니다 — 영어는 /, 중국어는 /zh.
API: Hono(경량 웹 프레임워크)가 모든 /api/* 라우트, 미디어, sitemap, robots.txt 등을 처리합니다.
결제: 기본값은 Waffo Pancake(기록 판매자, 즉 판매세를 처리). Dodo Payments는 대안입니다. Stripe도 지원되지만 귀하가 판매자가 되어 세금을 직접 처리해야 합니다. 로컬 개발의 경우 mock 제공업체가 결제를 시뮬레이션합니다.
비디오 생성: 기본적으로 fal.ai의 큐 API를 사용합니다. 선택적 대안: yir.ai 라우터 또는 NanoAPI. 로컬 테스트에는 mock 제공업체를 사용합니다.

주요 기능

사용자 및 크레딧

Google 로그인(One Tap 포함).
크레딧 팩(일회성 구매) 및 월간/연간 구독.
크레딧 원장이 모든 거래를 추적합니다.
사용자 대시보드: 비디오 보기, 청구, 설정, 코드 사용, 초대 링크, 계정 삭제, 데이터 내보내기.

주문 및 생성

크레딧을 회수하는 전체 및 부분 환불.
실패한 작업을 위한 데드 레터 큐가 있는 생성 큐.
생성 실패 시 크레딧이 자동으로 반환됩니다.

성장 및 분석

퍼스트 터치 및 라스트 터치 기여(UTM 매개변수, 광고 클릭 ID).
퍼널 추적: 방문 → 가입 → 체크아웃 → 결제 → 생성.
동의 배너 뒤의 GA4 이벤트.
비디오 공개 공유 페이지(비디오별 옵트인, 링크 미리보기 포함).

관리 패널

개요 대시보드(제공업체 비용 및 총 마진 포함).
사용자, 주문, 생성, 삭제 요청, 문의 메시지, 결제 이벤트, 이메일, 감사 로그, 보고서, 사용 코드, 추천 리더보드, 런타임 설정, 연결 테스트 관리.
필터 및 검색이 있는 사용자, 주문, 생성 상세 보기.

이메일 및 알림

트랜잭션 이메일: 크레딧 추가, 비디오 준비 완료, 생성 실패, 환불, 삭제 요청 영수증.
관리자는 새 삭제 요청, 마감일 알림, 문의 메시지에 대한 알림을 받습니다.
Telegram, Feishu, Discord 등을 통한 즉시 결제 알림.

규정 준수 및 안전

비디오의 AI 생성 라벨.
사진은 7일 후 삭제되고 비디오는 30일 후 삭제됩니다.
삭제 요청은 48시간 큐에서 처리됩니다(동일한 원본 사진에서 만든 모든 비디오를 제거하고 해당 사진을 차단).
업로드 검토 및 문의/신고 양식의 Turnstile(CAPTCHA).

운영 및 보안

유지 관리 모드, 체크아웃 일시 중지, 결제 제공업체 전환, 사이트 전체 공지, 일일 생성 상한 — 모두 재배포 없이 관리자에서 변경 가능.
상태 확인 알림 이메일, R2로의 일일 D1 백업, Workers Logs로의 브라우저 오류 보고.
요청별 nonce가 있는 콘텐츠 보안 정책(CSP) 및 Permissions-Policy.

콘텐츠 및 SEO

섹션이 있는 원페이지 홈: 작동 방식, 정의, 선택적 문제/DIY 블록.
확장 가능한 기사 컬렉션(/guides 허브, 관련 기사).
법적 페이지, 문의 양식.
SSR canonical, hreflang, JSON-LD, sitemap.
카피는 로케일별로 코드 분할됩니다(브라우저는 현재 언어만 로드).
npm run seo:check는 사이트 전체의 SEO 문제를 린트합니다.

로컬 개발

템플릿을 로컬에서 실행하려면:

npm install
cp .dev.vars.example .dev.vars   # 최소한 SESSION_SECRET 설정
npm run seed:local               # 데이터베이스 마이그레이션 적용 및 로컬 R2에 템플릿 미디어 업로드
npm run dev -- --host 127.0.0.1  # http://127.0.0.1:3000

npm 11.19 이상을 사용하세요.
기본적으로 PAYMENT_PROVIDER=mock 및 VIDEO_PROVIDER=mock — 실제 청구나 생성이 없습니다.
프로덕션 외부에서 개발 로그인을 사용할 수 있습니다(POST /api/auth/dev-login).
이메일은 로컬에서 시뮬레이션됩니다. GET /api/dev/emails?to=<email>&ref=<order or takedown id>로 보낸 편지함을 확인하세요.

새 사이트 시작

README에는 자세한 8단계 프로세스가 있습니다. 요점은 다음과 같습니다:

사이트 리포지토리 생성 — 템플릿을 클론하고 원격을 upstream으로 이름 변경하고 자체 origin을 추가합니다.
스캐폴더 실행 — node scripts/new-site.mjs가 site.ts, wrangler.jsonc, package.json을 키워드, 도메인 및 기타 설정으로 업데이트합니다.
카피 재작성 — src/content/en.ts 및 src/content/zh.ts를 편집하여 새 트렌드에 맞춥니다. 키워드만 바꾸지 마세요 — Google은 확장된 콘텐츠 남용을 처벌합니다.
미디어 교체 — 자체 템플릿 비디오, 데모 비디오, 로고 등을 업로드합니다.
wrangler.jsonc에서 환경 변수 설정(사이트 URL, 결제 제공업체, 관리자 이메일 등).
결제 제공업체로 제품 생성(크레딧 팩 및 구독 플랜).
로컬에서 검증 — 타입체크, 테스트, e2e, SEO 검사를 실행합니다.
배포한 다음 sitemap을 검색 엔진에 제출합니다.

2~4단계와 7단계의 로컬 부분을 자동화하는 Claude Code 스킬(new-hot-site)도 있습니다.

템플릿 업데이트 병합

각 사이트는 템플릿을 upstream으로 추적하는 별도의 리포지토리이므로 수정 사항과 새 기능을 가져올 수 있습니다:

git fetch upstream
git merge --no-ff upstream/main

동기화 계획 스크립트(scripts/sync-plan.mjs)는 충돌을 식별하는 데 도움이 됩니다. 사이트별 변경 사항은 src/config/site.ts, src/content/*, public/*, seed/, wrangler.jsonc, package.json에 유지하고 나머지는 템플릿과 동일하게 유지하세요.

Cloudflare에 배포

필요한 Cloudflare 리소스(D1 데이터베이스, R2 버킷, KV 네임스페이스, Queues)를 사이트별로 생성한 다음 마이그레이션을 실행하고 템플릿 미디어를 업로드해야 합니다. README에 정확한 명령이 있습니다.

문서 및 메모

릴리스 노트: CHANGELOG.md
기능 계획: docs/SAAS_VIDEO_FEATURES.md, ROADMAP.md
SEO 규칙: docs/SEO_AUDIT.md
환경 변수: docs/env.md
결제 제공업체 설정: docs/payments.md
구독 세부 정보: docs/subscriptions.md
코드 규칙: AGENTS.md

대부분의 문서 파일은 중국어입니다.

ShrimpReel은 사용자 인증부터 비디오 생성, 결제, 관리, SEO까지 모든 것을 Cloudflare의 무료 등급 친화적 스택에서 처리하는 완전하고 프로덕션 준비가 된 템플릿입니다. 새로운 바이럴 트렌드마다 클론하고 사용자 지정할 수 있도록 설계되어 새 사이트를 빠르게 시작할 수 있습니다.

qianshuixia/shrimpreel