Instant 参考实现：用 Stripe 按量计费 Credits 构建 AI 应用付费体系

后端数据库【免费下载链接】instantInstant is the best backend for AI-coded apps. You get auth, permissions, storage, presence, and streams — everything you need to ship apps your users will love.项目地址https://gitcode.com/gh_mirrors/inst/instant点击查看免费下载导读本文以examples/stripe-creditsHaiku Generator为完整参考实现讲解如何在 InstantDB 应用中接入 Stripe 信用卡包credit pack按量付费用户登录后购买 Credits、Webhook 幂等入账、服务端按次扣费、InstantDB 实时订阅即时刷新余额。读完本文你将掌握一套认证防伪 支付入账 服务端扣费 权限隔离的可直接复用的 usage-based 计费骨架。一、整体模式余额存于用户记录支付与计费职责分离examples/stripe-credits/README.md明确给出了该参考实现的核心定位为 InstantDB 应用添加基于用量的 Stripe 支付。Credit 包购买 实时余额更新——用户登录、买 Credits、消费 Credits。stripe-strategy.md将整个模式概括为一条 7 步流程1. User signs in (required — credits are tied to accounts) 2. User clicks Buy Credits 3. Create/fetch Stripe customer, link to InstantDB user 4. Redirect to Stripe checkout (one-time payment) 5. User pays → webhook adds credits to account 6. InstantDB real-time subscription updates the UI instantly 7. User spends credits → server deducts per use其中最关键的设计决策原文原话Credits 存活在用户记录上credits live on the user record。Stripe 只负责收钱服务端负责管余额。Webhook 借助 Stripe session metadata 做幂等InstantDB 的实时订阅负责把 UI 与余额保持同步——无需任何额外的轮询或同步端点。这一模式的两个活动部件如下Checkout API—— 校验认证、获取或创建 Stripe customer、创建支付 sessionWebhook—— 支付成功后入账 Credits且只需监听checkout.session.completed一个事件。与订阅模式不同信用卡包是一次支付、一次入账没有持续的生命周期需要维护因此事件面极小。二、Stripe 侧准备产品、密钥与本地 Webhook 转发2.1 创建信用卡包商品在 Stripe Dashboard → Products 中创建商品例如 10 Credit Pack定价设为$2.00 一次性one-time然后复制 Price IDprice_...。2.2 环境变量与 Stripe 客户端将密钥写入.env.localSTRIPE_SECRET_KEYsk_test_... STRIPE_PRICE_IDprice_... STRIPE_WEBHOOK_SECRETwhsec_... # stripe listen 会输出稍后获得仓库中的 src/lib/stripe.ts 提供了懒加载的单例客户端并集中定义了信用卡包常量import Stripe from stripe; let _stripe: Stripe | null null; export function getStripe(): Stripe { if (!_stripe) { const key process.env.STRIPE_SECRET_KEY; if (!key) { throw new Error(STRIPE_SECRET_KEY is not set); } _stripe new Stripe(key); } return _stripe; } export function getPriceId(): string { const priceId process.env.STRIPE_PRICE_ID; if (!priceId) { throw new Error(STRIPE_PRICE_ID is not set); } return priceId; } // Credits per purchase export const CREDITS_PER_PACK 10; export const PACK_PRICE_CENTS 200; // $2.00注意这里的两个细节getStripe()与getPriceId()都会在缺少环境变量时主动抛错防止配置缺失导致的静默失败CREDITS_PER_PACK 10与PACK_PRICE_CENTS 200把一包多少个 Credits、卖多少钱收敛到一处是后续 Webhook 入账与前端展示共用的单一事实来源。2.3 本地 Webhook 转发本地开发用 Stripe CLI 把线上事件转发到本机# 安装 Stripe CLI brew install stripe/stripe-cli/stripe # 登录一次即可 stripe login # 将 webhook 转发到本地服务 stripe listen --forward-to localhost:3000/api/stripe/webhookstripe listen启动后会打印一个whsec_...签名密钥把它填入STRIPE_WEBHOOK_SECRET。注意每次重启stripe listen都会生成新的密钥必须同步更新环境变量并重启 dev server详见下文常见错误。生产环境则需在 Stripe Dashboard → Webhooks 中添加端点URL 为https://your-app.com/api/stripe/webhook事件只选checkout.session.completed。三、数据模型余额挂在用户上内容按作者隔离仓库中的 src/instant.schema.ts 展示了完整的 schemaconst _schema i.schema({ entities: { $files: i.entity({ path: i.string().unique().indexed(), url: i.string(), }), $users: i.entity({ email: i.string().unique().indexed().optional(), credits: i.number().optional(), // Current credit balance stripeCustomerId: i.string().optional(), }), haikus: i.entity({ topic: i.string(), content: i.string(), createdAt: i.number().indexed(), }), }, links: { userHaikus: { forward: { on: haikus, has: one, label: author, onDelete: cascade }, reverse: { on: $users, has: many, label: haikus }, }, }, rooms: {}, });要点拆解$users.credits当前余额可选数字字段默认缺失时按 0 处理$users.stripeCustomerId把 Stripe customer 与 InstantDB 用户绑定这是重复购买也能正确入账的根基haikus生成的内容实体createdAt加了索引以支持按时间倒序查询userHaikus链接haikus.author指向$users一对一方向$users.haikus反向一对多onDelete: cascade保证删除用户时级联清理。credits.md中的 Data Model 图清晰说明了这套结构$users.credits是余额stripeCustomerId关联到 Stripe Customer其下的 checkout sessions 的 metadata 里带着instantUserIduserHaikus链接把$users.haikus与haikus.author双向关联。推送 schemanpx instant-cli push schema --yes四、Checkout 流程认证、建客户、开 Session4.1 客户端发起购买购买按钮携带用户的 refresh token 调用 checkout APIAuthorization: Bearer ...async function handlePurchase() { const res await fetch(/api/stripe/checkout, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${user.refresh_token}, }, }); const { url } await res.json(); window.location.href url; }4.2 服务端 Checkout API完整实现见 src/app/api/stripe/checkout/route.tsexport async function POST(request: NextRequest) { try { // Verify auth — userId comes from the token, not the request body const auth await verifyAuth(request); if (auth.error) return auth.error; const userId auth.user.id; // Get user from InstantDB const { $users } await adminDb.query({ $users: { $: { where: { id: userId } } }, }); const user $users[0]; if (!user) { return NextResponse.json({ error: User not found }, { status: 404 }); } // Get or create Stripe customer let customerId user.stripeCustomerId; const stripe getStripe(); if (!customerId) { const customer await stripe.customers.create({ email: user.email || undefined, metadata: { instantUserId: userId }, }); customerId customer.id; // Save Stripe customer ID to InstantDB await adminDb.transact( adminDb.tx.$users[userId].update({ stripeCustomerId: customerId }) ); } // Create checkout session for credit pack (one-time payment) const session await stripe.checkout.sessions.create({ customer: customerId, mode: payment, line_items: [{ price: getPriceId(), quantity: 1 }], allow_promotion_codes: true, success_url: ${request.headers.get(origin)}/?successtrue, cancel_url: ${request.headers.get(origin)}/?canceledtrue, metadata: { instantUserId: userId }, }); return NextResponse.json({ url: session.url }); } catch (error) { console.error(Checkout error:, error); return NextResponse.json( { error: Failed to create checkout session }, { status: 500 } ); } }几个值得强调的工程细节身份来源userId来自verifyAuth(request)校验后的 token绝不出自请求体——这是防止用户伪造身份/余额的关键客户复用已有stripeCustomerId就直接复用没有才创建并把 customer 创建结果回写 InstantDB保证下次购买不需要重建客户双向绑定Stripe Customer 的metadata.instantUserId与 Checkout Session 的metadata.instantUserId都携带用户 IDWebhook 阶段就是靠它定位入账对象allow_promotion_codes: true这是后面生产环境 100% off 优惠券测试能成立的前提。五、Webhook 入账先签名、再取活数据、三保险幂等5.1 完整实现见 src/app/api/stripe/webhook/route.tsexport async function POST(request: NextRequest) { const body await request.text(); const signature request.headers.get(stripe-signature)!; const webhookSecret process.env.STRIPE_WEBHOOK_SECRET!; const stripe getStripe(); let event: Stripe.Event; try { event stripe.webhooks.constructEvent(body, signature, webhookSecret); } catch (err) { console.error(Webhook signature verification failed:, err); return NextResponse.json({ error: Invalid signature }, { status: 400 }); } try { switch (event.type) { case checkout.session.completed: { // Re-fetch the session from Stripe to get live metadata. // The event payloads metadata is frozen at creation time, // so retried webhooks would always bypass the idempotency check. const session await stripe.checkout.sessions.retrieve( (event.data.object as Stripe.Checkout.Session).id ); if (session.payment_status ! paid) { break; } // Skip if already processed (by a duplicate webhook) if (session.metadata?.creditsProcessed true) { break; } const userId session.metadata?.instantUserId; if (!userId) break; // Mark as processed in Stripe to prevent double-crediting await stripe.checkout.sessions.update(session.id, { metadata: { ...session.metadata, creditsProcessed: true }, }); const { $users } await adminDb.query({ $users: { $: { where: { id: userId } } }, }); await adminDb.transact( adminDb.tx.$users[userId].update({ credits: ($users[0]?.credits || 0) CREDITS_PER_PACK, }) ); break; } } return NextResponse.json({ received: true }); } catch (error) { console.error(Webhook handler error:, error); return NextResponse.json( { error: Webhook handler failed }, { status: 500 } ); } }5.2 为什么必须重新拉取 session而不是用事件负载这是本实现最精妙的点教程与策略文档都反复强调事件负载event.data.object的 metadata 在事件创建那一刻就被冻结了。如果 Stripe 因为网络等原因重试同一个事件重试时负载里的 metadata 依然是旧值没有creditsProcessed幂等检查会永远通过导致重复入账。因此代码在收到事件后调用stripe.checkout.sessions.retrieve(...)重新拉取实时的 session再用其 metadata 做判断——重试时就能看到上一次写入的creditsProcessed: true并直接跳过。5.3 三重防线Webhook 入账共设了三个关卡逐层收窄payment_status ! paid直接跳过防止未支付/支付中的 session 提前入账session.metadata?.creditsProcessed true跳过幂等主检查先写标志再入账先把creditsProcessed: true写回 Stripe再执行adminDb.transact加 Credits——标志写入先于入账缩小了并发/重试窗口。credits.md用流程图把幂等逻辑画得很直观支付完成 → Webhook → 重新拉取 session → 检查creditsProcessed true→ Yes 跳过 / No 置标志并入账。5.4 入账后的实时同步Credits 写入后客户端无需任何额外动作InstantDB 的实时订阅会立刻把新余额推送到 UI。这正是credits.md中Credit 更新 ◀── 实时订阅那一步的含义——不需要单独的同步端点。六、服务端扣费一次事务原子完成扣 1 建内容 关联作者6.1 生成 API见 src/app/api/generate/route.tsexport async function POST(request: NextRequest) { try { const auth await verifyAuth(request); if (auth.error) return auth.error; const userId auth.user.id; const { topic: rawTopic } await request.json(); const topic typeof rawTopic string ? rawTopic.trim() : ; if (!topic) { return NextResponse.json({ error: Topic required }, { status: 400 }); } const { $users } await adminDb.query({ $users: { $: { where: { id: userId } } }, }); const user $users[0]; if (!user) { return NextResponse.json({ error: User not found }, { status: 404 }); } const currentCredits user.credits || 0; if (currentCredits 1) { return NextResponse.json( { error: Insufficient credits, needsCredits: true }, { status: 402 } ); } const content generateHaiku(topic); const haikuId id(); // Deduct credit and create haiku atomically await adminDb.transact([ adminDb.tx.$users[userId].update({ credits: currentCredits - 1 }), adminDb.tx.haikus[haikuId] .update({ topic, content, createdAt: Date.now() }) .link({ author: userId }), ]); return NextResponse.json({ haiku: { id: haikuId, topic, content }, }); } catch (error) { console.error(Generate error:, error); return NextResponse.json( { error: Failed to generate haiku }, { status: 500 } ); } }6.2 关键设计余额不足返回 402{ error: Insufficient credits, needsCredits: true }客户端拿到needsCredits标志后弹出购买弹窗见tutorial.md中的处理片段原子事务adminDb.transact([...])把扣减 1 Credits、创建 haiku、建立 author 链接打包成一次事务——要么全部成功要么全部失败不存在扣了钱没生成内容或生成了内容没扣钱的中间态身份永不来自请求体userId依旧来自verifyAuth的 token客户端无法指定他人 ID 或伪造余额真实业务替换点示例里的generateHaiku(topic)只是从内置模板src/app/api/generate/route.ts顶部的HAIKU_TEMPLATES随机生成接入真实场景时把它替换为你的 LLM 调用或付费能力即可Credits 逻辑完全不变。七、权限隔离内容只对作者可见7.1 权限规则src/instant.perms.ts 定义了 haikus 的访问规则const rules { haikus: { allow: { view: isAuthor, create: false, // Created via admin SDK update: false, delete: isAuthor, }, bind: [isAuthor, auth.id in data.ref(author.id)], }, } satisfies InstantRules;view / delete 仅限作者通过bind绑定规则auth.id in data.ref(author.id)即登录用户的 ID 必须等于该 haiku 的author.idcreate: false内容由服务端 admin SDK 创建客户端不开放直接写权限同时update: false也禁止了修改。推送权限npx instant-cli push perms --yes7.2 查询时权限自动生效客户端无需任何额外逻辑直接正常查询即可InstantDB 会在服务端强制过滤const { data } db.useQuery({ haikus: { $: { order: { createdAt: desc } } }, });每个用户只能看到自己的 haikus——权限执行发生在 InstantDB 服务端客户端代码无法绕过。八、测试指南从测试卡到零成本生产验证8.1 测试模式测试卡CardResult4242 4242 4242 4242Success4000 0000 0000 0002Declined任意未来有效期、任意 CVC、任意 ZIP。8.2 完整 Credit 流测试登录购买一个 Credit 包反复生成直到 Credits 耗尽验证出现余额不足提示再买一包验证余额叠加CREDITS_PER_PACK累加而非覆盖。8.3 生产环境零成本测试由于 Checkout Session 设置了allow_promotion_codes: true可以在 Stripe Dashboardlive 模式→ Coupons 创建一个100% off、一次性优惠券设个容易记的代码如TESTING100部署后走真实 checkout 流程并输入该码总价归零Webhook 照常触发入账实际不产生任何扣款。测试结束后清理在 Dashboard 删除/停用该优惠券如需重置测试用户余额可通过 InstantDB admin SDK 直接修改credits字段。九、常见错误清单直接来自官方教程tutorial.md专门列了 5 个高频踩坑点逐一引用1. Webhook 密钥不匹配每次重启stripe listen都会打印新的whsec_...必须同步更新STRIPE_WEBHOOK_SECRET并重启 dev server。2. 不处理重复 WebhookStripe 可能重发同一事件必须有幂等机制// BAD - Credits added twice! await addCredits(userId, CREDITS_PER_PACK); // GOOD - Check the flag first if (session.metadata?.creditsProcessed true) break; await stripe.checkout.sessions.update(session.id, { metadata: { ...session.metadata, creditsProcessed: true }, }); await addCredits(userId, CREDITS_PER_PACK);3. 信任客户端传来的用户 ID任何人可伪造任意 ID必须用verifyAuth从 token 推导// BAD - Anyone can impersonate any user const { userId } await request.json(); // GOOD - User ID comes from verified auth token const auth await verifyAuth(request); if (auth.error) return auth.error; const userId auth.user.id;4. 仅靠客户端执行扣费限制客户端检查不可信服务端必须自己查余额并扣减// BAD - Client checks credits, server blindly generates if (credits 0) callGenerateApi(); // GOOD - Server checks and deducts const currentCredits user.credits || 0; if (currentCredits 1) return 402;5. 忘记配置生产 Webhook本地stripe listen可用不代表生产可用必须在 Stripe Dashboard 添加https://your-app.com/api/stripe/webhook且只选checkout.session.completed。十、认证中间件的底层实现三个 API 路由checkout、webhook 入账前无需认证、generate中需要认证的两个都依赖同一个 src/lib/auth.ts 工具函数。它从Authorization: Bearer token头取 token调用 admin SDK 的adminDb.auth.verifyToken(token)校验返回结构化结果export async function verifyAuth(request: NextRequest): PromiseAuthResult { const authHeader request.headers.get(authorization); if (!authHeader || !authHeader.startsWith(Bearer )) { return { error: NextResponse.json({ error: Authorization required }, { status: 401 }), }; } // ...token 提取、verifyToken 校验、异常兜底 }缺头、token 为空、token 无效或过期分别返回 401 与对应错误信息校验成功返回{ user: { id, email } }调用方解构出auth.user.id作为可信身份。配套的 src/lib/adminDb.ts 与 src/lib/db.ts 分别基于instantdb/admin服务端需INSTANT_APP_ADMIN_TOKEN与instantdb/react客户端只需NEXT_PUBLIC_INSTANT_APP_ID初始化二者共享同一份 schema保证类型两端一致。十一、快速上手仓库根目录执行参考 README.mdpnpm install cp .env.example .env.local # 填入你的密钥 npx instant-cli push schema npx instant-cli push perms pnpm dev常用脚本pnpm dev # 启动 dev servernext dev --turbopack npx instant-cli push schema # 推送 schema 变更 npx instant-cli push perms # 推送权限变更依赖方面package.json 显示该示例基于next15.4.10、react19.1.0、stripe^20.3.0并使用instantdb/admin与instantdb/react。十二、小结这套骨架的可复用要点Token 校验的认证所有 API 路由从 token 取身份杜绝用户冒充Stripe customer 与 InstantDB 用户绑定重复购买、多包叠加都正确Session metadata 幂等标志防止 Webhook 重试导致双写入Webhook 重拉 session保证重试时幂等检查读到的是活数据服务端扣费余额不可被客户端篡改InstantDB 实时订阅支付完成即 UI 更新零轮询InstantDB 权限内容天然按作者隔离。完整的三份配套文档分别从不同视角覆盖本主题建议对照阅读策略总览 stripe-strategy.md、流程与数据模型图解 credits.md、逐步实现教程 tutorial.md以及源码checkout 路由、webhook 路由、generate 路由。若需更丰富的 Stripe 能力分层定价、批量折扣、计量计费等可在该骨架之上扩展本实现不涉及这些进阶场景。赞分享后端数据库【免费下载链接】instantInstant is the best backend for AI-coded apps. You get auth, permissions, storage, presence, and streams — everything you need to ship apps your users will love.项目地址https://gitcode.com/gh_mirrors/inst/instant点击查看免费下载相关推荐Instant 按量计费实战用 Stripe 信用包Credits为 AI 生成应用搭建付费墙Instant 按量计费实战用 Stripe 信用包Credits为 AI 生成应用搭建付费墙 本指南以仓库中的 Haiku Generator俳句生成后端数据库Instant 接入 Stripe 支付完全指南一次性购买、订阅与按量计费的三种实战模式Instant 接入 Stripe 支付完全指南一次性购买、订阅与按量计费的三种实战模式 在 Instant 应用中接入 Stripe 支付最核心的设计思想后端数据库Beads 入门文档瘦身路线图从 1600 行 Getting Started 到 5 条命令的体验优化Beads 入门文档瘦身路线图从 1600 行 Getting Started 到 5 条命令的体验优化 Beads命令行工具 bd 是一款为编码 Age后端数据库上一篇终极汉语拼音词典使用指南快速掌握汉字学习的10个高效技巧下一篇WiFi-Password快速获取WiFi密码的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考