跳到主要内容

n8n v1.0 迁移指南#

本文档概述了在升级到 n8n 1.0 版本前需要注意的事项。

n8n 1.0 的发布标志着 n8n 在满足严苛生产环境需求的道路上迈出了重要一步。该版本凝聚了过去四年的研发成果，使 n8n 成为最易用、功能最强大且最多样化的自动化工具。n8n 1.0 现已具备生产环境使用条件。

新功能#​

代码节点支持 Python#​

虽然 JavaScript 仍是默认语言，但现在您可以在代码节点中选择 Python 作为编程语言，甚至能够使用众多 Python 模块。请注意，在 v1.0 之前添加到工作流的代码节点无法使用 Python 功能。

PR #4295, PR #6209

执行顺序#​

n8n 1.0 为多分支工作流引入了新的执行顺序：

在多分支工作流中，n8n 需要确定各分支节点的执行顺序。此前版本采用广度优先策略：先执行所有分支的第一个节点，再执行所有分支的第二个节点，依此类推。新的执行顺序确保每个分支都会完全执行完毕后再开始下一个分支（深度优先）。分支按照在画布上的位置从上到下执行，若两个分支处于同一高度，则最左侧分支优先执行。

过去多输入节点只要在第一个输入端口接收到数据就会执行。连接到多输入节点第二个输入端的节点无论是否接收到数据都会自动执行。n8n 1.0 引入的新执行顺序简化了此行为：节点仅在接收到数据时才会执行，多输入节点需要至少一个输入端口接收到数据才会触发执行。

现有工作流将继续使用旧版执行顺序，而新建工作流将采用 v1 执行顺序。您可以在工作流设置中为每个工作流配置执行顺序。

PR #4238, PR #6246, PR #6507

弃用功能#​

MySQL 和 MariaDB#​

n8n 已弃用对 MySQL 和 MariaDB 作为存储后端的支持。这些数据库系统仅被少数用户使用，但却需要持续的开发和维护投入。n8n 建议迁移至 PostgreSQL 以获得更好的兼容性和长期支持。

PR #6189

EXECUTIONS_PROCESS 与 "own" 模式#​

此前可通过 EXECUTIONS_PROCESS 环境变量指定执行流程在 main 进程还是 own 进程中运行。该选项及 own 模式现已被弃用，并将在未来版本中移除。原因是该机制导致代码复杂度增加而收益有限。从 n8n 1.0 开始，main 将成为新的默认模式。

请注意，main 模式下的执行启动速度远快于 own 模式。但若工作流内存占用超过可用内存，可能会导致整个 n8n 应用崩溃而非仅影响工作线程。为避免此情况，请确保分配足够的系统资源或配置队列模式以在多个工作进程间分配执行任务。

PR #6196

重大变更#​

Docker#​

权限变更#​

在使用 Docker 部署时，n8n 进程现改由 node 用户而非 root 用户运行，此项变更提升了安全性。

若启动 n8n 时容器日志中出现权限错误，可能需要在 Docker 主机上执行以下命令更新权限：

docker run --rm -it --user root -v ~/.n8n:/home/node/.n8n --entrypoint chown n8nio/base:16 -R node:node /home/node/.n8n

镜像移除#​

我们已移除 Debian 和 RHEL 镜像。若您正在使用这些镜像，需更换所用镜像。除非您基于这些镜像制作了自定义镜像，否则不会引发任何错误。

入口点变更#​

容器入口点已变更，您不再需要指定 n8n 命令。若此前运行 n8n worker --concurrency=5，现在需改为 worker --concurrency=5

PR #6365

表达式错误导致的工作流故障#​

工作流执行可能因表达式中的语法或运行时错误（例如引用不存在节点的表达式）而失败。虽然表达式在前端已会抛出错误，但此项变更确保 n8n 在后端也会抛出错误（此前这些错误会被静默忽略）。为接收工作流失败通知，n8n 建议在工作流设置中配置"错误工作流"。

PR #6352

强制所有者账户#​

