Conductor 工作流定時調度實戰(zhàn)Cron 調度器、時區(qū)語義與生產配置指南【免費下載鏈接】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 事件驅動的 Agentic 工作流引擎中的調度器Scheduler模塊系統講解如何為工作流創(chuàng)建 Cron 調度、理解時區(qū)與夏令時行為、啟用追趕Catchup與時間窗口Bounds、使用調度器注入的輸入字段并通過 CLI 與完整 REST 接口完成調度的創(chuàng)建、預覽、暫停、恢復與歷史檢索。讀完本文你將掌握在 Conductor 中以“時鐘驅動”方式按時、按區(qū)、可追溯地觸發(fā)工作流的完整實操方案。何時使用調度器時鐘驅動 vs 事件驅動Conductor 的調度器會在每一個匹配的 Cron 槽位cron slot上創(chuàng)建一次新的工作流執(zhí)行。其適用場景是由時鐘來決定“何時運行”與之相對當由**消息來決定“何時運行”**時應當使用事件編排Event Orchestration。兩者邊界清晰調度器固定時刻、周期性觸發(fā)例如每日報表、定時清理、定期聚合事件編排由事件總線上的消息觸發(fā)例如訂單創(chuàng)建、支付回調、外部 webhook。調度器模塊的 REST 控制器掛載在/api/scheduler下并且僅當conductor.scheduler.enabledtrue默認值時才會裝配見 SchedulerResource.java 中的Conditional(SchedulerConditions.class)與RequestMapping(/api/scheduler)。前置條件在開始創(chuàng)建調度之前需要確認以下條件全部滿足目標工作流定義WorkflowDef已注冊到 Conductor 元數據服務服務端已啟用調度器且其持久化模塊已配置如conductor-scheduler-postgres-persistence、conductor-scheduler-mysql-persistence、conductor-scheduler-redis-persistence、conductor-scheduler-cassandra-persistence等見 scheduler 模塊下的各 persistence 子模塊目標工作流所需的 Worker 正在運行已配置 Conductor CLI 用于簡單的 CRUD 操作或可通過 REST 使用完整的調度器模型。創(chuàng)建第一個簡單調度倉庫中提供了一個可直接運行的規(guī)范示例 every-minute-schedule.json它代表每分鐘在 UTC 時區(qū)觸發(fā)一次{ name: every-minute-demo-schedule, cronExpression: 0 * * * * *, zoneId: UTC, startWorkflowRequest: { name: daily_report_workflow, version: 1, input: {} }, runCatchupScheduleInstances: false, paused: false }使用 Conductor CLI 創(chuàng)建并讀取該調度conductor schedule create scheduler/examples/every-minute-schedule.json conductor schedule get every-minute-demo-schedule成功判據有兩點調度已保存且nextRunTime非空下一個 Cron 槽位之后出現一次對應的工作流執(zhí)行。CLI 與 REST 的能力邊界CLI 是“簡單 CRUD”入口并非所有調度器字段和操作都能在 CLI 的各個發(fā)行版本中一致暴露。對于多表達式 Cron、時間窗口bounds、追趕行為catchup、執(zhí)行時間預覽、執(zhí)行歷史檢索等高級能力請使用 REST 接口。使用完整的 REST 接口調度器的核心 CRUD 端點均返回200 OK成功時。創(chuàng)建或更新一個調度curl -sS -X POST http://localhost:8080/api/scheduler/schedules \ -H Content-Type: application/json \ --data-binary scheduler/examples/every-minute-schedule.json同一個POST /api/scheduler/schedules按調度名執(zhí)行“創(chuàng)建或更新”create-or-update響應體為存儲后的調度對象其中包含服務端計算的狀態(tài)字段如nextRunTime。完整的請求體字段、查詢參數與狀態(tài)碼請參考 Scheduler API 文檔。調度模型字段一覽調度對象對應源碼中的WorkflowSchedule模型見 WorkflowSchedule.java字段類型是否必填運行時默認值或行為namestring是唯一鍵用于創(chuàng)建或更新cronExpressionstring兩種 Cron 形式必填其一傳統的單表達式zoneIdstring否UTCcronSchedulesarray兩種 Cron 形式必填其一非空數組時優(yōu)先于cronExpression/zoneId每個條目的zoneId默認UTCstartWorkflowRequestobject是標準的工作流啟動請求runCatchupScheduleInstancesboolean否falsepausedboolean否falsepausedReasonstring否由暫停操作設置scheduleStartTimelong否時間窗口下界epoch 毫秒scheduleEndTimelong否時間窗口上界epoch 毫秒descriptionstring否用戶描述createTime、updatedTime、createdBy、updatedBy、nextRunTime服務端字段否由服務端填充從源碼可以確認兩個關鍵行為WorkflowSchedule.getEffectiveCronSchedules()在cronSchedules非空時優(yōu)先返回該列表否則回退到單元素列表cronExpression zoneIdzoneId為空時兜底UTCCronSchedule條目本身也只含cronExpression與默認為UTC的zoneId兩個字段見 CronSchedule.java。Cron 與時區(qū)行為Spring 六字段 Cron 表達式Conductor 調度器使用Spring 六字段 Cron 表達式秒、分、時、日月、月、星期day of week。同時 Spring 解析器也接受daily之類的宏┌─────────────── second (0-59) │ ┌───────────── minute (0-59) │ │ ┌─────────── hour (0-23) │ │ │ ┌───────── day of month (1-31) │ │ │ │ ┌─────── month (1-12 or JAN-DEC) │ │ │ │ │ ┌───── day of week (0-7 or MON-SUN) │ │ │ │ │ │ * * * * * *常用表達式示例表達式含義0 * * * * *每分鐘0 0 9 * * MON-FRI工作日 09:000 0 0 1 * *每月第一天 00:000 0/30 9-17 * * MON-FRI工作時間內每 30 分鐘單表達式與多表達式多時區(qū)單表達式形式使用cronExpression加zoneId默認UTC多表達式形式使用cronSchedules數組當該數組非空時它優(yōu)先于cronExpression/zoneId兩個傳統字段且每個條目可獨立指定zoneId默認UTC。一個典型的多時區(qū)場景——同一工作流分別在美國東部與倫敦的當地 9 點觸發(fā){ name: regional-report, cronSchedules: [ {cronExpression: 0 0 9 * * MON-FRI, zoneId: America/New_York}, {cronExpression: 0 0 9 * * MON-FRI, zoneId: Europe/London} ], startWorkflowRequest: { name: daily_report_workflow, version: 1 } }夏令時DST下的求值語義Cron 求值遵循所選 IANA 時區(qū)包括夏令時轉換春季“向前撥”spring-forward時不存在本地時間該本地時刻會被 Cron 引擎跳過重復出現的本地時間秋季回撥遵循引擎的“下一時刻”計算規(guī)則。因此對業(yè)務敏感的調度務必在 DST 邊界前后進行測試驗證。預覽執(zhí)行時間Preview的時區(qū)注意點預覽端點不接受時區(qū)參數它在conductor.scheduler.schedulerTimeZone默認UTC下求值而不是調度自身的zoneId并且無論limit傳多大最多只返回 5 個時間。這與調度實際執(zhí)行時所遵循的時區(qū)可能存在差異使用時需留意。curl http://localhost:8080/api/scheduler/nextFewSchedules?cronExpression0*****limit5該端點對應源碼中的getNextFewSchedules見 SchedulerResource.javalimit的默認值即為 5。追趕Catchup與時間窗口Bound停機后的追趕執(zhí)行runCatchupScheduleInstances: true會在停機恢復后逐個推進錯過的 Cron 槽位為每一個錯過的槽位各觸發(fā)一次執(zhí)行。倉庫中的 catchup-schedule.json 即為此模式的示例{ name: catchup-demo-schedule, cronExpression: 0 * * * * *, zoneId: UTC, runCatchupScheduleInstances: true, paused: false, startWorkflowRequest: { name: catchup_demo_workflow, version: 1, input: {} } }需要注意追趕可能造成執(zhí)行突刺burst因此目標工作流及其下游依賴必須滿足冪等且具備容量意識。當使用默認值false時調度器從當前時間繼續(xù)推進而不會重放每一個錯過的槽位。觀察追趕行為的方法停止 Conductor 數分鐘重啟后即可看到針對錯過的槽位按順序觸發(fā)的一系列執(zhí)行。時間窗口scheduleStartTime / scheduleEndTime使用scheduleStartTime與scheduleEndTime均為 epoch 毫秒、含邊界把調度限制在一個窗口內。超出窗口的調度會停止產生新的執(zhí)行但不會被自動刪除。模板示例見 bounded-schedule-template.json其中__START_MS__/__END_MS__為占位符可用sed替換后提交NOW$(($(date %s) * 1000)) END$((NOW 300000)) # 5-minute window sed s/__START_MS__/$NOW/; s/__END_MS__/$END/ scheduler/examples/bounded-schedule-template.json | \ curl -sS -X POST http://localhost:8080/api/scheduler/schedules \ -H Content-Type: application/json -d -調度器注入的輸入字段每次調度觸發(fā)的執(zhí)行調度器會先復制startWorkflowRequest.input再向工作流輸入中追加以下 5 個字段。其實現證據位于 SchedulerService.java輸入字段含義_startedByScheduler調度名稱_scheduledTime預期的 Cron 槽位時間epoch 毫秒_executedTime實際派發(fā)時間epoch 毫秒_executionId唯一的調度執(zhí)行記錄 ID_schedulerCron產生本次執(zhí)行的 Cron 表達式與時區(qū)當下游系統需要“每次運行唯一標識”時可在工作流中使用${workflow.input._executionId}。倉庫示例 input-param-schedule.json 展示了靜態(tài)入參reportOwner、alertThreshold與注入字段并存{ name: input-param-demo-schedule, cronExpression: 0 * * * * *, zoneId: UTC, runCatchupScheduleInstances: false, startWorkflowRequest: { name: input_param_demo_workflow, version: 1, input: { reportOwner: platform-team, alertThreshold: 100 } } }一個真實運行中可見的時序差異來自 scheduler/examples/README.md 的實測記錄scheduledAt: 2026-02-19T23:22:00.000Z ← 精確的 cron 槽位 triggeredAt: 2026-02-19T23:22:00.837Z ← 實際派發(fā)約 837ms 輪詢開銷correlationId 的“字面量”語義startWorkflowRequest.correlationId會被原樣復制調度器不會在其中插值${scheduledTime}等模板。如果需要每個工作流執(zhí)行都有唯一 correlation ID應在工作流內部基于注入字段自行推導或通過代碼構造 ID 后再啟動工作流。調度器的運維操作用 CLI 操作調度conductor schedule list conductor schedule pause every-minute-demo-schedule conductor schedule resume every-minute-demo-schedule conductor schedule delete every-minute-demo-schedule用 REST 搜索、暫停與查看執(zhí)行歷史REST 還支持過濾、搜索、暫停原因pause reason以及已調度執(zhí)行的歷史檢索# 搜索未暫停的調度每頁 20 條 curl http://localhost:8080/api/scheduler/schedules/search?pausedfalsesize20 # 搜索調度執(zhí)行歷史 curl http://localhost:8080/api/scheduler/search/executions?freeTextevery-minute-demo-schedulesize20對應的端點均見 SchedulerResource.java方法路徑說明POST/api/scheduler/schedules創(chuàng)建或更新調度GET/api/scheduler/schedules?workflowName列出全部調度可按工作流名過濾GET/api/scheduler/schedules/search搜索調度按名稱、工作流、paused 過濾GET/api/scheduler/schedules/{name}按名稱獲取單個調度DELETE/api/scheduler/schedules/{name}刪除調度PUT/api/scheduler/schedules/{name}/pause?reason暫停reason 可選PUT/api/scheduler/schedules/{name}/resume恢復GET/api/scheduler/nextFewSchedules預覽未來 N 個執(zhí)行時間GET/api/scheduler/search/executions搜索調度執(zhí)行歷史PUT/api/scheduler/bulk/pause、/api/scheduler/bulk/resume批量暫停/恢復請求體為調度名 JSON 數組GET/api/scheduler/admin/requeue、/admin/pause、/admin/resume管理員端點作用于調度器內部狀態(tài)恢復/調試用不是針對單個調度的暫停/恢復應做好訪問控制搜索調度的查詢參數包括workflowName、scheduleName、paused、freeText默認*、start默認0、size默認100、sort逗號分隔字符串。執(zhí)行歷史搜索額外支持query返回SearchResultWorkflowScheduleExecutionModel執(zhí)行記錄包含調度執(zhí)行 ID、計劃與實際執(zhí)行時間、工作流名/ID、狀態(tài)以及失敗詳情。驗證暫停與恢復暫停后檢查存儲的paused狀態(tài)為 true并確認下一個 Cron 槽位之后不再出現新的執(zhí)行恢復后確認產生新的調度執(zhí)行并檢查全部 5 個注入字段是否正確。調度器服務端配置調度器相關配置集中在conductor.scheduler.*對應 SchedulerProperties.java以下是各配置項及其默認值配置項默認值說明conductor.scheduler.enabledtrue是否啟用調度器REST 控制器與執(zhí)行服務裝配條件conductor.scheduler.polling-interval100輪詢間隔毫秒conductor.scheduler.polling-thread-count1輪詢線程數conductor.scheduler.poll-batch-size5每個輪詢周期處理的調度數量conductor.scheduler.scheduler-time-zoneUTC服務端調度時區(qū)預覽端點在此時區(qū)求值conductor.scheduler.archival-max-records5每個調度保留的歷史記錄行數conductor.scheduler.archival-max-record-threshold10超過該閾值時觸發(fā)清理conductor.scheduler.max-schedule-jitter-ms1000每個調度的派發(fā)抖動上限毫秒conductor.scheduler.initial-delay-ms15000啟動后的初始延遲毫秒conductor.scheduler.cache-enabledfalse是否啟用外部SchedulerCacheDAO加速熱路徑查詢一個典型的 YAML 配置片段conductor: scheduler: enabled: true # default: true polling-interval: 1000 # ms between polls; default: 100 polling-thread-count: 1 # default: 1 poll-batch-size: 5 # schedules processed per cycle; default: 5 scheduler-time-zone: UTC # default: UTC archival-max-records: 5 # history rows to keep per schedule; default: 5 archival-max-record-threshold: 10 # prune when over threshold; default: 10 jitter-max-ms: 0 # dispatch jitter per schedule; default: 0 (disabled)實戰(zhàn)提示當大量調度在同一 Cron 時刻觸發(fā)時應把poll-batch-size提升到與預期扇出fanout匹配的數量例如test-11-thundering-herd.sh要求poll-batch-size N否則默認 5 只能每輪處理 5 個調度并設置較小的jitter-max-ms如 200來平滑對數據庫與執(zhí)行線程池的突發(fā)壓力。已知限制與設計要點沒有原生重疊策略如果前一個工作流仍在運行下一個槽位仍可啟動新的執(zhí)行。并發(fā)場景需自行在工作流或下游系統中實現并發(fā)控制與冪等策略倉庫 concurrent-schedule.json concurrent-workflow.json 即用于演示該行為沒有 “run now” 或手動回填端點臨時運行請直接啟動目標工作流并顯式傳入預期的窗口參數預覽能力受限單 Cron 表達式、最多 5 條、且使用服務端調度時區(qū)SDK 一致性Java、Python、TypeScript、Go SDK 可以通過生成式或底層客戶端調用 REST 面但本倉庫并未在所有 SDK 中定義一致的高層調度器 API請將 REST 視為可移植的完整接口correlationId是字面量不是調度模板?？蛇\行的完整示例場景倉庫的 scheduler/examples 目錄提供了 8 個經過實測的完整場景每個場景均包含“工作流定義 調度定義”一對文件可直接用于本地驗證基礎every-minute-schedule.json daily-report-workflow.json——每分鐘觸發(fā)并抓取示例數據集追趕catchup-schedule.json catchup-workflow.json時間窗口bounded-schedule-template.json bounded-workflow.json多步驟 FORK/JOINmultistep-schedule.json multistep-workflow.json注意時區(qū)查詢參數須用字面量/不要用%2F編碼否則 HTTP 任務會被遠程 API 拒絕失敗場景retry-schedule.json retry-workflow.json——無論上一次執(zhí)行成敗每個槽位都會產生新的調度執(zhí)行記錄并發(fā)執(zhí)行concurrent-schedule.json concurrent-workflow.json注意 WAIT 任務時長須寫90s/2m而非 ISO-8601 的PT90S輸入參數化input-param-schedule.json input-param-workflow.jsonDO_WHILE 變體dowhile-schedule.json dowhile-workflow.json。一次性初始化示例注冊工作流 創(chuàng)建每分鐘調度可參考 seed.sh。更完整的可運行教程追趕、窗口、并發(fā)、輸入、重試、多步驟等菜譜見 scheduled workflow recipes它們復用了上述scheduler/examples/中的文件完整的端點、請求字段、默認值與響應語義則統一收錄于 Scheduler API 文檔。【免費下載鏈接】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創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考