Discourse 订阅插件

[SubStrider]

[指南] 如何使用 Stripe 定价表设置 Discourse 订阅（及常见陷阱）

大家好，

经过漫长的故障排除过程，我想分享一个使用现代 Stripe 定价表 方法设置官方 discourse-subscriptions 插件的权威指南。这种方法功能强大，但有几个关键步骤并不显而易见，可能会导致诸如 webhook 失败（404 Not Found）或用户在付款成功后未被添加到群组等错误。

以下是已确认可行的分步过程。

---

第一部分：Stripe 配置

此过程使用 Stripe 作为所有产品和价格的“事实来源”。

1. 创建您的产品和价格

• 在您的 Stripe Dashboard 中，确保您处于实时模式。
• 转到产品 > 产品目录。
• 首先创建您的主要产品（例如，“高级会员”、“VIP 访问”）。
• 在每个产品下，创建所有相关的价格（例如，XX / 月、XXX / 年）。

2. 至关重要的元数据步骤 要让插件自动将用户添加到群组，您必须为每一个价格对象添加特定的元数据。Stripe 的仪表板界面可能很难找到它。

• 创建新价格时（或如果您能找到“编辑价格”选项），您必须添加元数据。您可能需要在价格创建过程中点击**“其他选项”**以显示元数据字段。
• 点击**+ 添加元数据**并输入以下内容：
  • 键： group_name
  • 值： Discourse 中群组的唯一、URL 安全的** slug/句柄**，而不是其完整名称。

示例：

• 如果您的 Discourse 群组的完整名称是**“Enclave Plus”**，则其 slug 可能是 EnclavePlus。
• 您必须使用 EnclavePlus 作为值。使用带空格的“Enclave Plus”将导致失败。

• 您必须为要链接到群组的每个价格计划重复此操作。

3. 创建您的 Stripe 定价表

• 转到产品 > 定价表。
• 创建一个新表并添加您刚刚配置的价格。
• 发布表格后，点击“复制代码”按钮以获取您的定价表 ID（它以 prctbl_... 开头）。

4. 配置 Webhook 端点（404 错误修复） 这是最常见的故障点。

• 转到开发人员 > Webhook，然后点击**+ 添加端点**。
• 端点 URL 必须符合以下格式：https://your-discourse-site.com/s/hooks
  注意：正确的路径是 /s/hooks，而不是 /s/stripe/webhook。
• 对于要发送的事件，至少添加：
  • checkout.session.completed
  • customer.subscription.deleted
• 创建端点并复制签名密钥（它以 whsec_... 开头）。

---

第二部分：Discourse 配置

现在，让我们配置插件以使用您在 Stripe 中设置的所有内容。

1. 输入 API 密钥和定价表 ID

• 转到 Admin > Settings 并搜索 discourse subscriptions。
• 填入您的实时 Stripe 密钥：
  • discourse subscriptions public key（pk_live_...）
  • discourse subscriptions secret key（sk_live_...）
  • discourse subscriptions webhook secret（whsec_...）
• 启用定价表模式：
  • 勾选 discourse subscriptions pricing table enabled 复选框。
  • 将您的 prctbl_... ID 粘贴到 discourse subscriptions pricing table id 字段中。

2. 将 Stripe 产品链接到 Discourse 群组 即使有定价表，您也需要告诉 Discourse 哪个群组属于哪个产品。

• 转到 Admin > Plugins > Subscriptions，然后点击产品选项卡。
• 点击创建新产品。
• 输入一个产品名称，该名称完全匹配 Stripe 中的产品名称（例如，Enclave Plus）。
• 保存产品。在产品页面上，向下滚动并点击添加新计划。
• 此计划仅作为“桥梁”。唯一关键的字段是用户群组。
  • 计划昵称： Enclave Plus Group Link（或任何供您参考的名称）。
  • 用户群组： 从下拉列表中选择正确的 Discourse 群组。
  • 其他字段（金额、间隔）可以保留默认值，因为它们将被忽略。
• 保存计划。为所有不同的产品重复此操作。

---

故障排除摘要

• 问题： Webhook 失败并出现 404 Not Found 错误。
  • 解决方案： 您在 Stripe 中的端点 URL 不正确。它必须是 https://your-discourse-site.com/s/hooks。
• 问题： Webhook 成功（200 OK），并且付款显示在用户的账单资料中，但他们未被添加到群组。
  • 解决方案： 您的元数据不正确。检查三件事：
    1. 元数据必须位于Stripe 价格对象上，而不是产品对象上。
    2. 元数据键必须完全是 group_name。
    3. 元数据值必须是群组的唯一slug/句柄（例如，EnclavePlus），而不是带空格的完整名称。

希望本指南能为他人节省在此复杂但功能强大的设置过程中可能遇到的时间和挫败感。