队列模式#

¥Queue mode

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

¥You can run n8n in different modes depending on your needs. The queue mode provides the best scalability.

Binary data storage

n8n 不支持在文件系统中使用二进制数据存储的队列模式。如果你的工作流需要在队列模式下持久化二进制数据，则可以使用 S3 外部存储。

¥n8n doesn't support queue mode with binary data storage in filesystem. If your workflows need to persist binary data in queue mode, you can use S3 external storage.

怎么运行的#

¥How it works

在队列模式下运行时，你可以设置多个 n8n 实例，其中一个主实例接收工作流信息（例如触发器），而其他工作实例执行工作流。

¥When running in queue mode, you have multiple n8n instances set up, with one main instance receiving workflow information (such as triggers) and the worker instances performing the executions.

每个工作进程都是一个独立的 Node.js 实例，以 main 模式运行，但由于其高 IOPS（每秒输入/输出操作数），能够处理多个并发工作流执行。

¥Each worker is its own Node.js instance, running in main mode, but able to handle multiple simultaneous workflow executions due to their high IOPS (input-output operations per second).

通过使用工作实例并在队列模式下运行，你可以根据需要扩展 n8n（通过添加工作实例）或缩减（通过移除工作实例）以处理工作负载。

¥By using worker instances and running in queue mode, you can scale n8n up (by adding workers) and down (by removing workers) as needed to handle the workload.

这是流程图：

¥This is the process flow:

主 n8n 实例处理计时器和 Webhook 调用，生成（但不运行）工作流执行。

¥The main n8n instance handles timers and webhook calls, generating (but not running) a workflow execution. 2. 它将执行 ID 传递给消息代理 Redis，该代理维护待执行任务的队列，并允许下一个可用的工作进程来处理这些任务。

¥It passes the execution ID to a message broker, Redis, which maintains the queue of pending executions and allows the next available worker to pick them up. 3. 工作池中的一个工作节点从 Redis 中获取消息。

¥A worker in the pool picks up message from Redis. 4. 工作进程使用执行 ID 从数据库获取工作流信息。

¥The worker uses the execution ID to get workflow information from the database. 5. 工作流执行完成后，工作进程：

¥After completing the workflow execution, the worker:

将结果写入数据库。

¥Writes the results to the database.
向 Redis 发送 POST 请求，表明执行已完成。

¥Posts to Redis, saying that the execution has finished. 6. Redis 会通知主实例。

¥Redis notifies the main instance.

正在配置 worker#

¥Configuring workers

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

¥Workers are n8n instances that do the actual work. They receive information from the main n8n process about the workflows that have to get executed, execute the workflows, and update the status after each execution is complete.

设置加密密钥#

¥Set encryption key

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

¥n8n automatically generates an encryption key upon first startup. You can also provide your own custom key using environment variable if desired.

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

¥The encryption key of the main n8n instance must be shared with all worker and webhooks processor nodes to ensure these worker nodes are able to access credentials stored in the database.

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

¥Set the encryption key for each worker node in a configuration file or by setting the corresponding environment variable:

export N8N_ENCRYPTION_KEY=<main_instance_encryption_key>

设置执行模式#

¥Set executions mode

Database considerations

n8n 建议使用 Postgres 13 或更高版本。不建议将 n8n 的执行模式设置为 queue 并连接到 SQLite 数据库。

¥n8n recommends using Postgres 13+. Running n8n with execution mode set to queue with an SQLite database isn't recommended.

使用以下命令将主实例和所有工作节点上的环境变量 EXECUTIONS_MODE 设置为 queue。

¥Set the environment variable EXECUTIONS_MODE to queue on the main instance and any workers using the following command.

export EXECUTIONS_MODE=queue

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

¥Alternatively, you can set executions.mode to queue in the configuration file.

启动 Redis#

¥Start Redis

Running Redis on a separate machine

你可以在单独的机器上运行 Redis，只需确保 n8n 实例可以访问它即可。

¥You can run Redis on a separate machine, just make sure that it's accessible by the n8n instance.

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

¥To run Redis in a Docker container, follow the instructions below:

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

¥Run the following command to start a Redis instance:

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

默认情况下，Redis 运行在 localhost 服务器的 6379 端口上，无需密码。根据你的 Redis 配置，为 n8n 主进程设置以下配置。这些将允许 n8n 与 Redis 交互。

¥By default, Redis runs on localhost on port 6379 with no password. Based on your Redis configuration, set the following configurations for the main n8n process. These will allow n8n to interact with 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 运行在不同的端口上，请配置该端口的值。

你还可以设置以下可选配置：

¥You can also set the following optional configurations:

使用配置文件	使用环境变量	描述
`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`	为工作进程设置优雅的关闭超时时间，以便在终止进程之前完成作业的执行。默认值为 `30` 秒。

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

¥Now you can start your n8n instance and it will connect to your Redis instance.

启动工作进程#

¥Start workers

你需要启动工作进程，以允许 n8n 执行工作流。如果你想在单独的机器上托管工作节点，请在该机器上安装 n8n，并确保它已连接到你的 Redis 实例和 n8n 数据库。

