Scheduler 环境变量
这些环境变量用于配置持久调度器。持久调度器会从数据库支持的队列运行基于时间的工作流,而不是从每个实例的内存中运行。从 n8n 2.45.0 起,持久调度器默认启用。要了解它会带来哪些变化、工作原理以及如何使用内存调度器,请参阅持久调度器。
使用 N8N_METRICS_INCLUDE_SCHEDULER_METRICS 和 N8N_METRICS_SCHEDULER_INTERVAL 开启持久调度器的 Prometheus 指标。这两个变量与其他指标变量一起列在端点页面。有关每项指标的含义,请参阅持久调度器可观测性。
提示
功能可用性
持久调度器从 n8n 2.36.0 起可用。从 n8n 2.32.0 到 2.35.x 的较早版本将其作为 Preview 功能提供。
启用调度器
| 变量 | 类型 | 默认值 | 描述 |
|---|---|---|---|
N8N_SCHEDULER_ENABLED |
Boolean | true |
是否使用持久调度器。从 n8n 2.45.0 起默认为 true(更早版本默认为 false)。设为 false 可使用内存调度器。要接管 Schedule Trigger 节点,还需启用同样默认开启的 N8N_USE_WORKFLOW_PUBLICATION_SERVICE。该变量从 n8n 2.45.0 起已弃用:未来版本将移除此变量和内存调度器。 |
N8N_SCHEDULER_POLL_TRIGGERS_ENABLED |
Boolean | false |
是否让持久调度器同时接管轮询触发器(带有 Poll Times 轮询时间参数的触发器节点)。需要启用 N8N_SCHEDULER_ENABLED 和 N8N_USE_WORKFLOW_PUBLICATION_SERVICE。自 n8n 2.33.0 起可用。 |
N8N_SCHEDULER_SYSTEM_TASKS_ENABLED |
Boolean | false |
是否由持久调度器运行 n8n 的内部维护任务,而不是使用领导者主实例的进程内计时器。需要启用 N8N_SCHEDULER_ENABLED。请为每个主实例上的这两个变量设置相同的值,并在每个主实例上运行相同的 n8n 版本。任何一个关闭了其中任一标志的主实例,都会在启动时移除这些任务的持久调度计划。请从 n8n 2.45.0 起使用此变量;这是首个让所有系统任务都在持久调度器上运行的版本。请参阅系统任务。 |
n8n 2.45.0 移除了 N8N_ENV_FEAT_SKIP_DURABLE_SCHEDULER 和 Skip Durable Scheduler 跳过持久调度器节点设置。要让所有 Schedule Trigger 节点使用内存调度器,请设置 N8N_SCHEDULER_ENABLED=false 并重启 n8n。请参阅使用内存调度器。
警告
轮询触发器支持尚未完全稳定。除非准备密切监控轮询工作流,否则请勿在生产环境中启用 N8N_SCHEDULER_POLL_TRIGGERS_ENABLED:检查执行列表是否存在缺失或重复运行,并启用调度器指标来监控调度延迟、重试和死信(请参阅持久调度器可观测性)。这不会影响已经稳定的 Schedule Trigger 支持。
轮询触发器
控制带 Poll Times 轮询时间参数的触发器节点(例如 Google Sheets Trigger 或 Airtable Trigger)如何存储游标、游标记录节点已经读取到的位置,以及单次轮询最长可运行的时间。要通过持久调度器运行这些节点,请启用“启用调度器”表中的 N8N_SCHEDULER_POLL_TRIGGERS_ENABLED。请参阅轮询触发器。
| 变量 | 类型 | 默认值 | 描述 |
|---|---|---|---|
N8N_POLLER_DURABLE_CURSORS_ENABLED |
Boolean | false |
是否将轮询触发器节点的游标存储在专用数据库表中,并与轮询产生的执行在同一事务中提交,使轮询中途崩溃时不会丢失或重复数据。自 n8n 2.36.0 起可用。从 n8n 2.37.0 起,需要启用 N8N_SCHEDULER_ENABLED、N8N_SCHEDULER_POLL_TRIGGERS_ENABLED 和 N8N_USE_WORKFLOW_PUBLICATION_SERVICE。请参阅持久轮询游标。 |
N8N_SCHEDULER_POLL_TIMEOUT |
Number | 45 |
单次轮询在 n8n 放弃前可运行的时长(秒)。放弃的轮询不会记录任何内容:游标保持不变,下一次轮询会覆盖相同范围,因此不会丢失数据。持续超时的轮询会计为失败,n8n 会以逐渐延长的间隔重新轮询。请将此超时设为小于 N8N_SCHEDULER_LEASE_DURATION 的值;超时计时器从轮询实际开始后才启动,因此如果允许轮询运行完整租约时长,另一实例可能会接管仍在运行的任务。超时达到租约时长时,n8n 会在启动时发出警告。必须大于 0。自 n8n 2.37.0 起可用。 |
物化
控制调度器提前多久、以及以多高频率将即将到来的运行记录到数据库。
| 变量 | 类型 | 默认值 | 描述 |
|---|---|---|---|
N8N_SCHEDULER_MATERIALIZATION_WINDOW |
Number | 60 |
调度器提前多长时间记录即将到来的运行,单位为秒。窗口越大,越多运行会被提前提交(停机恢复能力更强,但数据库写入/清理略多)。必须大于 0。 |
N8N_SCHEDULER_MATERIALIZATION_INTERVAL |
Number | 10 |
调度器每隔多少秒扫描已启用的调度计划,并记录落在窗口内的运行。必须大于 0。 |
N8N_SCHEDULER_MATERIALIZATION_TIMEOUT |
Number | 60 |
单次扫描最多可以运行多长时间,单位为秒;超过后会放弃并在下一个间隔重试。用于防止扫描卡在慢数据库上。必须大于 0。 |
执行
控制调度器启动到期运行的频率,以及如何声明每次运行以确保只有一个实例执行它。
| 变量 | 类型 | 默认值 | 描述 |
|---|---|---|---|
N8N_SCHEDULER_EXECUTOR_INTERVAL |
Number | 5 |
调度器每隔多少秒检查即将到期的已记录运行。每次检查会声明下一个间隔内到期的运行,并使用精确计时器保留它们,因此运行会在计划时刻启动,而不是跟随轮询节奏。该间隔限制调度器拾取新启用或已编辑调度计划所需的时间。必须大于 0。 |
N8N_SCHEDULER_EXECUTOR_TIMEOUT |
Number | 60 |
单次到期运行检查最多可以运行多长时间,单位为秒;超过后会放弃并在下一个间隔重试。必须大于 0。 |
N8N_SCHEDULER_LEASE_DURATION |
Number | 60 |
某个实例拾取运行后,对该运行持有独占声明的时长,单位为秒,这样其他实例不会启动同一运行。如果实例在完成前停止,声明会在这么久之后过期,另一个实例可以接管。请让它明显长于一次运行启动所需的时间:太短可能导致重复运行,太长会延迟崩溃后的恢复。必须大于 0。 |
N8N_SCHEDULER_CLAIM_BATCH_SIZE |
Number | 100 |
单次声明最多从队列中取出的运行数。较大的批次能更快清空积压,但会在单次 tick 中把更多工作交给同一个实例。必须大于 0。 |
恢复
控制 reaper。它会释放某个实例已声明但从未完成的运行,让其他实例可以接手。
| 变量 | 类型 | 默认值 | 描述 |
|---|---|---|---|
N8N_SCHEDULER_REAPER_INTERVAL |
Number | 30 |
调度器每隔多少秒查找实例已声明但从未完成的运行(例如崩溃或关闭后),并让它们重新可用。必须大于 0。 |
N8N_SCHEDULER_REAPER_BATCH_SIZE |
Number | 100 |
单次 reaper pass 最多回收的过期声明运行数。较大的批次能更快恢复积压,但会在单次 pass 中把更多工作交给同一个实例。必须大于 0。 |
N8N_SCHEDULER_REAPER_TIMEOUT |
Number | 60 |
单次恢复 pass 最多可以运行多长时间,单位为秒;超过后会放弃并在下一个间隔重试。必须大于 0。 |
N8N_SCHEDULER_MAX_ATTEMPTS |
Number | 5 |
计划运行在 n8n 放弃并将其放入 dead-letter 前,可以被回收(例如崩溃后)或因错误重试的次数。对于容易发生实例重启或 transient errors 的基础设施,可提高该值;如果希望更快放弃并继续,可降低该值。必须大于 0。 |
保留
控制调度器将已完成运行作为历史保留多久,以及多久删除旧运行。n8n 会比正常完成的运行更久保留失败和错过的运行,以便你有时间发现并调试问题。
| 变量 | 类型 | 默认值 | 描述 |
|---|---|---|---|
N8N_SCHEDULER_RETENTION |
Number | 86400 |
调度器在删除之前保留正常完成运行(成功或取消)的时长,单位为秒。默认一天。提高它可保留更多历史,降低它可更快回收数据库空间。必须大于 0。 |
N8N_SCHEDULER_FAILED_RETENTION |
Number | 604800 |
调度器在删除之前保留异常运行(失败或错过)的时长,单位为秒。默认七天。请让它长于 N8N_SCHEDULER_RETENTION,以便有时间调试;如果设置得更低,调度器会发出警告。必须大于 0。 |
N8N_SCHEDULER_RETENTION_INTERVAL |
Number | 3600 |
调度器每隔多少秒删除超过保留窗口的已完成运行。默认一小时。必须大于 0。 |
N8N_SCHEDULER_RETENTION_TIMEOUT |
Number | 300 |
单次清理 pass 最多可以运行多长时间,单位为秒;超过后会放弃并在下一个间隔重试。默认五分钟。必须大于 0。 |
所有者协调
控制调度器回收那些所有者不再存在的调度,例如不再发布的工作流。它会立即停止这些调度,并在宽限期后将其删除。请参阅持久调度器的工作原理。
提示
功能可用性
所有者协调从 n8n 2.39.0 起可用。
| 变量 | 类型 | 默认值 | 描述 |
|---|---|---|---|
N8N_SCHEDULER_OWNER_RECONCILIATION_ENABLED |
Boolean | true |
是否让调度器定期检查每个调度的所有者是否仍然存在,并回收所有者缺失的调度。关闭后,这些调度会继续保留。 |
N8N_SCHEDULER_OWNER_RECONCILIATION_INTERVAL |
Number | 900 |
扫描每隔多少秒运行一次。默认 15 分钟。它只是安全兜底,不是常规清理路径,因此较长间隔也可以。必须大于 0。 |
N8N_SCHEDULER_OWNER_RECONCILIATION_TIMEOUT |
Number | 300 |
单次扫描最多可以运行多长时间,单位为秒;超过后会放弃并在下一个间隔重试。默认五分钟。必须大于 0。 |
N8N_SCHEDULER_OWNER_RECONCILIATION_BATCH_SIZE |
Number | 500 |
扫描每个数据库查询检查多少个所有者。更大的批次能用更少的查询完成扫描;更小的批次能让每个查询更轻。必须在 1 到 1000 之间。 |
N8N_SCHEDULER_OWNER_QUARANTINE_GRACE |
Number | 86400 |
扫描在删除已停止的调度前会保留它多久,单位为秒。默认一天。调度会在扫描找到它时立即停止触发;该值只会延后删除。必须大于 0。 |
N8N_SCHEDULER_OWNER_SETTLE_PERIOD |
Number | 300 |
调度在被扫描前必须存在多久,单位为秒。默认五分钟。n8n 可能会在其所有者之前稍晚写入调度,因此这一项可避免扫描把新建调度误判为被遗弃的调度。必须大于 0。 |
跨实例协调
控制调度器如何重叠后台 pass,并在多个实例之间分散数据库负载。
| 变量 | 类型 | 默认值 | 描述 |
|---|---|---|---|
N8N_SCHEDULER_MAX_CONCURRENT_PASSES |
Number | 10 |
当数据库支持重叠 pass(PostgreSQL)时,同一实例上同类后台 pass 最多可同时运行多少个。如果某个 pass 到期时已达到上限,n8n 会跳过它。在 SQLite 上,pass 从不重叠,因此此设置无效。必须大于 0。 |
N8N_SCHEDULER_JITTER_RATIO |
Number | 0.1 |
添加到每个周期性 pass 时间上的小随机变化,以间隔的比例表示。使用 0.1 时,设置为每 10 秒运行一次的 pass 实际会每 9 到 11 秒运行一次。这会分散同时启动的实例(例如滚动部署期间)发出的数据库查询。设置为 0 可使用精确间隔,也可增大该值以更均匀地分散负载。必须至少为 0 且小于 1。 |
调度计划行为
| 变量 | 类型 | 默认值 | 描述 |
|---|---|---|---|
N8N_SCHEDULER_TRIGGER_NODE_MODE |
Enum (legacy, new) |
new |
Schedule Trigger 节点的「每 N 秒」和「每 N 分钟」调度计划如何触发。new 从工作流发布时刻开始,以稳定的 N 间隔触发。从 n8n 2.45.0 起,它是默认值。legacy 保持与内存调度器一致的时钟对齐时间,并且是更早版本的默认值。只影响秒和分钟间隔。该变量从 n8n 2.45.0 起已弃用:未来版本将移除此变量和 legacy 模式。请参阅 Schedule Trigger 触发时序。 |
N8N_SCHEDULER_MISFIRE_GRACE |
Number | 60 |
允许运行延迟多少秒仍视为准时。超过此时间的运行会被视为错过,其触发器的失火策略会决定如何处理该运行及其后面的积压运行。这是调度计划继承的默认值;从 n8n 2.36.0 起,Schedule Trigger 节点可改为设置自己的宽限期。该值应大于 N8N_SCHEDULER_EXECUTOR_INTERVAL,并至少等于 N8N_SCHEDULER_MATERIALIZATION_WINDOW;如果不满足,n8n 会在启动时发出警告。上限为 30 天。请参阅 失火策略。自 n8n 2.34.0 起可用。 |