Xây dựng và ra mắt hệ thống website AI tập trung từ khóa với shipwords

shipwords làm gì

shipwords là một framework mã nguồn mở, được cấp phép MIT, dùng để vận hành một hệ thống các trang web AI tạo ảnh và video trên Cloudflare, với mỗi trang dành riêng cho một từ khóa. Các khả năng dùng chung như tài khoản, thanh toán, tín dụng và tạo nội dung AI chỉ được triển khai một lần trong framework, trong khi mỗi trang có thể có các trang, nhận diện hình ảnh, tên miền, cơ sở dữ liệu, bộ lưu trữ và tài khoản thanh toán riêng.

Mỗi trang là một ứng dụng TanStack Start và React 19 chạy trên Cloudflare Worker riêng, cùng với D1, R2 và Workflows. Sự tách biệt này cho phép bạn khởi chạy, cập nhật hoặc ngừng hoạt động từng trang độc lập, đồng thời vẫn nhận được các cải tiến từ lõi dùng chung trong những lần triển khai sau.

Tính năng chính

• Đăng nhập bằng Google và email cùng các trang tài khoản.
• Hỗ trợ Stripe và PayPal, bao gồm gói tín dụng, gói đăng ký, đơn hàng, hoàn tiền và tranh chấp.
• Thông báo email và lượt dùng thử miễn phí cho khách với giới hạn chống lạm dụng bằng reCAPTCHA v3.
• Các trang về quyền riêng tư, điều khoản, hoàn tiền và DMCA.
• Công cụ hỗ trợ SEO và GEO, bao gồm sitemap.xml, robots.txt và llms.txt.
• Runtime tạo nội dung dựa trên workflow với các trạng thái công việc chỉ đi theo một chiều và tự động hoàn tín dụng cho công việc thất bại.
• Tích hợp API Yir cho các model như GPT Image, Nano Banana, Seedream, FLUX, Seedance, Veo, Kling và Wan.
• Upstream giả lập để phát triển cục bộ mà không cần khóa API model.
• Tùy chọn ghép video bằng container ffmpeg.

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

Trước khi bắt đầu, hãy cài đặt Node 24 như được chỉ định trong .nvmrc của repository và bật Corepack để sử dụng đúng phiên bản pnpm:

corepack enable

Trên Windows, hãy dùng Git Bash hoặc WSL. Bạn cần tài khoản Cloudflare và tài khoản Stripe hoặc PayPal khi sẵn sàng triển khai và nhận thanh toán. Chúng không bắt buộc cho thiết lập cục bộ cơ bản.

Cài đặt repository

Fork hoặc clone repository, sau đó cài đặt các dependency:

pnpm install

Tạo khung cho trang mới

Dùng trình tạo site để tạo một trang từ template AI site hoàn chỉnh. Đối số đầu tiên sẽ trở thành thư mục bên dưới sites/, còn tên miền được ghi vào cấu hình của trang:

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

Trang được tạo bao gồm trang chủ, bảng giá, luồng tài khoản và đăng nhập, các trang chính sách, cùng các tệp sitemap.xml, robots.txt và llms.txt tiêu chuẩn. Chạy lại pnpm install để cài đặt dependency cho trang mới.

Cấu hình secret cục bộ

Giữ các secret cục bộ bên ngoài repository. Tạo thư mục cấu hình, sao chép tệp biến mẫu của trang vừa tạo và kết nối cấu hình worktree:

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

Cấu hình mẫu được thiết kế để hoạt động ngay cho việc phát triển cục bộ. Mã đăng nhập qua email sẽ được in trong terminal của máy chủ phát triển, tài khoản mới nhận tín dụng đăng ký và quá trình tạo nội dung sử dụng upstream giả lập khi UPSTREAM_MOCK=1. Nhờ đó, bạn có thể kiểm thử ứng dụng mà không cần khóa API model.

Thêm khả năng tạo nội dung thực

Để gửi yêu cầu đến model thực, hãy thêm khóa API Yir và tắt upstream giả lập bằng cách thay đổi UPSTREAM_MOCK.

Kiểm thử thanh toán

Để kiểm thử việc mua tín dụng, hãy thêm khóa kiểm thử Stripe bắt đầu bằng sk_test_. Từ thư mục của trang, chạy tiện ích chuyển tiếp webhook của repository để môi trường phát triển cục bộ có thể nhận các sự kiện Stripe:

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

Mã thanh toán dùng chung được thiết kế để xử lý các sự kiện thanh toán lặp lại hoặc đến không đúng thứ tự, các khoản tính phí trùng và việc hoàn tiền cho các công việc thất bại.

Cấu hình đăng nhập và quyền truy cập khách tùy chọn

Lượt dùng thử miễn phí cho khách cần các khóa reCAPTCHA. Nếu không có chúng, khách truy cập phải đăng nhập trước lần tạo nội dung đầu tiên. Đăng nhập Google là tùy chọn; nếu bật, hãy tạo một ứng dụng khách Google OAuth và sử dụng http://localhost:<port> làm origin được phép. Đăng nhập qua email hoạt động mà không cần Google OAuth.

