MuseMVP

MuseMVP 集成了 Dodo Payments 作为支付网关之一。通过统一的 Muse Billing 模块，它与 Creem、Stripe 共用同一套合约与权益模型，支持订阅、一次性购买与客户门户。本文介绍如何配置 Dodo 网关并了解其工作原理。

设置默认网关

当 Dodo Payments 是你的主要结账渠道时，将计费默认网关指向 muse_dodo，并保持公开变量同步：

MUSE_BILLING_DEFAULT_GATEWAY="muse_dodo"
NEXT_PUBLIC_MUSE_BILLING_DEFAULT_GATEWAY="muse_dodo"

网关选择

你仍可在单次结账请求中覆盖网关。以上变量仅定义定价与 launch 流程使用的默认值。

获取 `MUSE_DODO_GATEWAY_API_KEY`

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

# Dodo Payments API 密钥
MUSE_DODO_GATEWAY_API_KEY="DODO_PAYMENTS_API_KEY"
# 可选：强制 Dodo 环境（"test_mode" | "live_mode"）
# 若省略，生产环境使用 live_mode，其他环境使用 test_mode。
MUSE_DODO_GATEWAY_ENV="test_mode"

在 Dodo Payments 控制台的 Developer → API 中获取 API 密钥。

密钥安全

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

获取 `MUSE_DODO_GATEWAY_WEBHOOK_SECRET`

# Webhook 签名校验密钥
MUSE_DODO_GATEWAY_WEBHOOK_SECRET="DODO_PAYMENTS_WEBHOOK_SECRET"

在 Dodo Payments 控制台创建 Webhook，并将回调 URL 设为：

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

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

payment.succeeded
payment.failed
payment.processing
payment.cancelled
subscription.active
subscription.updated
subscription.on_hold
subscription.renewed
subscription.plan_changed
subscription.cancelled
subscription.failed
subscription.expired

将 Webhook 签名密钥复制到 MUSE_DODO_GATEWAY_WEBHOOK_SECRET。

密钥安全

生产环境必须配置 MUSE_DODO_GATEWAY_WEBHOOK_SECRET，且只能保存在服务端。

创建产品并获取产品 ID

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

# Pro 月付订阅产品 ID
NEXT_PUBLIC_MUSE_DODO_PRICE_PRO_MONTHLY_ID="prod_muse_dodo_monthly_xxx"
# Pro 年付订阅产品 ID
NEXT_PUBLIC_MUSE_DODO_PRICE_PRO_YEARLY_ID="prod_muse_dodo_yearly_xxx"
# 终身买断产品 ID
NEXT_PUBLIC_MUSE_DODO_PRICE_LIFETIME_ID="prod_muse_dodo_lifetime_xxx"

在 Dodo Payments 控制台创建对应产品后，通过上述环境变量或 src/config/index.ts 填写产品 ID。

本地开发测试

下载 Ngrok

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

运行

ngrok http 3000

回调域名

将终端中显示的域名作为 Webhook 配置中的回调地址。

切换到测试模式

确保 MUSE_DODO_GATEWAY_ENV 设为 test_mode，并在 Dodo Payments 控制台使用测试模式完成支付验证。

测试模式

Dodo 测试模式不会产生真实扣款，适合在本地验证订阅与一次性购买流程。

工作原理

了解 Muse Billing 如何将 Dodo Payments 接入系统。

集成文件

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

src/modules/muse-billing/lib/gateways/dodo/mappers.ts

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

文件	作用
`dodo/gateway.ts`	Dodo 网关实现：创建 checkout session、解析 Webhook、客户门户。
`dodo/mappers.ts`	将 Dodo Webhook 事件与订阅状态映射为 Muse 合约快照。
`router.ts`	API 路由：暴露 `/api/muse-billing/*` 端点。

核心流程

支付与客户门户的调用链路：

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

服务端从 config.payments.productCatalog 映射中解析 Dodo 产品 ID。

创建 Dodo checkout session，并返回 launchUrl 供前端跳转到托管结账页。

支付完成后，Dodo 发送 Webhook；服务端校验签名并将合约生命周期与访问窗口同步到数据库。

当用户需要进入平台门户时，调用 POST /api/muse-billing/customer-hub 获取跳转到 Dodo 客户门户的链接，用于管理订阅或下载收据。

Dodo Payments