用积分对用量计费

完成后,用户通过方案或手动发放获得积分余额,AI 任务等按量计费的工作从余额中扣除。

积分是产品对按量计费的工作收费的单位。用户通过付费方案、运营人员发放或注册奖励获得积分。每个任务在运行前先冻结价格,工作成功后才扣除。积分不需要服务商和环境变量,除非开启注册奖励,新用户余额为零;积分不会过期。

准备工作

  • 拥有 credits.read 和 credits.write 的管理员账号。要在方案上设置积分还需要 products.write;内置的 Commerce Manager 角色已包含产品和积分相关权限。
  • 如果希望买家付款后拿到方案积分,需要先接入支付服务商,见 接入支付服务商。

给用户积分

打开方案

进入 商业化 → 产品(/admin/products),点击产品键,在 定价方案 卡片中选择一个方案。

填写数量

在 包含积分 中填入数量,点击 保存方案。不附带积分的方案保持 0 即可。

该方案的订单付款后,买家会获得这些积分;即使服务商重复推送付款事件,也只发放一次。发放时优先读取 en 那一行方案,所以请在 en 方案上设置 包含积分,其他语言填同样的数字。

设置工作的价格

AI 任务的积分价格在 设置 → AI 配置 中设置:每个任务固定价格、按请求参数定价,或按 Token 用量计费。操作见 设置场景路由和定价。任务价格高于可用余额时,在调用服务商之前就会被拒绝。

为自己的功能收取积分

工作开始前先冻结价格,然后对这笔预留只结算一次:成功时扣除,失败时退还。先解析出用户,再在服务端代码中调用。

src/server/services/export.service.ts
import {
  captureAiTaskCredits,
  refundAiTaskCredits,
  reserveAiTaskCredits,
} from "@/server/services/credits-ledger.service";

const { reservationId } = await reserveAiTaskCredits({
  userId,
  taskId: `export_${jobId}`,
  amount: 5,
});

try {
  await runExport(jobId);
  await captureAiTaskCredits({ reservationId, userId });
} catch (error) {
  await refundAiTaskCredits({ reservationId, userId });
  throw error;
}

可用余额不足时预留会失败,错误信息包含 /system/insufficient-credits,界面可以据此跳转。把 reservationId 与任务一起保存,让重试或轮询程序结算同一笔预留。

不要让用户直接改动余额

不要新增可由用户调用的发放、预留、扣除、退还或修复积分的 server function。面向用户的函数只读并绑定当前会话用户,否则 pnpm validate:session-owner 会失败。

查看或修复余额

打开用户

在 概览 → 用户 的用户行点击 详情。积分 卡片显示当前余额和最近的账本记录。

必要时修复

如果余额和账本对不上(例如有人直接改过数据库),点击 修复余额快照。系统会根据账本重建余额,并把修复前后的数值写入审计日志。

验证

给测试用户发放 10 积分

手动发放 10 积分,以该用户登录并打开 /app/credits。可用余额显示 10,账本里能看到这次发放。

购买方案

在服务商测试模式下购买一个设置了 包含积分 的方案,刷新 /app/credits。方案积分以一条购买记录出现。

注册新用户

开启注册奖励后注册一个新账号并打开 /app/credits。账本中有一条数量等于设置值的 signup.bonus 发放记录。

用完积分

发起一个价格高于剩余余额的 AI 任务。任务不会被创建,用户会被带到 /system/insufficient-credits。

用户在 /app/credits/ledger 查看完整账本和余额是否一致的标识,在 /app/credits/reservations 查看预留和退还记录。pnpm validate:credits 会检查积分不足的处理、余额偏差修复和页面接线。

常见问题

任务因积分不足失败

可用余额低于任务价格。仍在运行的任务所冻结的积分不计入可用余额。发放积分或购买设置了 包含积分 的方案,然后重试。

Reservation is already settled.

该预留已被扣除或退还。每笔预留只结算一次,重试扣除或退还前先检查它的状态。

账本页面显示余额不一致

存储的余额不再等于账本之和,通常是直接修改了数据库。在后台打开该用户,点击 修复余额快照。

付费方案没有增加积分

确认方案 en 那一行的 包含积分 大于零,并在 商业化 → 订单 中确认订单已付款。如果订单仍为待付款,参考 接入支付服务商。

参考

下一步