SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

n8n 队列模式:单台 VPS 何时需要 worker

了解 n8n 队列模式是否适合单台 VPS,涵盖 1 个 vCPU 不适用的原因、Redis 与 Postgres 要求,以及 n8n 2.41.6、Redis 7.4.11 和 Postgres 17.11 的固定版本 Compose 配置。

n8n 队列模式的变化

n8n 队列模式会将一个 n8n 实例的工作分配到多个进程。主实例仍负责提供编辑器并接收 Webhook,也会触发定时任务。它不再自行执行生产任务,而是将每个任务放入 Redis 队列,再由独立的 worker 进程从队列中取出并执行。在单台 VPS 上,只有当单个 n8n 进程成为瓶颈时,这种模式才有明显收益。大多数小型实例在普通模式下设置并发上限,效果更好。

只需设置一个变量 EXECUTIONS_MODE=queue,并将其配置到每个 n8n 进程上,即可启用该模式。本指南中的其他配置都基于这一变化。worker 必须使用与主实例相同的数据库和加密密钥。这是因为 worker 会从 Postgres 加载工作流及其凭据,并且必须解密这些内容。队列模式不支持 SQLite,因此必须使用 Postgres。Redis 会成为一个需要运行并加以保护的新服务。

本指南先帮助您做出选择,然后使用固定版本构建 Compose 服务栈。截至 2026 年 10 月,版本固定为 n8n 2.41.6、Redis 7.4.11 和 Postgres 17.11。如果您还没有运行 n8n,请先从 在 VPS 上通过 HTTPS 运行单个 n8n 实例 开始。等您有明确理由进行拆分后,再回到这里。

单个 VPS 何时适合使用 n8n worker?

n8n 运行在 Node.js 上。一个 Node.js 进程会在一个线程上执行 JavaScript,因此一个 n8n 进程最多只能让一个 CPU 核心持续满负载处理工作流逻辑。在常规模式下,编辑器、Webhook 监听器、触发器和所有执行任务共享同一个进程。队列模式会运行多个进程。这样,多个 CPU 核心可以同时执行任务,并且某个 worker 中的慢速执行不会拖慢编辑器。

在单个 VPS 上,出现以下情况时,队列模式通常值得使用:

  • n8n 容器在 docker stats 中长期接近一个核心的 100% 使用率,而其他核心保持空闲。
  • 运行大型工作流时,编辑器和 Webhook 响应变慢。处理大型 JSON,以及在 Code 节点中遍历数千个项目,都是常见原因。
  • 某个大型执行任务耗尽内存,导致整个实例(包括编辑器)重启。队列模式可以将生产执行任务的内存与主实例分开。
  • 您至少有 2 个 vCPU(虚拟 CPU 核心),并且有足够的空闲 RAM 再运行一个完整的 n8n 进程。

以下情况则应继续使用常规模式:

  • VPS 只有 1 个 vCPU。worker 会与主实例共享这一个核心,因此只会增加内存消耗,不会提升 CPU 性能。
  • 工作流大部分时间都在等待外部 API。等待不会占用 CPU,一个 Node.js 进程已经可以同时处理大量等待中的请求。
  • 您遇到的是短时流量突增,而不是持续负载。使用并发上限即可处理突发流量,无需新增服务。
  • 您无法提供额外内存。每个 worker 都是一个完整的 n8n 进程,并有自己的基础内存占用,因此启用队列模式后,总内存占用一定会增加。

本指南不提供具体的内存数值,因为实际需求取决于您的工作流和已安装的节点。请使用 docker stats --no-stream 在您自己的 VPS 上进行测量,分别在更改前和更改后测量一次。

常规模式的替代方案:限制并发数

如果实例在流量突发期间崩溃,请先尝试设置并发上限,再考虑增加工作进程。N8N_CONCURRENCY_PRODUCTION_LIMIT限制同时运行的生产执行数量。默认情况下,该功能处于禁用状态。达到上限后,新执行会等待,然后按 FIFO(先进先出)顺序运行。

