快来看,n8n更新了!n8n新功能:公共API速率限制,保障实例上每个团队稳定运行

内容来源:https://blog.n8n.io/new-in-n8n-public-api-rate-limits-that-keep-every-team-on-your-instance-running/
内容总结:
n8n 2.47.0 版本起正式上线公共 API 速率限制功能,所有版本(包括云端版和自托管版)均可使用。管理员现可为每个 API 密钥设定请求上限,避免单一失控工作流触发密钥限额而阻塞其他团队。该功能与自 2.45.0 版本起提供的幂等键机制配合使用,后者可确保重试操作安全,帮助客户端判断何时应降速、何时可重试。
多团队共享实例时速率限制的必要性
当多个团队共用同一个 n8n 实例时,公共 API 成为多方同时依赖的资源。各团队构建的 API 客户端,以及通过 n8n 节点或 HTTP 请求节点调用本实例 API 的工作流,都会产生大量请求。由于节点对每个条目执行一次,包含 1000 个条目的列表会一次性发出约 1000 个请求。若无按密钥的管控,此类工作流可能阻塞实例上的所有其他用户,部分客户此前不得不在 n8n 外围自行搭建限流器。速率限制功能将这一保护能力内置于 n8n 中,无需额外构建限流组件,既为各团队保留构建空间,又能在单个工作流失控时保护实例。
公共 API 速率限制的具体作用
速率限制为每个 API 密钥发往实例的流量设定上限,使繁忙或失控的客户端触发自身限额而非阻塞其他团队。具体包括:
- 管理员可自主决定可接受的流量水平。读操作与写操作分别设限,既支持全端点统一限制,也支持按端点单独限制,因此可对写操作设置更严格的限额。每个 API 密钥在上述限额内独立计数。
- 客户端触及限额时会收到明确信号。n8n 返回 429 响应,并附带 Retry-After 和速率限制相关响应头,告知客户端何时重试、剩余请求数,便于其在触及限额前主动降速。
- 支持从合理默认值起步并逐步调整。所有限额均有默认值,在设置页面或通过 API 所做的修改立即生效,无需重启。
- 横向扩展时保护依然有效。在多主节点部署中,各主节点通过 Redis 共享每个 API 密钥的计数,已达限额的密钥在窗口结束前从任一主节点访问均会收到 429 响应。
启用方式
速率限制默认关闭,由管理员自行决定开启时机,可通过以下三种方式配置:
- 设置页面:进入“设置 > 策略 > 公共 API 限制”,开启“启用 API 密钥速率限制”,调整限额与时间窗口,并选择“启用限制”。
- 通过公共 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_RATELIMIT* 系列变量调整各项限额与窗口。
设置页面或 API 所做的修改立即生效,无需重启。环境变量优先级高于两者,设置页面会将相应字段显示为锁定状态,在修改变量并重启 n8n 前该值保持不变。
客户端与工作流的合规建议
API 客户端可读取速率限制响应头,判断何时降速、何时重试。以下四项习惯有助于保持在限额之内:
- 按 Retry-After 指定的秒数等待后再重试。
- 增加最多 5 秒的随机延迟,使不同客户端的重试请求分散开来。
- 关注 X-RateLimit-Remaining,在其接近 0 时降速,直至 X-RateLimit-Reset 指定的时间。
- 将大型任务分散处理,在时间窗口内以稳定速率发送请求。
调用本实例 n8n API 的工作流需额外一步。n8n 节点和 HTTP 请求节点对每个条目发送一次请求,遇 429 即失败,因此需为节点添加批处理(n8n 节点在“请求选项”中设置,HTTP 请求节点在“选项”中设置),并设定每批条目数和批处理间隔(毫秒)。每秒 5 个条目即每分钟 300 个请求,低于所有默认限额。此处批处理优于“失败时重试”,后者每次重试最多等待 5 秒,且常在同一窗口内重试。
幂等键保障重试安全
速率限制意味着客户端有时会收到 429 并需要重试,而重试 POST 请求存在风险:若首次请求已成功,重试可能造成重复创建。幂等键可使此类重试安全无虞,客户端在收到 429 后可放心退避并重试。
在公共 API 的 POST 请求中携带 Idempotency-Key 请求头。若请求成功,n8n 会保存响应 12 小时,使用相同密钥和请求体重试时将直接返回已保存的响应,不再重复执行 POST。若首次请求失败,n8n 会释放该密钥,重试正常执行。API 幂等性文档中载有密钥格式及冲突或进行中请求的响应说明。
常见问题
- 哪些请求计入 n8n 公共 API 速率限制?仅 /api/v1 下使用 API 密钥的请求计入限额,来自 n8n 编辑器的请求不计入。每个 API 密钥独立计数,所有密钥适用相同限额。
- 如何为某一集成分配更多余量?将该集成部署在独立的 n8n 实例上。同一实例内所有 API 密钥共享相同限额(各自独立计数),因此独立实例是为某一集成设置不同限额的唯一方式。
- 请求进行中修改速率限制会怎样?新限额立即生效。若新限额低于某 API 密钥的当前计数,该密钥的下一个请求将收到 429,计数在窗口结束后重置。
- 如何关闭某一类速率限制?将该限额设为 0。可分别关闭读或写的全局限制或按端点限制,同时保留其他限额。启用速率限制时,至少须有一项限额大于 0。
- 为何工作流调用 n8n API 时因 429 错误失败?该工作流发送的请求超出了实例速率限制。n8n 节点和 HTTP 请求节点对每个条目执行一次,遇 429 即失败,条目列表较大时很快触及限额。为节点添加批处理并设置每批条目数和批处理间隔,即可将请求速率控制在限额之下。
后续步骤
升级至 n8n 2.47.0 或更高版本,在“设置 > 策略 > 公共 API 限制”中开启速率限制,并查阅 API 速率限制文档获取完整配置说明。若客户端发送 POST 请求,建议同步参照 API 幂等性文档添加幂等键。
中文翻译:
n8n 现在允许管理员限制每个 API 密钥可以发起的公共 API 请求数量,这样单个失控的工作流会触发其 API 密钥的限制,而不会阻塞其他团队。
速率限制从 n8n 2.47.0 起在所有版本计划中可用,包括 n8n Cloud 和自托管版本。它与幂等键(自 n8n 2.45.0 起可用)配合使用,后者使重试变得安全,确保调用您实例的客户端知道何时应放慢速度以及何时应重试。
为什么多个团队共享一个实例时速率的限制很重要
当多个团队在同一个 n8n 实例上构建时,公共 API 就成为许多人同时依赖的资源。不同团队构建的 API 客户端会调用它,通过 n8n 节点或 HTTP Request 节点调用自身实例 API 的 n8n 工作流也会调用它。
这些工作流可能在短时间内产生大量流量。一个节点对每个条目运行一次,因此一个包含 1,000 个条目的列表会一次性发送约 1,000 个请求。如果没有按密钥的控制,这样一个工作流就可能阻塞实例上的其他所有人,一些客户已经在 n8n 周围构建了自己的速率限制器来防范这种情况。
速率限制让管理员在 n8n 内部获得这种保护,无需构建单独的速率限制器。每个团队都有空间进行构建,而当某个工作流失控时,实例仍然受到保护。
n8n 中公共 API 速率限制的作用
速率限制为每个 API 密钥可以发送到您实例的流量设定了上限,因此繁忙或失控的客户端会触发自己的限制,而不会阻塞其他团队,实例也能免受失控自动化的影响。
- 您决定多少流量是可接受的。读取和写入有各自的限制,既包括所有端点的总量限制,也包括每个端点的限制,因此您可以为写入设置比读取更严格的限制。每个 API 密钥在这些限制内有自己的计数。
- 客户端在达到限制时会收到明确的信号。n8n 会返回 429 响应,其中包含 Retry-After 和速率限制相关的响应头,这样客户端就知道何时应重试、还剩多少请求,并可以在达到限制之前放慢速度。
- 您可以从合理的默认值开始,并根据需要调整。每个限制都有默认值,您在设置页面或通过 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_RATELIMIT* 变量来修改各个限制和时间窗口。
在设置页面或通过 API 所做的更改会立即生效,无需重启。环境变量会覆盖两者,设置页面会将该字段显示为锁定状态,因此在您修改变量并重启 n8n 之前,该值保持不变。
如何让您的 API 客户端和工作流保持在限制范围内
API 客户端可以读取速率限制响应头,了解何时应放慢速度以及何时应重试。以下四个习惯有助于它们保持在限制范围内:
- 在重试前等待 Retry-After 中指定的秒数。
- 添加最多 5 秒的小幅随机延迟,使来自不同客户端的重试分散开来。
- 关注 X-RateLimit-Remaining,当其接近 0 时放慢速度,直到 X-RateLimit-Reset 指定的时间。
- 将大型任务分散处理,在整个时间窗口内以稳定的速率发送请求。
调用自身实例 n8n API 的工作流需要额外一步。n8n 节点和 HTTP Request 节点对每个条目发送一个请求,并在收到 429 时失败,因此请为节点添加批处理(n8n 节点在 Request Options 中设置,HTTP Request 节点在 Options 中设置),并设置 Items per Batch 和 Batch Interval (ms)。每秒 5 个条目意味着每分钟发送 300 个请求,低于所有默认限制。在这里,批处理比 Retry On Fail 更有效,后者在重试之间最多等待 5 秒,且经常在同一时间窗口内重试。
幂等键如何使重试变得安全
速率限制意味着客户端有时会收到 429 并需要重试,而重试 POST 请求存在风险:如果第一个请求已经成功,重试可能会创建重复数据。幂等键使这些重试变得安全,因此客户端可以在收到 429 后退避,并放心地重试。
在公共 API POST 请求中发送 Idempotency-Key 请求头。如果请求成功,n8n 会将响应存储 12 小时,使用相同密钥和请求体重试时会获得已存储的响应,而不会再次执行 POST。如果第一个请求失败,n8n 会释放该密钥,重试会正常执行。
API 幂等性文档涵盖了密钥格式以及冲突或进行中请求的响应说明。
常见问题
哪些请求会计入 n8n 公共 API 速率限制?
只有使用 API 密钥访问 /api/v1 的请求才会计入限制。来自 n8n 编辑器的请求不计入。每个 API 密钥有自己的计数,所有密钥在相同的限制内运行。
如何给某个集成比其他集成更多的余量?
将该集成运行在单独的 n8n 实例上。一个实例中的每个 API 密钥共享相同的限制,而每个密钥保持自己的计数,因此单独的实例是为某个集成设置不同限制的方法。
如果在请求进行中更改速率限制会发生什么?
新限制立即生效。如果新限制低于某个 API 密钥的当前计数,该密钥的下一个请求将收到 429,计数在时间窗口结束时重置。
如何关闭某一类型的速率限制?
将该限制设为 0。您可以关闭读取或写入限制(全局或按端点),同时保留其他限制。启用速率限制时,至少有一个限制必须大于 0。
为什么我的 n8n 工作流在调用 n8n API 时因 429 错误而失败?
该工作流发送的请求超过了实例速率限制所允许的数量。n8n 节点和 HTTP Request 节点对每个条目运行一次并在收到 429 时失败,因此大量条目列表可能很快达到限制。为节点添加批处理并设置 Items per Batch 和 Batch Interval,使请求速率保持在限制以下。
下一步做什么
更新到 n8n 2.47.0 或更高版本,在 Settings > Policies > Public API Limits 中开启速率限制,并查看 API 速率限制文档以获取完整的配置参考。如果您的客户端发送 POST 请求,请同时参考 API 幂等性文档添加幂等键。
英文来源:
n8n now lets admins cap how many public API requests each API key can make, so a single runaway workflow hits its API key's limit instead of blocking other teams.
Rate limiting is available from n8n 2.47.0 on every plan, on n8n Cloud and self-hosted. It works alongside idempotency keys (available since n8n 2.45.0), which make retries safe, ensuring clients calling your instance know when to slow down and when to retry.
Why rate limits matter when several teams share one instance
When several teams build on the same n8n instance, the public API becomes something many people depend on at once. API clients built by different teams call it, and so do n8n workflows that call the API of their own instance through the n8n node or the HTTP Request node.
Those workflows can create a lot of traffic in a short time. A node runs once for each item, so a list of 1,000 items sends about 1,000 requests at once. Without per-key controls, one workflow like that can block everyone else on the instance, and some customers have been building their own rate limiters around n8n to protect against it.
Rate limits give admins that protection inside n8n, without building a separate rate limiter. Each team gets room to build, and the instance stays protected when one workflow runs away.
What public API rate limits do in n8n
Rate limits put a ceiling on how much traffic each API key can send to your instance, so a busy or runaway client hits its own limit instead of blocking other teams, and the instance stays protected from runaway automation.
- You decide how much traffic is acceptable. Reads and writes get separate limits, both across all endpoints and per endpoint, so you can set a tighter limit on writes than on reads. Each API key has its own count within those limits.
- Clients get a clear signal when they reach a limit. n8n answers with a 429 response that includes Retry-After and rate-limit headers, so clients know when to retry and how many requests they have left, and can slow down before they reach the limit.
- You can start with sensible defaults and adjust as you go. Every limit starts with a default value, and changes you make in the settings page or through the API apply immediately, without a restart.
- The protection holds as you scale out. In multi-main setups, every main shares one count per API key through Redis, so an API key that reaches its limit gets a 429 from every main until the window ends.
How to turn on rate limits in n8n
Rate limiting is off by default, so you decide when to switch it on. You can configure it in whichever of three ways fits how you run n8n: - In the settings page: go to Settings > Policies > Public API Limits, turn on Enable API key rate limits, adjust the limits and windows, and select Enable limits.
- Through the public API: use GET /api/v1/settings/rate-limits to read the current settings and PUT /api/v1/settings/rate-limits to replace them. The API key needs the securitySettings:manage scope.
- With environment variables on self-hosted: set N8N_PUBLIC_API_RATE_LIMIT_ENABLED to true and restart n8n, then use the N8N_PUBLIC_API_RATELIMIT* variables to change individual limits and windows.
Changes in the settings page or through the API apply immediately, without a restart. An environment variable overrides both, and the settings page shows that field as locked, so the value stays fixed until you change the variable and restart n8n.
How to keep your API clients and workflows within the limits
API clients can read the rate-limit headers to know when to slow down and when to retry. Four habits help them stay within the limits: - Wait for the number of seconds in Retry-After before retrying.
- Add a small random delay of up to 5 seconds, so retries from different clients spread out.
- Watch X-RateLimit-Remaining, and slow down as it gets close to 0 until the time in X-RateLimit-Reset.
- Spread large jobs out, sending requests at a steady rate across the window.
Workflows that call the n8n API of their own instance need one extra step. The n8n node and the HTTP Request node send one request per item and fail on a 429, so add Batching to the node (in Request Options for the n8n node, and in Options for the HTTP Request node) and set Items per Batch and Batch Interval (ms). Five items each second sends 300 requests a minute, which is below every default limit. Batching works better here than Retry On Fail, which waits at most 5 seconds between tries and often retries inside the same window.
How idempotency keys make retries safe
Rate limits mean clients will sometimes get a 429 and need to try again, and retrying a POST carries a risk: if the first request already succeeded, the retry can create a duplicate. Idempotency keys make those retries safe, so clients can back off after a 429 and try again with confidence.
Send an Idempotency-Key header with a public API POST request. If the request succeeds, n8n stores the response for 12 hours, and a retry with the same key and body gets that stored response instead of running the POST again. If the first request fails, n8n releases the key, so the retry runs normally.
The API idempotency documentation covers the key format and the responses for conflicting or in-progress requests.
Frequently Asked Questions
What counts toward the n8n public API rate limit?
Only requests that use an API key at /api/v1 count toward the limits. Requests from the n8n editor don't count. Each API key has its own count, and every key works within the same limits.
How do I give one integration more headroom than the others?
Run that integration on a separate n8n instance. Every API key in an instance shares the same limits, while each key keeps its own count, so a separate instance is the way to give one integration different limits.
What happens if I change a rate limit while requests are in progress?
The new limit applies immediately. If the new limit is lower than an API key's current count, that key's next request gets a 429, and the count resets when the window ends.
How do I turn off one type of rate limit?
Set that limit to 0. You can turn off reads or writes, globally or per endpoint, and keep the other limits in place. When rate limiting is enabled, at least one limit must be more than 0.
Why does my n8n workflow fail with a 429 error when it calls the n8n API?
The workflow is sending more requests than the instance's rate limits allow. The n8n node and the HTTP Request node run once for each item and fail on a 429, so a large list of items can reach a limit quickly. Add Batching to the node and set Items per Batch and Batch Interval to keep the request rate under the limits.
What to do next
Update to n8n 2.47.0 or later, turn on rate limits in Settings > Policies > Public API Limits, and check the API rate limits documentation for the full configuration reference. If your clients send POST requests, add idempotency keys at the same time using the API idempotency documentation.
文章标题:快来看,n8n更新了!n8n新功能:公共API速率限制,保障实例上每个团队稳定运行
文章链接:https://news.qimuai.cn/?post=5556
本站文章均为原创,未经授权请勿用于任何商业用途