Guide / Share and move
从 Camunda 7 迁移到 Camunda 8
迁移助手会显示 Camunda 7 项目中哪些内容无法直接迁移到 Camunda 8,转换能转换的部分,并生成一份可以交给他人的报告。
目的与适用对象
Camunda 7 Community Edition 已经停止维护。使用它的团队必须决定是否迁移到 Camunda 8,然后付诸实施:流程图、决策、表单,以及它们背后的 Java 代码。迁移助手在您的工具中、在代码旁边,完成分析工作和大部分转换工作。
它适用于 Camunda 7、Operaton 和 CIB seven 项目。这两个分支都按 Camunda 7 源项目读取,因为它们的流程图使用相同的 camunda: 命名空间。
哪些免费,哪些属于 Pro
| 部分 | 方案 |
|---|---|
| 分析:哪些内容无法直接迁移、原因、怎么做、由谁来做 | Free |
| 迁移报告,Markdown 格式和单个 HTML 页面 | Free |
| 转换流程图、决策或表单,带预览 | Pro,在流水线中需要 Team |
| 根据您的 delegate 生成的 job worker 骨架 | Pro |
迁移工作区和 penstock migrate plan:每项变更,附带类别和原因 | Free |
只写入您接受的变更(migrate apply --write) | Pro |
penstock migrate verify:在两个引擎上运行相同的场景并进行比较 | Pro,在流水线中需要 Team。前 3 个场景免费。 |
penstock migrate agents:将 AI 智能体迁移到 8.10 模板 | 预览免费,限前 3 个元素。--write:Pro |
查看哪些内容无法直接迁移
- 打开一张 Camunda 7 流程图。
- 点击工具栏上的 Migrate to Camunda 8。对于 Camunda 7、Operaton 和 CIB seven 流程图,它默认固定在工具栏上,也可以取消固定,放回 More 菜单。
- 侧边栏的 Problems 标签页会打开并定位到 Migrate to Camunda 8 分组。它会显示例如 7 to do, 3 to check, 19 convert unchanged 这样的内容。再次点击 Migrate to Camunda 8 即可关闭。
- 阅读各个分组,每组都带有计数:Needs work(需要人工处理)、Review after converting(由 Penstock 转换,您来检查),以及默认折叠的 Convert unchanged(可以精确转换的内容)。如果流程图在其他分组中没有问题,标签页顶部仍会显示 No problems found.
- 点击某一行,画布上对应的元素会被选中。每一行都说明了问题是什么、原因以及处理方法。

