SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场tl-openmeter-local-dev

tl-openmeter-local-dev

部署与运维

查看项目

更新于 10-16 03:34

技能介绍

用途

本技能用于在本地开发环境中搭建并排查 OpenMeter，支持完整的计量（metering）、计费（billing）与 Webhook 功能。它重点说明自托管（Docker）与 Cloud（预发/生产）之间的差异与常见坑点。

适用触发场景包括：本地搭建 OpenMeter、为 Webhook 配置 ngrok、调试 catalog 同步错误、排查 Webhook 返回 500、在 OpenMeter 中安装 Stripe 应用、判断本地与预发环境的功能差异，以及用户提到 OpenMeter + Docker、本地开发或 Webhook 问题时。

主要能力

  • 通过 Docker 启动本地 OpenMeter 服务并验证健康状态。
  • 安装 Stripe 应用并创建计费配置（billing profile）。
  • 使用 ngrok 暴露本地端口，以接收 Stripe 应用回调与 Stripe Webhook。
  • 运行 catalog 同步脚本，处理自托管环境下的 Webhook 通道限制。
  • 配置 Stripe Webhook 端点与签名密钥。
  • 提供 Webhook 认证模式说明：Cloud 使用 Svix 签名，自托管可使用 x-webhook-secret 头校验，本地无密钥时为开发直通模式。
  • 提供验证脚本与手动验证命令，检查 OpenMeter、Stripe 应用与 Webhook 端点状态。
  • 提供故障排查表，覆盖端口占用、容器启动失败、连接被拒、Stripe 应用缺失、ngrok URL 变更等问题。

使用方式

技能按步骤组织，先通过 AskQuestion 工具确认用户环境（本地 Docker 还是预发/生产）、是否需要 Stripe 计费、ngrok 是否已配置，再决定执行范围。

主要步骤与命令：

  1. 启动 Docker 服务：npm run docker:up，验证 curl http://localhost:8888/api/v1/meters，Portal UI 为 http://localhost:8889，或运行 ./scripts/verify-setup.ps1。
  2. 安装 Stripe 应用：npx tsx scripts/openmeter/openmeter-install-stripe-app.ts，需要 .env 中的 STRIPE_SECRET_KEY，验证 curl http://localhost:8888/api/v1/apps。
  3. 设置 ngrok：安装（choco install ngrok 或 brew install ngrok）、认证（ngrok config add-authtoken YOUR_TOKEN）、启动（./scripts/start-ngrok.ps1 或 ngrok http 3001）、获取 URL（curl http://127.0.0.1:4040/api/tunnels），再运行 npx tsx scripts/openmeter/set-openmeter-webhook-url.ts；手动配置需更新三处，改后执行 docker compose restart openmeter。
  4. 运行 catalog 同步：npx tsx scripts/openmeter/openmeter-catalog-sync.ts，本地输出中出现跳过 Webhook 通道的提示属正常。
  5. 启动 API 服务：npm run dev；若使用 ngrok HTTP 转发，在 .env 中设置 API_HTTP_FOR_NGROK=true。
  6. 配置 Stripe Webhook：在 Stripe Dashboard 添加端点 https://YOUR-NGROK-URL/webhooks/stripe，事件为 checkout.session.completed、customer.subscription.updated、customer.subscription.deleted，将签名密钥写入 .env 的 STRIPE_WEBHOOK_SECRET_DEV=whsec_...。

验证可运行 ./scripts/verify-setup.ps1，或手动执行上述 curl 命令，包括向 http://127.0.0.1:3001/webhooks/openmeter 发送测试事件。

适用场景

  • 本地开发中需要完整计量、计费与 Webhook 支持。
  • 需要区分自托管与 Cloud 行为差异，避免按 Cloud 方式配置本地环境。
  • 调试 catalog 同步、Webhook 认证与 Stripe 集成问题。

限制

  • 自托管（本地）不支持通过 API 创建 Webhook 通道（返回“not implemented”），仅能通过 config.local.yaml 静态配置；Cloud 使用 Svix 支持的 API 通道。
  • 自托管无 Svix 签名校验，使用普通 HTTP；Cloud 使用 Svix 签名。
  • 本地无密钥时 Webhook 为开发直通模式，接受所有请求。
  • 该技能属于 tl-openmeter 套件，相关技能包括 tl-openmeter-api（REST API 参考）与 tl-openmeter-api-mcp-server（供 Cursor 调用本地 OpenMeter 的 MCP 服务器）。
  • 资料未提供具体收费、价格、平台支持范围或效果数据。