services:
  n8n:
    environment:
      N8N_CONCURRENCY_PRODUCTION_LIMIT: 10

该上限仅适用于由 webhook 和触发器节点启动的生产执行。不适用于手动执行、子工作流执行、错误工作流,或从 CLI(命令行界面)启动的执行。要确定数值,请在负载较高期间监控 docker stats 中的内存使用情况。然后逐步降低上限,直到峰值能够在保留充足余量的情况下运行。

并发上限可以保护服务器,但不会缩短任务完成时间,因为仍由同一个进程运行每个执行。如果等待中的执行持续增加,就需要更多进程。这时应使用队列模式。

开始前的准备

  • 一台安装了 Docker 和 Compose 插件的 VPS。如果您不熟悉 Compose,请先阅读VPS 的 Docker Compose 基础知识。
  • 一个为 n8n 主机名终止 TLS(传输层安全)的反向代理。
  • 一个已经使用 Postgres 的 n8n 实例,或一个全新实例。将现有数据从 SQLite 迁移到 Postgres 属于单独的迁移操作,本指南不涉及。
  • 如果您要转换的实例中已经保存了凭据,请准备现有的 N8N_ENCRYPTION_KEY。

加密密钥最重要。n8n 使用它加密已保存的凭据。新密钥无法解密使用旧密钥保存的凭据。如果您从未手动设置过该密钥,n8n 会生成一个密钥,并将其存储在数据卷内的配置文件中。使用以下命令从当前堆栈中输出该密钥:

docker compose exec n8n cat /home/node/.n8n/config

将 encryptionKey 值复制到下一步中的 .env 文件。不要使用新的随机密钥。

创建 .env 文件

将密钥放入与 compose.yaml 同目录的一个 .env 文件中。Compose 会读取此文件,并将其中的值替换到堆栈配置中。Docker Compose 中的环境文件和密钥介绍了引号用法和优先级规则。

mkdir -p ~/n8n-queue && cd ~/n8n-queue
cat > .env <<'EOF'
N8N_HOST=n8n.example.com
GENERIC_TIMEZONE=Europe/Berlin
POSTGRES_USER=n8n
POSTGRES_DB=n8n
EOF
printf 'POSTGRES_PASSWORD=%s\nREDIS_PASSWORD=%s\nN8N_ENCRYPTION_KEY=%s\n' \
  "$(openssl rand -hex 24)" "$(openssl rand -hex 24)" "$(openssl rand -hex 32)" >> .env
chmod 600 .env

如果您要转换现有实例,请将生成的 N8N_ENCRYPTION_KEY 行替换为旧密钥。十六进制输出不包含在 YAML 或 shell 中需要加引号的字符,因此可以直接使用这些值。

n8n 队列模式的 Compose 文件

下面的文件会运行一个主实例、一个 worker 服务、Redis 和 Postgres。共享设置集中在一个 YAML 锚点中,因此主实例和 worker 不会出现配置偏差。这样可以确保每个进程都使用相同的 N8N_ENCRYPTION_KEY 和同一个数据库。

x-n8n: &n8n
  image: n8nio/n8n:2.41.6
  restart: unless-stopped
  environment: &n8n-env
    DB_TYPE: postgresdb
    DB_POSTGRESDB_HOST: postgres
    DB_POSTGRESDB_DATABASE: ${POSTGRES_DB}
    DB_POSTGRESDB_USER: ${POSTGRES_USER}
    DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
    EXECUTIONS_MODE: queue
    QUEUE_BULL_REDIS_HOST: redis
    QUEUE_BULL_REDIS_PORT: 6379
    QUEUE_BULL_REDIS_PASSWORD: ${REDIS_PASSWORD}
    QUEUE_HEALTH_CHECK_ACTIVE: "true"
    N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
    N8N_DEFAULT_BINARY_DATA_MODE: database
    GENERIC_TIMEZONE: ${GENERIC_TIMEZONE}
    TZ: ${GENERIC_TIMEZONE}
  healthcheck:
    test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:5678/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
    interval: 30s
    timeout: 5s
    retries: 3
    start_period: 60s

