n8n 中文文档

队列模式

您可以根据需要以不同模式运行 n8n。队列模式提供最佳的可扩展性。

提示

二进制数据存储

在队列模式下,除非你配置了其他存储模式,否则 n8n 默认将二进制数据存储在数据库中。如果你的许可证包含相应的外部存储选项,可以使用 AWS S3 或 Azure Blob Storage。如果你使用文件系统存储,所有处理二进制数据的主实例、worker 和 webhook 处理器都必须能在相同的配置路径下访问同一个共享卷。详情请参阅处理二进制数据。

工作原理

在队列模式下运行时,需要设置多个 n8n 实例:一个主实例接收工作流信息(例如触发器),worker 实例负责执行工作流。

每个 worker 都是自己的 Node.js 实例,以 main 模式运行,但由于高 IOPS(每秒输入输出操作)能够处理多个同时的工作流执行。

通过使用 worker 实例并在队列模式下运行,您可以根据需要扩展 n8n(通过添加 worker)和缩减(通过删除 worker)来处理工作负载。

这是流程:

  1. 主 n8n 实例处理定时器和 webhook 调用,生成(但不运行)工作流执行。
  2. 它将执行 ID 传递给消息代理 Redis,该代理维护待处理执行的队列,并允许下一个可用的 worker 选择它们。
  3. 池中的 worker 从 Redis 中选择消息。
  4. worker 使用执行 ID 从数据库获取工作流信息。
  5. 完成工作流执行后,worker:
    • 将结果写入数据库。
    • 向 Redis 发布,说明执行已完成。
  6. Redis 通知主实例。

显示主 n8n 实例、Redis、n8n worker 和 n8n 数据库之间数据流的图表

配置worker

Worker 是执行实际工作的 n8n 实例。它们从主 n8n 进程接收有关必须执行的工作流的信息,执行工作流并在每次执行完成后更新状态。

提示

Per-process event log files 每个进程的事件日志文件

如果您的工作进程共享可写文件系统,请为每个工作进程提供唯一的事件日志路径。有关详细信息,请参阅每进程事件日志文件。

设置加密密钥

n8n 在首次启动时自动生成加密密钥。如果需要,您还可以使用 环境变量 提供自己的自定义密钥。

主 n8n 实例的加密密钥必须与所有 worker 和 Webhook 处理器节点共享,确保这些节点能够访问数据库中存储的凭据。

在配置文件中或通过设置相应的环境变量为每个工作节点设置加密密钥:

export N8N_ENCRYPTION_KEY=<main_instance_encryption_key>

设置执行模式

提示

Database considerations 数据库注意事项

有关 n8n 支持的 PostgreSQL 版本,请参阅支持的 PostgreSQL 版本。

不建议使用 SQLite 数据库并将 n8n 的执行模式设置为 queue。

使用以下命令在主实例和任何 worker 上将环境变量 EXECUTIONS_MODE 设置为 queue。

export EXECUTIONS_MODE=queue

或者,您可以在配置文件中将executions.mode设置为queue。

启动Redis

提示

Running Redis on a separate machine 在单独的机器上运行 Redis

您可以在单独的计算机上运行 Redis,只需确保 n8n 实例可以访问它即可。

要在 Docker 容器中运行 Redis,请按照以下说明操作:

运行以下命令启动 Redis 实例:

docker run --name some-redis -p 6379:6379  -d redis

默认情况下,Redis 在 localhost 的端口 6379 上运行,没有密码。根据您的 Redis 配置,为主 n8n 进程设置以下配置。这些将允许 n8n 与 Redis 交互。

使用配置文件 使用环境变量 描述
queue.bull.redis.host:localhost QUEUE_BULL_REDIS_HOST=localhost 默认情况下,Redis 在 localhost 上运行。
queue.bull.redis.port:6379 QUEUE_BULL_REDIS_PORT=6379 默认端口是 6379。如果 Redis 在不同端口上运行,请配置该值。

您还可以设置以下可选配置:

使用配置文件 使用环境变量 描述
queue.bull.redis.username:USERNAME QUEUE_BULL_REDIS_USERNAME 默认情况下,Redis 不需要用户名。如果您使用特定用户,请配置此变量。
queue.bull.redis.password:PASSWORD QUEUE_BULL_REDIS_PASSWORD 默认情况下,Redis 不需要密码。如果您使用密码,请配置此变量。
queue.bull.redis.db:0 QUEUE_BULL_REDIS_DB 默认值是 0。如果您更改此值,请更新配置。
queue.bull.redis.timeoutThreshold:10000ms QUEUE_BULL_REDIS_TIMEOUT_THRESHOLD 告诉 n8n 如果 Redis 不可用,在退出之前应该等待多长时间。默认值是 10000(毫秒)。
queue.bull.gracefulShutdownTimeout:30 N8N_GRACEFUL_SHUTDOWN_TIMEOUT worker 在终止进程之前完成执行作业的优雅关闭超时。默认值是 30 秒。

现在您可以启动 n8n 实例,它将连接到您的 Redis 实例。

启动 worker

通过从根目录运行以下命令启动 worker 进程:

./packages/cli/bin/n8n worker

如果您使用 Docker,请使用以下命令:

docker run --name n8n-queue -p 5679:5678 n8nio/n8n worker

您可以设置多个工作进程。确保所有工作进程都能访问 Redis 和 n8n 数据库。

工作服务器

每个工作进程运行一个服务器,暴露可选端点:

  • /healthz:如果启用 QUEUE_HEALTH_CHECK_ACTIVE 环境变量,则返回工作线程是否已启动
  • /healthz/readiness:如果启用QUEUE_HEALTH_CHECK_ACTIVE环境变量,则返回worker的DB和Redis连接是否准备就绪
  • 凭证覆盖端点
  • /metrics

提示

Customizing health check endpoints 自定义健康检查端点

您可以使用 N8N_ENDPOINT_HEALTH 环境变量自定义运行状况检查端点路径。

查看正在运行的 worker

提示

Feature availability 功能可用性

可查看运行中的 worker 的版本包括:

  • Self-hosted: Enterprise

在 n8n Cloud Enterprise 上,请联系 n8n启用此功能。

在 n8n 中选择 Settings 设置 > Workers 工作进程,即可查看正在运行的 worker 及其性能指标。

使用队列运行 n8n

使用队列运行 n8n 时,所有生产工作流执行都由 worker 进程处理。对于 Webhook,这意味着 HTTP 请求由 main/webhook 进程接收,但实际的工作流执行会被交给 worker,这可能会增加一些开销和延迟。

Redis 充当消息代理,数据库持久化数据,因此需要访问两者。不支持在 SQLite 上使用此设置运行分布式系统。

提示

Migrate data 迁移数据

如果要将数据从一个数据库迁移到另一个数据库,可以使用导出和导入命令。请参阅 n8n 的 CLI 命令 文档以了解如何使用这些命令。

Webhook 处理器

提示

Keep in mind 请记住

Webhook 进程依赖于 Redis,也需要设置 EXECUTIONS_MODE 环境变量。按照上面的配置工作人员 部分设置 Webhook 处理器节点。

Webhook 处理器是 n8n 中另一层扩展。配置 webhook 处理器是可选的,允许您扩展传入的 webhook 请求。

此方法允许 n8n 处理大量并行请求。您只需要相应地添加更多 webhook 进程和 worker。webhook 进程将在同一端口(默认:5678)上监听请求。在容器或单独的机器中运行这些进程,并使用负载均衡系统相应地路由请求。

n8n 不建议将主进程添加到负载均衡器池中。如果您将主进程添加到池中,它将接收请求并可能承受重负载。这将导致编辑、查看和与 n8n UI 交互的性能下降。

您可以通过从根目录执行以下命令启动 webhook 处理器:

./packages/cli/bin/n8n webhook

如果您使用 Docker,请使用以下命令:

docker run --name n8n-queue -p 5679:5678 -e "EXECUTIONS_MODE=queue" n8nio/n8n webhook

配置 webhook URL

要配置您的 webhook URL,请在运行主 n8n 实例的机器上执行以下命令:

export N8N_WEBHOOK_URL=https://your-webhook-url.com

N8N_WEBHOOK_URL 从 n8n 2.30.0 起可用;更早的版本请使用 WEBHOOK_URL。

您也可以在配置文件中设置此值。