该分组只针对一张流程图。对于整个项目(一次处理所有文件),Penstock 会列出每个文件的状态(ready、converts、needs work、blocked)和检查结果,以及 Java 代码中每个类将变成什么。
迁移整个项目
JetBrains
打开 Penstock 工具窗口,找到 Migrate to Camunda 8。它列出每个文件的状态和检查结果,以及 Java 代码中每个类将变成什么。右键点击一个文件并选择 Convert to Camunda 8…,或者在根节点上使用 Convert All…。
VS Code
不可用于 VS Code. VS Code 暂不支持 Camunda 7 到 Camunda 8 的转换,也没有显示它的项目列表。请在命令行中使用 penstock migrate。
Command line
$ penstock migrate .
ready src/main/resources/approve-order.form 1 convert
needs work src/main/resources/order-process.bpmn 1 to do, 8 convert
error migration/message-catch: Shipment confirmed: The message shipment-confirmed needs a correlation key. ...
error migration/delegate-expression: Send receipt: Delegate ${sendReceipt} becomes the job type sendReceipt. ...
ready src/main/resources/shipping-method.dmn 1 convert
3 files to migrate for Camunda 8.8: 2 ready, 0 convert, 1 need work, 0 blocked.
Job workers to write: 2
migrate、migrate analyze:列出无法直接迁移的内容。有错误时,或使用--fail-on warning且有警告时,退出码为 1。免费。migrate convert:转换文件。它会把 Camunda 8 文件写入所给文件夹旁边的camunda-8文件夹,或写入--out <dir>,原始文件保持不变。请先使用--dry-run。属于 Pro,在流水线中需要 Team。migrate report:生成报告。免费。--target 8.5到8.9、--format text|json|sarif|github、--baseline、--update-baseline、--verbose。
转换后的文件夹会带有它自己的 penstock.yaml,其中写明 engine: camunda-8,Camunda 7 文件的 penstock.yaml 不会被改动。参见所有命令。
术语含义
| 文件状态 | 含义 |
|---|---|
| Ready | 无需任何处理。 |
| Converts | 由 Penstock 转换,剩余部分需要检查。 |
| Needs work | 其中一部分需要人工处理。 |
| Blocked | 它用到了 Camunda 8 中没有对应形式的内容。 |
| 检查结果的标记 | 含义 |
|---|---|
| Converts | Penstock 会精确转换它。 |
| To check | 由 Penstock 转换,再由人工检查结果。转换后该检查结果仍会保留。 |
| To do | Penstock 不做处理,只在对应元素上做标记,由人工完成。 |
在流水线中
分析无需编辑器即可运行,因此当项目中仍有 Camunda 7 流程图时,可以用它作为流水线的关卡。
| 选项 | 作用 |
|---|---|
--target <version> | 用于检查的 Camunda 8 目标版本,默认为 8.8。 |
--format text|json|sarif|github | 以表格、JSON(包含工作量统计和阻塞项)、SARIF 或变更行上的注解形式输出检查结果。SARIF 和注解属于 Pro,在流水线中需要 Team。 |
--fail-on error|warning | 决定哪些情况使退出码为 1。错误总是会;使用 warning 时,警告也会。 |
--baseline、--update-baseline | 只在出现自上次 --update-baseline 以来新增的问题时失败,该选项会在项目根目录写入 penstock-migration-baseline.json。属于 Pro,在流水线中需要 Team。 |
--verbose | 同时列出说明性条目,即只会原样迁移的内容。 |
检查哪些内容
- 实现。Java 类、delegate expression、表达式或 external task topic 会变成一个 job type。在有 worker 之前,没有任何东西会执行这个 job,所以在您编写 worker 之前,这都是一个错误。
- 监听器。执行监听器和任务监听器会变成 job type,分别适用于 Camunda 8.6 及以后版本(执行监听器)和 8.8 及以后版本(任务监听器)。更早的目标版本会得到一个标记。
- 表达式。JUEL 会变成 FEEL,但只在结果完全精确时才转换。拒绝转换时会注明原因。
- 脚本。Groovy 和 JavaScript 脚本无法在 Camunda 8 中运行。请改写为 FEEL,或移到 job worker 中。
- 表单。生成的表单会变成 Camunda Forms,写在流程图旁边,绝不会覆盖已有的表单。嵌入式表单在 Camunda 8 中没有对应形式。
- 消息。消息需要一个关联键。
- 调用的流程、决策、多实例循环、定时器、错误、重试和优先级:每一项都有自己的规则,并附有指向 Camunda 文档的链接。
- Java 代码。每个 delegate、external task handler 和监听器都会被追溯到其源代码,以及它将变成什么。
迁移工作区
工作区列出转换到 Camunda 8 时会进行的每一项变更,按文件列出,BPMN 还会按元素列出。每项变更都显示当前内容、转换后的内容、类别和原因,并配有复选框、实时计数和工作量估算。
| 自动转换 | 结果含义不变。 |
| 转换后含义有变化 | Penstock 会转换它;由您判断新的含义是否正确。 |
| 需要人工处理 | 无法精确转换。 |
| 保持原样 | 原样迁移,不做改动。 |
在 Penstock Web 中,它位于命令面板里。
各工具中迁移工作区的位置
JetBrains
迁移工作区位于 Penstock 工具窗口和 Tools 菜单中。
VS Code
使用 Migration workspace 命令。
Command line
penstock migrate plan 列出各项变更及其 id,penstock migrate apply --only 应用所选的变更。参见 migrate。
Apply selected 只以原子方式写入已接受的变更。和以前一样,它会拒绝已被修改的文件和符号链接。被拒绝的元素会逐字节保持原样。只有当您选择 Save selection 时,所选内容才会保存在 .penstock/migration-selection.json 中。
penstock migrate plan --format json src/orders
penstock migrate plan --only ID1,ID2 --save-selection
penstock migrate apply --saved --write
penstock migrate apply --only ID1,ID2 --exclude ID3 --write
migrate plan 列出各项变更的 id,不写入任何内容,除非您使用 --save-selection 要求保存所选内容。migrate apply 接受 --only、--exclude 和 --saved。计划中不存在的 id、空列表或过长的 id 会在写入任何内容之前被拒绝。migrate_apply MCP 工具接受 only 和 exclude。
转换
Pro
- 在 Problems 标签页的 Migrate to Camunda 8 分组中,点击 Convert。您的工具也可以转换单个文件或项目中的所有文件。
- 流程图会在可视化流程图差异对比中左右并排打开两次:转换前和转换后,各自居中显示在自己的窗格中,共用一个标题。预览还会显示 Camunda 8 文件将要写入的文件夹,即被转换文件夹旁边的
camunda-8,您可以在预览中修改它,也可以用--out指定。此时还不会写入任何内容。 - 阅读变更内容,然后点击 Convert。Camunda 7 文件保持不变,新文件会带有它们自己的
penstock.yaml,其中写明engine: camunda-8。 - 如果目标文件夹中已有转换过的文件,也不会卡住:预览会提供 Replace the files in <folder> 选项,当该文件夹不在版本控制之下时会给出警告,只有在您勾选后才会覆盖这些文件。
Penstock 无法精确转换的内容会保留在文件中,并在对应元素上用 conversion:message 标记,Camunda Modeler 也能读取这个标记。它同时仍作为一条检查结果保留。重复转换不会再产生任何变化。
Job worker 骨架
Pro
每个 Java delegate、external task handler 或监听器都会被追溯到其源代码,并给出文件、行号以及它将变成什么。Penstock 可以在代码旁边生成一个骨架:Spring job worker、Node worker 或 Python worker。骨架根据代码读取和写入的变量以及它抛出的 BPMN 错误生成。Penstock 绝不会覆盖已有文件。
在您的工具中生成骨架
JetBrains
在工具窗口中依次打开 Migrate to Camunda 8 和 Code。右键点击一项并选择 Job Worker Skeleton…(Spring)、Node Worker Skeleton… 或 Python Worker Skeleton…。属于 Pro。
VS Code
不可用于 VS Code. Job worker 骨架只能在 JetBrains IDE 中生成,VS Code 暂不支持。penstock migrate 会打印需要编写的 job worker 数量。
Command line
不可用于 Command line. 骨架只能在 IDE 中生成。penstock migrate 会打印需要编写的 job worker 数量。
报告
报告包括 Markdown 格式和一个自包含的 HTML 页面。
在您的工具中生成报告
JetBrains
在工具窗口中 Migrate to Camunda 8 的根节点上点击 Migration Report。
VS Code
在 Penstock 视图中 Migrate to Camunda 8 的根节点上点击 Migration Report。
Command line
$ penstock migrate report .
wrote migration-report.md
wrote migration-report.html
使用 --out <dir> 选择输出文件夹。
HTML 是一个面向管理者的自包含页面:范围、迁移的成本(需要编写的 job worker、需要改写的表达式、需要替换的脚本、需要迁移的监听器、需要重建的表单、调用的流程、决策)、各文件及其状态,以及代码。
检查转换后的流程行为是否一致
Pro 前 3 个场景免费。
penstock migrate verify --original-profile c7-test --converted-profile c8-test src/orders
它在一个测试引擎上用原始的 Camunda 7 流程图(或 Operaton、CIB seven)运行项目中保存的场景,在另一个测试引擎上用转换后的 Camunda 8 流程图运行同样的场景。对每个场景,它会报告:
- EQUIVALENT;
- DIFFERS,并给出第一个分歧点和两边的执行轨迹;
- NOT COMPARABLE,并给出原因。
它会通过转换生成的 id 映射比较元素路径,并比较最终状态、incident,以及变量的名称和值。所有场景都等价时退出码为 0,至少有一个不同时为 1,有内容无法比较或因被拒绝而没有运行任何内容时为 2。
两个引擎都必须标记为 deployment.forTests。不会在共享引擎或生产引擎上运行任何内容。如果转换添加了可执行内容,运行会被拒绝,直到您用 --run-unreviewed 或工作区中的按钮确认为止,该按钮会列出添加了哪些内容。密钥的值绝不会出现在结果中。工作区会在每个结果旁边显示它涉及的变更,并带有一个汇总横幅。migrate_verify MCP 工具为智能体提供同样的功能。
AI 智能体
penstock migrate agents [paths] 会按照新模板中声明的迁移规则,把 AI 智能体元素从 8.9 及更早的模板版本迁移到 8.10 的智能体任务模板和智能体子流程模板。默认只做演练(dry run)。无法证明映射正确的元素会保持不变,并与原因一起列出。预览中的前 3 个元素免费;--write 以原子方式替换文件,属于 Pro。migrate_agents MCP 工具提供同样的功能。参见 Camunda 8 的 AI 智能体。
它不做什么
- 它不迁移正在运行的实例或历史数据。实例可以在 Camunda 7 上运行结束,也可以用 Camunda 的 Data Migrator 迁移。Data Migrator 要求元素 id 保持不变,转换器会保留这些 id。
- 它不改写您的 Java 代码。请在构建中使用 Camunda 迁移指南里的 OpenRewrite recipe,这样评审者能看到差异。迁移助手会在旧代码旁边编写新文件。
- 它从不猜测。凡是无法精确转换的内容,它都会做出标记。
常见问题
- 没有 Migrate to Camunda 8 按钮。
- 它只对 Camunda 7、Operaton 和 CIB seven 流程图显示。Camunda 8 或 Classic BPMN 流程图没有这个按钮。该分组会显示 Nothing to convert: this is not a Camunda 7 diagram.
- 点击 Convert 时提示我购买 Pro。
- 转换是 Pro 功能。分析和报告免费。参见方案与许可证。
- 转换后,检查仍然列出了一些结果。
- 这些是需要人工处理或检查的内容。在您修复之前,它们会一直留在对应元素上。
- “Unknown target”。
- 请使用 8.5、8.6、8.7、8.8 或 8.9。
- “There is nothing to migrate”。
- 在您指定的路径中没有找到 Camunda 7 流程图、决策或表单。