Stripe-Stack 项目部署指南：从开发到生产环境全流程解析

Stripe-Stack 项目部署指南：从开发到生产环境全流程解析

stripe-stack A Stripe focused Remix Stack that integrates User Subscriptions, Authentication and Testing. Driven by Prisma ORM. Deploys to Fly.io 项目地址: https://gitcode.com/gh_mirrors/st/stripe-stack

前言

Stripe-Stack 是一个基于 Remix 框架构建的 SaaS 应用模板，集成了 Stripe 支付系统和现代化开发工具链。本文将详细介绍如何将 Stripe-Stack 项目从本地开发环境部署到 Fly.io 生产环境，帮助开发者理解完整的部署流程和关键配置要点。

部署前准备

在开始部署前，我们需要完成几个关键准备工作：

1. 数据库迁移处理

确保 Prisma 迁移文件已准备就绪，这是部署过程中不可或缺的一环。开发环境中的 Stripe 测试数据应当清理干净，避免影响生产环境数据。

2. Stripe Webhook 生产环境配置

Webhook 是 Stripe 与你的应用通信的重要渠道，正确配置至关重要：

1. 访问 Stripe 仪表板的 Webhook 管理页面
2. 创建新的 Webhook 端点
3. 在 URL 输入框中填入即将部署的应用地址（格式如：https://your-app.fly.dev/api/webhook）
4. 选择最新的 Stripe API 版本
5. 配置监听以下关键事件：
   • checkout.session.completed（支付会话完成）
   • customer.subscription.updated（用户订阅更新）
   • customer.subscription.deleted（用户订阅取消）
6. 获取生成的签名密钥（Signing Secret）
7. 将此密钥设置为 .env 文件中的 STRIPE_WEBHOOK_ENDPOINT 变量

专业提示：Webhook 配置的正确性直接影响支付流程的可靠性，建议在部署前在本地通过 ngrok 等工具进行充分测试。

Fly.io 部署详细步骤

1. 环境准备

首先需要安装 Fly.io 命令行工具并完成认证：

# 新用户注册
fly auth signup

# 已有账户登录
fly auth login

2. 应用初始化

使用以下命令启动部署流程：

fly launch

此命令会自动检测项目配置并引导完成初始化过程。注意确保 Fly CLI 中的模板名称与项目中的 fly.toml 文件一致。

3. 环境变量配置

Fly.io 通过 secrets 管理敏感环境变量，这是保障应用安全的重要环节：

fly secrets set SESSION_SECRET="" \
  ENCRYPTION_SECRET="" \
  PROD_HOST_URL="https://my-app.fly.dev" \
  RESEND_API_KEY="" \
  STRIPE_SECRET_KEY="" \
  STRIPE_WEBHOOK_ENDPOINT="" \
  HONEYPOT_ENCRYPTION_SEED=""

关键注意事项：

• PROD_HOST_URL 必须包含完整的协议和域名
• 首次部署时不需要配置所有变量，如 GitHub 相关配置可暂缓

4. 数据库种子处理

首次部署会自动执行数据库种子脚本，完成后应禁用此功能：

1. 检查 Fly 应用日志确认种子脚本执行成功
2. 修改 docker-entrypoint.js 文件，注释掉种子脚本执行代码
3. 重新部署应用

// 首次部署后应注释掉此行
// await exec('npx prisma db seed')

5. 完成部署

执行最终部署命令并验证：

fly deploy

部署完成后，访问 https://your-app.fly.dev 即可查看运行中的生产环境应用。

部署后维护

应用更新流程

代码变更后，只需重新运行部署命令：

fly deploy

生产环境监控建议

虽然本文未涉及 CI/CD 流水线配置，但建议开发者：

1. 设置 Fly.io 的自动健康检查
2. 配置日志监控和告警
3. 定期检查数据库备份状态

常见问题排查

1. Webhook 无法正常工作

   • 验证签名密钥是否正确
   • 检查生产环境 URL 是否与 Stripe 配置一致
   • 确认网络设置未阻止请求

2. 数据库连接问题

   • 检查 Fly.io 的 Postgres 附加组件状态
   • 验证数据库连接字符串配置

3. 支付流程异常

   • 确保 Stripe API 密钥对应正确的环境（生产/测试）
   • 验证监听事件配置完整

结语

通过本文的详细指导，您应该已经成功将 Stripe-Stack 项目部署到生产环境。这套模板提供了完整的 SaaS 应用基础架构，包括用户认证、订阅管理和支付处理等核心功能。部署只是开始，建议进一步探索 Fly.io 的扩展功能和性能优化选项，以构建更健壮的生产级应用。

stripe-stack A Stripe focused Remix Stack that integrates User Subscriptions, Authentication and Testing. Driven by Prisma ORM. Deploys to Fly.io 项目地址: https://gitcode.com/gh_mirrors/st/stripe-stack