camunda-process-mgmt

Camunda 流程管理

通过 c8ctl 对 Camunda 8.8+ 集群进行运行时操作：部署资源、启动实例、检查状态、解决事故、完成任务、发布消息、取消实例。一个技能，涵盖模型编写完成后的所有操作。

前提条件

• Camunda 8.8+ 集群（通过 c8run 本地运行、SaaS 或 Self-Managed）
• 已安装 c8ctl CLI，并配置了适用于目标集群的配置文件；设置方法请参阅 camunda-c8ctl

交叉引用

• camunda-c8ctl：用于设置 c8ctl、保障集群安全以及了解通用约定（标志、配置文件、输出模式）
• camunda-bpmn：用于修复调试时发现的 BPMN 流程问题
• camunda-dmn：用于修复 DMN 决策问题——EXTRACT_VALUE_ERROR / DECISION_EVALUATION_FAILED 事故通常可追溯到决策文件
• camunda-connectors：用于修复调试时发现的连接器配置问题
• camunda-job-workers：当事故可追溯到处理程序代码而非流程模型时使用——对应 zeebe:taskDefinition type 的 Worker 端
• camunda-connectors-development：当事故可追溯到自定义连接器的运行时、注册或托管，而非其模板配置时使用
• camunda-feel：用于诊断事故中的 FEEL 求值错误（EXTRACT_VALUE_ERROR、CONDITION_ERROR）
• camunda-process-test：用于针对嵌入式 Zeebe 引擎测试流程

说明

部署资源

集群安全——部署到 c8run 本地集群以外的任何环境之前，都应先征求用户确认。

当前全局激活的 c8ctl 配置文件可能仍指向之前会话使用的共享集群（prod、staging、客户名称等）。此时直接运行 c8ctl deploy process.bpmn 会在不提示的情况下将资源部署到该集群。

• 首先运行 c8ctl which profile。如果配置文件名称表明它指向共享环境，请在部署前向用户确认。
• 在 deploy 和其他会修改状态的命令（run、cancel、resolve、complete、publish、watch）中，始终显式传入 --profile=<name>。
• 对于验证性部署（仅运行一次变更以检查是否有效），优先使用运行中的 c8run 集群，并指定 --profile=local；如果 c8run 未运行，则运行 c8ctl cluster start。

集群安全的权威规则请参阅 camunda-c8ctl。

示例——将单个 BPMN 文件部署到本地配置文件：

c8ctl deploy process.bpmn --profile=local

一次部署多个资源（BPMN、DMN、表单）：

c8ctl deploy process.bpmn decision.dmn approval-form.form

部署整个目录（递归）：

c8ctl deploy ./my-project

部署前检查（推荐）：

1. 部署前对 BPMN 进行 lint 检查：

   c8ctl bpmn lint process.bpmn
   

2. 如果存在 DMN 和表单文件，则先验证这些文件（请参阅 camunda-dmn 和 camunda-forms 工作流），然后仅部署已准备就绪的资源。

Spring Boot 资源树提示：

• 对于将可部署资源放在 src/main/resources/ 下的项目，优先显式部署 processes/、decisions/ 和 forms/ 路径。
• 如果父目录 src/main/resources 中包含不可部署文件（application.yaml、application.properties 等），请避免直接部署整个目录。

示例：

c8ctl deploy \
  src/main/resources/processes \
  src/main/resources/decisions \
  src/main/resources/forms \
  --profile=local

部署后进行验证：

c8ctl list pd
c8ctl search pd --iname="MyProcess"

每次部署都会为其中包含的所有资源创建一个新版本。使用 c8ctl list pd --fields Key,Name,Version 查看版本。

启动流程实例

根据意图选择启动命令：

需求	命令
启动后立即返回（默认）	c8ctl create pi --id <bpmnProcessId> [--variables '{...}']
一次性完成部署和启动	c8ctl run <file.bpmn> [--variables '{...}']
启动并阻塞，直到完成	c8ctl await pi --id <bpmnProcessId> [--variables '{...}']

为已部署的流程创建实例：

c8ctl create pi --id MyProcess

使用输入变量：

c8ctl create pi --id MyProcess --variables '{"orderId": "ORD-123", "amount": 1500}'

--id 对应 <bpmn:process id="...">（BPMN 流程 ID），而不是数字形式的流程定义键。

一步完成部署和启动：

c8ctl run process.bpmn --variables '{"orderId": "ORD-123"}'

启动并阻塞，直到实例完成（适用于测试／冒烟检查）：

c8ctl await pi --id MyProcess --variables '{"orderId": "ORD-123"}'

使用自定义请求超时时间：

c8ctl await pi --id MyProcess --requestTimeout 60000

不适用于长时间运行的活动。 await pi 使用集群的启动并等待 REST 端点；如果某项活动的运行时间超过请求超时时间（例如 LLM Agent、缓慢的 HTTP 调用、用户任务），该端点会超时。超时响应不包含实例键，因此你无法跟进部分运行状态。对于此类流程，请使用 c8ctl create pi，并轮询 c8ctl get pi <key> 直至进入终止状态；或者在 await 失败后，使用 c8ctl search pi --state=ACTIVE 找回遗留实例。

编写脚本时，使用 --json 运行 create pi，提取返回的 key 字段（流程实例键），然后将其用于后续操作（c8ctl get pi <key>、c8ctl cancel pi <key>，以及按流程实例键查询事件）。

监视模式（开发）

在本地开发期间，文件发生变化时自动重新部署：

c8ctl watch ./my-project