¥You will need to start worker processes to allow n8n to execute workflows. If you want to host workers on a separate machine, install n8n on the machine and make sure that it's connected to your Redis instance and the n8n database.

从根目录运行以下命令启动工作进程：

¥Start worker processes by running the following command from the root directory:

1	`./packages/cli/bin/n8n worker`

如果你使用 Docker，请使用以下命令：

¥If you're using Docker, use the following command:

1	`docker run --name n8n-queue -p 5679:5678 docker.n8n.io/n8nio/n8n worker`

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

¥You can set up multiple worker processes. Make sure that all the worker processes have access to Redis and the n8n database.

工作服务器#

¥Worker server

每个工作进程运行一个服务器，该服务器公开可选的端点：

¥Each worker process runs a server that exposes optional endpoints:

/healthz：如果启用了 QUEUE_HEALTH_CHECK_ACTIVE 环境变量，则返回工作进程是否已启动

¥/healthz: returns whether the worker is up, if you enable the QUEUE_HEALTH_CHECK_ACTIVE environment variable

/healthz/readiness：如果启用了 QUEUE_HEALTH_CHECK_ACTIVE 环境变量，则返回工作进程的数据库和 Redis 连接是否已准备就绪

¥/healthz/readiness: returns whether worker's DB and Redis connections are ready, if you enable the QUEUE_HEALTH_CHECK_ACTIVE environment variable

凭据覆盖端点

¥credentials overwrite endpoint

/metrics

查看正在运行的工作进程#

¥View running workers

Feature availability

适用于自托管企业版套餐。

¥Available on Self-hosted Enterprise plans.

如果你想在 Cloud Enterprise 上使用此功能，请使用联系 n8n。

¥If you want access to this feature on Cloud Enterprise, contact n8n.

你可以通过选择“设置”>“工作节点”在 n8n 中查看正在运行的工作节点及其性能指标。

¥You can view running workers and their performance metrics in n8n by selecting Settings > Workers.

运行带队列的 n8n#

¥Running n8n with queues

当使用队列运行 n8n 时，所有生产工作流的执行都将由工作进程处理。这意味着即使是 webhook 调用也会被委托给工作进程，这可能会增加一些开销和额外的延迟。

¥When running n8n with queues, all the production workflow executions get processed by worker processes. This means that even the webhook calls get delegated to the worker processes, which might add some overhead and extra latency.

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

¥Redis acts as the message broker, and the database persists data, so access to both is required. Running a distributed system with this setup over SQLite isn't supported.

Migrate data

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

¥If you want to migrate data from one database to another, you can use the Export and Import commands. Refer to the CLI commands for n8n documentation to learn how to use these commands.

Webhook 处理器#

¥Webhook processors

Keep in mind

Webhook 进程依赖于 Redis，并且需要设置 EXECUTIONS_MODE 环境变量。请按照上方配置工作节点部分的步骤设置 Webhook 处理器节点。

¥Webhook processes rely on Redis and need the EXECUTIONS_MODE environment variable set too. Follow the configure the workers section above to setup webhook processor nodes.

Webhook 处理器是 n8n 中另一个可扩展的层。配置 Webhook 处理器是可选的，它允许你扩展传入的 Webhook 请求。

¥Webhook processors are another layer of scaling in n8n. Configuring the webhook processor is optional, and allows you to scale the incoming webhook requests.

此方法允许 n8n 处理大量并行请求。你只需根据需要添加更多 webhook 进程和 worker 即可。Webhook 进程将监听同一端口（默认：5678）上的请求。在容器或独立机器上运行这些进程，并使用负载均衡系统来相应地路由请求。

¥This method allows n8n to process a huge number of parallel requests. All you have to do is add more webhook processes and workers accordingly. The webhook process will listen to requests on the same port (default: 5678). Run these processes in containers or separate machines, and have a load balancing system to route requests accordingly.

n8n 不建议将主进程添加到负载均衡池。如果你将主进程添加到池中，它将接收请求，并可能承受较大的负载。此操作会导致编辑、查看和与 n8n UI 交互时的性能下降。

¥n8n doesn't recommend adding the main process to the load balancer pool. If you add the main process to the pool, it will receive requests and possibly a heavy load. This will result in degraded performance for editing, viewing, and interacting with the n8n UI.

你可以通过在根目录下执行以下命令来启动 Webhook 处理器：

¥You can start the webhook processor by executing the following command from the root directory:

1	`./packages/cli/bin/n8n webhook`

如果你使用 Docker，请使用以下命令：

¥If you're using Docker, use the following command:

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

配置 Webhook URL#

¥Configure webhook URL

要配置 Webhook URL，请在运行主 n8n 实例的计算机上执行以下命令：

¥To configure your webhook URL, execute the following command on the machine running the main n8n instance:

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

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

¥You can also set this value in the configuration file.

配置负载均衡器#

¥Configure load balancer

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

