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