监视 .bpmn、.dmn 和 .form 文件，并在保存时重新部署。

检查流程实例

列出活动实例：

c8ctl list pi

按流程名称搜索（前缀 i 表示不区分大小写的子字符串匹配）：

c8ctl search pi --iprocessDefinitionName="MyProcess"

获取包含变量的实例详情：

c8ctl get pi <instanceKey> --variables

转储特定实例的变量值（使用 --fullValue 避免截断）：

c8ctl search variables --processInstanceKey=<key> --fullValue

获取流程定义已部署的 BPMN XML：

c8ctl get pd <key> --xml

处理事件

当发生无法恢复的故障（FEEL 错误、缺少变量、连接器故障、作业超时且重试次数耗尽）时，集群会通过事件暂停实例。处理前务必先检查。

第一步排查——用户报告“实例 X 卡住了”时，依次运行以下四项，在决定是否处理之前先进行评估：

PI=<instanceKey>
c8ctl get pi $PI                                              # state (ACTIVE = stuck on a step), processDefinitionId
c8ctl search inc --processInstanceKey=$PI                     # any incidents on this PI, with errorType
c8ctl search variables --processInstanceKey=$PI --fullValue   # variables at the failure point
c8ctl get inc <incidentKey> --json                            # full error message

通常仅凭这四项就能定位问题，无需打开 Operate。

列出活动事件：

c8ctl list inc
c8ctl search inc --state=ACTIVE

按错误消息筛选：

c8ctl search inc --ierrorMessage="Connection refused"

流程发生事件时的调试工作流：

1. 查找事件并查看错误类型和消息：

   c8ctl search inc --state=ACTIVE
   

2. 检查实例在故障点的变量：

   c8ctl search variables --processInstanceKey=<key> --fullValue
   

3. 找出根本原因。常见类别包括：

   • FEEL 错误（EXTRACT_VALUE_ERROR / CONDITION_ERROR）→ 参考 camunda-feel 修复表达式；检查是否存在点号变量名遮蔽或空值输入
   • 作业工作器缺失或超时 → 检查 <zeebe:taskDefinition type="..."> 是否与正在运行的工作器匹配
   • 连接器配置错误 → 参考 camunda-connectors 修复元素模板绑定
   • BPMN 逻辑错误 → 参考 camunda-bpmn 修复并重新部署

4. 修复根本问题（编辑 BPMN、重新配置连接器、修复工作器或更正变量）。

5. 处理事件以重试失败的步骤：

   c8ctl resolve inc <incidentKey>
   

未修复根本原因就处理事件，只会再次触发相同的事件。务必先修复。

完成用户任务

列出待处理的用户任务：

c8ctl list ut

使用输出变量完成任务：

c8ctl complete ut <taskKey> --variables '{"approved": true, "comments": "Looks good"}'

变量键必须与表单组件的 key 值匹配（参见 camunda-forms）——额外的键会被忽略；缺少必填键会阻止后续完成。

发布关联消息

发布消息以唤醒实例中等待的消息事件：

c8ctl publish msg <messageName> --correlationKey=<key> --variables '{"status": "approved"}'

关联键必须与从流程的消息订阅表达式中解析出的值匹配（通常是基于变量的 FEEL 表达式，例如 =orderId）。

取消实例

c8ctl cancel pi <instanceKey>

生产监控循环

使用这个轻量级循环持续检查流程健康状况：

1. 扫描活动事件 — 命令会返回一个扁平的 JSON 列表；在工具或 shell 中按 errorType / elementId 分组或筛选：

   c8ctl search inc --state=ACTIVE --json --fields=key,errorType,errorMessage,elementId,processInstanceKey
   

2. 判断事件是否反复出现：检查扁平列表，查看多个实例中是否存在重复的 elementId 和相似的 errorMessage 值。反复出现表明流程、模型或工作进程存在缺陷，而非一次性的运行时故障。

3. 结合变量和实例状态进行分析：至少检查一个失败示例：

   c8ctl get pi <instanceKey>
   c8ctl search variables --processInstanceKey=<instanceKey> --fullValue
   c8ctl get inc <incidentKey> --json
   

4. 实施最小化的根因修复，然后解决一个事件，并确认新实例不再以相同方式失败。重复执行第 1 步，直到扁平列表中不再出现此类活动事件。

对于 SLA 和吞吐量趋势（而不仅仅是事件排查），请将此运行手册与指标工具（Operate/Optimize 仪表板）配合使用，并将发现反馈到 BPMN 变更或工作进程可靠性改进中。

用于脚本的 JSON 输出

每次调用时传递 --json，也可以使用 --fields 缩小范围。不要切换整个会话的输出模式 — 关于原因，请参阅 camunda-c8ctl。

c8ctl list pi --json --fields=key,state,bpmnProcessId
c8ctl list pd --json --fields=key,bpmnProcessId,version
c8ctl get inc <key> --json

故障排查

部署失败 — 首先运行 c8ctl bpmn lint process.bpmn（参见 camunda-bpmn）。大多数部署错误都能在部署前被检查器发现。

流程无法启动 — 确认流程 ID 与已部署的定义匹配（c8ctl list pd）。检查必需的输入变量。

实例停滞在服务任务上 — 该任务类型没有注册工作进程、工作进程崩溃，或作业超时并超过最大重试次数。检查 c8ctl list jobs --processInstanceKey=<key>，并确认有工作进程正在处理匹配的任务类型。

重复出现相同的事件 — 你只是在解决事件，却没有修复问题。每次都要阅读错误消息；如果内容没有变化，说明根因尚未解决。