定时任务

数据库定时任务的配置、立即执行和执行日志查询。任务处理器必须由后端预先注册。

查询定时任务列表

接口地址

GET /admin/scheduled_task/list

接口参数说明

Query 参数	类型	必填	说明
keyword	string	否	任务名称或处理器标识
status	integer	否

响应示例

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 0,
      "name": "",
      "handler": "",
      "cron_expression": "",
      "payload": "",
      "status": 1,
      "timeout_seconds": 0,
      "remark": "",
      "last_run_at": "2026-09-25T10:00:00+08:00",
      "last_status": 0,
      "last_error": "",
      "next_run_at": "2026-09-25T10:00:00+08:00",
      "created_at": "2026-09-25T10:00:00+08:00",
      "updated_at": "2026-09-25T10:00:00+08:00"
    }
  ]
}

响应参数说明

响应字段	类型	说明
data[].id	integer
data[].name	string	任务名称
data[].handler	string	后端注册的安全任务处理器标识
data[].cron_expression	string	6段Cron表达式（秒 分 时 日 月 周），兼容已有5段表达式
data[].payload	string	JSON格式任务参数
data[].status	integer	1启用，2停用
data[].timeout_seconds	integer
data[].remark	string
data[].last_run_at	string
data[].last_status	integer	0未执行，1成功，2失败，3跳过
data[].last_error	string
data[].next_run_at	string
data[].created_at	string
data[].updated_at	string

查询允许配置的任务处理器与Cron示例

接口地址

GET /admin/scheduled_task/options

接口参数说明

无请求参数。

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "handlers": [
      {
        "value": "",
        "label": "",
        "description": "",
        "example": ""
      }
    ],
    "cron_examples": [
      {
        "label": "",
        "value": ""
      }
    ]
  }
}

响应参数说明

响应字段	类型	说明
handlers	array<ScheduledTaskHandlerOption>
handlers[].value	string	后端处理器稳定标识
handlers[].label	string	管理端显示名称
handlers[].description	string	处理器用途
handlers[].example	string	JSON参数示例
cron_examples	array<ScheduledTaskCronExample>
cron_examples[].label	string	周期说明
cron_examples[].value	string	六段Cron表达式

新增或修改定时任务

接口地址

POST /admin/scheduled_task/save

接口说明

保存成功后管理端服务立即热刷新调度配置。Cron支持秒级六段格式以及字段内逗号多选、范围和步长，并兼容已有五段格式。

接口参数说明

Body 参数	类型	必填	说明
id	integer	否	0表示新增
name	string	是
handler	string	是
cron_expression	string	是
payload	string	是
status	integer	是
timeout_seconds	integer	是
remark	string	否

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 0,
    "name": "",
    "handler": "",
    "cron_expression": "",
    "payload": "",
    "status": 1,
    "timeout_seconds": 0,
    "remark": "",
    "last_run_at": "2026-09-25T10:00:00+08:00",
    "last_status": 0,
    "last_error": "",
    "next_run_at": "2026-09-25T10:00:00+08:00",
    "created_at": "2026-09-25T10:00:00+08:00",
    "updated_at": "2026-09-25T10:00:00+08:00"
  }
}

响应参数说明

响应字段	类型	说明
id	integer
name	string	任务名称
handler	string	后端注册的安全任务处理器标识
cron_expression	string	6段Cron表达式（秒 分 时 日 月 周），兼容已有5段表达式
payload	string	JSON格式任务参数
status	integer	1启用，2停用
timeout_seconds	integer
remark	string
last_run_at	string
last_status	integer	0未执行，1成功，2失败，3跳过
last_error	string
next_run_at	string
created_at	string
updated_at	string

删除定时任务

接口地址

POST /admin/scheduled_task/delete

接口说明

软删除任务配置并保留历史执行日志。

接口参数说明

Body 参数	类型	必填	说明
id	integer	是	主键ID

响应示例

{
  "code": 0,
  "msg": "success",
  "data": null
}

响应参数说明

成功时 data 为 null。

立即异步执行任务

接口地址

POST /admin/scheduled_task/run

接口参数说明

Body 参数	类型	必填	说明
id	integer	是	主键ID

响应示例

{
  "code": 0,
  "msg": "success",
  "data": null
}

响应参数说明

成功时 data 为 null。

分页查询任务执行日志

接口地址

GET /admin/scheduled_task/log/list

接口参数说明

Query 参数	类型	必填	说明
task_id	integer	是
status	integer	否
page	integer	否	页码，默认 1
page_size	integer	否	每页数量，默认 20，最大 100

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 0,
        "task_id": 0,
        "task_name": "",
        "handler": "",
        "status": 1,
        "started_at": "2026-09-25T10:00:00+08:00",
        "finished_at": "2026-09-25T10:00:00+08:00",
        "duration_ms": 0,
        "error_message": ""
      }
    ],
    "total": 0
  }
}

响应参数说明

响应字段	类型	说明
list	array<ScheduledTaskLogItem>
list[].id	integer
list[].task_id	integer
list[].task_name	string	执行时的任务名称快照
list[].handler	string	执行时的处理器标识快照
list[].status	integer	1成功，2失败，3跳过
list[].started_at	string
list[].finished_at	string
list[].duration_ms	integer	执行耗时毫秒
list[].error_message	string	失败或跳过原因
total	integer