持久调度器
持久调度器从数据库支持的队列(而不是每个实例的内存)运行基于时间的工作流,例如由 Schedule Trigger 节点触发的工作流。从 n8n 2.45.0 起,它默认启用。本页介绍持久调度器会带来哪些变化、如何配置以及如何使用内存调度器。有关配置环境变量,请参阅调度器环境变量。
提示
功能可用性
持久调度器从 n8n 2.36.0 起可用。n8n 2.32.0 至 2.35.x 将其作为 Preview 功能提供。在 n8n 2.45.0 之前,它默认关闭。从 n8n 2.45.0 起,新实例和现有实例均默认启用,除非你明确将其关闭。
内存调度器与持久调度器的比较
内存调度器在 n8n 2.45.0 之前是默认选项。它会计算活动调度何时触发,并将这些计时器保存在主实例的进程中。这对单实例运行效果很好,但有一些限制:
- 重启会丢失待运行任务。 当实例停止时,其内存计时器也会消失。n8n 会跳过停机期间到期的运行,而不是在恢复后补运行。
- 多个实例需要 leader。 在多主设置中,只有 leader 会触发调度。如果 leader 在不合适的时刻变化,时间可能会偏移。
持久调度器通过将调度移入数据库来解决这两个问题:
- 运行可在重启后保留。 调度器会在每次即将到来的运行到期前将其记录到数据库中。重启不会丢弃它。停机期间已到期的运行只要仍在宽限期内,就会在实例恢复后迟到触发;超过宽限期后,则由触发器的失火策略决定如何处理。
- 每次运行由一个实例声明。 每个主实例共享同一个队列并从中声明运行。任何时刻,每次运行都只由一个实例持有,因此工作会分配到多个主实例,而不是依赖单个 leader。
功能上会发生什么变化
升级到 n8n 2.45.0 或开启持久调度器后,将应用以下行为:
- 时间仍然精确。 与内存调度器一样,运行仍会在计划时刻触发。
- 从 n8n 2.45.0 起,默认使用固定间隔。 “每 N 秒”和“每 N 分钟”调度会从工作流发布时刻开始,以均匀间隔运行。设置
N8N_SCHEDULER_TRIGGER_NODE_MODE=legacy可保留时钟对齐的时序。请参阅Schedule Trigger 触发时序。 - 错过的运行遵循失火策略。 由于调度器会提前记录运行,停机期间错过的运行仍保留在记录中。在宽限期内,它仍会迟到触发;超过宽限期后,触发器的失火策略会决定 n8n 是丢弃它还是执行一次追赶运行。
配置持久调度器
从 n8n 2.45.0 起,N8N_SCHEDULER_ENABLED 默认为 true,因此无需设置。如果你在升级前已将它设为 false,可保留该设置以继续使用内存调度器,或移除该设置并重启 n8n 以使用持久调度器。在 n8n 2.45.0 之前,请将其设为 true 以选择启用。
警告
只有同时开启工作流发布服务时,持久调度器才会接管 Schedule Trigger 节点。N8N_USE_WORKFLOW_PUBLICATION_SERVICE 默认开启。如果将其设为 false,即使 N8N_SCHEDULER_ENABLED 为 true,n8n 也会记录警告,Schedule Trigger 节点仍会使用内存调度器运行。
其余变量仅在调度器开启时生效。默认值适合大多数实例,因此只有在需要调整时间精度、存储或跨实例负载时才修改它们。除非另有说明,所有持续时间均以秒为单位。
使用内存调度器
要保留或恢复内存调度,请设置以下环境变量并重启 n8n:
export N8N_SCHEDULER_ENABLED=false
这适用于实例上的所有 Schedule Trigger 节点和旧版 Cron 节点。在多主实例设置中,请在每个主实例上使用相同的值。
n8n 2.45.0 弃用了内存调度器和 N8N_SCHEDULER_ENABLED。它们仍可作为备用方案,但未来版本将移除它们。如果设置了 N8N_SCHEDULER_ENABLED 或 N8N_SCHEDULER_TRIGGER_NODE_MODE,n8n 会在启动时记录弃用警告。如果值与新默认值一致,请移除该变量。
n8n 2.45.0 还移除了 Skip Durable Scheduler 跳过持久调度器节点设置和 N8N_ENV_FEAT_SKIP_DURABLE_SCHEDULER。现有节点设置不再让单个触发器使用内存调度。请改用 N8N_SCHEDULER_ENABLED=false 切换整个实例。
轮询触发器和系统任务
轮询触发器(带 Poll Times 轮询时间参数的触发器节点,例如 Google Sheets Trigger 或 Airtable Trigger)仍使用内存调度器,除非还通过 N8N_SCHEDULER_POLL_TRIGGERS_ENABLED 选择启用;该变量从 n8n 2.33.0 起可用。轮询触发器支持尚未完全稳定,因此除非准备密切监控轮询工作流,否则请在生产环境中将其保持关闭。要了解轮询在持久调度器下的行为,以及 n8n 建议与 N8N_SCHEDULER_POLL_TRIGGERS_ENABLED 一起启用的持久轮询游标,请参阅轮询触发器。
n8n 的内部维护任务也会继续使用进程内计时器,除非通过 N8N_SCHEDULER_SYSTEM_TASKS_ENABLED 选择启用持久调度器;该变量自 n8n 2.45.0 起可用。请参阅在持久调度器上运行系统任务。
持久调度器的工作原理
这些术语使环境变量更容易理解:
- 调度(Schedule):重复规则,例如 Schedule Trigger 节点的“每 15 分钟”设置。调度器会在数据库中存储每个调度。
- 运行(Run):某个调度在特定时间的一次触发。调度器会提前将即将到来的运行记录为单独的行。
调度器会让每次运行经过五个阶段,每个阶段都有自己的环境变量:
- 具体化。 调度器扫描活动调度并记录即将到来的运行(在具体化窗口内),在到期前将运行提交到数据库。如果具体化捕获运行时已经超过失火宽限期,则由调度的失火策略处理,而不是按原样记录。
- 执行。 调度器最多提前一个检查间隔声明每个已记录的运行,确保没有其他实例占用它,然后在计划时刻启动工作流。
- 恢复。 如果实例声明运行但在完成前停止(例如崩溃),reaper 会释放该运行,以便其他实例接续处理。
- 保留。 调度器会将完成的运行保留一段时间作为近期历史记录,然后删除它们以保持表较小。
- 所有者协调。 每个调度都有一个所有者,例如创建它的工作流。调度器会定期检查每个所有者是否仍然存在,并回收所有者不再存在的调度。请参阅所有者协调环境变量。
在多个实例之间,每个主实例都会运行这五个阶段。声明机制保证安全:每次运行只能由一个实例声明,因此在所有实例上运行这些循环会分担负载,而不会重复工作。
失火策略
运行超过宽限期后,就会被视为错过。宽限期默认为 N8N_SCHEDULER_MISFIRE_GRACE(默认一分钟);从 n8n 2.36.0 起,在该版本或更高版本中添加的 Schedule Trigger 节点可以使用 Missed Execution Grace Period (Seconds) 错过执行宽限期(秒)选项设置自己的宽限期。如果节点设置的宽限期低于实例推导出的最小值(根据 N8N_SCHEDULER_EXECUTOR_INTERVAL 和 N8N_SCHEDULER_MATERIALIZATION_WINDOW 计算),n8n 会将其提高到该最小值;宽限期上限为 30 天。
如何处理错过的运行及其积压取决于触发器的失火策略:
- Don't Run Missed Executions 不运行错过的执行(默认)。n8n 会完全丢弃错过运行的积压,并从下一次运行恢复调度计划。这与内存调度器一致,后者从不迟到运行错过的事件。
- Run the Most Recent Missed Execution 运行最近一次错过的执行。 积压会合并为该节点的一次追赶运行,时间取所有触发规则最近一次错过的时间,然后恢复调度计划。
- Run the Most Recent Missed Execution Per Rule 按规则运行最近一次错过的执行。 与上一策略类似,但每条触发规则会独立追赶,因此具有多条触发规则的节点可以为每条规则各触发一次追赶运行。
从 n8n 2.36.0 起,在该版本或更高版本中添加的 Schedule Trigger 节点可通过 If Execution Is Missed 如果错过执行选项选择策略;请参阅 Schedule Trigger 节点文档。轮询触发器节点(例如 Google Sheets Trigger 或 Airtable Trigger)始终跳过错过的运行,并从下一次计划运行恢复轮询。
无论采用哪种策略,调度计划的时钟都会越过积压:没有策略会逐次重放积压。一次性调度计划没有下一次事件可供恢复,因此追赶策略仍会迟到运行,而跳过则会永久丢弃它。
提示
选择宽限期时,请从下限开始:让 N8N_SCHEDULER_MISFIRE_GRACE 大于 N8N_SCHEDULER_EXECUTOR_INTERVAL,并至少等于 N8N_SCHEDULER_MATERIALIZATION_WINDOW(不满足时 n8n 会在启动时发出警告)。在此下限之上,请将其设置为一次运行在被视为错过之前可以容忍的最长延迟,例如实例重启或 leader 变更所需的时间。使用默认值时,应设置为 60 秒或更长。
调度触发时序(偏差)
在持久调度器下,大多数 Schedule Trigger 节点调度计划的触发方式与内存调度器相同。上述实例级变化仍然适用:错过的运行遵循失火策略,每次运行由一个实例声明。除此之外,两种节奏会在特定情况下以不同于内存调度器的方式触发:
- “每 N 秒”和“每 N 分钟”。
N8N_SCHEDULER_TRIGGER_NODE_MODE控制这些调度的触发方式。这是该设置唯一会影响的节奏。 - “每 N 小时”、“天”、“周”或“月”。 在日常使用中,无论采用哪种模式,这些调度都与以前一样触发。持久调度器能比内存调度器更正确地处理少见的日历边缘情况,例如闰年、一年中的第 53 周和夏令时转换(内存调度器可能会偏移一个周期)。
N8N_SCHEDULER_TRIGGER_NODE_MODE 有两个值:
new(从 n8n 2.45.0 起为默认值):运行按固定秒数间隔触发,从工作流发布时刻开始计算,而不是从时钟边界开始。例如,在一分钟的第 7 秒发布工作流后,“每 30 秒”运行会在 :37、下一分钟的 :07 等时刻触发。即使跨越分钟边界,也始终保持所设置的间隔,因此“每 7 秒”不会漂移。legacy(在 n8n 2.45.0 之前为默认值):与内存调度器相同,在时钟边界触发。“每 30 秒”会在每分钟的 :00 和 :30 触发。该模式在每分钟开始时重新计数,因此不能整除 60 的间隔会在分钟边界产生不均匀间隙。“每 7 秒”会在 :00、:07、:14 等时刻触发,直到 :56,然后回到 :00,此时间隙为 4 秒而不是 7 秒。
要保留时钟对齐的时序,请设置 N8N_SCHEDULER_TRIGGER_NODE_MODE=legacy。这不会关闭持久调度器。n8n 2.45.0 弃用了 legacy 模式和此变量,未来版本将移除它们。如果已将该变量设为 new,可以将其移除。
提示
N8N_SCHEDULER_TRIGGER_NODE_MODE 仅影响“每 N 秒”和“每 N 分钟”计划。所有其他节奏(包括原始 cron 表达式)在任一值下都会以相同的方式触发。
轮询触发器
启用 N8N_SCHEDULER_POLL_TRIGGERS_ENABLED 后,轮询触发器的每个轮询时间都会作为独立的持久调度计划运行:轮询像其他运行一样能在重启后保留,并分散到多个实例。轮询触发器有三种特有行为:
- 始终跳过错过的轮询。 一次轮询会获取自上次运行以来的所有新内容,因此追赶轮询会重复相同的获取。请参阅失火策略。
- 轮询偶尔可能运行两次。 调度器保证每个已分派的轮询至少运行一次,而不是只运行一次。例如,当一个实例停滞而另一个实例接管时,轮询可能重复。请启用持久轮询游标,确保重复轮询不会丢失或重复处理数据项。
- 运行时间过长的轮询会被放弃。 从 n8n 2.37.0 起,运行时间超过
N8N_SCHEDULER_POLL_TIMEOUT(默认 45 秒)的轮询会被放弃。n8n 会停止等待且不记录任何内容:游标保持不变,下一次轮询会覆盖相同范围,因此不会丢失数据。这可以防止轮询卡在永不响应的服务上。持续超时的轮询会计为失败,n8n 会以逐渐延长的间隔重新轮询,而不是持续请求无法跟上的服务。请将超时设为小于N8N_SCHEDULER_LEASE_DURATION的值,确保另一实例接管任务时,被放弃的轮询不会仍在运行。超时达到租约时长时,n8n 会在启动时发出警告。
持久轮询游标
每个轮询触发器节点都会维护一个游标:它记录节点已经读取到的位置,使每次轮询只获取新内容。默认情况下,n8n 将游标存储在工作流静态数据中,并与轮询产生的执行分开保存。如果实例在两次保存之间崩溃,或两个实例同时轮询同一节点,游标和执行就会不同步,导致工作流跳过数据项或处理两次。
从 n8n 2.36.0 起,将 N8N_POLLER_DURABLE_CURSORS_ENABLED 设置为 true 可避免此问题。n8n 随后会把每个节点的游标保存在独立数据库表中,并与执行一同保存,因此一次轮询要么完全发生,要么完全未发生。只要通过持久调度器运行轮询触发器,n8n 就建议启用该选项。
从 n8n 2.37.0 起,只有同时启用 N8N_SCHEDULER_ENABLED、N8N_SCHEDULER_POLL_TRIGGERS_ENABLED 和 N8N_USE_WORKFLOW_PUBLICATION_SERVICE,该设置才会生效。如果任一设置关闭,n8n 会在启动时记录警告,游标继续保存在工作流静态数据中。
启用后会发生以下情况:
- 切换过程安全。 节点的下一次轮询会将当前游标迁移到新表,因此不会重复获取或跳过任何内容。
- n8n 会先检查工作流(仅 n8n 2.36)。 启动时,n8n 会扫描每个已启用工作流的已发布版本,查找重复或缺失的触发器节点 ID。如果发现问题或无法扫描某个工作流,它会关闭持久轮询游标,让整个实例的轮询触发器继续使用内存调度器,并记录错误,列出受影响的工作流及修复方法。
- 关闭后不会撤销迁移。 游标会保留在其专用表中,只是不再与执行一起保存。
- 可以监控游标保存。 使用
N8N_METRICS_INCLUDE_POLL_TRIGGER_METRICS启用轮询触发器指标。
警告
请同时启用 N8N_POLLER_DURABLE_CURSORS_ENABLED 和 N8N_SCHEDULER_POLL_TRIGGERS_ENABLED。通过持久调度器运行轮询触发器、但仍将游标保存在工作流静态数据中,可能导致数据项丢失或重复。
可观测性
持久调度器会在 /metrics 端点公开 Prometheus 指标,帮助判断运行是否准时启动、是否成功以及队列是否在清空。使用两个环境变量启用:
export N8N_METRICS=true
export N8N_METRICS_INCLUDE_SCHEDULER_METRICS=true
只有主实例会公开调度器指标。要设置端点本身,请参阅启用 Prometheus 指标。要绘制指标图表,请参阅使用 Grafana 可视化指标;n8n 发布了现成的持久调度器仪表板,并为每个面板提供建议操作。
n8n 自身的维护任务有一组专用指标,可通过 N8N_METRICS_INCLUDE_SYSTEM_TASK_METRICS 启用。无论这些任务通过持久调度器还是内存计时器运行,该指标组都会涵盖它们。请参阅系统任务。
指标名称中的两个词需要说明。task 是调度器记录到数据库中的一次运行。occurrence 是调度器根据调度计划计算出的一次运行;物化过程将其记录后,它就成为 task。大多数序列都带有 task_type 标签,其值为 workflow:schedule-trigger 或 workflow:poll-trigger,可据此区分 Schedule Trigger 节点和轮询触发器。
队列健康状况
以下四个仪表是每次抓取时新读取的队列快照。它们描述整个集群,因此每个主实例报告的值相同:请使用 max 或 avg 聚合,绝不能使用 sum。
| 指标 | 含义 |
|---|---|
n8n_scheduler_tasks_pending |
等待中的已记录运行数。该值会随调度计划数量变化,因此应观察趋势,而不是绝对值。 |
n8n_scheduler_tasks_due |
已经过期但尚未启动的已记录运行数。应保持接近零。 |
n8n_scheduler_tasks_running |
当前由整个集群中的实例声明并正在运行的运行数。 |
n8n_scheduler_oldest_pending_age_seconds |
最早到期运行的落后时间。这是最清晰的积压信号:0 表示没有到期等待的运行;持续增长表示调度器无法跟上。 |
每次抓取只会查询数据库一次,获取所有四个仪表。N8N_METRICS_SCHEDULER_INTERVAL(默认 20 秒)会缓存该查询,因此较短的抓取间隔不会频繁冲击调度器读取的表。
运行吞吐量和故障
计数器和直方图记录每个主实例自身的工作,因此应在所有主实例之间求和以获得集群总数。
| 指标 | 类型 | 含义 |
|---|---|---|
n8n_scheduler_tasks_dispatched_total |
Counter | 调度器交给处理程序启动的运行数,即调度吞吐量。 |
n8n_scheduler_tasks_completed_total |
Counter | 达到最终结果的运行数,按 result 标签的 success 或 failure 分组。故障比例上升通常指向工作流或数据库,而不是调度器。 |
n8n_scheduler_task_retries_total |
Counter | 调度器排队等待再次尝试的失败运行数。 |
n8n_scheduler_tasks_reclaimed_total |
Counter | reaper 从已声明运行但停止的实例中回收的运行数。持续增加表示实例在运行中崩溃或丢失声明。 |
n8n_scheduler_tasks_lease_lost_total |
Counter | 在另一个实例已回收其声明后才完成的运行数,因此同一运行可能执行了两次。按 task_type 分组。对于轮询触发器,这是跨实例重叠信号;发生这种情况时,持久轮询游标会保持游标正确。 |
n8n_scheduler_tasks_dead_lettered_total |
Counter | 尝试 N8N_SCHEDULER_MAX_ATTEMPTS 次后 n8n 放弃的运行数。每次增加都表示某次运行未发生,应将其作为告警。 |
n8n_scheduler_dispatch_lag_seconds |
Histogram | 每次运行从到期到启动的等待时间。应观察高百分位数:p99 与 p50 的差距增大,表示部分运行停滞,而不是整个队列变慢。 |
后台 pass
以下计数器覆盖保持队列运行的五个阶段。当某个阶段停止工作时,它们最有用。
| 指标 | 类型 | 含义 |
|---|---|---|
n8n_scheduler_occurrences_materialized_total |
Counter | 调度器写入数据库的即将到期运行数。有已发布调度计划时该值仍为零,表示物化已停止。 |
n8n_scheduler_jobs_deferred_total |
Counter | 物化无法规划且将重试的调度计划数,例如含有无法读取的表达式。 |
n8n_scheduler_occurrences_misfired_total |
Counter | 失火策略丢弃而未记录的到期运行数,按 task_type 和丢弃它们的 policy 分组。停机后出现峰值属正常现象;持续增长表示运行经常迟到。 |
n8n_scheduler_occurrences_retired_total |
Counter | 因追赶运行取代而被调度器丢弃的已记录运行数。 |
n8n_scheduler_occurrences_missed_total |
Counter | 超过截止时间仍未被声明、并由 reaper 标记为错过的已记录运行数。 |
n8n_scheduler_tasks_pruned_total |
Counter | 保留阶段删除的已完成运行数。如果从不增长,调度器表会不断增大。 |
n8n_scheduler_jobs_quarantined_total |
Counter | 有多少调度因所有者不再存在而被所有者协调停止。自 n8n 2.39.0 起可用。 |
n8n_scheduler_orphaned_jobs_deleted_total |
Counter | 有多少已停止的调度在所有者持续缺失并超过隔离宽限后被所有者协调删除。自 n8n 2.39.0 起可用。 |
n8n_scheduler_jobs_revived_total |
Counter | 有多少已停止的调度因所有者后来证明仍然存在而被所有者协调恢复。自 n8n 2.39.0 起可用。 |
轮询触发器指标
轮询触发器有自己的一组指标,由独立的 N8N_METRICS_INCLUDE_POLL_TRIGGER_METRICS 开关控制,与上述调度器指标无关:
export N8N_METRICS=true
export N8N_METRICS_INCLUDE_POLL_TRIGGER_METRICS=true
只有主实例会公开这些指标。它们来自轮询引擎本身,而不是调度器,因此即使持久调度器没有分派轮询也会生效。与调度器计数器一样,它们记录每个主实例自身的轮询:应在所有主实例之间求和以获得集群总数。n8n 为它们发布了现成的轮询触发器仪表板。
| 指标 | 类型 | 含义 |
|---|---|---|
n8n_poll_trigger_duration_seconds |
Histogram | 每次轮询的持续时间,按 node_type 和 status 分组。随着时间逐渐变慢的轮询会接近自身间隔;当持续时间超过该间隔时,轮询开始重叠。 |
n8n_poll_trigger_errors_total |
Counter | 抛出错误的轮询数,按 node_type 和 kind 标签的 auth、rate_limited 或 thrown 分组。auth 表示凭据损坏,rate_limited 表示轮询速度超过服务限制。 |
n8n_poll_trigger_overlapping_ticks_total |
Counter | 同一进程中相同节点的上一次轮询仍在运行时启动的新轮询数。跨实例重叠会改为显示在 n8n_scheduler_tasks_lease_lost_total 中。 |
n8n_poll_trigger_timeouts_total |
Counter | 持久调度器因轮询运行时间超过 N8N_SCHEDULER_POLL_TIMEOUT 而放弃的轮询数,按 node_type 分组。放弃的轮询不会记录任何内容,下一次轮询会覆盖相同窗口。持续增长表示被轮询服务的响应速度低于超时设置。只有持久调度器会放弃轮询,因此使用内存调度器时该值保持为零。自 n8n 2.37.0 起可用。 |
n8n_poll_trigger_cursor_commits_total |
Counter | 已完成的游标保存数,按 operation(with_execution 或 cursor_only)和 result 分组。result 为 fence_rejected 表示过时轮询已丢失声明,且不允许推进游标,这说明保护机制正在发挥作用。result 为 failure 表示保存本身失败。 |
n8n_poll_trigger_cursor_commit_duration_seconds |
Histogram | 每次游标保存所需的时间,使用相同的 operation 和 result 标签。 |
这两个游标指标跟踪专用游标表。启用持久轮询游标后,节点会从首次轮询起开始报告。关闭该设置后仍会继续报告,因为游标仍保留在该表中。
以上所有名称都假定使用默认的 n8n_ 指标前缀。如果设置了 N8N_METRICS_PREFIX,请替换为自己的前缀。