Stripe

MuseMVP 集成了 Stripe 作为支付网关之一，通过统一的 Muse Billing 模块处理订阅、一次性购买与客户门户。本文介绍如何配置 Stripe 网关并了解其工作原理。

获取 Stripe 密钥

从 Stripe Dashboard 获取密钥。把 secret key 填入 后台 → 运行时设置（/app/admin/settings），不要写进 .env。 Stripe

密钥安全

网关凭证加密落库。切勿暴露到前端或版本库。

获取 Stripe Webhook 密钥

创建webhook： Stripe 填写回调地址并选择事件类型： Stripe

在 Stripe Dashboard 添加 Webhook 端点，将 URL 设为：

https://example.com/api/muse-billing/notify/muse_stripe

选择配置需要监听的事件类型（或全部）：

checkout.session.completed
customer.subscription.*
invoice.*

得到 webhook 密钥后填入 后台 → 运行时设置。保存后请在 Stripe 侧确认同一份 secret 仍然匹配。 Stripe

密钥安全

Webhook secret 加密落库。与 Stripe 不一致会导致全部 webhook 被拒绝。

创建产品并得到产品 ID

结账产品 ID 存在 后台 → 运行时设置（billing.productMap）。公开定价页使用稳定套餐 ID（pro_monthly、pro_yearly、lifetime）。

Stripe Stripe

本地开发测试

下载 Ngrok

Ngrok下载（https://dashboard.ngrok.com/get-started/setup/windows）是反向代理工具，用于将本地开发服务器暴露到公网。

Ngrok

运行

ngrok http 3000

Ngrok

回调域名

将上述终端域名填向上述webhook中的回调地址

测试

测试卡号	预期结果
`4242 4242 4242 4242`	支付成功 (Successful payment)
`4000 0000 0000 0002`	卡被拒绝 (Card declined)
`4000 0000 0000 9995`	余额不足 (Insufficient funds)
`4000 0000 0000 0127`	CVC 错误 (Incorrect CVC)
`4000 0000 0000 0069`	卡已过期 (Expired card)

利用上述测试信用卡，可以在本地模拟生产环境进行各种支付测试，包括订阅、一次性购买、用户支付管理等。

开启支付宝/微信支付

如果你的产品需要支持支付宝/微信支付，可以在Stripe后台开启。

Stripe

工作原理解析

了解 Muse Billing 是如何将 Stripe 融入系统中的。

集成文件分布

src/modules/muse-billing/lib/gateways/muse-stripe-gateway.ts

src/modules/muse-billing/lib/orchestrator.ts

src/backend/api/routes/muse-billing/router.ts

文件	职责
`muse-stripe-gateway.ts`	Stripe 网关实现：Checkout Session、Webhook 解析、合约同步。
`orchestrator.ts`	计费编排层：launch、customer-hub、Webhook 分发。
`router.ts`	API 路由：暴露 `/api/muse-billing/*` 接口。

核心工作流

针对付款和获取 Customer Hub 的动作流程如下：

前端调用 POST /api/muse-billing/launch，传入 productId、gatewayId（可选，默认由 orchestrator 选择）等参数。

服务端从后台 billing.productMap 设置中解析 Stripe 价格 ID。

创建 Stripe Checkout Session，返回 launchUrl 供前端跳转至结账页。

用户完成支付后，Stripe 发送 Webhook，服务端校验签名并同步合约状态到数据库。

当用户需要进入平台后，通过调用 POST /api/muse-billing/customer-hub 取得跳转 Stripe 官方 Customer Portal 的链接来管理订阅或下载收据等。