定时调度

Braidrun 的调度器支持四种触发类型：CRON（周期表达式）、INTERVAL（固定间隔）、ONE_TIME（一次性）、DELAYED_COMPLETION（工作流链式触发）。所有 schedule 由平台调度服务统一管理，服务重启后按各自时间表继续触发。

概念：schedule 与 execution

一个 schedule 描述"何时触发"；每次触发会创建一次 execution。Schedule 自身是长期对象，execution 是一次性的运行记录。Schedule 可以携带一份静态的 inputs（键值对），每次触发都作为 execution 的输入变量。

四种调度类型

四种类型共用一套通用字段：enabled（是否启用）、maxRuns（最大触发次数）、inputs（静态输入变量）。endTime 已过或触发次数达到 maxRuns 时，schedule 会被自动停用，但不会被删除。

创建 CRON schedule

curl -X POST https://braidrun.com/api/schedules \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "<workflow-id>",
    "name": "Daily 9 AM report",
    "scheduleType": "CRON",
    "cronExpression": "0 9 * * *",
    "timezone": "Asia/Shanghai",
    "inputs": {
      "environment": "production"
    }
  }'

cron 表达式为 5 段制：分 时 日 月 周。支持 *、列表（1,3,5）、区间（1-5）、步进（*/6）；周日可写 0 或 7。触发时间按 schedule 自己的 timezone 计算。

INTERVAL：固定间隔

请求体和 CRON 一样发到 POST /api/schedules，只是字段不同：

{
  "workflowId": "<workflow-id>",
  "name": "每 5 分钟同步一次",
  "scheduleType": "INTERVAL",
  "interval": 300000,
  "startTime": 1785542400000,
  "endTime": 1788220800000,
  "maxRuns": 500
}

• interval — 触发间隔，单位毫秒；小于 1 秒的值会被抬到 1 秒
• startTime / endTime — 可选，epoch 毫秒时间戳；设了 startTime 会先等到该时刻再开始，过了 endTime 自动停用
• maxRuns — 可选，触发满这么多次后自动停用

ONE_TIME：一次性

{
  "workflowId": "<workflow-id>",
  "name": "上线前补跑一次",
  "scheduleType": "ONE_TIME",
  "startTime": 1785546000000
}

startTime 为 epoch 毫秒时间戳。到点触发一次后 schedule 自动停用；多实例部署下由一次性锁保证只触发一次。

工作流链式调度（DELAYED_COMPLETION）

DELAYED_COMPLETION 把两个工作流串成链：上游工作流 A 每次以 COMPLETED 状态结束后，等 delaySeconds 秒，自动触发本 schedule 绑定的工作流 B。典型用法：数据拉取工作流跑完 10 分钟后自动跑报表工作流。

{
  "workflowId": "<workflow-B-id>",
  "name": "A 完成 10 分钟后跑 B",
  "scheduleType": "DELAYED_COMPLETION",
  "triggerWorkflowId": "<workflow-A-id>",
  "delaySeconds": 600,
  "maxRuns": 10
}

• 无论 A 是被手动、Webhook、定时还是链式触发的，只要成功完成就会计入；失败或被取消的执行不会触发下游
• delaySeconds — 必填，0 到 30 天（2592000 秒）；0 表示完成后立即触发
• maxRuns — 不填为不限次数；填 1 表示只链一次；填 N 表示最多链 N 次，达到后自动停用
• triggerWorkflowId — 不能等于 workflowId（自己触发自己会无限循环），且创建者需要对上游工作流有查看权限
• 等待中的延迟触发会持久化存储，服务重启或滚动发布不会丢：到点后照常触发

管理 schedule

# 立即执行一次（返回这次 execution）
curl -X POST https://braidrun.com/api/schedules/<schedule-id>/run \
  -H "Authorization: Bearer <token>"

# 停用（enabled=true 则启用；不带参数则在两者间切换）
curl -X POST "https://braidrun.com/api/schedules/<schedule-id>/toggle?enabled=false" \
  -H "Authorization: Bearer <token>"

# 最近 50 条触发历史
curl "https://braidrun.com/api/schedules/<schedule-id>/history?limit=50" \
  -H "Authorization: Bearer <token>"

toggle 的 enabled 可以放 query 参数或 JSON body；两者都不传时在启用 / 停用之间切换。history 每条记录含状态、成功与否、起止时间，limit 默认 50、最大 500。

共享输入与参数预设

除了在 schedule 上直接设置 inputs，还可以给工作流建"参数预设"：同一个 workflow 用不同预设跑不同配置。

# 创建一个参数预设
curl -X POST https://braidrun.com/api/workflows/<wf>/presets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "生产环境",
    "description": "生产环境参数",
    "variables": {
      "environment": "production",
      "debug_mode": "false",
      "max_retries": "3"
    }
  }'

# 用预设触发执行
curl -X POST https://braidrun.com/api/workflows/<wf>/presets/<id>/execute \
  -H "Authorization: Bearer <token>"

多工作流批量并发

从工作流列表多选后点击"并发执行"，会一次启动一批 execution。

• 每个被选中的 workflow 都会创建自己的 execution 记录
• 超出 maxConcurrency 的 execution 会先进入 PENDING
• 前面运行中的 execution 完成后，队列中的下一个自动转成 RUNNING
• 0 表示不限制，同时启动整批

服务重启后的行为

• 已触发的 execution：默认标 INTERRUPTED，除非开启了自动续跑（见重启与自动续跑）
• 未到时间的 CRON / INTERVAL / ONE_TIME：重启后照常触发
• 等待中的 DELAYED_COMPLETION 延迟触发：已持久化，重启后继续等到点触发
• 宕机期间错过的触发点：不补跑（避免双写风险）

相关页面

• Webhook 触发
• 服务重启自动续跑