Skip to content

n8n v2.0 破坏性变更#

n8n v2.0 即将发布。本文档重点介绍重要的破坏性变更以及你需要采取的准备行动。这些更新提升了安全性、简化了配置，并移除了旧功能。

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 命令按 ID 发布工作流，并可选择指定版本。使用新的 unpublish:workflow 命令取消发布。这样可更清晰地控制工作流发布状态。

外部 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 时遇到问题，请访问社区论坛获取帮助与支持。