企业官网建设流程全解析

Cal.diy 怎么配置 Stripe 集成启用付费事件：API Key、重定向地址与 Webhook

【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy

在 Cal.diy 的自托管部署中，付费功能（付费事件、应用商店支付）由内置的 Stripe 支付集成提供。要启用它，需要在 Stripe 仪表盘中完成三件事：保存 API Key、配置 OAuth 重定向地址、添加 Webhook，再把对应的值写入实例的环境变量。配置完成后，Stripe 应用会进入“已安装”状态，支付功能随之可用。

以下步骤基于官方 Stripe 设置文档 与故障排查文档。整个配置针对一个已经部署并可访问的 Cal.diy 实例进行。

准备条件

• 一个已在运行的 Cal.diy 实例，可以编辑根目录.env（以及.env.appStore）文件并能重启服务。
• 一个 Stripe 账户。如果先在测试环境验证，请在 Stripe 仪表盘右上角打开Test-Mode开关，后续步骤使用测试密钥。
• 实例的外部可访问 URL。下文的重定向地址与 Webhook 地址都要使用它，且应与NEXT_PUBLIC_WEBAPP_URL一致，末尾不带斜杠（如https://cal.yourdomain.com）。

配置 Stripe API Key

在 Stripe 仪表盘的API Keys页面获取两个 token，写入环境变量文件：

# .env（根目录） STRIPE_PRIVATE_KEY=sk_test_... # .env.appStore；如果只维护单个 .env，也可以直接写在 .env 中 NEXT_PUBLIC_STRIPE_PUBLIC_KEY=pk_test_...

对应关系按 token 前缀区分：pk_...（公钥）写入NEXT_PUBLIC_STRIPE_PUBLIC_KEY，sk_...（私钥）写入STRIPE_PRIVATE_KEY。

这些变量分布在两个文件中，配置时容易遗漏：STRIPE_PRIVATE_KEY、STRIPE_CLIENT_ID、STRIPE_WEBHOOK_SECRET写入根.env；NEXT_PUBLIC_STRIPE_PUBLIC_KEY写入.env.appStore（单文件配置时写入根.env）。

启用 OAuth 并添加重定向地址

Stripe 集成通过 OAuth 连接你的账户，需要两处配置：

1. 打开 Stripe 仪表盘的Connect设置页，启用OAuth for Standard Accounts。
2. 添加 OAuth 重定向 URL，其中<Cal.diy URL>替换为你的实例外部地址：

<Cal.diy URL>/api/integrations/stripepayment/callback

例如实例地址为https://cal.yourdomain.com时，重定向地址就是https://cal.yourdomain.com/api/integrations/stripepayment/callback。

然后复制 Connect 设置页显示的 Client ID（以ca_...开头），写入根.env：

# .env STRIPE_CLIENT_ID=ca_...

添加 Webhook

1. 打开 Stripe 仪表盘的Webhooks页面，添加以下 URL 作为已连接应用的 Webhook 地址，<Cal.diy URL>同样替换为你的实例外部地址：

<Cal.diy URL>/api/integrations/stripepayment/webhook

2. 勾选 Webhook 需要接收的事件：官方文档要求选择全部payment_intent和setup_intent事件。应用源码中的旧 README（stripepayment/README.md）只提到payment_intent，按现行文档把两类事件都选中即可覆盖旧说明。
3. 复制 Webhook 编辑页显示的密钥（以whsec_...开头），写入根.env：

# .env STRIPE_WEBHOOK_SECRET=whsec_...

应用配置并连接 Stripe 账户

修改环境变量后需要重启服务才能生效。Docker 部署可执行以下命令（会重启整个 stack 的所有容器）：

docker compose down && docker compose up -d

在 Cal.diy 的应用管理入口发起与 Stripe 账户的连接。浏览器会跳转到 Stripe OAuth 授权页，授权完成后由回调接口/api/integrations/stripepayment/callback处理授权码，然后页面重定向回/apps/installed/payment支付应用页（见 回调处理逻辑）。如果 OAuth 授权失败，页面 URL 会带上error=stripe_oauth_failed参数（见 setup 页逻辑）。

验证结果

文档层面有两个判断依据：

1. 应用显示为已安装。Stripe 应用的安装状态由三个环境变量STRIPE_CLIENT_ID、NEXT_PUBLIC_STRIPE_PUBLIC_KEY、STRIPE_PRIVATE_KEY同时非空决定（判断逻辑见 _metadata.ts）。任一缺失或为空，应用就会被标记为“未安装”，支付功能不可用。
2. 使用支付功能时不再报错。故障排查文档描述的配置缺失症状是：付费事件、应用商店支付等功能不可用，或尝试使用时出现报错。此时按上一节核对三个变量是否写入了正确文件、值是否完整。

注意事项与限制

• 如果不需要支付功能，这些变量可以留空，应用照常运行，只是 Stripe 相关功能保持禁用。
• Docker 部署时，API v2 服务（/api/v2/...）还要求根.env中同时存在STRIPE_API_KEY和STRIPE_WEBHOOK_SECRET，否则服务启动时报Missing environment variable并退出。STRIPE_API_KEY是 API 侧与STRIPE_PRIVATE_KEY对应的变量，两个变量被不同服务消费；如果 API 端不启用 Stripe，可以填占位值，但变量必须存在。详见故障排查文档的 “API v2 Service Not Starting” 一节。
• 实例 URL 直接决定回调与 Webhook 地址是否可达，注意两点：不要带末尾斜杠；Docker 部署中NEXT_PUBLIC_WEBAPP_URL是构建期变量，修改后需要重新构建镜像。
• 测试模式下使用测试密钥（pk_test_.../sk_test_...），即故障排查文档示例所使用的形式。

【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy