Skip to content

n8n v2.0 破坏性变更#

n8n v2.0 has been released, and with it came some important changes. This document highlights breaking changes and actions you should take to prepare for the transition. These updates improve security, simplify configuration, and remove legacy features.

n8n 2.0 的发布延续了 n8n 对安全、可靠、可用于生产的自动化平台的承诺。该重大版本包含关键的安全增强，并清理了已弃用的功能。

行为变更#

当子工作流从等待状态恢复时返回预期的子工作流数据（等待 webhook、表单、HITL 等）#

此前，当一个执行（父）调用了包含会让子执行进入等待状态节点的子执行（子），并且父执行设置为等待子执行完成时，父执行会收到错误结果。

例如，当子执行包含等待时长超过 65 秒的 Wait 节点、webhook 调用、表单提交，或像 Slack 节点这样的 human-in-the-loop 节点时，就会进入等待状态。

父工作流： 父工作流

子工作流： 子工作流

v1：父执行会将子执行的输入作为输出： v1：父执行不会收到子执行的结果

v2：父执行将收到子执行的结果： v2：父执行会收到子执行的结果

这允许在子工作流中使用 human-in-the-loop 节点，并在父工作流中使用其结果（例如批准或拒绝某个操作）。

迁移路径：检查所有调用子工作流且期望接收子工作流输入的工作流，并更新以适配新行为：父工作流将收到子工作流末尾的输出。

Start 节点移除#

Start 节点不再受支持。该节点是早期用于启动工作流的方式，但现在已被更具体的触发器节点取代。

迁移路径：根据工作流用途替换 Start 节点：

  • 手动执行：将 Start 节点替换为 Manual Trigger 节点。
  • 子工作流：如果其他工作流调用此工作流作为子工作流，将 Start 节点替换为 Execute Workflow Trigger 节点并启用该工作流。
  • 禁用的 Start 节点：如果 Start 节点被禁用，请从工作流中删除。

保存与发布工作流#

新的工作流发布系统替代了原有的激活/停用切换。这意味着旧的 “Activate/Deactivate” 切换按钮变成新的 “Publish/Unpublish” 按钮。该变更可更好地控制工作流何时上线，降低意外将进行中的更改部署到生产环境的风险。更多信息请参阅：保存与发布工作流。

已退役服务的节点移除#

以下节点因其连接的外部服务不再可用而被移除：

  • Spontit 节点
  • crowd.dev 节点
  • Kitemaker 节点
  • Automizy 节点

迁移路径：如果工作流中使用了这些节点，请更新或移除相应工作流以避免出错。

安全#

默认阻止 Code 节点访问环境变量#

为了提高安全性，n8n 将默认阻止 Code 节点访问环境变量。N8N_BLOCK_ENV_ACCESS_IN_NODE 的默认值现在为 true。

迁移路径：如果你的工作流需要在 Code 节点中访问环境变量，请在环境配置中设置 N8N_BLOCK_ENV_ACCESS_IN_NODE=false。对于敏感数据，请使用凭据或其他安全方式替代环境变量。

强制设置文件权限#

n8n 将对配置文件要求严格的文件权限以提升安全性。默认情况下，配置文件必须使用 0600 权限，这意味着只有文件所有者可以读写。该方式类似于 SSH 保护私钥的方式。

迁移路径：要在 v2.0 之前测试该行为，请设置 N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true。如果你的环境不支持文件权限（例如 Windows），请设置 N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=false 以禁用该要求。

默认启用 task runners#

n8n 将默认启用 task runners，以提升安全性和隔离性。所有 Code 节点执行都将在 task runner 上运行。

迁移路径：在升级到 v2.0 之前，请设置 N8N_RUNNERS_ENABLED=true 以测试该行为。确保你的基础设施满足运行 task runners 的要求。为获得更高安全性，可考虑使用外部模式。

从 n8nio/n8n Docker 镜像中移除 task runner#

从 v2.0 开始，主 n8nio/n8n Docker 镜像不再包含外部模式的 task runner。你必须使用独立的 n8nio/runners Docker 镜像在外部模式下运行 task runner。

迁移路径：如果你在 Docker 中使用外部模式运行 task runner，请将镜像从 n8nio/n8n 更新为 n8nio/runners。

移除基于 Pyodide 的 Python Code 节点和工具#

n8n 将移除基于 Pyodide 的 Python Code 节点和工具，并用基于 task runner 的实现替代，以使用原生 Python 提升安全性与性能。从 v2.0 开始，仅能在外部模式下使用 task runners 和原生 Python 工具来运行 Python Code 节点。

原生 Python Code 节点不再支持 Pyodide 版本中的内置变量（如 _input）或点访问语法。详情请参阅 Code 节点文档。

原生 Python 工具支持 _query，用于 AI Agent 调用该工具时传入的输入字符串。

迁移路径：若要继续在 Code 节点中使用 Python，请在外部模式下设置 task runner，并检查现有 Python Code 节点与工具的兼容性。

默认禁用 ExecuteCommand 和 LocalFileTrigger 节点#

出于安全风险考虑，n8n 将默认禁用 ExecuteCommand 和 LocalFileTrigger 节点。这些节点允许用户执行任意命令并访问文件系统。

迁移路径：如需使用这些节点，请在 n8n 配置中更新 NODES_EXCLUDE 环境变量，从禁用列表中移除它们。例如，将 NODES_EXCLUDE="[]" 设置为启用所有节点，或仅移除你需要的节点。

默认要求 OAuth 回调 URL 认证#

n8n 将默认要求 OAuth 回调端点进行认证。N8N_SKIP_AUTH_ON_OAUTH_CALLBACK 的默认值将从 true（不需要认证）改为 false（需要认证）。

迁移路径：在升级到 v2.0 之前，请设置 N8N_SKIP_AUTH_ON_OAUTH_CALLBACK=false 并测试你的 OAuth 集成，确保在启用认证后正常工作。

设置 N8N_RESTRICT_FILE_ACCESS_TO 的默认值#

n8n 将为 N8N_RESTRICT_FILE_ACCESS_TO 设置默认值，以控制文件操作范围。这影响 ReadWriteFile 和 ReadBinaryFiles 节点。默认情况下，这些节点只能访问 ~/.n8n-files 目录中的文件。

迁移路径：检查使用文件节点的工作流，确保它们只访问允许的目录。如需访问其他目录，请将 N8N_RESTRICT_FILE_ACCESS_TO 设置为你想要的路径。

将 N8N_GIT_NODE_DISABLE_BARE_REPOS 的默认值改为 true#

出于安全原因，Git 节点默认将阻止裸仓库。N8N_GIT_NODE_DISABLE_BARE_REPOS 的默认值为 true，意味着除非你更改设置，否则将禁用裸仓库。

迁移路径：如果你的工作流需要使用裸仓库，请在环境配置中设置 N8N_GIT_NODE_DISABLE_BARE_REPOS=false 以启用。

数据#

移除 MySQL/MariaDB 支持#

n8n 将不再支持 MySQL 和 MariaDB 作为存储后端。该支持在 v1.0 中已弃用。为了获得更好的兼容性和长期支持，请使用 PostgreSQL。MySQL 节点仍按原样继续支持。

迁移路径：在升级到 v2.0 之前，请使用数据库迁移工具将数据从 MySQL 或 MariaDB 迁移到 PostgreSQL 或 SQLite。

移除 SQLite 旧驱动#

n8n 将移除旧版 SQLite 驱动，因为其可靠性问题。连接池驱动将成为默认且唯一的 SQLite 驱动。连接池驱动使用 WAL 模式、单写连接和读连接池。基准测试显示其速度可提升至 10 倍。

迁移路径：sqlite-pooled 驱动将自动成为默认值。你现在可以将 DB_SQLITE_POOL_SIZE 设置为大于 0 来启用连接池。默认连接池大小将设置为 2。

