Puter MonthlyUsage 对象完全解析读懂月度资源用量与配额余额数据【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterMonthlyUsage是 Puter 生态中描述用户当月资源用量的标准返回对象由 puter.auth.getMonthlyUsage() 等接口返回其数据还支撑着 GUI 仪表盘中的用量展示与后端计费计量逻辑。通过本文你将掌握该对象allowanceInfo、appTotals、usage三个属性的完整语义、微美分microcents金额单位换算以及它从计量服务到客户端 SDK 的完整产生链路。MonthlyUsage 在 Puter 用量体系中的定位Puter 对用户在云端调用 API、消耗 AI 资源、读写文件等行为进行统一的资源计量。MonthlyUsage定义见 src/docs/src/Objects/monthlyusage.md正是这类计量结果面向开发者/上层 UI 的结构化视图它把一个自然月内三个维度的数据打包成一份对象返回配额与余额allowanceInfo本月可用额度与剩余额度按应用统计appTotals本账号各应用各消耗了多少资源按 API 统计usage每个 API 被调用的次数、消耗的资源及计量单位。在文档站中该对象归属 Objects对象类型总览 一节其姊妹对象 DetailedAppUsage 则提供单一应用维度的细粒度用量视图详见下文对比。获取方式puter.auth.getMonthlyUsage()MonthlyUsage通常不是开发者手工构造的而是由 Puter 官方 JS SDK 的auth模块提供的方法返回。其完整说明见 puter.auth.getMonthlyUsage()适用平台websites、apps、nodejs、workers语法puter.auth.getMonthlyUsage()参数无返回值一个Promiseresolve 为MonthlyUsage对象。调用示例SDK 通过页面引入https://js.puter.com/v2/后可直接使用puter.auth.getMonthlyUsage().then(function (usage) { puter.print(pre${JSON.stringify(usage, null, 2)}/pre); });官方文档站点中还提供了可直接交互的 play-ground 示例页 auth-get-monthly-usage.html用于实时观察该接口返回的完整 JSON。从 SDK 源码看src/puter-js/src/modules/Auth.js该方法实际发起一次对${APIOrigin}/metering/usage的请求因此凡是能调用官方 API 的合法应用含 Node.js 与 Workers 环境都可拿到同样的数据结构。结构总览三个顶层字段依据官方对象定义MonthlyUsage共包含三个顶层属性。SDK 侧的类型注解src/puter-js/src/modules/Auth.js与后端计量服务的返回结构完全对应interface MonthlyUsage { allowanceInfo: { monthUsageAllowance: number; // 本月资源总配额 remaining: number; // 还可使用的剩余额度 }; appTotals: Recordstring, { count: number; total: number }; usage: Recordstring, { cost: number; count: number; units: number }; }allowanceInfo配额与余额反映用户本月的资源配额与消耗情况字段类型含义monthUsageAllowanceNumber本月资源总配额subscription 的月度用量上限remainingNumber本还可继续使用的剩余配额值得强调的是后端对remaining的计算并不是简单用总配额 − 本月已用。从 src/backend/services/metering/MeteringService.ts 的remainingFrom()实现可看出它由两部分相加remaining max(0, monthUsageAllowance − allowanceUsed) max(0, purchasedCredits − consumedPurchaseCredits)也就是说超出配额后若用户另行购买的 creditsaddons也会被计入remaining且本月消耗会先在配额与已购 credits两个独立池之间分流结算源码注释明确说明each spend lands in exactly one of them (allowance first)。因此remaining的语义是本预算池整体剩余而非单纯的配额余量。同名方法与实现细节可继续查看 MeteringService.getAllowedUsage()。appTotals按应用汇总按应用 idkey统计各应用的消耗值为{ count, total }countNumber该应用发起的 Puter API 调用次数totalNumber该应用累计消耗的资源量。这里有一个值得注意的后端行为appTotals中只会包含当前调用上下文所属应用的明细其余应用的消耗会被合并进一个名为others的键下见 MeteringService.ts 中按actor.app.uid过滤、将其他 appKey 累加进others的逻辑相应的聚合行为在 MeteringService.test.ts 中有测试覆盖。usage按 API 汇总按 API 名称key统计每一种 API 的用量值为字段类型含义costNumber该 API 累计消耗的资源总量countNumber该 API 被调用的次数unitsNumber该 API 的计量单位数量AI 调用以 tokens 计、FS 操作以 bytes 计等注意cost与units是两个不同口径units描述用了多少物理资源单位cost则把消耗折算成统一的资源计费金额。以 AI 对话为例units可能是 token 数cost则是由 token 数经单价换算后的微美分金额。金额单位约定microcents微美分官方对象定义中的info说明框给出了 Puter 统一的资源计价单位Resources in Puter are measured in microcents (e.g.,$0.011,000,000).即 1 美分被细分为 1 亿1e8个微美分。换算速记如下$0.011,000,000microcents$1100,000,000microcents$0.2525,000,000microcents。后端代码中大量使用toMicroCents()帮助函数把美元金额换算成 microcents。例如各类订阅策略文件就以此定义月度配额注册用户免费档registeredUserFreePolicy.ts 中monthUsageAllowance: toMicroCents(0.5)相当于每月 $0.5临时匿名用户档tempUserFreePolicy.ts 中monthUsageAllowance: toMicroCents(0.25)本地自托管无限档localUnlimitedUserPolicy.ts 中monthUsageAllowance: toMicroCents(1_000_000)每月高达百万美元量级。所以当你读取MonthlyUsage中的任何金额类字段total、cost、remaining、monthUsageAllowance时都应按 microcents 理解展示给用户前通常需要除以1e8换算成美元。一份典型的返回结构示例结合三个字段的定义与 microcents 约定一次调用可能返回形如下面的 JSON以下为便于理解字段取值整理的示意结构并非某个真实账号的实际数据{ allowanceInfo: { monthUsageAllowance: 25000000, remaining: 18200000 }, appTotals: { 6b1f9c2e8d7a4f5a9b0c3d2e1f0a9b8c: { count: 142, total: 2300000 }, others: { count: 78, total: 4500000 } }, usage: { puter.ai.chat: { cost: 5200000, count: 96, units: 260000 }, puter.fs.read: { cost: 300000, count: 87, units: 15728640 } } }数据从何而来后端的计量与月度结算链路MonthlyUsage不是一个临时拼接的查询结果而是 Puter 后端计量服务MeteringService的产物其读取链路在 src/backend/services/metering/MeteringService.ts 中可完整看到以actor.user.uuid 当前月形如${METRICS_PREFIX}:actor:{uuid}:{yyyy-mm}为 key从 metering buffer 存储中同时读取本月总量与本月各应用分布两组聚合数据读取本月用量会触发当月周期费用结算applyMonthlyCharges——这是读取月用量是结算当月 recurring charges 的两个时机之一的体现源码注释明示 Reading the month 本身会结算费用随后得到最终usage若当前请求带有actor.app上下文则按上文所述对appTotals做当前应用 others的过滤归一allowanceInfo由getAllowedUsage()结合用户订阅、addons 与当月用量计算得出并最终合并返回。值得了解的是写入侧的用量记录并非即时落库而是先进内存缓冲、再按周期批量冲刷flush到存储层见 flushBufferedUsages()因此刚发生的调用可能存在较短延迟后才体现在MonthlyUsage中这也解释了按 API 明细比总量晚一拍可见的注释说明。计量相关的测试 MeteringService.test.ts 覆盖了getActorCurrentMonthUsageDetails()的行为包括空结果返回{}、appTotals的过滤与others合并、配额外扣 credits 等边界场景可作为理解该对象语义的补充依据。与 DetailedAppUsage 的分工同样描述用量Puter 还提供面向单个应用的DetailedAppUsage详细字段说明其结构为interface DetailedAppUsage { total: number; // 该应用总消耗 [apiName]: { cost; count; units }; // 按 API 维度字段同 MonthlyUsage.usage }在 SDK 中对应 puter.auth.getDetailedAppUsage(appId)请求的是/metering/usage/${appId}路由。使用建议可以这样划分查看当前应用的整体健康度、预算剩余 →puter.auth.getMonthlyUsage()深挖某个具体应用在各 API 上的开销分布 →puter.auth.getDetailedAppUsage(appId)。两者都受同一约束用量数据仅限调用方应用可见usage data is scoped to the calling app only见 getMonthlyUsage 文档。也就是说某个 app 通过 SDK 拿到的appTotals/usage只包含它自己被授权的视角跨应用全量数据属于部署方管理端范畴普通应用无法越权读取。在真实界面中的使用前端 GUI 同样消费这套数据仪表盘模块 usageBudget.js 及其配套测试 usageBudget.test.js 中即引用了monthUsageAllowance字段把后端返回的 microcents 数额渲染为用户可见的配额/余额展示。开发者在自己的应用中复刻类似用量看板时可参考以下典型流程调用puter.auth.getMonthlyUsage()获取MonthlyUsage用allowanceInfo.remaining / allowanceInfo.monthUsageAllowance计算剩余比例并渲染进度条注意金额单位是 microcents用usage按 API 列出 Top 消耗项把units/cost结合各 API 的计量口径做可读化如 tokens、bytes用appTotals展示本应用与其他来源的占比。小结MonthlyUsage是理解 Puter 用户侧资源账本的一把钥匙allowanceInfo告诉你还剩多少预算由月度配额与已购 credits 共同决定appTotals告诉你各应用花了多少usage告诉你每种 API 花了多少、以什么单位计量而所有金额字段统一以 microcents 计价。沿 Auth 模块文档 中getMonthlyUsage、getDetailedAppUsage两条入口即可上手实践想深入了解配额结算、addons 与 credits 的抵扣规则可直接阅读计量服务实现 MeteringService.ts 中getAllowedUsage()、remainingFrom()与allowanceUsedFrom()三处核心逻辑及其测试用例。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Puter MonthlyUsage 对象完全解析读懂月度资源用量与配额余额数据【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterMonthlyUsage是 Puter 生态中描述用户当月资源用量的标准返回对象由 puter.auth.getMonthlyUsage() 等接口返回其数据还支撑着 GUI 仪表盘中的用量展示与后端计费计量逻辑。通过本文你将掌握该对象allowanceInfo、appTotals、usage三个属性的完整语义、微美分microcents金额单位换算以及它从计量服务到客户端 SDK 的完整产生链路。MonthlyUsage 在 Puter 用量体系中的定位Puter 对用户在云端调用 API、消耗 AI 资源、读写文件等行为进行统一的资源计量。MonthlyUsage定义见 src/docs/src/Objects/monthlyusage.md正是这类计量结果面向开发者/上层 UI 的结构化视图它把一个自然月内三个维度的数据打包成一份对象返回配额与余额allowanceInfo本月可用额度与剩余额度按应用统计appTotals本账号各应用各消耗了多少资源按 API 统计usage每个 API 被调用的次数、消耗的资源及计量单位。在文档站中该对象归属 Objects对象类型总览 一节其姊妹对象 DetailedAppUsage 则提供单一应用维度的细粒度用量视图详见下文对比。获取方式puter.auth.getMonthlyUsage()MonthlyUsage通常不是开发者手工构造的而是由 Puter 官方 JS SDK 的auth模块提供的方法返回。其完整说明见 puter.auth.getMonthlyUsage()适用平台websites、apps、nodejs、workers语法puter.auth.getMonthlyUsage()参数无返回值一个Promiseresolve 为MonthlyUsage对象。调用示例SDK 通过页面引入https://js.puter.com/v2/后可直接使用puter.auth.getMonthlyUsage().then(function (usage) { puter.print(pre${JSON.stringify(usage, null, 2)}/pre); });官方文档站点中还提供了可直接交互的 play-ground 示例页 auth-get-monthly-usage.html用于实时观察该接口返回的完整 JSON。从 SDK 源码看src/puter-js/src/modules/Auth.js该方法实际发起一次对${APIOrigin}/metering/usage的请求因此凡是能调用官方 API 的合法应用含 Node.js 与 Workers 环境都可拿到同样的数据结构。结构总览三个顶层字段依据官方对象定义MonthlyUsage共包含三个顶层属性。SDK 侧的类型注解src/puter-js/src/modules/Auth.js与后端计量服务的返回结构完全对应interface MonthlyUsage { allowanceInfo: { monthUsageAllowance: number; // 本月资源总配额 remaining: number; // 还可使用的剩余额度 }; appTotals: Recordstring, { count: number; total: number }; usage: Recordstring, { cost: number; count: number; units: number }; }allowanceInfo配额与余额反映用户本月的资源配额与消耗情况字段类型含义monthUsageAllowanceNumber本月资源总配额subscription 的月度用量上限remainingNumber本还可继续使用的剩余配额值得强调的是后端对remaining的计算并不是简单用总配额 − 本月已用。从 src/backend/services/metering/MeteringService.ts 的remainingFrom()实现可看出它由两部分相加remaining max(0, monthUsageAllowance − allowanceUsed) max(0, purchasedCredits − consumedPurchaseCredits)也就是说超出配额后若用户另行购买的 creditsaddons也会被计入remaining且本月消耗会先在配额与已购 credits两个独立池之间分流结算源码注释明确说明each spend lands in exactly one of them (allowance first)。因此remaining的语义是本预算池整体剩余而非单纯的配额余量。同名方法与实现细节可继续查看 MeteringService.getAllowedUsage()。appTotals按应用汇总按应用 idkey统计各应用的消耗值为{ count, total }countNumber该应用发起的 Puter API 调用次数totalNumber该应用累计消耗的资源量。这里有一个值得注意的后端行为appTotals中只会包含当前调用上下文所属应用的明细其余应用的消耗会被合并进一个名为others的键下见 MeteringService.ts 中按actor.app.uid过滤、将其他 appKey 累加进others的逻辑相应的聚合行为在 MeteringService.test.ts 中有测试覆盖。usage按 API 汇总按 API 名称key统计每一种 API 的用量值为字段类型含义costNumber该 API 累计消耗的资源总量countNumber该 API 被调用的次数unitsNumber该 API 的计量单位数量AI 调用以 tokens 计、FS 操作以 bytes 计等注意cost与units是两个不同口径units描述用了多少物理资源单位cost则把消耗折算成统一的资源计费金额。以 AI 对话为例units可能是 token 数cost则是由 token 数经单价换算后的微美分金额。金额单位约定microcents微美分官方对象定义中的info说明框给出了 Puter 统一的资源计价单位Resources in Puter are measured in microcents (e.g.,$0.011,000,000).即 1 美分被细分为 1 亿1e8个微美分。换算速记如下$0.011,000,000microcents$1100,000,000microcents$0.2525,000,000microcents。后端代码中大量使用toMicroCents()帮助函数把美元金额换算成 microcents。例如各类订阅策略文件就以此定义月度配额注册用户免费档registeredUserFreePolicy.ts 中monthUsageAllowance: toMicroCents(0.5)相当于每月 $0.5临时匿名用户档tempUserFreePolicy.ts 中monthUsageAllowance: toMicroCents(0.25)本地自托管无限档localUnlimitedUserPolicy.ts 中monthUsageAllowance: toMicroCents(1_000_000)每月高达百万美元量级。所以当你读取MonthlyUsage中的任何金额类字段total、cost、remaining、monthUsageAllowance时都应按 microcents 理解展示给用户前通常需要除以1e8换算成美元。一份典型的返回结构示例结合三个字段的定义与 microcents 约定一次调用可能返回形如下面的 JSON以下为便于理解字段取值整理的示意结构并非某个真实账号的实际数据{ allowanceInfo: { monthUsageAllowance: 25000000, remaining: 18200000 }, appTotals: { 6b1f9c2e8d7a4f5a9b0c3d2e1f0a9b8c: { count: 142, total: 2300000 }, others: { count: 78, total: 4500000 } }, usage: { puter.ai.chat: { cost: 5200000, count: 96, units: 260000 }, puter.fs.read: { cost: 300000, count: 87, units: 15728640 } } }数据从何而来后端的计量与月度结算链路MonthlyUsage不是一个临时拼接的查询结果而是 Puter 后端计量服务MeteringService的产物其读取链路在 src/backend/services/metering/MeteringService.ts 中可完整看到以actor.user.uuid 当前月形如${METRICS_PREFIX}:actor:{uuid}:{yyyy-mm}为 key从 metering buffer 存储中同时读取本月总量与本月各应用分布两组聚合数据读取本月用量会触发当月周期费用结算applyMonthlyCharges——这是读取月用量是结算当月 recurring charges 的两个时机之一的体现源码注释明示 Reading the month 本身会结算费用随后得到最终usage若当前请求带有actor.app上下文则按上文所述对appTotals做当前应用 others的过滤归一allowanceInfo由getAllowedUsage()结合用户订阅、addons 与当月用量计算得出并最终合并返回。值得了解的是写入侧的用量记录并非即时落库而是先进内存缓冲、再按周期批量冲刷flush到存储层见 flushBufferedUsages()因此刚发生的调用可能存在较短延迟后才体现在MonthlyUsage中这也解释了按 API 明细比总量晚一拍可见的注释说明。计量相关的测试 MeteringService.test.ts 覆盖了getActorCurrentMonthUsageDetails()的行为包括空结果返回{}、appTotals的过滤与others合并、配额外扣 credits 等边界场景可作为理解该对象语义的补充依据。与 DetailedAppUsage 的分工同样描述用量Puter 还提供面向单个应用的DetailedAppUsage详细字段说明其结构为interface DetailedAppUsage { total: number; // 该应用总消耗 [apiName]: { cost; count; units }; // 按 API 维度字段同 MonthlyUsage.usage }在 SDK 中对应 puter.auth.getDetailedAppUsage(appId)请求的是/metering/usage/${appId}路由。使用建议可以这样划分查看当前应用的整体健康度、预算剩余 →puter.auth.getMonthlyUsage()深挖某个具体应用在各 API 上的开销分布 →puter.auth.getDetailedAppUsage(appId)。两者都受同一约束用量数据仅限调用方应用可见usage data is scoped to the calling app only见 getMonthlyUsage 文档。也就是说某个 app 通过 SDK 拿到的appTotals/usage只包含它自己被授权的视角跨应用全量数据属于部署方管理端范畴普通应用无法越权读取。在真实界面中的使用前端 GUI 同样消费这套数据仪表盘模块 usageBudget.js 及其配套测试 usageBudget.test.js 中即引用了monthUsageAllowance字段把后端返回的 microcents 数额渲染为用户可见的配额/余额展示。开发者在自己的应用中复刻类似用量看板时可参考以下典型流程调用puter.auth.getMonthlyUsage()获取MonthlyUsage用allowanceInfo.remaining / allowanceInfo.monthUsageAllowance计算剩余比例并渲染进度条注意金额单位是 microcents用usage按 API 列出 Top 消耗项把units/cost结合各 API 的计量口径做可读化如 tokens、bytes用appTotals展示本应用与其他来源的占比。小结MonthlyUsage是理解 Puter 用户侧资源账本的一把钥匙allowanceInfo告诉你还剩多少预算由月度配额与已购 credits 共同决定appTotals告诉你各应用花了多少usage告诉你每种 API 花了多少、以什么单位计量而所有金额字段统一以 microcents 计价。沿 Auth 模块文档 中getMonthlyUsage、getDetailedAppUsage两条入口即可上手实践想深入了解配额结算、addons 与 credits 的抵扣规则可直接阅读计量服务实现 MeteringService.ts 中getAllowedUsage()、remainingFrom()与allowanceUsedFrom()三处核心逻辑及其测试用例。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
