StripeMeter

StripeMeter 是一款原生集成 Stripe 的用量计量系统，可确保基于用量的计费获得准确的用量总计。它能对重试进行去重，通过水印处理延迟事件，维护持续运行的计数器，并仅将增量数据推送至 Stripe。

快速开始

bash
git clone https://github.com/geminimir/stripemeter && cd stripemeter
cp .env.example .env && docker compose up -d && pnpm -r build
pnpm db:migrate && pnpm dev

核心概念

事件（不可变账本）

计数器（物化聚合）

水印（延迟事件处理）

增量推送（Stripe同步）

API 端点

事件采集

bash
curl -X POST http://localhost:3000/v1/events/ingest \
-H Content-Type: application/json \
-d {
events: [{
tenantId: your-tenant-id,
metric: api_calls,
customerRef: cus_ABC123,
quantity: 100,
ts: 2025-01-16T14:30:00Z
}]
}

获取费用预估

bash
curl -X POST http://localhost:3000/v1/usage/projection \
-H Content-Type: application/json \
-d {tenantId: your-tenant-id, customerRef: cus_ABC123}

健康检查与指标

• - 就绪检查：GET /health/ready
• 指标：GET /metrics
• 事件：GET /v1/events?tenantId=X&limit=10

Node.js SDK

typescript
import { createClient } from @stripemeter/sdk-node;

const client = createClient({
apiUrl: http://localhost:3000,
tenantId: your-tenant-id,
customerId: cus_ABC123
});

// 记录用量
await client.track({
metric: api_calls,
customerRef: cus_ABC123,
quantity: 100,
meta: { endpoint: /v1/search }
});

// 获取实时用量
const usage = await client.getUsage(cus_ABC123);
const projection = await client.getProjection(cus_ABC123);

Python SDK

python
from stripemeter import StripeMeterClient

client = StripeMeterClient(
api_url=http://localhost:3000,
tenant_id=your-tenant-id,
customerid=cusABC123
)

client.track(
metric=api_calls,
customerref=cusABC123,
quantity=100
)

Stripe计费驱动

如需直接集成 Stripe，请使用 stripe-driver 包：

typescript
import { StripeBillingDriverImpl } from @stripemeter/stripe-driver;

const driver = new StripeBillingDriverImpl({
liveKey: process.env.STRIPESECRETKEY,
testKey: process.env.STRIPETESTSECRET_KEY
});

// 向 Stripe 记录用量
await driver.recordUsage({
mode: live,
stripeAccount: default,
subscriptionItemId: si_xxx,
quantity: 100,
periodStart: 2025-01-01,
idempotencyKey: unique-key
});

// 获取用量摘要
const summary = await driver.getUsageSummary(
si_xxx,
2025-01-01,
default
);

影子模式

在不影响实际发票的情况下测试 Stripe 用量提交：

1. 1. 在环境中设置 STRIPETESTSECRET_KEY
2. 将价格映射标记为 shadow=true
3. 提供 shadowStripeAccount、shadowPriceId
4. 实际发票不受影响

定价模拟器

typescript
import { InvoiceSimulator } from @stripemeter/pricing-lib;

const simulator = new InvoiceSimulator();

const result = simulator.simulate({
customerId: test,
periodStart: 2024-01-01,
periodEnd: 2024-02-01,
usageItems: [{
metric: api_calls,
quantity: 25000,
priceConfig: {
model: tiered,
currency: USD,
tiers: [
{ upTo: 10000, unitPrice: 0.01 },
{ upTo: 50000, unitPrice: 0.008 },
{ upTo: null, unitPrice: 0.005 }
]
}
}]
});

项目结构

stripemeter/
├── packages/
│ ├── core/ # 共享类型、模式
│ ├── database/ # Drizzle ORM + Redis
│ ├── pricing-lib/ # 定价计算器
│ ├── stripe-driver/ # 直接 Stripe API 驱动
│ ├── sdk-node/ # Node.js SDK
│ └── sdk-python/ # Python SDK
├── apps/
│ ├── api/ # REST API (Fastify)
│ ├── workers/ # 后台工作进程 (BullMQ)
│ ├── admin-ui/ # 管理后台
│ └── customer-widget/# 可嵌入组件

环境变量

bash
STRIPESECRETKEY=sklivexxx # 正式 Stripe 密钥
STRIPETESTSECRETKEY=sktest_xxx # 测试 Stripe 密钥（用于影子模式）
DATABASE_URL=postgres://... # PostgreSQL 连接
REDIS_URL=redis://... # Redis 连接

常见任务

验证幂等性

bash

发送相同事件两次 - 仅计数一次

运行对账

检查本地总计与 Stripe 之间的偏差：

• - 偏差超过 0.5% 阈值将触发调查
• 参见 RECONCILIATION.md 获取操作手册

重放延迟事件

bash
curl -X POST http://localhost:3000/v1/replay \
-H Content-Type: application/json \
-d {tenantId: X, dryRun: true}

其他资源

• - API 文档
• 模拟器指南
• 对账操作手册
• 告警配置