Chạy trang cục bộ

Chuyển vào trang vừa tạo, tạo các artifact cơ sở dữ liệu cục bộ, áp dụng migration cục bộ và khởi động máy chủ phát triển:

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

Mở URL cục bộ được máy chủ phát triển in ra. Bạn có thể thử xác thực qua email, tạo tài khoản, tín dụng và tạo nội dung giả lập bằng cấu hình mẫu.

Sử dụng các lệnh của repository

Hầu hết các lệnh có thể được giới hạn trong một trang hoặc dùng để kiểm tra toàn bộ repository:

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

Lệnh list-sites xây dựng danh sách trang từ mã nguồn và README của từng trang. Lệnh check của một trang sẽ chạy kiểm tra kiểu, build và kiểm tra khởi chạy. Các bước kiểm tra package bao phủ các package core và jobs dùng chung, còn kiểm tra template và tools giúp phát hiện vấn đề trước khi khởi chạy.

Xây dựng trang bằng tác nhân lập trình AI

Nếu bạn đã biết từ khóa muốn nhắm đến, repository hỗ trợ quy trình làm việc do tác nhân điều khiển. Trong Claude Code, Codex hoặc Cursor, hãy cung cấp hướng dẫn tác nhân của repository và yêu cầu tác nhân xây dựng trang:

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

Tác nhân có thể sao chép kho lưu trữ, tạo trang web và chạy trang web đó cục bộ. Các quy tắc dành cho tác nhân lập trình AI được ghi lại trong AGENTS.md. Nếu bạn cần ý tưởng về các từ khóa mới nổi, dự án new-term-radar độc lập sẽ theo dõi các thuật ngữ AI mới trên X, Hugging Face, GitHub và các sitemap.

Tùy chỉnh hành vi nâng cao của trang web

Sử dụng runtime tạo dùng chung

Gói packages/jobs cung cấp runtime dựa trên workflow, giao diện adapter upstream, adapter Yir, upstream giả lập cục bộ và chức năng ghép tùy chọn bằng ffmpeg. Giữ hành vi tạo dành riêng cho từng trang web trong cấu hình của trang web, đồng thời sử dụng runtime dùng chung để xử lý công việc và hoàn tiền.

Đặt giới hạn chi phí tạo

Các lệnh gọi model thông qua Yir được tính phí theo từng yêu cầu. Chi phí tối đa của mỗi công việc được đặt trong site.models.ts. Hãy xem lại các giới hạn này trước khi bật tính năng tạo thực tế để bảo đảm giá và cơ chế tín dụng của trang web phù hợp với chi phí upstream tối đa.

Nghiên cứu ví dụ về video

Đối với trang web tập trung vào video, hãy xem sites/tinydeskai-example. Đây là mã nguồn đầy đủ của Tiny Desk AI, minh họa các ô ảnh, chỉnh sửa video một lần, kiểm tra đầu ra, ghép bằng ffmpeg và các trang nội dung. Workflow của trang biến một clip lan truyền thành mẫu mà khách truy cập có thể sử dụng với ảnh đã tải lên.

Giữ các trang web độc lập

Mỗi trang web được triển khai độc lập với cơ sở dữ liệu, bộ nhớ lưu trữ và tài khoản thanh toán riêng. Kiến trúc này cho phép bạn cải tiến phần lõi dùng chung một lần rồi triển khai bản cập nhật cho các trang web được chọn mà không ràng buộc thời điểm ra mắt hoặc ngừng hoạt động của chúng.

Chuẩn bị cho môi trường production

Khi trang web cục bộ hoạt động ổn định, hãy làm theo sổ tay ra mắt trang web để thực hiện quy trình production. Hãy lập kế hoạch cho chi phí tên miền, việc sử dụng Cloudflare, phí xử lý thanh toán và các yêu cầu model Yir. Các trang web video ghép nhiều clip sử dụng Cloudflare Containers và yêu cầu gói Workers Paid.

Trước khi ra mắt, hãy xác minh tính năng xác thực, webhook thanh toán, cơ chế tín dụng, lỗi tạo, hoàn tiền, các trang chính sách, tệp SEO và cấu hình phân tích của trang web. Kho lưu trữ cũng cung cấp tài liệu về kiến trúc và phát triển cục bộ để tìm hiểu các chi tiết cấu hình chuyên sâu hơn.

Kết luận

shipwords cung cấp nền tảng thực tế để ra mắt nhiều trang web AI tập trung vào từ khóa mà không phải xây dựng lại tính năng xác thực, thanh toán, tín dụng, workflow tạo và hỗ trợ SEO cho từng dự án. Hãy bắt đầu với mẫu, sử dụng upstream giả lập để kiểm thử cục bộ, thêm các nhà cung cấp thực khi sẵn sàng và triển khai độc lập từng trang web hoàn thiện trên Cloudflare.