Stripe 计费

Documentation Index

Fetch the complete documentation index at: https://docs.fim.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

您将获得

• 免费版和专业版 配有月度令牌配额（默认值：免费版 1M / 专业版 5M；激活后可调整）
• Stripe 托管结账 — 用户无需您的代码接触卡数据即可升级
• 客户门户 — 用户可更新支付方式、下载发票、取消订阅——全部在 Stripe 的界面上完成
• Webhook 驱动的生命周期 — 订阅自动配置和续期；已取消的订阅在周期结束时降级为免费版
• 配额强制执行 — 按周期跟踪令牌使用情况；中途截断并显示结构化升级提示
• 管理页面 用于计划 CRUD 和订阅监控

​

前置条件

1. Stripe账户已启用实时模式。新加坡注册公司必须完成KYC（营业执照、董事身份证、银行账户）。审批通常需要1-3天。
2. Stripe实时API密钥，类型为受限制（推荐使用，相比标准sk_live_***更易撤销、权限范围更小）。
3. Webhook端点可公开访问，地址为<your-domain>/api/webhooks/stripe。
4. 银行账户用于支付。建议多币种结算（例如USD支付到USD账户），以避免非USD默认Stripe账户每笔交易产生1.5-2%的汇兑损失。

​

设置

​

1. Stripe 仪表板

​

创建Pro产品

1. Catalog → Products → + Add product
2. Name: Pro, description: 5M tokens / month, priority support
3. Pricing: Recurring, monthly, $20.00 USD (根据您的定价策略调整)
4. Save → 复制生成的 price_*** ID（激活后，您将使用此值更新本地 billing_plans 表）

​

创建受限API密钥

1. Developers → API keys → + Create restricted key
2. Name: fim-one production
3. Permissions (minimum):
   • Customers: Write
   • Subscriptions: Write
   • Checkout Sessions: Write
   • Customer portal: Write
   • Prices: Read
   • Products: Read
4. Save → copy rk_live_***

​

注册webhook端点

1. Developers → Webhooks → + Add endpoint
2. URL: https://<your-domain>/api/webhooks/stripe
3. 要接收的事件：
   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed
4. 保存后，点击”Reveal signing secret”→ 复制 whsec_***

​

配置多币种结算（推荐）

1. Settings → Bank accounts and currencies → Add a settlement currency
2. 选择价格币种（例如USD）
3. 关联匹配的银行账户（例如Aspire USD虚拟账户）
4. 保存——Stripe将USD费用直接路由到USD支付，无需外汇转换

​

2. 后端 .env

STRIPE_SECRET_KEY=rk_live_***
STRIPE_WEBHOOK_SECRET=whsec_***
STRIPE_BILLING_RETURN_URL=https://<your-domain>/settings?tab=billing

./deploy.sh   # or: docker compose restart fim-one

​

3. 在管理员中激活

1. 以管理员身份登录
2. 管理员 → 系统设置 → 计费
3. 切换启用 Stripe 计费为 ON
4. 后端验证 STRIPE_SECRET_KEY 和 STRIPE_WEBHOOK_SECRET 都存在——如果任一缺失，返回 400 并且切换保持 OFF
5. 仅在首次激活时，后端运行幂等设置：
   • 种子化免费版和专业版套餐（如果已存在则跳过）
   • 设置 system_settings.default_plan_id 为免费版套餐 id
   • 为任何没有套餐的用户回填 users.plan_id = free.id
   • 同步 default_token_quota → 免费版套餐 monthly_token_quota，使现有的管理员控制的全局配额得以保留
6. 后续的切换关闭/打开是纯标志翻转，无数据副作用

​

4. 使用您的实时价格更新Pro套餐

• Admin → Billing → Plans → Pro → Edit
• 将您的price_1***（来自第1步）粘贴到Stripe Price ID
• 保存

UPDATE billing_plans
SET stripe_price_id = 'price_1***'
WHERE slug = 'pro';

​

5. 烟雾测试

1. 以普通用户身份打开 /settings?tab=billing
2. 点击升级到 Pro
3. Stripe Checkout 打开；使用低额真实卡片完成支付（之后退款）
4. Webhook 应该触发——在 Stripe Dashboard → Webhooks → 最近事件中验证显示 2xx 响应
5. 订阅行出现在 subscriptions 表中；users.plan_id 切换为 pro
6. UI 现在显示 Pro 计划 + “管理订阅”按钮

​

禁用账单

