MuseMVP

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

获取 `MUSE_STRIPE_GATEWAY_SECRET_KEY` 密钥

在部署或本地开发前，你需要配置相关密钥。

# Stripe 密钥（以 `sk_` 开头）
MUSE_STRIPE_GATEWAY_SECRET_KEY="sk_test_xxx1"

获取密钥： Stripe

密钥安全

MUSE_STRIPE_GATEWAY_SECRET_KEY 仅用于服务端，切勿暴露到前端或版本库。

获取 `MUSE_STRIPE_GATEWAY_WEBHOOK_SECRET` 密钥

# Webhook 签名校验密钥（以 `whsec_` 开头）
MUSE_STRIPE_GATEWAY_WEBHOOK_SECRET="whsec_xxx2"

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

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

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

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

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

得到webhook密钥： Stripe

密钥安全

MUSE_STRIPE_GATEWAY_WEBHOOK_SECRET 仅用于服务端，切勿暴露到前端或版本库。

创建产品并得到产品 ID

产品与产品 ID 默认来自 src/config/index.ts 的 config.payments.productCatalog.*.gatewayProductIds.muse_stripe，也可通过以下环境变量覆盖：

# 订阅 月付价格 ID
NEXT_PUBLIC_MUSE_STRIPE_PRICE_PRO_MONTHLY_ID="prod_xxx1"
# 订阅 年付价格 ID
NEXT_PUBLIC_MUSE_STRIPE_PRICE_PRO_YEARLY_ID="prod_xxx2"
# 终身一次性价格 ID
NEXT_PUBLIC_MUSE_STRIPE_PRICE_LIFETIME_ID="prod_xxx3"

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 选择）等参数。

服务端从 config.payments.productCatalog 映射找到相关的 Stripe 价格 ID。

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

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

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