配置负载均衡器

使用多个 webhook 进程时,您需要负载均衡器来路由请求。如果您为 n8n 实例和 webhook 使用相同的域名,可以设置负载均衡器按以下方式路由请求:

  • 将 Webhook 触发器重定向到 Webhook 服务器池。需要考虑的路径:
  • /webhook/*:Webhook触发节点端点
  • /webhook-waiting/*:执行“发送和等待”操作的节点(例如 Slack 节点)使用的人机交互 Webhook 端点。
  • 所有其他路径(n8n 内部 API、编辑器的静态文件等)应路由到主进程

注意: 手动工作流执行的默认 URL 是 /webhook-test/*。确保这些 URL 路由到您的主进程。

您可以在配置文件 endpoints.webhook 中更改此路径,或使用 N8N_ENDPOINT_WEBHOOK 环境变量。如果您更改这些,请相应地更新您的负载均衡器。

在主进程中禁用 webhook 处理(可选)

您有 webhook 处理器来执行工作流。您可以在主进程中禁用 webhook 处理。这将确保在 webhook 处理器中执行所有 webhook 执行。在配置文件中将 endpoints.disableProductionWebhooksOnMainProcess 设置为 true,这样 n8n 就不会在主进程上处理 webhook 请求。

或者,您可以使用以下命令:

export N8N_DISABLE_PRODUCTION_MAIN_PROCESS=true

在主进程中禁用 webhook 进程时,运行主进程但不要将其添加到负载均衡器的 webhook 池中。

大型 Webhook 响应

在队列模式下,worker 负责运行工作流执行,但发送 Webhook 请求的客户端仍会与主实例或 Webhook 实例保持连接。Respond to Webhook 节点生成的响应会由 worker 通过队列消息发回该实例,因此 Redis 会在消息传输期间保存完整响应。

N8N_WEBHOOK_RESPONSE_RELAY_SIZE_MAX 用于设置该消息的大小上限(以 MiB 为单位),默认值为 64。Redis 会保留正在传输的响应的多个副本,因此每个传输中的响应应预留约为该值 1.5 倍的 Redis 内存。如果未启用转存,超过上限的响应会导致节点执行失败。

从 worker 返回的 MCP Trigger 工作流工具结果也受同一上限约束。工具结果无法转存,因此结果过大时,MCP 客户端会收到一条注明该上限的工具错误。

将大型响应正文转存至存储

提示

自 n8n 2.34.0 起可用

在 worker 上设置 N8N_WEBHOOK_RESPONSE_RELAY_OFFLOAD_ENABLED=true,即可将超过上限的响应正文存入二进制数据存储,而不是让节点执行失败。此时队列消息只携带引用,主实例会从存储中将正文流式传输给客户端,并在响应送达后删除已存储的正文。

转存功能需要所有实例都能读取的存储。除 default 外,其他模式都会持久化数据,因此请将 N8N_DEFAULT_BINARY_DATA_MODE 设置为 filesystem、database、s3 或 azure:

export N8N_WEBHOOK_RESPONSE_RELAY_SIZE_MAX=64
export N8N_WEBHOOK_RESPONSE_RELAY_OFFLOAD_ENABLED=true
export N8N_DEFAULT_BINARY_DATA_MODE=s3

对于大型响应,n8n 建议使用 s3 或 azure。两者都会流式传输正文,因此主实例每次只需在内存中保存一个数据块。有关配置方法,请参阅外部存储。在 database 模式下,主实例会先将整个正文加载到内存,再发送给客户端,而且响应会经过主数据库。在 filesystem 模式下,每个实例都必须挂载同一个磁盘,n8n 不建议采用这种方式。default 模式会将二进制数据保存在内存中,因此主实例没有可读取的持久化数据;超过上限的响应仍会导致节点执行失败。

n8n 只会转存响应正文。响应的其余部分(即响应头和状态码)仍按同一上限计算,因此即使启用了转存,仅响应头就超过上限的响应仍会失败。

升级期间启用转存

只有运行 n8n 2.34.0 或更高版本的主实例和 Webhook 实例才能完整处理转存后的正文。旧版本实例仍可将正文流式传输给客户端,但会发送状态码 200 而不是响应本身的状态码,并且不会删除已存储的正文。请先升级所有主实例和 Webhook 实例,再在 worker 上设置 N8N_WEBHOOK_RESPONSE_RELAY_OFFLOAD_ENABLED。未设置此变量的 worker 会以内联方式发送所有响应,并在响应超过上限时失败。

排查大型 Webhook 响应问题

错误 原因 解决方法
The response is too large to be sent back from the worker,且错误中提到 N8N_WEBHOOK_RESPONSE_RELAY_OFFLOAD_ENABLED worker 未启用转存。 在 worker 上设置该变量,或提高 N8N_WEBHOOK_RESPONSE_RELAY_SIZE_MAX。
The response is too large to be sent back from the worker,且错误中提到 N8N_DEFAULT_BINARY_DATA_MODE 二进制数据存储将数据保存在内存中,因此没有可用于转存的位置。 将 N8N_DEFAULT_BINARY_DATA_MODE 设置为 filesystem、database、s3 或 azure。
The response is too large for the binary-data store to hold database 模式因自身的大小限制拒绝存储该正文。 提高 N8N_BINARY_DATA_DATABASE_MAX_FILE_SIZE,最高不得超过数据库列可容纳的 1 GB;或者切换到本身不设大小上限的 filesystem、s3 或 azure。
The stored webhook response body could not be read 主实例无法读取 worker 写入的存储。 让所有实例指向同一存储。在 filesystem 模式下,每个实例都必须挂载同一个磁盘,n8n 不建议采用这种方式。

配置worker并发

您可以使用 concurrency 标志定义 worker 可以并行运行的作业数。默认为 10。要更改它:

n8n worker --concurrency=5

并发和扩展建议

n8n 建议为您的 worker 实例设置并发为 5 或更高。使用大量 worker 设置低并发值可能会耗尽数据库的连接池,导致处理延迟和失败。

多主设置

提示

Feature availability 功能可用性

多主设置适用于:

  • Self-hosted: Enterprise

n8n Cloud 不支持此功能。

在队列模式下,您可以运行多个 main 进程以实现高可用性。

在单模式设置中,main 进程执行两组任务:

  • 常规任务,如运行 API、服务 UI 和监听 webhook,以及
  • 最多一次任务,如运行非 HTTP 触发器(定时器、轮询器和持久连接如 RabbitMQ 和 IMAP)以及清理执行和二进制数据。

在多主设置中,有两种 main 进程:

  • 追随者,运行常规任务,以及
  • 领导者,运行常规和最多一次任务。

领导者指定

在多主设置中,所有主实例对用户透明地处理领导过程。如果当前领导者变得不可用,例如因为它崩溃或其事件循环变得太忙,其他追随者可以接管。如果以前的领导者再次响应,它就成为追随者。

配置多主设置

要在多主设置中部署 n8n,请确保:

  • 所有 main 进程都在队列模式下运行并连接到 Postgres 和 Redis。
  • 所有 main 和 worker 进程都运行相同版本的 n8n。
  • 所有 main 进程都将环境变量 N8N_MULTI_MAIN_SETUP_ENABLED 设置为 true。
  • 所有 main 进程都在启用会话持久性(粘性会话)的负载均衡器后面运行。

如果两个或多个 n8n 部署共享同一个 Redis,请为每个部署设置不同的 N8N_REDIS_KEY_PREFIX 值,并在同一部署的每个 main 和 worker 进程上使用相同的值。这样可以将领导者选举和实例之间的消息限制在同一个部署内。在 n8n 2.3.0 之前,该前缀不适用于 pub/sub 频道,因此请为每个部署使用单独的 Redis。

如果需要,您可以调整领导者密钥选项:

使用配置文件 使用环境变量 描述
multiMainSetup.ttl:10 N8N_MULTI_MAIN_SETUP_KEY_TTL=10 多主设置中领导者密钥的生存时间(秒)。
multiMainSetup.interval:3 N8N_MULTI_MAIN_SETUP_CHECK_INTERVAL=3 多主设置中领导者检查的间隔(秒)。

有关 AWS 上的参考多 main 部署,包括 worker 自动扩缩和 Redis 高可用,请参阅在 AWS 上扩展并以高可用运行。

相关资源

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