¥When using multiple webhook processes you will need a load balancer to route requests. If you are using the same domain name for your n8n instance and the webhooks, you can set up your load balancer to route requests as follows:

将任何匹配 /webhook/* 的请求重定向到 Webhook 服务器池。

¥Redirect any request that matches /webhook/* to the webhook servers pool

所有其他路径（n8n 内部 API、编辑器的静态文件等）都应路由到主进程。

¥All other paths (the n8n internal API, the static files for the editor, etc.) should get routed to the main process

注意：手动工作流执行的默认 URL 为 /webhook-test/*。请确保这些 URL 指向你的主流程。

¥Note: The default URL for manual workflow executions is /webhook-test/*. Make sure that these URLs route to your main process.

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

¥You can change this path in the configuration file endpoints.webhook or using the N8N_ENDPOINT_WEBHOOK environment variable. If you change these, update your load balancer accordingly.

禁用主进程中的 Webhook 处理（可选）#

¥Disable webhook processing in the main process (optional)

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

¥You have webhook processors to execute the workflows. You can disable the webhook processing in the main process. This will make sure to execute all webhook executions in the webhook processors. In the configuration file set endpoints.disableProductionWebhooksOnMainProcess to true so that n8n doesn't process webhook requests on the main process.

或者，你可以使用以下命令：

¥Alternatively, you can use the following command:

export N8N_DISABLE_PRODUCTION_MAIN_PROCESS=true

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

¥When disabling the webhook process in the main process, run the main process and don't add it to the load balancer's webhook pool.

配置工作进程并发数#

¥Configure worker concurrency

你可以使用 concurrency 标志定义工作进程可以并行运行的作业数。默认值为 10。更改：

¥You can define the number of jobs a worker can run in parallel by using the concurrency flag. It defaults to 10. To change it:

n8n worker --concurrency=5

并发和扩展建议#

¥Concurrency and scaling recommendations

n8n 建议你将工作实例的并发数设置为 5 或更高。使用大量工作进程设置较低的并发值可能会耗尽数据库的连接池，导致处理延迟和故障。

¥n8n recommends setting concurrency to 5 or higher for your worker instances. Setting low concurrency values with a large numbers of workers can exhaust your database's connection pool, leading to processing delays and failures.

多主设置#

¥Multi-main setup

Feature availability

适用于自托管企业版套餐。

¥Available on Self-hosted Enterprise plans.

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

¥In queue mode you can run more than one main process for high availability.

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

¥In a single-mode setup, the main process does two sets of tasks:

常规任务，例如运行 API、提供 UI 和监听 Webhook，以及

¥regular tasks, such as running the API, serving the UI, and listening for webhooks, and

最多一次的任务，例如运行非 HTTP 触发器（定时器、轮询器以及 RabbitMQ 和 IMAP 等持久连接），以及清理执行和二进制数据。

¥at-most-once tasks, such as running non-HTTP triggers (timers, pollers, and persistent connections like RabbitMQ and IMAP), and pruning executions and binary data.

在多主节点设置中，有两种 main 进程：

¥In a multi-main setup, there are two kinds of main processes:

运行常规任务的关注者，以及

¥followers, which run regular tasks, and

领导者，它运行常规任务和最多一次任务。

¥the leader, which runs both regular and at-most-once tasks.

领导者指定#

¥Leader designation

在多主节点设置中，所有主实例都会透明地处理领导过程，用户无法察觉。如果当前领导者不可用，例如由于崩溃或其事件循环过于繁忙，其他追随者可以接管。如果之前的领导者再次响应，它将变为追随者。

¥In a multi-main setup, all main instances handle the leadership process transparently to users. In case the current leader becomes unavailable, for example because it crashed or its event loop became too busy, other followers can take over. If the previous leader becomes responsive again, it becomes a follower.

配置多主节点设置#

¥Configuring multi-main setup

要在多主设置中部署 n8n，请确保：

¥To deploy n8n in multi-main setup, ensure:

所有 main 进程均以队列模式运行，并已连接到 Postgres 和 Redis。

¥All main processes are running in queue mode and are connected to Postgres and Redis.

所有 main 和 worker 进程均运行相同版本的 n8n。

¥All main and worker processes are running the same version of n8n.

所有 main 进程均已将环境变量 N8N_MULTI_MAIN_SETUP_ENABLED 设置为 true。

¥All main processes have set the environment variable N8N_MULTI_MAIN_SETUP_ENABLED to true.

所有 main 进程均在启用了会话持久性（粘性会话）的负载均衡器后运行。

¥All main processes are running behind a load balancer with session persistence (sticky sessions) enabled.

如有必要，你可以调整 leader 键选项：

¥If needed, you can adjust the leader key options:

使用配置文件	使用环境变量	描述
`multiMainSetup.ttl:10`	`N8N_MULTI_MAIN_SETUP_KEY_TTL=10`	多主设置中领导者键的生存时间（以秒为单位）。
`multiMainSetup.interval:3`	`N8N_MULTI_MAIN_SETUP_CHECK_INTERVAL=3`	多主节点设置中领导者检查的间隔（秒）。