Chuyển đến nội dung chính
Hướng dẫn AI

Xây dựng và ra mắt SaaS video lan truyền bằng AI với ShrimpReel

Tìm hiểu cách chạy ShrimpReel trên máy cục bộ, tùy chỉnh cho một xu hướng video lan truyền, thiết lập thanh toán và tính năng tạo video, cấp phát tài nguyên Cloudflare, triển khai an toàn và giữ cho từng trang web theo từ khóa luôn đồng bộ với mẫu nguồn.

Thời gian đọc khoảng 30 phút
Xây dựng và ra mắt SaaS video lan truyền bằng AI với ShrimpReel

ShrimpReel là gì?

ShrimpReel là một mẫu SaaS mã nguồn mở để xây dựng các website biến một ảnh được tải lên thành video do AI tạo ra dựa trên một định dạng lan truyền. Quy trình dự kiến là tạo một repository riêng cho từng từ khóa đang thịnh hành, thay đổi cấu hình và nội dung song ngữ của website, thay thế nội dung đa phương tiện, rồi triển khai ứng dụng hoàn chỉnh trên Cloudflare.

Công nghệ sử dụng TanStack Start cùng React 19 và Tailwind CSS 4 cho frontend và kết xuất phía máy chủ. API Hono xử lý các route dưới /api/*, phân phối nội dung đa phương tiện, chỉ thị robots, sitemap và xác minh IndexNow. Điểm vào của máy chủ là src/server.ts.

Ứng dụng được thiết kế cho Cloudflare Workers, D1, R2, KV, Queues, Rate Limiting và Cron Triggers. Các trang tiếng Anh được phục vụ tại /, trong khi các trang tiếng Trung có tại /zh.

Trạng thái dự án: Theo README, quy trình hoàn chỉnh vượt qua các bài kiểm thử đơn vị cục bộ và kiểm thử end-to-end bằng Playwright, nhưng mẫu này vẫn chưa được xác minh khi triển khai production. Hãy xem ROADMAP.md trước khi phụ thuộc vào từng tích hợp với dịch vụ thực.

Tính năng chính

Tài khoản, thanh toán và credit

  • Đăng nhập Google, bao gồm Google One Tap, cùng chức năng đăng nhập phát triển chỉ dành cho localhost.
  • Gói credit và các gói đăng ký tùy chọn theo tháng hoặc năm.
  • Sổ cái credit, mã đổi thưởng, liên kết giới thiệu, lịch sử thanh toán, chi tiết đơn hàng có thể in, xóa tài khoản và xuất dữ liệu.
  • Waffo Pancake là nhà cung cấp thanh toán mặc định hoặc Dodo Payments là lựa chọn thay thế.
  • Hoàn tiền một phần hoặc toàn bộ kèm thu hồi credit tự động.

Tạo video

  • Queue API của fal.ai là nhà cung cấp video mặc định.
  • Tùy chọn định tuyến qua yir.ai.
  • Nhà cung cấp giả lập sao chép video mẫu trong quá trình phát triển và kiểm thử cục bộ.
  • Hàng đợi tạo video, hàng đợi thư chết và tự động hoàn credit khi quá trình tạo thất bại.
  • Các trang chia sẻ video công khai mà người dùng có thể bật cho từng video.

Tăng trưởng, quản trị và vận hành

  • Phân bổ lượt chạm đầu tiên và cuối cùng bằng giá trị UTM và mã nhận dạng lượt nhấp quảng cáo.
  • Phễu từ lượt truy cập đến lượt tạo video và các sự kiện GA4 được kiểm soát theo sự đồng ý.
  • Giao diện quản trị cho người dùng, đơn hàng, video được tạo, sự kiện thanh toán, yêu cầu gỡ bỏ, báo cáo, email, bản ghi kiểm toán, lượt giới thiệu, cài đặt runtime và kiểm thử kết nối.
  • Báo cáo chi phí nhà cung cấp và biên lợi nhuận gộp.
  • Chế độ bảo trì, thông báo, giới hạn tạo video hằng ngày, cảnh báo tình trạng hệ thống, báo lỗi trình duyệt và thông báo thanh toán.
  • Sao lưu D1 hằng ngày vào R2.

An toàn, lưu trữ và SEO

  • Kiểm duyệt nội dung tải lên và nhãn do AI tạo trên video.
  • Tự động xóa ảnh sau bảy ngày và video sau 30 ngày.
  • Hàng đợi gỡ bỏ trong 48 giờ, xóa các video được tạo từ cùng ảnh nguồn và chặn ảnh đó.
  • Hỗ trợ Turnstile trên biểu mẫu liên hệ và báo cáo.
  • URL chuẩn, metadata hreflang, JSON-LD, sitemap, các trang pháp lý, hướng dẫn, bài viết liên quan và nội dung bản địa hóa được tách mã.
  • Công cụ kiểm tra SEO trên toàn site, có thể chạy bằng npm run seo:check.

Điều kiện tiên quyết

Cài đặt Node.js và npm 11.19 trở lên. Các phiên bản npm cũ hơn có thể viết lại package-lock.json theo cách khiến npm ci thất bại trong quá trình tích hợp liên tục.

Để triển khai production, bạn cũng cần tài khoản Cloudflare, tài khoản nhà cung cấp thanh toán, khóa API của nhà cung cấp video và thông tin xác thực Google OAuth. Chỉ cần FFmpeg khi tạo lại nội dung đa phương tiện giữ chỗ bằng script đi kèm.

Cài đặt và chạy ShrimpReel cục bộ

1. Cài đặt các gói phụ thuộc và tạo biến cục bộ

npm install
cp .dev.vars.example .dev.vars

Mở .dev.vars và đặt ít nhất SESSION_SECRET. Production và staging yêu cầu giá trị mạnh có độ dài tối thiểu 32 ký tự. README khuyến nghị tạo giá trị này bằng:

openssl rand -hex 32

2. Chuẩn bị cơ sở dữ liệu và bộ nhớ đa phương tiện cục bộ

npm run seed:local

Lệnh này áp dụng các migration D1 và tải các tệp từ seed/templates/*.mp4 lên bộ nhớ R2 được mô phỏng cục bộ.

3. Khởi động máy chủ phát triển

npm run dev -- --host 127.0.0.1

Mở http://127.0.0.1:3000. Trên Windows, sử dụng rõ ràng 127.0.0.1 cũng tránh được trường hợp công cụ kiểm thử phân giải localhost thành IPv6.

Không chạy máy chủ phát triển trên 0.0.0.0 hoặc công khai trực tiếp trên internet. Chức năng đăng nhập phát triển, thanh toán giả lập và /api/dev/* chỉ dành cho các yêu cầu trực tiếp từ localhost.

Thử quy trình cơ bản

Cấu hình cục bộ mặc định sử dụng PAYMENT_PROVIDER=mock, VIDEO_PROVIDER=mock và MODERATION_PROVIDER=mock. Nhờ đó, bạn có thể sử dụng thử sản phẩm mà không bị tính phí thẻ hoặc gửi tác vụ đến dịch vụ video bên ngoài.

  1. Mở trang đăng nhập và sử dụng chức năng đăng nhập phát triển được hiển thị ngoài môi trường production.
  2. Chọn một gói credit. Quy trình thanh toán giả lập mô phỏng giao dịch mà không tính phí.
  3. Tải ảnh lên và bắt đầu tạo video.
  4. Nhà cung cấp video giả lập sao chép video mẫu đã seed thay vì gọi mô hình AI.
  5. Mở bảng điều khiển để kiểm tra video đã tạo, sổ cái credit, bản ghi thanh toán và cài đặt chia sẻ.

Để mô phỏng việc từ chối tệp tải lên, hãy gửi biểu mẫu tải lên với mockOutcome=reject. Để trống TURNSTILE_SITE_KEY nếu bạn muốn tắt Turnstile cục bộ.

Bạn cũng có thể kiểm thử việc dọn dẹp dữ liệu lưu trữ đối với nội dung đa phương tiện của người dùng hiện đang đăng nhập:

POST /api/dev/sweep
Content-Type: application/json

{"days": 8}

Việc gửi email cục bộ được mô phỏng. Kiểm tra hộp thư đi bằng:

GET /api/dev/emails?to=user@example.com&ref=<order-or-takedown-id>

Tạo một website cho xu hướng mới

1. Sao chép repository nhưng vẫn giữ lịch sử upstream

git clone https://github.com/qianshuixia/shrimpreel.git moonhop
cd moonhop
git remote rename origin upstream
git remote add origin git@github.com:<owner>/moonhop.git

Không sử dụng nút template của GitHub nếu bạn muốn hợp nhất các bản cập nhật template trong tương lai. Repository được tạo theo cách đó không chia sẻ lịch sử với repository nguồn. Việc clone thông thường cùng remote upstream sẽ giữ lại điểm chung để hợp nhất.

2. Chạy trình tạo site

Bắt đầu bằng lần chạy thử, kiểm tra các thay đổi được đề xuất, sau đó thêm --write:

node scripts/new-site.mjs --keyword "Moon Hop" --domain moonhop.ai --keywords "AI dance video,Moon Hop filter"
node scripts/new-site.mjs --keyword "Moon Hop" --domain moonhop.ai --keywords "AI dance video,Moon Hop filter" --write

Trình tạo site cập nhật site.ts, tên tài nguyên Cloudflare trong wrangler.jsonc và tên package. Trình này đặt lại các mã định danh dành riêng cho việc triển khai và xóa cấu hình staging của template. Sau đó, trình này in ra danh sách kiểm tra cho các công việc thủ công còn lại.

3. Cấu hình giá và tính năng tạo nội dung

Chỉnh sửa src/config/site.ts. Kiểm tra các gói credit trong packages, công tắc subscriptionsEnabled, các gói đăng ký plans, các durations khả dụng và video.falModel.

Đặt subscriptionsEnabled thành false nếu site chỉ nên bán các gói mua một lần. Một gói có thể sử dụng anchorPriceCents để hiển thị giá so sánh bị gạch ngang, nhưng README cảnh báo rằng giá này phải phản ánh mức giá mà gói thực sự từng được bán. Các site mới thường để trống giá trị này.

4. Viết lại nội dung bản địa hóa

Thay thế nội dung theo xu hướng trong src/content/en.ts và src/content/zh.ts. Tối thiểu, hãy viết lại phần hero, phần giải thích, ý tưởng, FAQ và cả hai bài viết được tích hợp. Các khối vấn đề và so sánh tùy chọn cũng nên được viết lại hoặc đặt thành null.

Tránh chỉ thay đổi từ khóa trong toàn bộ văn bản hiện có. Template nêu rõ rằng các site được sao chép một cách máy móc có thể bị công cụ tìm kiếm xem là lạm dụng nội dung trên quy mô lớn.

Để thêm một bài viết, hãy tạo mục siêu dữ liệu trong phần articles của site.ts, sau đó thêm khóa nội dung tương ứng vào mọi locale. Bài viết sẽ tự động được đưa vào trung tâm hướng dẫn, sitemap và các liên kết bài viết liên quan đã cấu hình. Giữ lại các mục trend và howTo hiện có vì trang chủ liên kết đến chúng.

5. Thay thế toàn bộ media mẫu

  • Đặt các clip tạo nội dung nguồn trong seed/templates/ theo mẫu <template.id>-<seconds>s.mp4.
  • Thay thế video và ảnh poster trên trang chủ trong public/demo/.
  • Thay thế public/og.png và public/favicon.svg.
  • Chỉ sử dụng media demo do bạn tự tạo hoặc được cấp phép, đồng thời ghi thông tin ghi công trong site.examples.*.credit.

Nếu có FFmpeg, hãy tạo lại các tài nguyên mẫu gốc của dự án bằng:

node scripts/generate-placeholder-media.mjs

Sau khi thay đổi template.id, hãy xóa các tệp template không còn sử dụng khỏi seed/templates/.

Cấu hình các nhà cung cấp thực

Biến thời gian chạy

Đặt các biến production không bí mật trong wrangler.jsonc. Các giá trị quan trọng gồm SITE_URL, APP_ENV=production, PAYMENT_PROVIDER, VIDEO_PROVIDER, MODERATION_PROVIDER, TURNSTILE_SITE_KEY, ADMIN_EMAILS, EMAIL_FROM, ánh xạ sản phẩm và GOOGLE_CLIENT_ID.

Giá sản phẩm của nhà cung cấp thanh toán là nguồn có thẩm quyền. Giá hiển thị trên site phải được đồng bộ với bảng điều khiển của nhà cung cấp. Ánh xạ sản phẩm liên kết mỗi gói hoặc kế hoạch đã cấu hình với ID sản phẩm của nhà cung cấp.

Bí mật

Tùy thuộc vào các tích hợp được chọn, các bí mật có thể bao gồm SESSION_SECRET, GOOGLE_CLIENT_SECRET, thông tin xác thực Waffo, thông tin xác thực Dodo, FAL_KEY, YIR_API_KEY tùy chọn, OPENAI_API_KEY tùy chọn cho việc kiểm duyệt và TURNSTILE_SECRET_KEY.

Đặt một bí mật riêng lẻ bằng:

npx wrangler secret put <NAME>

Hoặc sao chép và hoàn thiện tệp biến production, kiểm tra kế hoạch, sau đó áp dụng các bí mật còn thiếu:

cp .dev.vars.example .dev.vars.production
node scripts/sync-secrets.mjs
node scripts/sync-secrets.mjs --apply

Script đồng bộ không in ra giá trị bí mật. Các bí mật từ xa hiện có được giữ nguyên trừ khi cung cấp --overwrite.

Cấp phát tài nguyên Cloudflare

Tạo một bộ tài nguyên riêng cho mỗi site theo từ khóa. Tên phải khớp với các binding trong wrangler.jsonc.

npx wrangler d1 create <name>
npx wrangler r2 bucket create <name>-media
npx wrangler kv namespace create <name>-kv
npx wrangler queues create <name>-jobs
npx wrangler queues create <name>-jobs-dlq
npm run db:migrate:remote
npx wrangler r2 object put <name>-media/templates/<file>.mp4 --file seed/templates/<file>.mp4 --content-type video/mp4 --remote

Sao chép ID cơ sở dữ liệu D1 và ID namespace KV được tạo vào wrangler.jsonc. namespace_id giới hạn tốc độ của mỗi site cũng phải là duy nhất trong tài khoản Cloudflare.

Cấu hình các quy tắc vòng đời R2 được dự án mô tả để ảnh đã tải lên và video được tạo tuân theo thời hạn lưu giữ bảy ngày và 30 ngày. Miền gửi cũng phải được đăng ký với Cloudflare Email Service trước khi email giao dịch có thể hoạt động.

Xác minh và triển khai

Chạy các bước kiểm tra chất lượng cục bộ

npm run typecheck
npm test
npm run test:e2e
npm run seo:check

Trước khi triển khai, hãy chạy trình kiểm tra cấu hình:

npm run doctor

Trình kiểm tra sẽ kiểm tra môi trường, miền, các nhà cung cấp đã chọn, ánh xạ sản phẩm, các liên kết tài nguyên Cloudflare, hàng đợi, cấu hình Cron, tên secret bắt buộc, các migration chưa áp dụng và các dấu TODO(site) chưa được xử lý. Sử dụng --offline khi chủ động không thể thực hiện các kiểm tra từ xa.

Triển khai và chạy kiểm tra nhanh

npm run deploy
SMOKE_BASE_URL=https://<domain> npm run test:smoke

npm run deploy sẽ chạy các bước kiểm tra trước khi triển khai. Sau khi triển khai, hãy gắn miền tùy chỉnh trong Cloudflare và bảo đảm SITE_URL khớp chính xác với site.domain. URL chuẩn, sitemap và các kiểm tra CSRF cùng nguồn gốc đều phụ thuộc vào sự khớp này.

Khi miền tùy chỉnh hoạt động, hãy đặt workers_dev và preview_urls thành false. Nếu không, Worker production vẫn có thể được truy cập thông qua các URL phát triển và URL phiên bản Cloudflare công khai bằng cùng các tài nguyên D1 và R2.

Hoàn tất các tác vụ ra mắt SEO

npm run seo:check -- --base https://<domain> --production
npm run seo:indexnow -- --submit

Chỉ chạy lệnh IndexNow sau khi cấu hình site.seo.indexNowKey. Xác minh miền trong Google Search Console và Bing Webmaster Tools, sau đó gửi https://<domain>/sitemap.xml.

Mẹo nâng cao

Không để mock trong production

Production và staging sẽ từ chối thanh toán, tạo nội dung và tải lên bằng phản hồi 503 nếu các nhà cung cấp đã chọn vẫn được đặt thành mock. Đăng nhập trong môi trường development, các route thanh toán mock và các endpoint API development sẽ trả về 404 trong những môi trường đó. Hãy xem đây là cơ chế an toàn, không phải giải pháp thay thế cho việc chạy npm run doctor.

Gộp các bản cập nhật template thay vì sao chép bản vá

Đặt các phần dành riêng cho từng site trong src/config/site.ts, src/content/*, public/*, seed/, wrangler.jsonc và tên package. Các bản sửa dùng chung nên được thực hiện trong template rồi gộp vào từng site.

git fetch upstream
git show upstream/main:scripts/sync-plan.mjs > .tmp/sync-plan.mjs
node .tmp/sync-plan.mjs
git merge --no-ff upstream/main
npm install
npm run typecheck
npm test
npm run test:e2e
npm run db:migrate:remote

Sử dụng merge commit thay vì squash merge, rebase hoặc cherry-pick. Kế hoạch đồng bộ dựa trên git merge-base HEAD upstream/main. Khi ghi nhận lần gộp, hãy kết thúc thông điệp commit bằng Template-sync: <template commit sha>.

Duy trì khả năng tương thích ngược trong quá trình triển khai

Nếu quá trình triển khai thất bại sau khi migration đã chạy, phiên bản Worker mới có thể được khôi phục, nhưng các migration D1 sẽ không tự động được hoàn tác. Hãy giữ các migration tương thích với phiên bản ứng dụng trước đó để vẫn có thể khôi phục.

Sử dụng các workflow Claude Code đi kèm khi phù hợp

Kho lưu trữ bao gồm skill new-hot-site để tạo khung cho một site theo xu hướng, skill sync-upstream để gộp các thay đổi từ template và skill chỉ đọc launch-audit để kiểm tra trước khi ra mắt và kiểm tra trực tiếp. Các công cụ này không thay thế việc đánh giá thủ công: nội dung được tạo, media có giấy phép, miền, sản phẩm của nhà cung cấp, cài đặt OAuth, đăng ký email và chính sách vòng đời vẫn cần được xác minh.

Xem lại tài liệu dự án trước khi thay đổi logic cốt lõi

Tham khảo AGENTS.md trước khi sửa đổi credit, hoàn tất thanh toán, nội dung song ngữ, migration hoặc các bài kiểm thử end-to-end. Thông tin chi tiết bổ sung có trong docs/env.md, docs/payments.md, docs/subscriptions.md, docs/SEO_AUDIT.md và docs/SAAS_VIDEO_FEATURES.md. README lưu ý rằng các tài liệu này hiện được viết bằng tiếng Trung.

Kết luận

ShrimpReel cung cấp một nền tảng khởi đầu đáng kể cho một SaaS video AI tập trung vào từ khóa, bao gồm hàng đợi tạo nội dung, thanh toán, credit, quản trị, lưu giữ dữ liệu, quy trình tuân thủ, phân tích, SEO và vận hành Cloudflare. Hãy bắt đầu với quy trình mock an toàn, tùy chỉnh mọi lớp dành riêng cho site, thay nội dung giữ chỗ bằng tài sản có giấy phép, xác minh tất cả cài đặt của nhà cung cấp và Cloudflare, rồi chỉ triển khai sau khi toàn bộ chuỗi kiểm thử, doctor, SEO và kiểm tra nhanh đã chạy đạt.