services:
  n8n:
    <<: *n8n
    environment:
      <<: *n8n-env
      N8N_HOST: ${N8N_HOST}
      N8N_PROTOCOL: https
      WEBHOOK_URL: https://${N8N_HOST}/
    ports:
      - "127.0.0.1:5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  n8n-worker:
    <<: *n8n
    command: worker --concurrency=5
    mem_limit: 1g
    depends_on:
      n8n:
        condition: service_healthy

  redis:
    image: redis:7.4.11-alpine
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD} --appendonly yes
    environment:
      REDISCLI_AUTH: ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5

  postgres:
    image: postgres:17.11-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 3s
      retries: 5

volumes:
  n8n_data:
  redis_data:
  pg_data:

为何要设置每个选项

Redis 没有 ports: 条目。 工作进程和主实例通过 Compose 网络中的服务名 redis 访问 Redis。在主机上发布的 Redis 端口可能会从互联网访问,除非防火墙阻止该访问。在许多配置中,Docker 发布的端口还会绕过 ufw 规则。密码在此基础上增加了一层保护。REDISCLI_AUTH 是 redis-cli 读取的密码变量。健康检查和您自己的 redis-cli 命令随后无需在命令行中提供密码即可登录。

--appendonly yes 会将每次更改写入磁盘,因此队列中等待的作业可在 Redis 重启后保留。保留默认内存策略 noeviction。诸如 allkeys-lru 这样的驱逐策略会在内存占满时让 Redis 删除键,因此不适合删除队列键。

N8N_DEFAULT_BINARY_DATA_MODE: database 会在没有共享文件系统的情况下,将二进制数据存储在 Postgres 中。default 模式会将二进制数据(文件、图像、PDF)保存在内存中。n8n 在队列模式下支持 filesystem 模式,但所有处理二进制数据的主实例、工作进程和 webhook 处理器都必须访问同一个共享卷,并使用相同的配置路径。database 模式会将二进制数据存储在 Postgres 中。n8n 也可以将二进制数据存储在 AWS S3 或 Azure Blob Storage 中,但这种外部存储功能属于 Business 或 Enterprise 功能;没有有效许可证时,n8n 不会在 s3 模式下启动。本堆栈在免费的 Community 版本中使用 database。将大文件存储在 Postgres 中会使数据库增长,因此应清理旧的执行记录。

--concurrency=5 设置每个工作进程同时运行的作业数量。默认值为 10。n8n 文档建议每个工作进程使用 5 或更高的值。许多并发数很低的工作进程会分别打开自己的数据库连接,因此在 CPU 用尽前,Postgres 连接可能已经耗尽。VPS 上的 Postgres 连接池指南说明了如何根据 max_connections 统计连接数。除非有明确目的,否则不要在队列模式下设置 N8N_CONCURRENCY_PRODUCTION_LIMIT。如果将其设置为除 -1 以外的任何值,它都会覆盖每个工作进程上的 --concurrency 标志。

mem_limit: 1g 限制每个工作进程的 RAM 使用量。在此配置下,如果主机配置了 swap,工作进程还可以使用最多 1 GiB 的 swap。内存耗尽时,内核会终止容器内的进程;子进程可能被终止,而容器本身不会退出。如果容器退出,Docker 会根据 unless-stopped 重启工作进程。该限制不能保证主实例和 Postgres 在主机内存耗尽时仍能运行。将 1g 视为起始值,并根据 docker stats 的读数设置自己的值。Docker Compose 中的内存限制指南介绍了内存限制与 swap 的交互方式。

