# 防范 API 密钥泄露

API 密钥是用于验证您的集成与 Stripe 连接的凭证。
您负责安全管理几种类型的 [API 密钥](https://docs.stripe.com/keys)，包括绝不应在运行集成外部暴露的**秘密密钥**。
如果未经授权的方获得了您的秘密密钥，他们可能会冒充您的集成进行欺诈活动，可能导致您遭受经济损失、未经授权的付款或账户配置的不必要更改。要了解如何保护您的 Stripe API 密钥，请遵循我们的[管理秘密 API 密钥的最佳实践](https://docs.stripe.com/keys-best-practices)。
为保障企业安全，一旦怀疑 API 密钥可能泄露，您应立即采取行动。
Stripe 知道，获取 Stripe 用户 API 密钥的恶意分子可能会以停用威胁诱使用户启用某些产品。**Stripe 不会因用户未采用 Stripe 产品而停用用户。**参见[常见问题解答](#FAQ)。
## 立即行动
如果您认为集成的秘密 API 密钥已泄露，则应尽快**轮换密钥**。
1. 在管理平台 → 开发人员 → [API 密钥](https://dashboard.stripe.com/apikeys)中**找到被泄露的密钥**。
1. 选择“...”→ **轮换密钥**。此操作将创建一个新密钥，并使泄露的密钥失效。
1. 选择一个足够长的有效期，以便您使用新密钥测试您的集成。
1. **更新集成的后端**以使用新密钥。
1. **确认您的集成能够使用新密钥正常运行**。您可以在新密钥页面点击“...”→ **查看请求日志**，以确认您的集成正在使用该密钥。
1. 选择“...”→ **删除密钥**，**删除泄露的密钥**。删除操作会立即生效。不过，您仍然可以查看已删除密钥的请求日志。
## 密钥轮换后的补救工作
1. 如果您发现不认识的全新 Connect 子账户、未经授权的提现，或是您不认识的外部银行账户，请立即在管理平台中[暂停向其提现](https://docs.stripe.com/connect/pausing-payments-or-payouts-on-connected-accounts)或予以拒绝。
1. [撤销已发送至欺诈银行账户的任何提现](https://docs.stripe.com/connect/payout-reversals)，并将这些银行账户从您的账户中移除。提现撤销不保证一定成功，但您应尽快发起撤销操作，以最大程度提高追回资金的可能性。如需撤销提现方面的帮助，请联系 Stripe 支持团队。
1. 尽快[退还任何欺诈性收款](https://docs.stripe.com/refunds)，以降低争议风险。如果您的 Stripe 余额不足以支付退款金额，您需要向您的[账户](https://docs.stripe.com/get-started/account/add-funds)中[存入资金](https://docs.stripe.com/get-started/account/add-funds)以完成退款。
1. 在 [Workbench](https://dashboard.stripe.com/workbench/logs) 中，检查密钥近期使用情况，查看是否存在异常活动，例如与您的集成功能不匹配的活动模式。
1. 请轮换所有其他密钥和受限密钥，以防不止一个密钥被泄露。
1. 如果在补救过程中发现了新的泄露风险——例如，某个密钥被提交到了代码仓库或嵌入在源代码中——请在修复漏洞后再次轮换您的密钥。您的替换密钥可能以与被替换密钥相同的方式泄露。请重复上述步骤，直到您确信没有真实密钥被泄露为止。
## 安全最佳实践
遵循[管理秘密 API 密钥的最佳实践](https://docs.stripe.com/keys-best-practices)。除了安全地存储和处理密钥外，还应采用纵深防御方法，即使密钥落入恶意行为者手中，也能限制其使用范围和方式。例如：
* **[将您的 API 密钥限制在特定的 IP 地址范围内](https://docs.stripe.com/keys#limit-api-secret-keys-ip-address)**。即使受 IP 地址限制的密钥遭到泄露，也无法在您的环境之外被使用。
* **[使用受限 API 密钥 (RAK) 而非秘密密钥](https://docs.stripe.com/keys-best-practices#limit-access)**。配置多个密钥，每个密钥仅具备其运行所需的特定权限，这可以限制密钥泄露可能造成的损害范围。例如，您的集成系统可以使用不同的 API 密钥分别处理收款和付款操作。如果需要与第三方应用共享 Stripe API 密钥，受限密钥是最佳选择。
常规安全防护措施可以进一步降低恶意行为者获取您的密钥或利用密钥损害您业务的风险。您可以立即采取的做法包括：
* **定期审计 API 密钥用量**。每个 Stripe API 密钥都有对应的请求日志，您可以从中查看异常活动。在 API 密钥列表中，点击密钥菜单中的[查看请求日志](https://docs.stripe.com/keys#view-request-logs)选项。注意检查任何您无法识别的操作，包括异常的费用、退款或 Connect 子账户。如果您的密钥未设置 IP 地址限制，请特别留意来自陌生 IP 地址的事件记录。
* 使用通行密钥或单点登录 (SSO) **保护您的管理平台**，并定期审计您的账户配置。
* 使用具备安全漏洞检测指令的 AI 代码审查工具，在您的代码中查找安全漏洞。
* **保持插件和框架的更新**以降低依赖项带来的供应链风险。
* **在生产系统中禁用调试相关功能**。绝不要在错误信息中显示环境信息（如环境变量的值）。
## 为什么我的密钥被泄露？
Stripe 的安全团队会在互联网上监测是否存在暴露的 Stripe API 密钥。大多数密钥泄露问题都源于少数几种情况。
### 前端环境变量使用不当
现代前端框架会自动将某些环境变量打包到发送给浏览器的文件中。这些特殊变量专用于存储安全且可公开的值（如分析 ID、可发布的密钥），**而不是秘密密钥**。如果您将秘密密钥放入此类变量中，该密钥将被内联到您的 JavaScript 打包文件或初始 HTML 中，任何访问您网站的人都能看到。
切勿将 API 密钥（前缀为 `sk_live_` 或 `rk_live_`）放在框架会打包的变量中。请务必将密钥存储在服务器配置中，确保其永远不会向访问者展示。以下是各主流框架中应避免的做法示例：
* **React，Create React App**：`REACT_APP_STRIPE_SECRET_KEY`—会被访客看到。
* **Vue**：`VUE_APP_STRIPE_SECRET_KEY`
* **Vite**：`VITE_STRIPE_SECRET_KEY`
* **Nuxt**：`NUXT_ENV_STRIPE_SECRET_KEY`
* **Next.js, Vercel SSR**：页面代码中对秘密密钥的_任何_引用都可能出现在初始服务器渲染的 HTML 中。
* **Angular**：`environment.ts` 中的秘密密钥会被打包到供浏览器执行的 JavaScript 中。
请查阅您所用框架关于安全使用秘密密钥的文档，并考虑使用自动化扫描工具，在秘密密钥误用问题影响用户之前及时发现并标记。
### 公共代码存储库
如果您意外将包含`sk_live_…`秘密密钥的`.env`文件或配置文件提交到 GitHub、GitLab 等公共代码仓库，这些密钥很可能会被恶意网络爬虫抓取并在黑客论坛上被再次传播。
### CMS 或插件漏洞（如 WordPress、Joomla 等）
过时或不安全的 WordPress 插件（如 Elementor 或 Contact Form 7）可能允许攻击者读取 `.env`或`wp-config.php`配置文件，或者直接访问您的 SQL 数据库。
### Laravel 配置不当
Laravel 项目通常依赖 `.env` 文件来存储包括 `STRIPE_SECRET_KEY` 在内的敏感配置信息。常见的陷阱包括：
* `.env`文件被遗留在 Web 根目录下且可直接访问 (`https://example.com/.env`)
* **调试模式已启用** (`APP_DEBUG=true`)：错误页面可能会转储环境变量，包括 Stripe 密钥。
* **Ignition 调试面板在生产环境中保持启用状态**：可显示详细的堆栈跟踪和环境数据，包括 Stripe 密钥。
### 移动端应用（Android APK，Apple iOS）
当您将 `sk_live_…` 密钥直接硬编码到应用程序中时，任何下载该应用的人都能读取到它。
## 常见问题解答
### Stripe 是如何找到密钥的？
Stripe 的安全团队会持续监控各类代码仓库、包注册表、网站及论坛中是否泄露了包括 API 密钥在内的客户数据。一旦发现秘密密钥，我们会立即通知其所有者，并可能自动作废该密钥。
### 密钥泄露会带来什么风险？
一旦获得您的密钥，恶意行为者就能执行该密钥所允许的任何操作，包括：
* 创建欺诈性收款或订阅
* 发起退款，包括退给自己
* 访问客户数据
* \** 对于 Connect 平台：**
  * 更改提现收款账户
  * 创建提现
  * 创建 Connect 子账户，在平台及其 Connect 子账户之间转账资金
### 如果 Stripe 自动使我的密钥失效，会发生什么情况？
Stripe 高度确信您的密钥已遭泄露，因此已将其作废以防止滥用，并启动了上述密钥轮换流程。您必须完成该流程：
1. 在管理平台中创建一个新密钥。
1. 更新集成，以使用新密钥。
1. 测试并确认功能。
### 如何保护我的 Connect 子平台免受密钥盗用的风险？
在 Connect 平台上，一旦密钥泄露，攻击者可以利用该密钥创建新的 Connect 子账户、更新提现账户信息，或转移和支付资金。请务必遵循上述最佳实践，确保您的 API 密钥安全无虞。
考虑使用 [Radar 平台版](https://docs.stripe.com/radar/radar-for-platforms) 来监控新账户，并对欺诈评分较高的账户暂停提款。
通过监听 [Connect Webhook](https://docs.stripe.com/connect/webhooks) 来监控您的平台，以便在新账户创建时接收 `account.updated` 事件通知，在打款目的地变更时通过 `account.external_account.updated` 事件了解情况，或在发生新提现时通过 `payout.created` 获取信息。
### 我收到一封邮件，称必须启用某项 Stripe 产品，否则我的 Stripe 账户将被停用。
\**该通知并非来自 Stripe。**Stripe 不会以停用账户相威胁，要求用户使用其产品。您如何集成 Stripe 由您自行决定。
持有您 Stripe 密钥的不法分子无法使用该密钥登录您的 Stripe 管理平台，但他们可能会利用您的密钥攻击您尚未启用的 Stripe 功能。向您发送威胁停用账户的邮件，可能是为间接获取这些功能权限而设的圈套。
Stripe 在所有沟通中均使用明确且易于识别的域名。参见 已验证的 Stripe 域名，了解如何判断一封邮件是否真的来自 Stripe。