v3.0 重大变更
n8n 3.0 带来一些重要变更。本文档概述了重大变更,以及你应为迁移采取的准备措施。这些更新提高了安全性、简化了配置,并移除了旧功能。
提示
抢先体验版本
n8n 3.0.0 目前作为抢先体验版本提供。
升级前,请使用 Settings 设置 > Migration Report 迁移报告 中的 n8n 3.0 迁移工具。它会列出你自己的实例中需要关注的工作流和实例设置,因此无需手动检查本页中的每一项变更。
部署
自托管 n8n 必须使用 Docker 部署
自托管 n8n 必须使用基于 Docker 的部署。n8n 3.0 不再支持通过 npm 或 npx n8n 运行的安装方式,也不会再向 npm 发布可运行的 n8n package。
该怎么做: 如果使用 npm 或 npx n8n 运行 n8n,请在升级到 n8n 3.0 前迁移到基于 Docker 的部署。最快的方法是使用一行设置:它会检查 Docker、写入配置文件,并通过一条命令启动新的 n8n 实例:
curl -fsSL https://get.n8n.io | sh
如果已经在运行自己的 Docker Compose 文件,则无需切换。对于团队或生产实例,使用 Docker Compose 安装介绍了如何使用 Postgres 而不是捆绑的 SQLite 数据库运行 n8n。
社区节点开发
从节点描述中移除 defaults.color
n8n 3.0 会从节点描述类型中移除已弃用的 defaults.color 属性。此属性仅用于为 Font Awesome 图标(icon: 'fa:...')着色。仍设置该属性的社区节点可以继续运行,但编辑器会以中性色显示 Font Awesome 图标。使用文件图标(icon: 'file:...')的节点不受影响,因为 n8n 从不为文件图标着色。
该怎么做: 移除 defaults.color。如果节点使用 Font Awesome 图标,请按照标准参数参考中的建议,改用 SVG 或 PNG 文件图标。
以下其余变更只影响 n8n-node dev 测试循环。n8n-node build、n8n-node lint、n8n-node release 和 npm create @n8n/node 保持不变。
n8n-node dev 需要 Docker 或 Podman
n8n-node dev 过去通过 npx n8n@latest 启动 n8n。n8n 3.0 不再向 npm 发布可运行的 n8n package,因此该命令现在会在容器中运行官方镜像。
该怎么做: 对于默认容器路径,请安装 Docker 或 Podman。如需使用外部管理的实例,请运行 n8n-node dev --external-n8n,并以 N8N_DEV_RELOAD=true 启动该实例。如需固定容器路径中的版本,请传入 tag:n8n-node dev --n8n-image docker.n8n.io/n8nio/n8n:<n8n-version>。热重载仅适用于提供 POST /rest/dev/reload 的镜像,因此旧 tag 可以加载节点,但必须重启才能获取更改。
n8n-node dev 测试数据迁移到各镜像独立的容器卷
测试节点时创建的工作流和凭据现在保存在 n8n-node-cli-data-<image> 容器卷中,而不是 ~/.n8n-node-cli/.n8n。每个 --n8n-image 都有自己的卷,因为 n8n 只支持数据库向前迁移。切换镜像时会得到空实例,而不是让旧版 n8n 读取无法兼容的数据库。
警告
旧版本的测试数据不会迁移
升级 CLI 或切换镜像前,请导出希望保留的测试工作流。
该怎么做: 导出希望保留的测试工作流。使用 docker volume ls --filter name=n8n-node-cli-data 和 docker volume rm <volume> 列出及重置 volumes,podman 可使用对应命令。
--custom-user-folder 仅与 --external-n8n 配合使用
此 flag 过去用于设置 CLI 链接节点的位置。现在它用于指定自行运行实例的 N8N_USER_FOLDER,在容器模式下不起作用。
该怎么做: 如果传入 --custom-user-folder,请同时添加 --external-n8n,并使用相同的 N8N_USER_FOLDER 启动该实例。
已移除的节点和辅助函数
n8n 3.0 会移除已被新模式取代的旧节点、模式和辅助函数。
删除节点
使用已移除节点的工作流在运行时会失败。如果这样的工作流已发布,n8n 3.0 启动时不会激活它,因此它的触发器会停止触发。升级前,Settings 设置 > Migration Report 迁移报告 会列出实例中受影响的工作流,已弃用和版本化的节点页面则记录此处每个节点的最终版本。
- Function 节点(旧版)
- Function Item 节点(旧版)
- Item Lists 节点(旧版)
- LangChain Code 节点(旧版)
- Cron 和 Interval 节点
- HTML Extract 节点
- iCalendar 节点
- Convert to/from binary data 节点
- Read Binary File、Read Binary Files 和 Write Binary File 节点
- Read PDF 节点
- Workflow Trigger 节点
- Orbit 节点
- OpenAI 节点(旧版)。AI 区域中当前的 OpenAI 节点会保留。
- OpenAI Assistant 和 OpenAI Model 节点
- HTTP Request Tool 节点(旧版)。仍可将 HTTP Request 节点用作工具。
- SerpApi (Google Search) 节点
- Manual Chat Trigger 节点
- Chat Messages Retriever 节点
- Motorhead 和 Zep memory 节点
- Binary Input Loader、JSON Input Loader 和 GitHub Document Loader 节点
- In Memory Vector Store Insert、In Memory Vector Store Load、Pinecone: Insert、Pinecone: Load、Supabase: Insert、Supabase: Load、Zep Vector Store、Zep Vector Store: Insert 和 Zep Vector Store: Load 节点
- AI Transform 节点:你不能再添加或运行 AI Transform 节点。要让现有节点继续工作,请从 Settings 设置 > Migration Report 迁移报告 把它们迁移为 Code 节点。迁移会保留生成的 JavaScript,因此工作流会运行相同的代码。n8n 不会在升级时自动迁移这些节点。如果某个 AI Transform 节点从未生成代码,报告无法迁移它,请手动替换为 Code 节点。
- 该怎么做: 升级前,将受影响的工作流迁移到当前推荐的替代方案:
- 使用 Code 节点替换 Function 和 Function Item 节点。以 Run Once for All Items 对所有数据项运行一次模式替代 Function,以 Run Once for Each Item 对每个数据项运行一次模式替代 Function Item。
- 根据所用操作,将 Item Lists 节点替换为 Split Out、Aggregate、Sort、Limit、Remove Duplicates 或 Summarize 节点。
- 使用 Schedule Trigger 节点替换 Cron 和 Interval。
- 使用 HTML 节点的 Extract HTML Content 提取 HTML 内容操作替换 HTML Extract。
- 使用 Convert to File 节点的 Convert to ICS 转换为 ICS 操作替换 iCalendar。
- 使用 Convert to File 或 Extract from File 节点替换 Convert to/from binary data。
- 使用 Read/Write Files from Disk 节点替换 Read Binary File、Read Binary Files 和 Write Binary File。
- 使用 Extract from File 节点的 Extract From PDF 从 PDF 提取操作替换 Read PDF。
- 使用 n8n Trigger 节点替换 Workflow Trigger。
- 使用 OpenAI 节点替换旧版 OpenAI 和 OpenAI Assistant 节点。对于 assistant,请使用其 Assistant 助手资源。
- 使用 OpenAI Chat Model 节点替换 OpenAI Model。
- 使用连接到 AI Agent 节点 Tool 工具 输入端的 HTTP Request 节点替换旧版 HTTP Request Tool。
- 使用 Chat Trigger 节点替换 Manual Chat Trigger。
- 使用 Chat Memory Manager 节点替换 Chat Messages Retriever,或在 Chat Trigger 节点中加载先前的 session。
- 使用 Default Data Loader 节点替换 Binary Input Loader、JSON Input Loader 和 GitHub Document Loader。对于 GitHub 内容,请先使用 GitHub 节点获取。
- 将 Vector Store 的 Insert 和 Load 节点替换为对应存储的单一节点:Simple Vector Store、Pinecone Vector Store 或 Supabase Vector Store,然后在节点中选择 Insert Documents 插入文档、Get Many 获取多个或 Retrieve Documents 检索文档操作。
- LangChain Code 没有直接替代项。
- Motorhead、Zep 和 Zep Vector Store 节点没有直接替代项。请改用其他受支持的 memory 或 vector store 节点。
- SerpApi (Google Search) 没有直接替代项。可使用连接为 tool 的 HTTP Request 节点调用 SerpApi REST API,或使用经过验证的社区节点。
- Orbit 没有替代项,因为 Orbit 服务已关闭。
已移除的表达式辅助函数
n8n 3.0 会移除已弃用的 $getPairedItem 表达式辅助函数。仍调用它的表达式会在节点运行时失败。
该怎么做: 改用 n8n 标准的数据项链接。以下三种形式可替代 $getPairedItem:
$('<node-name>').item返回<node-name>中当前数据项链接回去的数据项。$('<node-name>').itemMatching(<item-index>)返回<node-name>中输入数据项<item-index>链接回去的数据项。$('<node-name>').pairedItem(<item-index>)直接返回<item-index>对应的 paired item。
Execute Sub-workflow 节点:移除 Local File 和 URL 来源
n8n 3.0 会从 Execute Sub-workflow 节点的 Source 来源 参数中移除 Local File 和 URL 选项。只有 1.1 及更早版本的节点提供这些选项。仍使用其中任一来源的节点会报错失败。
该怎么做: 将子工作流导入实例,并以 Database 数据库 来源选择它;或使用 Define Below 在下方定义 来源粘贴其 JSON(节点版本 1.1 及更早版本中名为 Parameter 参数)。升级前,请前往 Settings 设置 > Migration Report 迁移报告 识别受影响的节点。
从 Code 节点移除 $evaluateExpression()
n8n 3.0 会从 Code 节点(JavaScript)中移除 $evaluateExpression() 便捷方法。只有不安全模式下的 task runners(N8N_RUNNERS_INSECURE_MODE=true)受影响。自 n8n 2.0 起成为默认值的安全模式 runners 已无法执行此调用。
该怎么做: 改在节点字段中计算表达式,例如在 Code 节点前的 Edit Fields (Set) 节点中计算,再从输入数据项读取结果。$evaluateExpression() 在 {{ }} 表达式字段中仍可使用。
AI Agent 节点:移除旧版 agent 模式
版本 1 的 AI Agent 节点支持多种 agent 类型模式,包括 SQL Agent、Conversational Agent、OpenAI Functions Agent、Plan and Execute Agent 和 ReAct Agent。n8n 3.0 会移除节点版本 1 及这些模式。
该怎么做: 将使用版本 1 AI Agent 节点的工作流和 templates 更新到最新版本。最新版本使用 Tools Agent 取代所有已移除模式;已经设为 Tools Agent 的工作流在更新后行为不变。对于 SQL Agent 使用场景,请改用 Postgres 或 MySQL tool 子节点,并将其连接到较新版本的 AI Agent 节点。
Edit Image 节点:移除节点版本 1 和 1.1
n8n 3.0 会移除对 Edit Image 节点已弃用版本 1 和 1.1 的支持。仍使用这些版本的工作流会报错失败,直到你升级该节点。
节点版本 2 使用了不同的图像处理库,因此图像输出可能发生变化。迁移会转换模糊设置,但会移除 Sigma。文本位置可能发生变化。Get Information 获取信息 会返回规范化的结果。PNG 和 TIFF 输出会忽略 Quality 质量 设置。使用零或负数尺寸的调整大小操作会失败。
该怎么做: 升级前,请前往 Settings 设置 > Migration Report 迁移报告 识别受影响的工作流。从报告中迁移它们,或者手动将每个 Edit Image 节点更新到节点版本 2。然后测试输出,尤其是会对图像进行模糊处理或调整尺寸、添加文本、读取图像信息,或设置 PNG 或 TIFF 质量的工作流。
行为变更
n8n 3.0 会改变部分节点和凭据的行为。这些节点仍可使用,但现有工作流可能产生不同结果。
多输出节点的 Always Output Data
启用 Always Output Data 始终输出数据 后,If 和 Switch 等多输出节点现在只会在所有输出都为空时添加一个空数据项。此前,每个空输出都会得到一个空数据项,可能导致不应运行的分支也被执行。
该怎么做: 升级前,请前往 Settings 设置 > Migration Report 迁移报告 识别受此变更影响的节点。检查各节点,并根据预期行为调整此设置。
Gmail Trigger 节点:旧版本按 1.4 版本行为运行
n8n 3.0 会移除 Gmail Trigger 节点 1 到 1.3 版本各自独立的行为。使用这些版本的工作流仍可加载,但节点会按照 1.4 版本的行为运行:
- Max Emails per Poll 每次轮询的最大邮件数 会应用于每次轮询。默认值为 10 封邮件,最多可设置为 50。节点会在后续轮询中继续处理剩余邮件。
- 除非启用 Include Drafts 包含草稿 筛选器,否则节点会跳过草稿。版本 1 和 1.1 默认包含草稿。
- 不在收件箱中的已发送邮件和定时邮件不再触发工作流。
该怎么做: 检查使用低于 1.4 版本 Gmail Trigger 节点的工作流。升级前,请前往 Settings 设置 > Migration Report 迁移报告 识别受影响的节点。如果工作流依赖草稿,请启用 Include Drafts 包含草稿。如果依赖已发送或定时邮件,请将触发器替换为 Schedule Trigger 节点,后接 Gmail 节点的 Get Many 获取多个消息操作。
Webflow OAuth2 凭据:Legacy 开关默认关闭
Webflow OAuth2 API 凭据上的 Legacy 旧版开关默认关闭。新凭据会请求 Webflow v2 API scopes(cms:read cms:write sites:read forms:read)。从未显式保存 Legacy 值的现有凭据会在下次重新连接时请求这些 scopes。已连接的凭据可继续运行。n8n 不会修改保存的 token,token 刷新也不会发送 scopes。
该怎么做: 如果仍在使用已弃用的 Webflow v1 Data API,例如旧版 Webflow OAuth app 或版本 1 的 Webflow 节点,请在重新连接凭据前启用 Legacy 旧版。如果你的 app 未配置所请求的 scopes,Webflow 会拒绝连接。
Chat Trigger 节点:WebSocket 消息改为 JSON frame
在 Using Response Nodes 使用响应节点 响应模式下,Chat Trigger 节点使用的 chat WebSocket endpoint(由 Chat 节点发送回复)现在会将每个 frame 作为带有 type 字段的 JSON 对象发送:heartbeat、continue、error、message 或 with-buttons。此前,control frame 和纯文本回复均为原始字符串。文本回复现在形如 { "type": "message", "text": "..." }。客户端使用 { "type": "heartbeat-ack" } 确认 heartbeat,n8n 会忽略非 JSON 的传入 frame。
n8n chat widget(@n8n/chat)从 1.31.0 版本起同时兼容这两种格式,托管聊天页面始终加载当前版本的 widget。
该怎么做: 如果构建了直接连接 chat WebSocket 的自定义聊天客户端,请将每个 frame 解析为 JSON,并根据 type 进行处理。如果自行嵌入 @n8n/chat,请在升级 n8n 前将其更新到 1.31.0 或更高版本。
安全
n8n 正在强化安全默认设置,使其开箱即用时更加安全。这些更改可能会影响现有工作流或凭据。
默认启用 encryption key rotation
n8n 3.0 默认启用 encryption key rotation。此前,自托管实例需要主动启用此功能。启用后,n8n 会保留一个 data encryption key,你可以在 Settings 设置 > Data Encryption Keys 数据加密密钥 中轮换它。升级前加密的凭据和其他数据仍可读取,下一次更新记录时,n8n 会使用当前 key 重新加密。
此功能过去一旦启用便无法关闭。从 n8n 2.40.3 起,可以再次关闭。
该怎么做: 无需操作。与任何升级一样,请先备份数据库。
Slack API 凭据要求 signing secret
n8n 3.0 要求 Slack API 凭据包含 signing secret。Slack Trigger 节点会使用它验证传入请求。当包含 Slack Trigger 节点的工作流被发布或 n8n 启动时,n8n 会检查凭据,如果缺少 secret 就停止激活。
何时需要处理取决于你如何使用凭据:
- 包含 Slack Trigger 节点的工作流: 升级前添加 secret。完成前,工作流无法发布。已经发布的工作流在升级后不会激活,并停止接收事件。
- 其他所有 Slack 工作流: 下次编辑凭据时添加 secret。
警告
升级前添加 secret
在 Slack API 凭据包含 signing secret 之前,带有 Slack Trigger 节点的工作流会停止接收事件。
该怎么做:
- 在 Slack app 设置中打开 Basic Information,复制 Signing Secret。
- 将其粘贴到 n8n 中 Slack API 凭据 的 Signature Secret 字段。
- 再次发布工作流。
扩大默认 SSRF 阻止列表
当 N8N_SSRF_PROTECTION_ENABLED 为 true 且 N8N_SSRF_BLOCKED_IP_RANGES 包含 default 时,n8n 3.0 会向内置默认列表新增四个范围:
| 范围 | 说明 |
|---|---|
::/128 |
IPv6 未指定地址 |
100.64.0.0/10 |
共享地址空间(carrier-grade NAT) |
2002::/16 |
6to4 |
64:ff9b::/96 |
NAT64 well-known prefix |
向这些范围内主机发出的请求会失败。
该怎么做: 如果工作流会调用这些范围内的主机,请将其 IP 范围添加到 N8N_SSRF_ALLOWED_IP_RANGES,或将主机名添加到 N8N_SSRF_ALLOWED_HOSTNAMES。请在 N8N_SSRF_BLOCKED_IP_RANGES 中保留 default:它是整个内置列表的关键字,包括 localhost、私有网络和 cloud metadata endpoint。如果用具体范围替换它,就必须自行列出当前内置列表中的每个范围。请参阅启用 SSRF 保护和 SSRF 保护环境变量。
降低 Compression 节点解压限制
N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES 的默认值从 2 GiB 降至 256 MiB,N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES 的默认值从 5,000 降至 1,000。Compression 节点处理超过任一限制的 archive 时会失败。
该怎么做: 如果工作流会解压大于 256 MiB 或包含超过 1,000 个条目的 archive,请在升级到 n8n 3.0 前,将这些变量显式设置为之前的值(2147483648 和 5000)。请参阅节点环境变量参考。
配置
n8n 3.0 会更改部分默认值,并移除仅用于保留旧行为的设置。当实例受到这些变更影响时,n8n 2.x 会在启动时针对每项变更记录弃用警告。
移除 N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION
n8n 3.0 会移除 N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION 环境变量。如果 workflow.preExecute external hook 抛出错误,n8n 不会创建执行记录。由于运行从未开始,因此不会计入 Insights 或 license 用量。无法保留旧行为。
该怎么做: 如果设置了 N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION=true,以便 hook 抛出错误时仍创建失败执行,请在升级到 n8n 3.0 前移除此变量。升级后,n8n 会忽略它。如果依赖这些失败执行记录发出 alert,请改为在 external hook 自身中发出。升级前,Settings 设置 > Migration Report 迁移报告 会显示此实例是否设置了该变量。
存储目录更名
n8n 3.0 首次启动时会将 ~/.n8n/binaryData 重命名为 ~/.n8n/storage,并移除 N8N_MIGRATE_FS_STORAGE_PATH。
警告
如果两个目录都存在,n8n 将无法启动
如果 ~/.n8n/binaryData 和 ~/.n8n/storage 同时存在,n8n 3.0 会停止并报错,而不是猜测要使用哪一个。
该怎么做: 如果在 ~/.n8n/binaryData 挂载了 volume,请改为挂载到 ~/.n8n/storage,或将 N8N_STORAGE_PATH 设置为旧路径以继续使用。如果两个目录都存在,请将 ~/.n8n/binaryData 的内容移入 ~/.n8n/storage,删除 ~/.n8n/binaryData,再启动 n8n。如果使用未挂载 volume 的默认路径,则无需操作。请参阅处理二进制数据。
移除内存二进制数据模式
N8N_DEFAULT_BINARY_DATA_MODE=default 不再有效。仍使用此设置的实例会在升级时切换为 filesystem。
该怎么做: 将 N8N_DEFAULT_BINARY_DATA_MODE 设置为 filesystem、s3、azure 或 database,并确认容器挂载磁盘有足够空间存储二进制数据。请参阅二进制数据环境变量参考。
更改默认值并移除变量
- 默认关闭未经验证的社区包。
N8N_UNVERIFIED_PACKAGES_ENABLED的默认值从true改为false。升级后,你无法从 npm 安装未经验证的社区节点,已安装的节点也会停止加载。 - 该怎么做: 设置
N8N_UNVERIFIED_PACKAGES_ENABLED=true,以继续从 npm 安装未经验证的社区节点;或迁移到经过验证的社区节点。 - 缩短 task runner 超时时间。
N8N_RUNNERS_TASK_TIMEOUT的默认值从300(5 分钟)降至60(1 分钟)。运行时间超过此限制的 Code 节点任务会失败。 - 该怎么做: 如果任务需要运行超过一分钟,请显式设置
N8N_RUNNERS_TASK_TIMEOUT。请参阅 task runner 环境变量。 - 队列模式下的手动执行始终在 worker 上运行。
OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS会被移除。 - 该怎么做: 移除该变量,并检查为 workers 分配的内存,因为 workers 现在也会处理手动执行。请参阅启用队列模式。
- 移除
N8N_DB_PING_TIMEOUT。 n8n 不再回退到此变量。 - 该怎么做: 改为设置
DB_PING_TIMEOUT_MS。请参阅数据库环境变量。 - 移除
N8N_WORKFLOW_TAGS_DISABLED。 工作流标签始终开启,n8n 会忽略该变量。标签关闭期间 n8n 仍保留了标签数据,因此升级后现有标签会重新出现在编辑器和 API 中。 - 该怎么做: 从配置中移除该变量。
退役功能
n8n 3.0 会停用一些遗留或使用率较低的产品功能。n8n 将在存在迁移路径或替代方案时提供指导。
- Chat Hub: n8n 3.0 默认关闭 Chat Hub module。导航中的 Chat 聊天部分会消失,Chat Hub endpoints 也不再响应。聊天 sessions、agents 和 messages 会保留在数据库中。n8n 4.0 将彻底移除此功能。
- 该怎么做: 如果仍需要 Chat Hub,请将
chat-hub添加到N8N_ENABLED_MODULES环境变量。该变量使用逗号分隔列表,因此应保留已经启用的 modules,例如N8N_ENABLED_MODULES=agents,chat-hub。这只会在 n8n 3.x 系列中继续提供 Chat Hub,n8n 会在启动时输出弃用警告。升级前,请前往 Settings 设置 > Migration Report 迁移报告,查看此变更对每个使用 Chat Hub 的实例有何影响。 - 从编辑器中的 URL 导入工作流: n8n 3.0 会移除此功能。Import from URL 从 URL 导入选项会从编辑器 UI 菜单中消失。
- 该怎么做: 使用其他导入方式:复制粘贴、编辑器 UI 菜单中的 Import from File 从文件导入、CLI 或 n8n API。如果你通过 URL 自动导入,请使用 HTTP Request 节点获取工作流 JSON,再通过 n8n API 创建工作流。
- Enable external secrets for project roles 为项目角色启用外部密钥设置:n8n 3.0 会移除此设置。项目 editors 和 admins 现在默认可以访问其项目中的外部密钥。这适用于提供外部密钥功能的 n8n Enterprise。
- 该怎么做: 如果曾使用此设置限制哪些项目角色可访问外部密钥,请在升级前创建具有所需访问权限的自定义项目角色。否则,升级时每个项目 editor 和 admin 都会获得外部密钥访问权限。
- Code 节点中的 Ask AI 标签页: n8n 3.0 会从 Code 节点中移除 Ask AI tab。此前生成的代码会保留在节点中并继续运行。
- 该怎么做: 直接在 Code tab 中编写 JavaScript 或 Python。