账单概览
Nebutra 账单系统的工作原理 — Stripe 订阅、计划同步与配额执行。
架构
Nebutra 的账单流水线由三层协同工作，根据计划控制访问权限并实时执行使用配额。
用户
└─▶ Stripe 结账
└─▶ Stripe 发送 webhook
└─▶ /api/v1/webhooks/stripe
└─▶ 数据库计划更新（租户记录）
└─▶ @nebutra/metering 执行配额限制所有 Stripe 集成代码位于 packages/commerce/billing/。应用代码调用 @nebutra/billing 中的辅助函数——不直接使用 Stripe SDK。
计划
FREE
$0 / 月
- 1,000 次 API 调用 / 月
- 1 个组织成员
- 社区支持
PRO
$49 / 月
- 100,000 次 API 调用 / 月
- 10 个组织成员
- 邮件支持
- 解锁所有功能
ENTERPRISE
自定义定价
- 无限次 API 调用
- 无限成员
- SSO / SAML
- SLA 保证
- 自定义合同
计划同步原理
用户被重定向至 Stripe 托管的结账页面。支付成功后，Stripe 触发 checkout.session.completed 事件。
API 网关端点 POST /api/v1/webhooks/stripe 接收事件，使用 STRIPE_WEBHOOK_SECRET 验证签名，并将事件路由到 @nebutra/billing 中对应的处理程序。
处理程序更新数据库中租户的 plan 和 planExpiresAt 字段，使 Stripe 订阅状态与本地保持同步。
此后每次 API 请求时，@nebutra/metering 从数据库读取租户当前计划的限额，并与 ClickHouse 中累积的用量进行比较。超出配额的请求将收到 429 Too Many Requests 响应。
Stripe 配置位置
| 位置 | 用途 |
|---|---|
packages/commerce/billing/src/stripe.ts | Stripe 客户端初始化 |
packages/commerce/billing/src/plans.ts | 计划定义和限额常量 |
packages/commerce/billing/src/handlers/ | Webhook 事件处理程序 |
packages/commerce/billing/src/checkout.ts | 结账会话创建辅助函数 |
packages/commerce/billing/src/portal.ts | Stripe 客户门户会话辅助函数 |
环境变量
在 .env 文件（或部署平台的密钥管理器）中设置以下变量：
# Stripe 密钥 — 开发环境使用 sk_test_，生产环境使用 sk_live_
STRIPE_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxxxxxx
# Webhook 签名密钥 — 从 Stripe Dashboard 或 Stripe CLI 获取
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxx
# 前端可公开使用的发布密钥
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_xxxxxxxxxxxxxxxxxxxx
# 各付费计划的价格 ID（从 Stripe Dashboard → Products → Prices 获取）
STRIPE_PRO_PRICE_ID=price_xxxxxxxxxxxxxxxxxxxx
STRIPE_ENTERPRISE_PRICE_ID=price_xxxxxxxxxxxxxxxxxxxx切勿将真实的 Stripe 密钥提交到源代码仓库。本地开发请使用 .env.local，生产部署请通过 CI/CD 环境注入密钥。
Stripe Dashboard 配置
在 stripe.com 注册并激活账户。
进入 Stripe Dashboard → Products → Add product。分别为 PRO（$49/月循环计费）和 ENTERPRISE（自定义）创建产品，并将价格 ID 填入环境变量。
进入 Developers → Webhooks → Add endpoint，将 URL 设为 https://api.yourdomain.com/api/v1/webhooks/stripe，并选择 Webhooks 页面中列出的事件。
创建端点后，展开并复制 Signing secret（whsec_...），填入 STRIPE_WEBHOOK_SECRET。
本地开发时，使用 Stripe CLI 将实时事件转发到本地服务器，无需配置公开端点。
相关文档
How is this guide?
最后更新于