n8n 2.47.0 推出 Public API rate limits

n8n 现在允许管理员限制每个公共 API 请求的 API 密钥可发出的请求数量，因此单个失控工作流会触及其 API 密钥的限制，而不会阻塞其他团队。

从 n8n 2.47.0 开始，所有套餐均可使用速率限制，适用于 n8n Cloud 和自托管版本。它可与幂等键配合使用（自 n8n 2.45.0 起提供），使重试更加安全，确保调用你实例的客户端知道何时应降低请求速度以及何时重试。

多个团队共享同一实例时，速率限制为何重要

当多个团队在同一个 n8n 实例上构建工作流时，公共 API 会同时成为许多人的依赖。不同团队构建的 API 客户端会调用它，n8n 工作流也会通过 n8n 节点或 HTTP Request 节点调用其自身实例的 API。

这些工作流可能会在短时间内产生大量流量。一个节点会为每个项目运行一次，因此包含 1,000 个项目的列表会同时发送约 1,000 个请求。如果没有按密钥设置控制，这样的工作流可能会阻塞实例上的所有其他用户；一些客户一直在 n8n 周围自行构建速率限制器来防范这种情况。

速率限制让管理员无需构建单独的速率限制器，就能在 n8n 内部获得这种保护。每个团队都有足够的空间进行构建，而当某个工作流失控运行时，实例仍能受到保护。

n8n 中公共 API 速率限制的作用

速率限制为每个 API 密钥可向你的实例发送的流量设置上限，因此繁忙或失控的客户端会触及自身的限制，而不是阻塞其他团队，同时实例也能免受失控自动化的影响。

• 你可以决定可接受的流量大小。读取和写入分别设置限制，并且同时支持跨所有端点和按端点设置，因此你可以为写入设置比读取更严格的限制。每个 API 密钥在这些限制范围内都有自己的计数。
• 客户端达到限制时会收到清晰的信号。n8n 会返回包含 Retry-After 和速率限制标头的 429 响应，因此客户端可以知道何时重试以及还剩多少请求，并可在达到限制前降低请求速度。
• 你可以从合理的默认值开始，并逐步进行调整。每项限制都会从默认值开始；你在设置页面或通过 API 所做的更改会立即生效，无需重启。
• 扩展部署时保护仍然有效。在多主节点设置中，每个主节点都会通过 Redis 共享每个 API 密钥的同一计数，因此达到限制的 API 密钥会在窗口结束前从每个主节点收到 429 响应。

如何在 n8n 中启用速率限制

速率限制默认处于关闭状态，因此你可以自行决定何时启用。你可以根据 n8n 的运行方式，通过以下三种方式中的任意一种进行配置：

• 在设置页面中：前往 Settings > Policies > Public API Limits，开启 Enable API key rate limits，调整限制和时间窗口，然后选择 Enable limits。
• 通过公共 API：使用 GET /api/v1/settings/rate-limits读取当前设置，使用 PUT /api/v1/settings/rate-limits 替换这些设置。该 API 密钥需要 securitySettings:manage 作用域。
• 在自托管版本中使用环境变量：将 N8N_PUBLIC_API_RATE_LIMIT_ENABLED 设置为 true 并重启 n8n，然后使用 N8N_PUBLIC_API_RATE_LIMIT_* 变量更改单独的限制和时间窗口。

设置页面或通过 API 进行的更改会立即生效，无需重启。环境变量会覆盖这两者，设置页面会将该字段显示为锁定状态，因此该值会保持不变，直到你更改变量并重启 n8n。

如何让 API 客户端和工作流不超出限制

API 客户端可以读取速率限制标头，以了解何时放慢速度以及何时重试。以下四个习惯有助于它们不超出限制：

• 重试前等待 Retry-After 中的秒数。
• 增加最多 5 秒的小幅随机延迟，让不同客户端的重试请求分散开来。
• 监控 X-RateLimit-Remaining，当它接近 0 时放慢速度，直到 X-RateLimit-Reset 中的时间到达。
• 分散处理大型任务，在整个时间窗口内以稳定速率发送请求。

调用自身 n8n 实例 API 的工作流还需要额外执行一步。n8n 节点和 HTTP Request 节点会为每个项目发送一个请求，并在收到 429 时失败，因此请为节点添加 Batching（n8n 节点位于 Request Options 中，HTTP Request 节点位于 Options 中），并设置 Items per Batch 和 Batch Interval (ms)。每秒发送 5 个项目意味着每分钟发送 300 个请求，低于所有默认限制。在这里，Batching 比 Retry On Fail 更有效，后者两次尝试之间最多等待 5 秒，并且经常会在同一个时间窗口内重试。

幂等键如何让重试变得安全

速率限制意味着客户端有时会收到 429 并需要重试，而重试 POST 存在风险：如果第一次请求已经成功，重试可能会创建重复内容。幂等键可以让这些重试变得安全，因此客户端在收到 429 后可以放心地退避并再次尝试。

为公共 API 的 POST 请求发送 Idempotency-Key 标头。如果请求成功，n8n 会将响应存储 12 小时，使用相同密钥和请求正文进行重试时，会获得已存储的响应，而不是再次执行 POST。如果第一次请求失败，n8n 会释放该密钥，因此重试会正常执行。

The API 幂等性文档介绍了密钥格式，以及冲突请求或处理中的请求所对应的响应。

常见问题

哪些请求会计入 n8n 公共 API 速率限制？

只有在 /api/v1 使用 API 密钥的请求才会计入限制。来自 n8n 编辑器的请求不计入。每个 API 密钥都有自己的计数，并且每个密钥都在相同的限制范围内运行。

如何让某个集成比其他集成拥有更大的余量？

在单独的 n8n 实例上运行该集成。同一实例中的每个 API 密钥共享相同的限制，而每个密钥保留自己的计数，因此单独的实例是为某个集成设置不同限制的方式。

如果在请求进行期间更改速率限制，会发生什么？

新限制会立即生效。如果新限制低于某个 API 密钥当前的计数，则该密钥的下一次请求会收到 429，计数会在时间窗口结束时重置。

如何关闭某一种速率限制？

将该限制设置为 0。你可以全局或按端点关闭读取或写入限制，同时保留其他限制。启用速率限制时，至少必须有一个限制大于 0。

为什么我的 n8n 工作流调用 n8n API 时会因 429 错误而失败？

该工作流发送的请求超过了实例允许的速率限制。n8n 节点和 HTTP Request 节点会针对每个项目运行一次，并在收到 429 时失败，因此包含大量项目的列表可能会很快触达限制。为节点添加 Batching，并设置 Items per Batch 和 Batch Interval，使请求速率保持在限制以内。

下一步该做什么

更新到 n8n 2.47.0 或更高版本，在 Settings > Policies > Public API Limits 中启用速率限制，并查看 API 速率限制文档 以获取完整的配置参考。如果你的客户端发送 POST 请求，请同时使用 API 幂等性文档 添加幂等性密钥。