指南
API
指南
API
简体中文

定时任务 API 文档

基础路径

/crons

接口列表

定时任务视图管理

获取视图列表

GET /views

获取所有定时任务视图。

创建视图

POST /views

请求体

{
  name: string,           // 视图名称
  sorts?: Array<any>,     // 排序规则
  filters?: Array<any>,   // 过滤规则
  filterRelation?: string // 过滤关系
}

更新视图

PUT /views

请求体

{
  id: number,            // 视图ID
  name: string,          // 视图名称
  sorts?: Array<any>,    // 排序规则
  filters?: Array<any>,  // 过滤规则
  filterRelation?: string // 过滤关系
}

删除视图

DELETE /views

请求体

number[]  // 视图ID数组

移动视图位置

PUT /views/move

请求体

{
  fromIndex: number,  // 原位置
  toIndex: number,    // 目标位置
  id: number         // 视图ID
}

禁用视图

PUT /views/disable

请求体

number[]  // 视图ID数组

启用视图

PUT /views/enable

请求体

number[]  // 视图ID数组

定时任务管理

获取定时任务列表

GET /

获取定时任务列表。

获取任务详情

GET /detail

获取指定任务的详细信息。

创建定时任务

POST /

请求体

{
  command: string,         // 执行的命令
  schedule: string,        // cron表达式
  name?: string,          // 任务名称
  labels?: string[],      // 标签
  sub_id?: number,        // 子任务ID
  extra_schedules?: any[], // 额外的定时规则
  task_before?: string,   // 前置任务
  task_after?: string     // 后置任务
}

运行任务

PUT /run

请求体

number[]  // 任务ID数组

停止任务

PUT /stop

请求体

number[]  // 任务ID数组

删除标签

DELETE /labels

请求体

{
  ids: number[],    // 任务ID数组
  labels: string[]  // 标签数组
}

添加标签

POST /labels

请求体

{
  ids: number[],    // 任务ID数组
  labels: string[]  // 标签数组
}

禁用任务

PUT /disable

请求体

number[]  // 任务ID数组

启用任务

PUT /enable

请求体

number[]  // 任务ID数组

获取任务日志

GET /:id/log

获取指定任务的执行日志。

更新任务

PUT /

请求体

{
  id: number,            // 任务ID
  command: string,       // 执行的命令
  schedule: string,      // cron表达式
  name?: string,        // 任务名称
  labels?: string[],    // 标签
  sub_id?: number,      // 子任务ID
  extra_schedules?: any[], // 额外的定时规则
  task_before?: string, // 前置任务
  task_after?: string   // 后置任务
}

删除任务

DELETE /

请求体

number[]  // 任务ID数组

置顶任务

PUT /pin

请求体

number[]  // 任务ID数组

取消置顶

PUT /unpin

请求体

number[]  // 任务ID数组

导入定时任务

GET /import

从 crontab 导入定时任务。

获取单个任务

GET /:id

获取指定ID的任务信息。

更新任务状态

PUT /status

请求体

{
  ids: number[],           // 任务ID数组
  status: string,          // 状态
  pid?: string,           // 进程ID
  log_path?: string,      // 日志路径
  last_running_time?: number,    // 最后运行时间
  last_execution_time?: number   // 最后执行时间
}

获取任务日志列表

GET /:id/logs

获取指定任务的所有日志记录。

错误处理

所有接口遵循相同的错误处理模式：

  • 错误会传递给下一个中间件
  • 成功响应返回 { code: 200, data: ... }
  • 错误日志由 Winston logger 处理

注意事项

  • 所有路由都使用 celebrate/Joi 进行参数验证
  • cron 表达式由 cron-parser 校验并标准化；Node 调度使用 node-cron，见定时规则与时区
  • 批量操作接口（如运行、停止、删除等）都接受任务ID数组

执行选项与任务实例

创建和更新除原有字段外，还支持：

字段 类型 说明
log_name string 自定义日志名，支持中文；相对名称最长 100 字符，不允许 ./.. 路径段；绝对路径须在日志目录内，或使用 /dev/null
allow_multiple_instances number 0 或 1，是否允许多实例运行
work_dir string 执行工作目录

command 和 schedule 在创建及更新时均必填。支持五字段和带秒字段的定时规则，具体语法见定时规则与时区。

方法 完整路径 说明
GET /open/crons/:id/instances 查询任务实例，按启动时间降序排列
POST /open/crons/:id/instances/:instanceId/stop 停止指定实例 
ql task instances 12 --json
ql task instance-stop 12 34 --json

日志分块

GET /open/crons/:id/log 支持 offset（非负字节偏移）、limit（最多 1048576 字节）和 tail（布尔值）。响应除 data 外，包含 logStatus、offset、nextOffset、total、truncated。与 CLI 的 --tail 行数参数不同，HTTP 参数按字节分块。

列表分页及 CLI 运行结果说明见远程 CLI。HTTP 运行接口接受 ID 数组；运行请求返回成功不表示脚本已经执行完成。

定时规则与时区

常用 cron 规则有五个字段，依次为分、时、日、月、星期；可在前面增加秒字段。旧版短写仍保留兼容，建议新规则使用明确的五字段或六字段格式。

规则 含义
*/5 * * * * 每五分钟
*/5 * * * * * 每五秒
0 0 9 ? * MON 每周一 09:00

支持月份和星期名称、合法步长（如 */5、0/5）及兼容的 L、# 规则。? 只允许用于日期和星期字段；不支持 H、裸 /N（如 /5）或未列出的 Quartz 扩展。

周期宏支持 @yearly、@annually、@monthly、@weekly、@daily、@midnight、@hourly 和 @minutely。@annually 等同 @yearly，@midnight 等同 @daily，@minutely 在每分钟第 0 秒触发。启动和一次性任务使用独立的 @boot、@once 模式。

日期和星期同时受限的规则由 Node 调度处理，保留 OR 语义：任一字段匹配即可触发，同时匹配的时间只执行一次。普通任务、额外定时规则、订阅的 cron 计划和系统 Node cron 共用标准化与调度规则；间隔计划独立配置。

禁用、删除或更新任务后，旧规则已排队且尚未执行的触发会失效。恢复调度时，无效的持久化任务或订阅规则会跳过并记录日志，配置仍保留以便修正。

规则和宏按面板进程时区解释；更改时区后，按设置流程重启相关服务使其生效。在有夏令时的时区，春季跳时不存在的当地时间跳过，秋季重复小时不执行第二次；Asia/Shanghai 不受这一差异影响。进程内迟到的触发可通过既有执行队列补执行；面板停止期间没有持久化补跑保证，也不保证多个面板只执行一次。