QUEUE_HEALTH_CHECK_ACTIVE: "true" 会让每个工作进程在其自身容器的 5678 端口上提供 /healthz。主实例始终提供 /healthz。健康检查会调用 node;该命令始终存在于 n8n 镜像中,因此不依赖是否安装 wget 或 curl。depends_on 条件会设置启动顺序:先启动 Postgres 和 Redis,再启动主实例,最后启动工作进程。主实例会在首次启动时执行数据库迁移,因此工作进程需要等待主实例。Docker Compose 健康检查指南介绍了 start_period 和其他时间参数。

工作进程没有卷,也没有发布端口。 它们从 Postgres 和 Redis 读取所需的全部内容。不要与它们共享主实例的 n8n_data 卷。

启动堆栈并检查各部分

docker compose up -d
docker compose ps

等待一两分钟后,docker compose ps 应显示全部 4 个服务,状态列中为 (healthy)。如果某个服务一直处于 (health: starting),或显示 (unhealthy),可通过其日志查看原因:

docker compose logs --tail=50 n8n
docker compose logs --tail=50 n8n-worker

检查 Redis 是否响应,以及 n8n 进程是否已连接到 Redis:

docker compose exec redis redis-cli ping
docker compose exec redis redis-cli info clients

第一个命令应输出 PONG。在第二个命令中,connected_clients 应大于 1,因为主实例和每个 worker 都会保持各自的连接。

检查 Redis 是否无法从 Compose 网络外部访问:

sudo ss -tlnp | grep 6379

此命令应无任何输出。如果输出中出现一行,表示主机上有进程监听 6379 端口。继续之前,先找出该进程。

现在验证 worker 是否执行了您的工作流。打开编辑器,激活一个使用 Webhook 触发器的工作流,然后使用 curl 调用其生产 URL。编辑器的执行列表中应显示执行成功。然后停止 worker,再次调用该 URL,并将 your-path 替换为 Webhook 的路径:

docker compose stop n8n-worker
curl -s --max-time 10 https://n8n.example.com/webhook/your-path
docker compose start n8n-worker

如果 Webhook 只有在工作流完成后才响应,--max-time 10 可避免 curl 永久等待。worker 停止期间,新执行不会完成,因为没有进程从队列中取出任务。worker 再次启动后,该执行才会运行。如果 worker 停止期间执行仍然完成,说明主实例未运行在队列模式下。使用 docker compose exec n8n printenv EXECUTIONS_MODE 检查。

添加第二个 worker

在一台 VPS 上,扩容只需设置一个标志:

docker compose up -d --scale n8n-worker=2
docker compose ps n8n-worker

每个副本都会从锚点获取相同的设置。只有在 CPU 核心和内存仍有余量时,才应添加 worker。在 2 vCPU 的 VPS 上,两个 worker 已经会与主实例和 Postgres 争用 CPU 时间。在这种情况下,第三个 worker 通常只会增加内存使用量,不会提高吞吐量。扩容后,检查 Postgres 连接数:

docker compose exec postgres psql -U n8n -d n8n -c "select count(*) from pg_stat_activity where datname = 'n8n';"

连接数应明显低于服务器的 max_connections。Postgres 通常默认允许 100 个连接,但如果内核设置有要求,initdb 可以选择更低的值;使用 SHOW max_connections; 检查正在运行的服务器。

队列模式无法解决什么问题

主实例仍然是单进程。它负责提供编辑器、接收所有 webhook,并触发所有计划任务。如果主实例崩溃,新的 webhook 会失败,计划工作流也不会启动,即使 worker 运行正常也是如此。自托管 n8n 持续离线的原因中介绍的单进程故障仍适用于主实例。队列模式会将执行负载从该进程转移出去,但不会提高该进程本身的可靠性。

手动执行(即从编辑器启动的执行)默认仍在主实例上运行。如果您在编辑器中测试大型工作流会导致实例崩溃,请在主实例上设置 OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true。

