Conductor 持久化工作流生产路径从本地成功运行到可运维生产服务的完整指南【免费下载链接】conductorConductor is an event driven agentic workflow engine providing durable and highly resilient execution engine for applications and AI Agents项目地址: https://gitcode.com/GitHub_Trending/co/conductor导读本文是 Conductor 中把本地跑通的工作流升级为可长期运行的生产服务的实操路线图。它围绕 docs/devguide/workflows/production-path.md 给出的五个生产阶段——定义契约、明确故障策略、测试真实边界、安全部署、运维执行——展开并深入结合本仓库的源码与配套文档说明每一条建议背后的实现机制。读完本文你将掌握如何为工作流建立可被调用方依赖的输入/输出契约、如何为每个外部副作用设计可重复的故障行为、如何在发布前测试真实边界、如何安全地滚动版本以及如何在事故发生时定位、检查并恢复一次执行。前置条件建议先完成 docs/quickstart/first-workflow.md 中基于内置系统任务HTTP、JSON_JQ_TRANSFORM的两步工作流理解定义注册—启动执行—查看结果的基本闭环再进入本文的生产化改造。生产路径全景五阶段路线图原文档将生产化过程归纳为五个阶段每一阶段都对应一个可验证的产出阶段核心动作交付物1. 定义契约把工作流定义与outputParameters当作 API 对待调用方可知的输入/输出契约2. 明确故障策略为每个外部副作用设计重试、幂等与超时行为有界且可预期的失败语义3. 测试真实边界用代表性输入测试已注册的定义而非只测 worker 函数覆盖成功/重试/终态失败/超时/幂等的验证记录4. 安全部署先部署 worker 与任务定义再切流量按版本滚动无中断的版本发布与排空5. 运维执行约定命名、版本、关联 ID 与负责人监控并演练恢复可被定位、检查与恢复的执行体系这与 docs/devguide/workflows/index.md 中描述的工作流生命周期一一对应Build构建定义→ Register注册版本→ Trigger启动触发→ Execute持久化执行→ Observe检查运维→ Evolve版本演进。生产路径本质上就是让这一生命周期中的每个环节都显式化、可审计、可恢复。关键前提是 Conductor 的定义与执行分离模型工作流定义声明了任务顺序与数据流而工作流执行是蓝图的单次运行拥有自己的 ID、输入和历史。因为二者分离修改定义永远不会改写已运行执行的历史——这正是版本演进与安全部署的基础具体语义见 docs/devguide/concepts/workflows.md 与 docs/architecture/durable-execution.md。阶段一把工作流定义当作 API 来定义契约契约的两个锚点输入声明与 outputParameters在生产中工作流定义的第一职责是成为一份稳定的接口契约。一个最小但完整的定义应显式声明inputParameters工作流期望的输入键清单outputParameters输出键到表达式通常引用任务输出的映射调用方据此消费结果tasks任务配置序列任务之间通过taskReferenceName引用彼此的输出。参考 docs/devguide/how-tos/Workflows/creating-workflows.md 中的最小示例结构{ name: order_flow, version: 1, schemaVersion: 2, inputParameters: [orderId], tasks: [ { name: process_order, taskReferenceName: process_order_ref, type: SIMPLE, inputParameters: { orderId: ${workflow.input.orderId} } } ], outputParameters: { status: ${process_order_ref.output.status} } }原文档强调的要点是把工作流定义连同其outputParameters视为一个 API。这意味着三件事文档化必需输入在定义中用inputParameters声明期望的输入键并配套文档说明格式与约束。在边界处校验对非法请求要能拒绝而不是让非法输入流经整条任务链后在某个深处以晦涩的方式失败。保持输出稳定调用方依赖outputParameters的键名与结构跨版本保持稳定当变更不向后兼容时注册新版本而不是原地修改活跃定义。动态引用语法契约的数据流基础输入输出契约在运行时通过动态引用表达式完成数据传递语法为${type.jsonpath}。参考 docs/devguide/how-tos/Tasks/task-inputs.md核心引用类型包括引用形式含义${workflow.input.key}当前工作流的输入参数${workflow.variables.key}工作流变量由 SET_VARIABLE 任务写入${taskReferenceName.output.key}某任务按引用名的输出参数${taskReferenceName.input.key}某任务的输入参数${workflow.workflowId}、${workflow.correlationId}、${workflow.version}执行 ID、关联 ID、版本号在定义契约阶段务必逐个核对outputParameters中每个表达式引用的任务输出是否确实存在、类型是否一致。若引用表达式格式错误或引用的任务输出在引用点尚未解析参数值会变成错误数据或 null——这类问题应在发布前通过真实执行暴露而不是留给调用方在生产中踩坑。向后不兼容时的新版本注册当输入、输出、任务顺序或失败语义发生调用方可观察的变化时不要原地修改正在被调用的定义版本而是递增version字段并注册新版本。版本化的运行时语义是每次执行在启动时引用工作流定义的一个快照此后对定义的任何修改都不会影响已运行执行。这一机制在 docs/devguide/how-tos/Workflows/versioning-workflows.md 中有完整说明并可从 docs/architecture/durable-execution.md 的故障矩阵中得到印证运行中的执行继续使用启动时的定义快照新执行使用更新后的定义零停机升级。阶段二把故障策略显式化原文档给出的原则是对每一个外部副作用都要先回答两个问题——它是否安全重试如何让它幂等然后再决定重试行为与超时配置并在需要业务回滚时引入故障工作流failure workflow或补偿逻辑。至少一次交付与幂等 WorkerConductor 对任务采用at-least-once至少一次交付网络分区、worker 重启、响应超时都可能导致同一任务被投递多次。因此 worker 必须以幂等为默认设计。常见模式见 docs/devguide/bestpractices.md模式适用场景幂等键将workflowId taskId作为唯一键传给下游服务由下游去重Upsert 而非 Insert重复写入收敛到同一状态Check-then-act执行前查询当前状态已完成则跳过幂等 HTTP 方法下游支持时优先 PUT 而非 POSTworkflowId与taskId的组合在每次任务执行尝试内唯一是理想的幂等键来源。幂等不是可选项只要 worker 可能被重复调用就必须保证执行两次与执行一次结果相同且无副作用。超时与重试参数的刻意配置任务定义中的超时参数是故障边界的主要控制面完整字段契约见 docs/documentation/configuration/taskdef.md。核心规则与推荐起点responseTimeoutSecondstimeoutSeconds前者是心跳窗口用于探测无响应的 worker后者是任务的整体 SLA。timeoutSeconds为 0 表示不设超时responseTimeoutSeconds为 0 表示禁用响应超时仅适合由外部完成的任务如 WAIT/HUMAN。retryLogic支持FIXED、EXPONENTIAL_BACKOFF、LINEAR_BACKOFF配合retryDelaySeconds计算基础延迟maxRetryDelaySeconds封顶延迟backoffJitterMs引入抖动防止惊群。参考 docs/devguide/bestpractices.md 的推荐配置矩阵任务模式responseTimeoutSecondstimeoutSecondstimeoutPolicyretryCountAPI 调用预期 5s1030RETRY3ML 推理120300RETRY1人工审批0禁用86400ALERT_ONLY0批处理6003600TIME_OUT_WF0快速数据转换515RETRY3超时策略决定超时后的动作RETRY按retryCount重试任务瞬态失败如网络、外部 APITIME_OUT_WF立即失败整个工作流任务至关重要且重试无意义如过期批窗口ALERT_ONLY标记任务超时但保持工作流运行人工参与或外部完成信号的任务。重试逻辑决定两次重试间的延迟FIXED恒定间隔EXPONENTIAL_BACKOFF按retryDelaySeconds × 2^attemptNumber递增适合限流 API 与过载服务LINEAR_BACKOFF按retryDelaySeconds × attemptNumber线性递增适合中等恢复场景。最终延迟公式为delay clamp(computedDelay, 0, maxRetryDelaySeconds) random(0, backoffJitterMs) ms见 docs/documentation/configuration/taskdef.md 的重试逻辑小节。cookbook/task-timeouts-and-retries.md 提供了几个可直接注册的完整任务定义配方例如带封顶与抖动的指数退避、长任务心跳租约续期callbackAfterSeconds、以及用totalTimeoutSeconds强制硬 SLA——它是独立于retryCount的墙钟总预算谁先到达谁生效。当业务操作有最大可接受时长时还应给工作流本身设置timeoutSeconds与timeoutPolicy工作流级支持TIME_OUT_WF与ALERT_ONLY把整个执行也约束在有界时间内。失败工作流与 Saga 补偿当后续失败需要业务回滚时用failureWorkflow声明补偿工作流主工作流失败后Conductor 自动触发它。可在主定义中同时指定failureWorkflowVersion以固定补偿流的版本。从源码看这一路径由核心执行引擎直接支持——WorkflowExecutor.java 中terminateWorkflow(...)的重载签名携带failureWorkflow与failureWorkflowVersion参数负责在终止失败工作流时联动触发补偿流。默认情况下以下参数会作为输入传给失败工作流见 docs/devguide/how-tos/Workflows/handling-errors.md参数内容reason工作流失败原因workflowId失败执行的 IDfailureStatus失败工作流的状态failureTaskId失败任务的执行 IDfailedWorkflow失败工作流的完整执行 JSON补偿任务应标记optional: true针对失败前可能未执行到的步骤并利用failedWorkflow.tasks[...].output中的事务 ID、资源句柄等元数据完成反向回滚——先取消发货、再恢复库存、最后退款逆序撤销已完成步骤。这正是 Saga 模式在 Conductor 中的落地形态完整可运行示例见 docs/devguide/how-tos/Workflows/handling-errors.md 中的order_processing/order_compensation双工作流示例。验证故障设计强制一次瞬态失败原文档给出了明确的验收手段强制一次瞬态任务失败确认预期的重试、超时或补偿路径在执行中可见。例如让一个SIMPLEworker 故意抛错观察任务按retryLogic重试、最终耗尽retryCount后转入FAILED随后failureWorkflow被触发并携带reason、failedWorkflow等上下文。对不可重试的业务错误worker 应返回FAILED_WITH_TERMINAL_ERROR状态跳过全部重试立即终态——例如余额不足的支付重试永远不会成功。阶段三测试真实边界原文档强调测试已注册的定义用代表性输入而不只是隔离测试 worker 函数。原因是定义级别的编排逻辑、数据流、分支决策只有端到端执行才能验证。测试应覆盖成功路径可重试的瞬态失败终态业务失败超时每个副作用的幂等行为。三层测试法docs/devguide/how-tos/Workflows/testing-workflows.md 给出了三层递进的测试结构Schema 校验POST /api/metadata/workflow/validate成功返回空200 OK。它只校验元数据与图规则不证明 worker 在轮询、外部端点可达。Mock 化编排测试POST /api/workflow/test用按引用名提供的 mock 输出来模拟任务验证分支与数据流决策不调用真实 worker。每个引用名对应一个列表因为循环或重试可能消耗多个 mockmock 上的executionTime、queueWaitTime可模拟超时行为。真实边界执行注册定义后启动一次真实执行验证 worker、队列、持久化与并发行为。使用真实依赖或 Testcontainers 时效果最佳。用测试关联 ID 做端到端验收原文档给出的验收步骤值得固化到发布清单中用测试关联 IDcorrelation ID启动工作流检查完整执行conductor workflow get-execution workflow-id -c断言输出契约与终态状态。启动时可通过 CLI 携带关联 ID 与固定版本见 docs/devguide/how-tos/Workflows/starting-workflows.mdconductor workflow create workflow.json conductor workflow start -w order_flow --version 1 \ --correlation order-test-001 -i {orderId:order-001} conductor workflow get-execution workflow-id -c关联 ID 便于在 docs/devguide/how-tos/Workflows/searching-workflows.md 中按业务维度检索执行但它不保证唯一也不能替代 workflow ID 作为执行的主键。需要特别注意SIMPLE任务若缺少已注册的任务定义或轮询中的 worker执行会一直停留在队列中——mock 测试无法发现这类部署缺口必须由真实执行暴露。阶段四安全部署定义与 Worker顺序先 worker 与任务定义后生产流量原文档的部署铁律在把生产流量路由到某个工作流之前先部署好它依赖的 worker 代码与任务定义。因为 Conductor 采用至少一次交付worker 必须幂等因为SIMPLE任务需要已注册的任务定义 轮询该精确任务类型的 worker两者齐备缺一则任务停留在队列、工作流不推进docs/devguide/concepts/workflows.md。部署前用conductor taskDef list核对每个SIMPLE任务的依赖是否齐备docs/devguide/how-tos/Workflows/creating-workflows.md。按版本滚动发布新版本工作流的发布流程参考 docs/devguide/how-tos/Workflows/versioning-workflows.md递增version并注册新版本conductor workflow create workflow.json而非覆盖生产调用方使用的版本校验与 mock 测试后用固定版本启动一次金丝雀执行conductor workflow start -w name --version 2 -i {orderId: test-1}刻意地把调用方、调度器与父工作流引用迁移到新版本对比两个版本的完成率、失败率、延迟与输出保留旧版本直至调用方完成迁移、旧执行的排空不再需要重启/重放支持。由于定义变更不影响运行中的执行蓝绿发布天然成立新执行走版本 N1存量版本 N 的执行继续在自己的定义快照上排空至完成。若版本 N1 出问题可停止向它启动新执行、让存量失败或终止、回到从未被修改过的版本 N 继续服务。因为 worker 与工作流定义解耦可以独立于 worker 部署回滚工作流版本。运行中执行升级的特殊情况定义变更从不影响运行中执行因此需要显式升级时方式是终止 以最新定义重启。UI 上依次选择Actions Terminate、Actions Restart with latest definitionsAPI 则用批量终止 批量重启curl -X POST http://localhost:8080/api/workflow/bulk/terminate \ -H Content-Type: application/json \ -d [workflow-id-1, workflow-id-2] curl -X POST http://localhost:8080/api/workflow/bulk/restart?useLatestDefinitionstrue \ -H Content-Type: application/json \ -d [workflow-id-1, workflow-id-2]不传useLatestDefinitionstrue时重启使用各自原始的定义快照不会发生升级。仓库中 WorkflowBulkServiceImpl.java 等实现为批量重启提供了useLatestDefinitions语义支持。必须注意终止并重启会重复副作用——除非工作流幂等或已定义补偿否则优先让运行中执行在自己的快照上自然完成。阶段五运维执行建立执行的可发现性基线原文档要求为运维者准备四件套工作流名、版本、关联 ID 约定、负责人。在此基础上补充两点启动执行时尽量固定版本省略 version 会默认取服务器最新注册版本牺牲可预测性为执行关联业务意义的 correlation ID作为跨系统的追踪线索。监控什么运维核心是队列—任务—工作流三层的可观测性docs/devguide/how-tos/Workers/scaling-workers.md指标含义告警参考任务队列深度未处理任务积压持续 5 分钟增长任务轮询数按类型worker 是否在活跃轮询降为零工作流失败率以 FAILED 终止的执行占比15 分钟窗口内 5%任务响应时间 p99与响应超时的接近程度responseTimeoutSeconds的 80%worker 线程利用率worker 是否饱和持续 10 分钟 90%外部负载存储错误S3/GCS 写入失败任何非零计数队列监控可通过 UIHome Task Queues、CLIconductor task list/conductor task get TASK_NAME或 API/tasks/queue/sizes、/tasks/queue/polldata获取Prometheus 指标如task_queue_depth、task_completed_seconds_count、task_queue_wait_time_seconds均带taskType标签可支撑按任务类型的告警与自动扩缩容。事故恢复流程先检查、后恢复事故处置的原则是先检查失败任务再决定重试。恢复动作包括 pause/resume暂停/恢复、rerun从指定任务重跑、restart从头重启与 terminate终止按业务策略选择。参考 docs/devguide/how-tos/Workflows/debugging-workflows.md从持久化执行开始conductor workflow get-execution workflow-id -c定位FAILED/TIMED_OUT/ 终态任务记录其reasonForIncompletion、输入、输出、worker ID 与重试次数先修复底层的 worker、依赖、凭据或定义问题再改变执行状态只在确定安全时才重试重试/重跑可能重复副作用。reasonForIncompletion是诊断的关键字段worker 返回FAILED/FAILED_WITH_TERMINAL_ERROR时由 worker 写入HTTP 任务在非 2xx 时记录响应体引擎则在超时、终止与定义错误时生成模板化消息例如Task timed out after {elapsed} seconds. Timeout configured as {timeoutSeconds} seconds...。恢复选项对比动作行为适用场景Restart with Current Definitions用原始定义从头重跑定义已变更但想按原定义执行Restart with Latest Definitions用最新定义从头重跑定义已修复需按最新定义执行Rerun from a specific task从指定任务重跑复用此前任务输出中间任务失败不想重跑前置全部步骤Retry - From failed task从最后失败任务重试瞬态失败、外部依赖临时不可用CLI 对应命令conductor workflow retry workflow-id、conductor workflow restart workflow-id、conductor workflow rerun workflow-id --task-id task-id。恢复后运行conductor workflow status workflow-id验证预期任务在运行或到达预期终态。restart/rerun/retry 三种操作对任意终态执行COMPLETED、FAILED、TIMED_OUT、TERMINATED都可用且长期可用——Conductor 保留完整执行图数月后仍可重放任意执行。恢复演练原文档给出一个可直接执行的演练脚本故意让一个工作流保持等待或使某个可重试任务失败通过 searching-workflows如conductor workflow search -w order_processing -s FAILED -c 20找到它用 debugging-workflows 的恢复控制将其恢复。演练的价值在于让运维者熟悉搜索定位 → 检查失败上下文 → 选择恢复动作 → 验证终态这条肌肉记忆确保真实事故时能在有界时间内完成处置。下一步平台部署与 AI 工作流原文档在生产路径之后给出了两条延伸线平台级部署与存储选型继续阅读 docs/devguide/running/deploy.mdAPI Server、Decider、Sweeper、事件处理器、数据库/队列/索引/分布式锁的架构角色以及 Docker Compose 各后端组合与 docs/architecture/durable-execution.md持久化内容、故障矩阵、任务状态机、分布式一致性。AI 工作流 / Agent 基线增强若你的工作流面向 AI 或 Agent在本文的生产基线上叠加 docs/devguide/ai/production-agent-architecture.md 的控制面——父工作流持有业务过程、Agent 在显式执行边界之后运行、不可逆操作必须经父级校验与审批用failureWorkflow做副作用补偿、用DO_WHILE循环条件做迭代/预算上限、用HUMAN任务做持久化审批门禁并把关联 ID 与幂等键带入外部效果。无论是普通业务工作流还是 Agent 工作流本文的五阶段路径都适用契约先行、故障有界、测试真实、部署安全、运维可恢复——这正是 Conductor 作为持久化执行引擎的生产使用方式。【免费下载链接】conductorConductor is an event driven agentic workflow engine providing durable and highly resilient execution engine for applications and AI Agents项目地址: https://gitcode.com/GitHub_Trending/co/conductor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
