n8n 中文文档

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 起可用。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。