Code 节点在任务运行器中执行。在 n8n 2.x 中,默认的内部模式会在每个 n8n 容器内将其作为子进程启动,因此此架构无需额外服务即可运行。对于生产环境,n8n 文档建议使用外部模式,为每个 worker 配置一个 runner sidecar 容器。如果不将手动执行转移出去,主实例也需要一个 runner sidecar。原因是内部模式无法隔离逃逸出沙箱的代码。在运行不受信任的 Code 节点之前,应提前规划这一点。

为实现高可用而运行多个主实例是单独的功能,称为 multi-main。该功能需要付费许可证,详见n8n Community 和 Enterprise 的对比。带 worker 的队列模式可在免费的 Community 版本中使用。

升级与备份

每个 n8n 进程都必须运行相同版本,因为它们共用同一个数据库架构。修改锚点中的标签,然后同时重新创建所有服务:

docker compose pull
docker compose up -d

每次升级 n8n 前都要备份 Postgres。主实例启动时会迁移数据库架构,切回旧镜像不会撤销这些更改。Postgres 保存工作流、凭据、执行记录,以及在此配置中保存二进制数据。.env 文件保存加密密钥。没有该密钥,仅凭数据库备份无法解密凭据。备份和升级 Docker Compose 堆栈指南提供了完整流程。Redis 保存待处理和活动中的作业。如果需要恢复排队中的作业,请保留其数据卷。

FAQ

何时应在单台 VPS 上使用 n8n 队列模式?

当一个 n8n 进程成为瓶颈,且 VPS 还有空闲 CPU 核心和内存时,可以使用队列模式。典型表现包括:n8n 容器长期占用一个核心接近 100%,而其他核心处于空闲状态;或者运行高负载工作流时,编辑器响应变慢。在 1 vCPU 的 VPS 上,或工作流主要等待外部 API 响应时,应继续使用常规模式,并改为设置 N8N_CONCURRENCY_PRODUCTION_LIMIT。

n8n 工作进程需要与主实例使用相同的加密密钥吗?

需要。工作进程从 Postgres 加载凭据,并使用 N8N_ENCRYPTION_KEY 解密。使用不同密钥的工作进程无法解密主实例保存的凭据,因此任何使用这些凭据的执行都会失败。在 .env 中设置一次密钥,然后将其传递给每个 n8n 进程。

n8n 队列模式是否应将 Redis 发布到主机端口?

不应。主实例和工作进程通过 Compose 网络中的服务名称访问 Redis,因此 Redis 服务不需要 ports: 条目。已发布的端口可能会从互联网访问;在许多配置中,Docker 发布的端口还会绕过 ufw 规则。不要发布 Redis 端口,并使用 --requirepass 设置密码。

队列模式可以继续使用 SQLite 或文件系统二进制数据吗?

n8n 队列模式要求使用 Postgres。只要所有处理二进制数据的主实例、工作进程和 webhook 处理进程,都能以相同的配置路径访问同一个共享卷,就可以使用文件系统二进制数据。本方案在免费的 Community 版本中使用 N8N_DEFAULT_BINARY_DATA_MODE=database。也可以使用 AWS S3 或 Azure Blob Storage 等外部存储,但必须使用 Business 或 Enterprise 计划,并持有有效许可证。

应使用多少个工作进程,以及设置多大的并发数?

先使用一个工作进程,并将其设置为 --concurrency=5;这符合 n8n 对每个工作进程使用 5 或更高并发数的建议。只有在 CPU 核心和内存仍有余量时,才添加第二个工作进程。每次调整后,在 pg_stat_activity 中检查 Postgres 连接数。除非希望 N8N_CONCURRENCY_PRODUCTION_LIMIT 覆盖工作进程标志,否则不要在队列模式中设置它。

这篇文章对您有帮助吗?

#n8n#queue-mode#redis#docker-compose#workflow-automation