移除内存中的二进制数据模式#

n8n 将移除 N8N_DEFAULT_BINARY_DATA_MODE 的 default 模式，该模式在执行期间将二进制数据保存在内存中。出于性能和稳定性考虑，从 v2 开始将提供以下选项：

  • filesystem：二进制数据存储在文件系统中。常规模式下的默认选项。
  • database：二进制数据存储在数据库中。队列模式下的默认选项。
  • s3：二进制数据存储在 S3 兼容存储中。

N8N_AVAILABLE_BINARY_DATA_MODES 设置也会被移除，因此模式将仅由 N8N_DEFAULT_BINARY_DATA_MODE 决定。

迁移路径：系统将根据配置自动使用文件系统或数据库模式。请确保你的 n8n 实例拥有足够的磁盘空间来存储二进制数据。详情请参阅二进制数据配置。

配置与环境#

升级 dotenv#

n8n 使用 dotenv 库从 .env 文件加载环境配置。该库将从 8.6.0 升级到最新版本，可能改变 .env 文件的解析方式。主要破坏性变更包括：

  • 反引号支持（#615）：如果值包含反引号，请使用单引号或双引号包裹。
  • 多行支持：现在可以使用多行值。
  • # 标记注释起始：以 # 开头的行将被视为注释。

迁移路径：查看 dotenv 变更日志 并更新 .env 文件，以确保与新版本兼容。

移除 n8n --tunnel 选项#

n8n --tunnel 命令行选项将在 v2.0 中移除。

迁移路径：如果你当前使用 --tunnel 进行开发或测试，请改用替代的隧道方案，例如 ngrok、localtunnel 或 Cloudflare Tunnel。并更新工作流与文档以反映该变更。

移除 QUEUE_WORKER_MAX_STALLED_COUNT#

QUEUE_WORKER_MAX_STALLED_COUNT 环境变量和 Bull 的卡住作业重试机制将被移除，因为它们经常引起困惑且不可靠。

迁移路径：从配置中删除该环境变量。升级后，n8n 将不会自动重试卡住的作业。如果你需要处理卡住作业，请考虑实现自定义重试逻辑或监控。

移除 N8N_CONFIG_FILES#

N8N_CONFIG_FILES 环境变量已被移除。

迁移路径：从配置中删除该环境变量。将配置迁移到环境变量、.env 文件或基于 _FILE 的配置方式。

CLI 与工作流#

替换 CLI 命令 update:workflow#

update:workflow CLI 命令将被弃用，并替换为两个新命令，以提供类似功能并提高清晰度：

  • publish:workflow，参数为 id 和 versionId（可选）
  • 将移除 --all 参数，以防止在生产环境中意外发布工作流

  • unpublish:workflow，参数为 id 和 all

  • publish:workflow with parameters id and versionId (optional)

    • The --all parameter will be removed to prevent accidental publishing of workflows in production environments
  • unpublish:workflow with parameters id and all

外部 Hooks#

已弃用的前端工作流 hooks#

hooks workflow.activeChange 和 workflow.activeChangeCurrent 将被弃用，替换为新 hook workflow.published。该 hook 会在任意版本工作流发布时触发。

迁移路径：请将代码更新为使用 workflow.published，替代 workflow.activeChange 与 workflow.activeChangeCurrent。该 hook 行为更一致，并会在工作流版本发布时触发。

发布渠道#

n8n 将发布渠道从 latest 和 next 重命名为 stable 和 beta。

stable 标签表示最新稳定版，beta 标签表示最新实验版。这些标签在 npm 和 Docker Hub 中都可用。当前 n8n 仍会继续发布 latest 和 next 标签，但在未来的主版本中将移除。

建议：请将 n8n 版本固定为具体版本号，例如 2.0.0。

问题反馈#

如果你在升级到 n8n 2.0 时遇到问题，请访问社区论坛获取帮助与支持。