此项变更将强制要求使用用户管理，并移除对其他认证方式（如 BasicAuth 和外部 JWT）的支持。请注意，n8n.cloud 或定制方案中的允许用户数量仍因订阅类型而异。

PR #6362

自定义节点安装目录#​

n8n 将不再从其全局 node_modules 目录加载自定义节点。您必须将自定义节点安装（或链接）至 ~/.n8n/custom（或由 N8N_CUSTOM_EXTENSIONS 定义的目录）。作为 npm 包的自定义节点将位于 ~/.n8n/nodes。 若您曾使用 npm link 将自定义节点链接至全局 node_modules 目录，需重新将其链接至 ~/.n8n/nodes。

PR #6396

WebSockets#​

N8N_PUSH_BACKEND 环境变量可用于配置两种向用户界面推送更新的可用方法之一：sse 和 websocket。从 n8n 1.0 开始，websocket 成为默认方法。

PR #6196

日期转换函数#​

n8n 提供多种可操作日期的转换函数。这些函数可能返回 JavaScript Date 或 Luxon DateTime 对象。新行为下，返回类型始终与输入类型匹配。若对 Date 调用日期转换函数，则返回 Date；同理，若对 DateTime 对象调用，则返回 DateTime 对象。

要识别可能受此变更影响的工作流和节点，可使用此实用工作流。

有关日期转换函数的更多信息，请参阅官方文档。

PR #6435

执行数据保留#​

从 n8n 1.0 开始，所有成功、失败和手动工作流执行默认都将被保存。这些设置可在"工作流设置"中针对每个工作流进行修改，或使用相应环境变量进行全局配置。此外，EXECUTIONS_DATA_PRUNE 设置将默认启用，且 EXECUTIONS_DATA_PRUNE_MAX_COUNT 设置为 10,000。这些默认设置旨在防止使用 SQLite 时出现性能下降。请根据您的具体需求和系统容量进行配置。

PR #6577

移除 N8N_USE_DEPRECATED_REQUEST_LIB#​

传统的 request 库已被弃用多时。截至 n8n 1.0，通过设置 N8N_USE_DEPRECATED_REQUEST_LIB 环境变量在 HTTP 请求节点中回退至该库的功能已被完全移除。HTTP 请求节点现在将始终使用新的 HttpRequest 接口。

若您构建自定义节点，请参阅 HTTP 请求助手 了解迁移至新接口的更多信息。

PR #6413

移除 WEBHOOK_TUNNEL_URL#​

自 0.227.0 版本起，n8n 已将 WEBHOOK_TUNNEL_URL 配置选项重命名为 WEBHOOK_URL。在 n8n 1.0 中，WEBHOOK_TUNNEL_URL 已被移除。请更新您的设置以使用新名称。有关此配置选项的更多信息，请参阅文档。

PR #1408

移除 Node 16 支持#​

n8n 现在需要 Node 18.17.0 或更高版本。

升级至 n8n 1.0#​

  1. 创建 n8n 的完整备份。
  2. n8n 建议在升级至 n8n 1.x 前先更新至最新的 n8n 0.x 版本。这将帮助您准确定位任何潜在问题所属的版本。确认 n8n 0.x 可无任何问题启动后，继续下一步。
  3. 仔细阅读上文的弃用说明和重大变更部分，评估其对您设置的影响。
  4. 升级至 n8n 1.0：
    • Beta 期间（2023 年 7 月 24 日前）：若使用 Docker，拉取 next Docker 镜像。
    • 2023 年 7 月 24 日后：若使用 Docker，拉取 latest Docker 镜像。
  5. 若遇到任何问题，请重新部署先前版本的 n8n 并恢复备份。

问题报告#​

若在升级至 n8n 1.0 过程中遇到任何问题，请在社区论坛寻求帮助。

致谢#​

我们谨向所有持续提供支持与反馈的用户表达诚挚谢意。您的贡献对帮助我们将 n8n 打造成最佳自动化工具至关重要。我们期待在 1.0 及后续版本的发布进程中继续与您携手共进。感谢您与我们同行！