Prmbr/docs/stripe-setup.md
2025-08-05 22:43:18 +08:00

5.7 KiB
Raw Permalink Blame History

Stripe 支付集成配置指南

本文档详细说明如何为 Prmbr 项目配置 Stripe 支付系统,实现订阅管理功能。

1. Stripe 账户设置

1.1 创建 Stripe 账户

  1. 访问 Stripe Dashboard
  2. 注册或登录 Stripe 账户
  3. 完成账户验证(可能需要提供业务信息)

1.2 获取 API 密钥

在 Stripe Dashboard 中:

  1. 进入 DevelopersAPI keys
  2. 复制以下密钥:
    • Publishable key (以 pk_ 开头)
    • Secret key (以 sk_ 开头)

2. 创建产品和价格

2.1 创建 Pro 订阅产品

  1. 在 Stripe Dashboard 中,进入 Products
  2. 点击 Add product
  3. 填写产品信息:
    • Name: Prmbr Pro Plan
    • Description: Professional plan with advanced features
  4. 添加价格:
    • Price: $19.90
    • Billing period: Monthly
    • Currency: USD
  5. 保存产品并复制 Price ID (以 price_ 开头)

2.2 配置产品元数据(可选)

为产品添加元数据以便识别:

  • plan_type: pro
  • features: 5000_prompts,10_versions,priority_support

3. 环境变量配置

在项目根目录的 .env.local 文件中添加以下环境变量:

# Stripe 配置
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_your_publishable_key_here"
STRIPE_SECRET_KEY="sk_test_your_secret_key_here"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Webhook 密钥(稍后配置)
STRIPE_WEBHOOK_SECRET="whsec_your_webhook_secret_here"

注意: 不再需要 NEXT_PUBLIC_STRIPE_PRO_PRICE_ID 环境变量,价格 ID 现在从数据库动态获取。

3.1 配置 Pro 套餐价格 ID

创建 Stripe 价格后,需要在数据库中更新 Pro 套餐的 stripePriceId 字段:

-- 在数据库中更新 Pro 套餐的 Stripe 价格 ID
UPDATE subscription_plans
SET "stripePriceId" = 'price_your_actual_pro_price_id_here'
WHERE name = 'pro';

或者使用管理员 API 更新:

curl -X PUT http://localhost:3000/api/admin/subscription-plans \
  -H "Content-Type: application/json" \
  -d '{
    "id": "pro",
    "stripePriceId": "price_your_actual_pro_price_id_here"
  }'

4. Webhook 配置

4.1 创建 Webhook 端点

  1. 在 Stripe Dashboard 中,进入 DevelopersWebhooks
  2. 点击 Add endpoint
  3. 设置端点 URL
    • 开发环境: http://localhost:3000/api/webhooks/stripe
    • 生产环境: https://yourdomain.com/api/webhooks/stripe

4.2 选择监听事件

添加以下事件类型:

  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
  • invoice.payment_succeeded
  • invoice.payment_failed

4.3 获取 Webhook 签名密钥

  1. 创建 webhook 后,点击进入详情页面
  2. Signing secret 部分,点击 Reveal 复制密钥
  3. 将密钥添加到环境变量 STRIPE_WEBHOOK_SECRET

5. 客户门户配置

5.1 启用客户门户

  1. 在 Stripe Dashboard 中,进入 SettingsBillingCustomer portal
  2. 点击 Activate 启用客户门户
  3. 配置门户设置:
    • Business information: 填写公司信息
    • Customer information: 允许客户更新邮箱和地址
    • Subscriptions: 允许客户取消订阅
    • Payment methods: 允许客户更新付款方式

5.2 自定义门户外观

  1. Branding 部分上传 Logo
  2. 设置主题颜色以匹配您的品牌
  3. 配置返回 URL: https://yourdomain.com/subscription

6. 测试配置

6.1 使用测试卡号

Stripe 提供测试卡号用于开发:

  • 成功支付: 4242 4242 4242 4242
  • 需要验证: 4000 0025 0000 3155
  • 被拒绝: 4000 0000 0000 0002

6.2 测试订阅流程

  1. 启动开发服务器: npm run dev
  2. 访问价格页面: http://localhost:3000/pricing
  3. 点击 "Upgrade to Pro" 按钮
  4. 使用测试卡号完成支付
  5. 验证用户订阅状态是否正确更新

7. 生产环境部署

7.1 切换到生产密钥

  1. 在 Stripe Dashboard 右上角关闭 Test mode
  2. 获取生产环境的 API 密钥
  3. 更新环境变量为生产密钥

7.2 更新 Webhook URL

  1. 创建新的生产环境 webhook 端点
  2. 使用生产域名: https://yourdomain.com/api/webhooks/stripe
  3. 更新 STRIPE_WEBHOOK_SECRET 为生产密钥

7.3 验证配置

  • 确保所有环境变量正确设置
  • 测试完整的订阅和取消流程
  • 验证 webhook 事件正常接收和处理

8. 常见问题

8.1 Webhook 验证失败

  • 检查 STRIPE_WEBHOOK_SECRET 是否正确
  • 确保 webhook URL 可以从外网访问
  • 验证请求头中的签名

8.2 订阅状态不同步

  • 检查 webhook 事件是否正常接收
  • 查看服务器日志中的错误信息
  • 确保数据库连接正常

8.3 支付失败

  • 检查 Stripe 密钥是否正确
  • 验证产品和价格 ID 是否匹配
  • 确保客户信息完整

9. 安全注意事项

  1. 密钥安全

    • 永远不要在客户端代码中暴露 Secret Key
    • 使用环境变量存储敏感信息
    • 定期轮换 API 密钥
  2. Webhook 安全

    • 始终验证 webhook 签名
    • 使用 HTTPS 端点
    • 实现幂等性处理
  3. 数据保护

    • 不要存储完整的信用卡信息
    • 遵循 PCI DSS 合规要求
    • 定期备份订阅数据

10. 监控和日志

10.1 Stripe Dashboard 监控

  • 定期检查支付状态
  • 监控失败的支付和订阅
  • 查看客户活动日志

10.2 应用程序日志

  • 记录所有 Stripe API 调用
  • 监控 webhook 处理状态
  • 设置错误告警

配置完成后,您的应用程序将具备完整的订阅管理功能,包括:

  • 用户订阅 Pro 计划
  • 自动处理订阅状态变更
  • 客户自助管理订阅
  • 安全的支付处理