• 所有 /api/billing/* 端点返回 503
• Webhook 端点返回 503（Stripe 将重试，然后在仪表板中显示为失败——这是正常的，如果账单永久关闭，你可以改为在 Stripe 仪表板中禁用 Webhook）
• Plan & Billing 用户界面标签页消失
• 管理员 → 账单导航组被隐藏
• 配额链跳过计划层级，直接回退到 default_token_quota

​

计算参考——配额和令牌数学

​

词汇表

​

什么算作一个令牌

• 计算：每次模型调用的提示令牌 + 完成令牌
• 计算：多步骤/工具使用智能体流中的每个往返（每次模型调用都是单独的扣费）
• 计算：嵌入请求（知识库摄取、检索评分）
• 不计算：输入已暂存但从未发送到模型的内容（例如用户丢弃的已上传文件）
• 不计算：在到达提供商之前失败的请求（身份验证错误、速率限制预检查）
• 缓存输入：在v1中按全价计算（不显示提供商缓存折扣）。v2可能会单独计入缓存提示令牌。

​

三态覆盖语义

​

配额解析链——v1（当前版本）

1. users.token_quota        ── NULL? skip. 0? unlimited. N>0? cap at N.
2. users.plan.monthly_token_quota   ── only when billing_enabled = TRUE
3. system_settings.default_token_quota  ── defensive fallback
4. unlimited                ── last resort if everything above is NULL

​

周期重置

• 对于付费用户，quota_reset_at 镜像 Subscription.current_period_end。invoice.payment_succeeded webhook 处理程序在每次成功续期时将 tokens_used_this_period 设置为 0，并将 quota_reset_at 推进到新周期结束。
• 对于免费用户（无 Stripe 订阅），每小时 cron 任务在以计划分配日期为锚点的日历月边界处将 tokens_used_this_period 重置为 0。
• 周期中途的计划变更不会重置计数器——仅续期会重置。这可防止配额循环利用漏洞（“订阅 → 使用专业版配额 → 取消 → 重新订阅”）。

​

中流强制执行

• 聊天调用入口的预检查：最便宜的路径，阻止用户无法承担的请求。
• 流式传输期间，运行中的令牌计数在每个分块上重新评估。超过上限会关闭流，返回结构化终止帧，而不是网络错误。
• 前端解释终止帧并显示 <QuotaExceededDialog>，其中包含指向 /settings?tab=billing 的深层链接。
• 非流式响应返回 HTTP 402，响应体为 { code: "QUOTA_EXCEEDED", reset_at, upgrade_url }。

​

账单禁用回退

• 跳过链的第 2 步——链折叠为 override → default → unlimited。
• /api/billing/* 和 /api/webhooks/stripe 返回 503。
• Plan & Billing 用户标签页和 Admin → Billing 导航组被隐藏。
• 所有账单数据（订阅、套餐、users.plan_id）被保留——重新启用时从相同状态恢复，无需迁移。

​

保留：配额链 v2 — 团队座位

• Subscription.quantity 携带座位数（Stripe 原生）。
• 用户的有效计划通过团队成员身份解析，然后回退到其个人计划：
  effective_plan = team.plan if team_member(user) else user.plan
  
• 配额是按座位（每个团队成员获得完整的 monthly_token_quota），而不是共享池。共享池会导致先到先得的耗尽，对客户不利。
• 覆盖语义保持不变——团队管理员仍然可以通过 users.token_quota = N 对单个成员进行硬限制，该限制在链中位于团队计划之上。

​

Reserved: quota chain v3 — native Org allocation (no Stripe)

• New table org_quota_allocations(user_id, monthly_token_quota, org_id) distributes a parent budget across members.
• Allocations are per user, not a shared pool — every member has a clear individual SLA.
• Updated chain:
  override → max(plan_quota, org_allocation) → default → unlimited
  
• max()，而非 sum()。付费Pro用户永远不会获得少于他们已支付的配额，即使他们的组织管理员设置了较低的分配。Stripe支付的配额是神圣的。

​

预留：按使用量付费的信用额度余额（v3 独立维度）

• 新表 user_credits(user_id, balance_cents, currency) ——通过 Stripe Checkout mode='payment' 充值。
• 消费顺序：订阅配额优先，然后是信用额度余额（仅在订阅耗尽后才开始扣除信用额度）。
• 信用额度余额不可退款（预付款行业标准）。
• UI 同时展示两个进度条：订阅配额：已使用 4.2M / 5M + 信用额度：剩余 $7.40。

​

默认值

​

定价模型

• 团队计划（Stripe 座位 / subscription.quantity）
• 年度计费
• 多币种展示
• 优惠券 / 促销代码
• 税务处理（Stripe Tax 集成——需要单独的合规审查）
• 基于使用量的计量 / 超额费用
• 按次付费信用余额（一次性充值）

​

故障排除