n8n 3.0 迁移工具
迁移工具会扫描您的 n8n 实例,列出 n8n 3.0 将要改变的工作流和实例设置,以便您在升级前修复它们。您可以在编辑器中把它作为迁移报告打开,位置是 Settings 设置 > Migration Report 迁移报告。
完整的变更列表请参阅 v3.0 重大变更。

谁可以使用迁移报告
所有用户都可以打开迁移报告,但能看到的内容取决于他们的权限。
| 实例所有者和 admin | 其他用户 | |
|---|---|---|
| 查看工作流问题 | 实例上的每个工作流 | 他们可以编辑的工作流 |
| 查看 Instance issues 实例问题 选项卡 | 是 | 否,不显示该选项卡 |
| 刷新报告 | 是 | 否 |
| 通知工作流所有者 | 是,如果您设置了电子邮件(SMTP) | 否 |
其他用户会在页面顶部看到说明:“This report only includes the workflows you can edit.(此报告只包含您可以编辑的工作流。)”
阅读兼容性摘要
页面顶部的进度条显示有多少工作流与 n8n 3.0 兼容。兼容的工作流在升级后无需更改即可继续运行。您的目标是解决阻碍其余工作流达到兼容的问题,以及实例问题。
您保存工作流时,n8n 会重新检查它,因此报告会随着您修复问题而保持最新。Last updated 上次更新 显示 n8n 上次运行完整扫描的时间。要自行运行完整扫描,请选择 Refresh 刷新。
该工具把问题组织为两个选项卡。
工作流问题
Workflow issues 工作流问题 选项卡列出影响您实例上工作流的变更。每个问题会显示:
- Title and description 标题和描述: 变更内容以及为何重要。
- Impact badge 影响徽章: 该变更如何影响您的工作流。将鼠标悬停在徽章上可查看详情。请参阅影响级别。
- Workflow count 工作流数量: 有多少工作流存在该问题。选择它即可打开该问题的详情页。
- Open count 未解决数量: 其中仍需修复的工作流数量。如果有被标记为不予修复的工作流,其数量会显示在旁边。
- Documentation 文档: 指向 v3.0 重大变更中对应章节的链接。
实例问题
Instance issues 实例问题 选项卡列出影响整个实例的配置变更,例如环境变量和部署设置。实例问题有标题、描述、影响徽章和文档链接,但没有工作流数量,因为它们适用于整个实例。只有实例所有者和 admin 能看到这个选项卡。
影响级别
每个问题都有五个影响级别之一。
| 影响 | 含义 |
|---|---|
| Upgrade blocked 升级被阻止 | 升级无法继续,或者实例在升级后可能无法启动。请先修复此项。 |
| Executions will fail 执行将会失败 | 受影响的工作流或实例在升级后会失败。请更新或替换受影响的节点或设置。 |
| Executions might fail 执行可能会失败 | 默认值发生变化,因此执行可能会失败。请阅读建议以保留当前值。 |
| Behavior changes 行为变更 | 受影响的工作流会继续运行,但行为会不同。请在升级前复查并测试。 |
| Capability removed 功能已移除 | 执行不受影响,但工作流或实例使用的某项功能不再可用。 |
处理工作流问题
选择某个问题上的工作流数量,即可打开它的详情页。该页列出每个受影响的工作流,并显示:
- Name 名称: 选择它即可在编辑器中打开该工作流。
- Owner 所有者: 负责修复的人。请参阅指定所有者。
- Nodes affected 受影响的节点: 存在该问题的节点。选择某个节点即可打开工作流,并定位到该节点。
- State 状态: 该发现项是 Open 未解决、Notified 已通知 还是 Won't fix 不予修复。
- Published 已发布: 工作流是否已上线,以及上次更新的日期。
- Usage 使用情况: 执行次数和上次运行的日期。
要同时对多个工作流操作,请选中每个工作流旁边的复选框。此时会出现批量操作栏,其中有 Migrate 迁移、Notify owners 通知所有者、Mark won't fix 标记为不予修复、Reopen 重新打开 和 Clear selection 清除选择。有些操作只在适用时出现,例如 n8n 可以自动迁移的问题才会显示 Migrate 迁移。

找出要优先修复的工作流
要缩小列表,请使用搜索框、排序菜单和快速筛选(Assigned to me 分配给我、Open 未解决、Won't fix 不予修复、Unassigned 未分配)。选择 Filters 筛选 可按以下条件筛选:
- State 状态
- Last run 上次运行
- Last updated 上次更新
- Number of executions 执行次数
- Status 状态(已发布或未发布)
- Owner 所有者
- Project 项目
按运行次数最多排序,以便先修复最繁忙的工作流。如果某个工作流超过 12 个月没有运行,横幅会提议将其标记为不予修复,以免碍事。
自动迁移工作流
对于某些问题,n8n 可以为您改写受影响的节点。当问题支持此操作时,每一行都会出现 Migrate 迁移 按钮。例如,n8n 可以把 Cron 节点替换为 Schedule Trigger 节点。
要迁移工作流:
- 选择 Migrate 迁移,或选中多个工作流后在批量操作栏中选择 Migrate 迁移。
- 查看 n8n 将更改的节点列表,然后确认。
- n8n 会把结果保存为该工作流的新版本。已发布的工作流会继续运行当前版本,直到您发布新版本。
- 选择 Publish 发布 使迁移后的版本上线,或选择 Skip publishing 跳过发布 先进行复查。
请在发布之前测试迁移后的工作流。自动迁移只涵盖节点变更,因此请检查工作流的输出是否仍符合您的预期。
指定所有者
每个工作流都可以有一个所有者,即负责修复它的人。n8n 会建议最后处理过该工作流的用户;如果没有特别突出的单个用户,则会建议该工作流所属项目的一位所有者。要更改它,请在 Owner 所有者 列中选择当前所有者,再挑选另一位用户。
通知所有者
实例所有者和 admin 可以就某个问题向工作流所有者发送电子邮件。在某一行上选择 Notify owner 通知所有者,或选中多个工作流后选择 Notify owners 通知所有者。该工作流的状态会变为 Notified 已通知。要再次发送电子邮件,请选择 Remind 提醒。
通知需要在实例上设置电子邮件(SMTP),并且工作流上的所有者要有电子邮件地址。通知不会解决问题。在您修复它或将其标记为不予修复之前,该工作流仍计为未解决。
将工作流标记为不予修复
如果您不打算修复某个工作流(例如因为它已经过时),请把它的状态设为 Won't fix 不予修复。此后它会计为已解决,不再显示为未解决。选择 Reopen 重新打开 即可撤销。如果您后来修复了该问题,n8n 会把它从报告中移除。
导出报告
选择 Export CSV 导出 CSV 即可把概览下载为 CSV 文件。用它来分享迁移进度,例如分享给 n8n 支持人员。导出内容与您在报告中看到的工作流和问题相同。
该文件中每个问题占一行。实例合计会在每一行重复,因此该文件可以直接在电子表格中打开。各列如下:
| 列 | 描述 |
|---|---|
target_version |
报告所对照检查的 n8n 版本。 |
current_version |
您的实例正在运行的 n8n 版本。 |
synced_at |
n8n 上次运行完整扫描的时间。 |
total_workflows |
报告中的工作流数量。 |
affected_workflows |
至少有一个未解决问题的工作流数量。 |
affected_instance_rules |
实例问题的数量。 |
rule_kind |
该行是工作流问题还是实例问题。 |
rule_id |
该问题的 ID。 |
rule_title |
该问题的标题。 |
impact |
作为标识符的影响级别,例如 executionsFail。 |
impact_label |
报告中显示的影响级别,例如 “Executions will fail(执行将会失败)”。 |
unresolved_workflows |
该问题处于未解决或已通知状态的工作流数量。 |
wont_fix_workflows |
被标记为不予修复的工作流数量。 |
空报告的含义
| 选项卡 | 为空的含义 |
|---|---|
| Workflow issues 工作流问题 | 您的所有工作流都与 n8n 3.0 兼容。请接着检查 Instance issues 实例问题。 |
| Instance issues 实例问题 | 您的实例配置已为 n8n 3.0 做好准备。请接着检查 Workflow issues 工作流问题。 |
| 两者 | 该工具没有发现需要修复的内容。请查阅 v3.0 重大变更,了解该工具无法检测的变更,然后再升级。 |
推荐流程
- 评估。 查看兼容性摘要,然后浏览两个选项卡,了解有多少工作。
- 从影响最高的问题开始。 先修复 Upgrade blocked 升级被阻止 和 Executions will fail 执行将会失败,然后是 Executions might fail 执行可能会失败、Behavior changes 行为变更 和 Capability removed 功能已移除。
- 修复工作流问题。 打开每个问题,迁移或编辑受影响的工作流,并在开发环境中测试它们。
- 修复实例问题。 按照每个问题的说明更新环境变量和服务器配置。
- 验证。 实例所有者和 admin 选择 Refresh 刷新 以运行完整扫描。其他用户重新加载报告,报告会反映他们保存过的工作流。确认没有剩余的未解决问题,并且兼容数量与报告中的工作流总数一致。
- 升级。 升级到 n8n 3.0。