定时任务

一句话：把「要周期执行的后台动作」登记成任务：填好处理器 Bean 名 + CRON 表达式，系统按点自动触发；每次执行都留下调度日志，失败能查到异常堆栈。

功能在哪

• 菜单路径：基础设施 → 定时任务
• 地址栏路由：/infra/job
• 主要权限：infra:job:query / create / update / delete / export（触发与改状态复用 update）

界面认识

区域	作用	常用操作
查询区	任务名称 / 任务状态 / 处理器的名字	「搜索」「重置」
工具条	整页级动作	「新增」「导出」「执行日志」「同步任务」；勾选后「批量删除」
列表	序号 / 任务编号 / 任务名称 / 任务状态 / 处理器的名字 / 处理器的参数 / CRON 表达式	行内「编辑」「开启|暂停」「删除」
更多菜单	行内折叠动作	「执行一次」「任务详细」「调度日志」

任务状态字典：初始化中 / 正常 / 暂停。行内按钮随状态变化——暂停态显示「开启」，正常态显示「暂停」。

常用操作

新增任务

1. 点「新增」；
2. 填「任务名称」——给人看的说明（如「访问日志清理 Job」）；
3. 填「处理器的名字」——后端 JobHandler 的 Bean 名（默认首字母小写，如 accessLogCleanJob）。填错保存时报「定时任务的处理器 Bean 不存在，注意 Bean 默认首字母小写」；
4. 可填「处理器的参数」——传给处理器的入参（文本/JSON，由处理器自己解析）；
5. 填「CRON 表达式」——触发时间点（写错报「CRON 表达式不正确」）；
6. 填「重试次数」「重试间隔」——失败后自动重试的策略；「监控超时时间」留空表示不监控；
7. 点「确定」。

结果：列表多一行，状态为初始化中/暂停——新建的任务不会自己跑起来，需要手动「开启」。

开启 / 暂停

行内点「开启」（或正常态的「暂停」），确认框形如：

确认要开启定时任务编号为"25"的数据项?

标题为「温馨提示」，确认后提示「开启成功」/「关闭成功」，列表状态列随之变化。

执行一次：不等 CRON，立刻跑一遍

更多 → 「执行一次」，确认「确认要立即执行一次访问日志清理 Job?」后立即触发一次，常用于上线新任务后先手工验证一遍再开启周期调度。

本演示环境未开启调度器，触发类操作会报错

本地演示环境的启动配置默认排除了 Quartz 自动配置，因此「执行一次」「开启」这类要真正驱动调度器的操作会原样收到报错：

[定时任务 - 已禁用][参考 https://doc.enlev.cn/job/ 开启]

任务的登记、修改、查询都正常，只是不真触发；生产环境按参考文档开启调度器后即恢复。下面这张就是该报错的实际样子，便于你对号入座：

任务详细：只读面板 + 后续执行时间

更多 → 「任务详细」：只读展示任务编号、名称、状态、处理器、参数、CRON、重试策略、监控超时时间，以及「后续执行时间」——按当前 CRON 推算的未来若干次触发点，改完 CRON 用它核对时间点是否符合预期最直观。

调度日志：每次执行的台账

更多 → 「调度日志」跳到该任务的执行台账（工具条「执行日志」则看全部任务）：日志编号 / 任务编号 / 处理器的名字 / 处理器的参数 / 第几次执行 / 执行时间 / 执行时长 / 任务状态。

失败那条点「详细」，「执行结果」里是处理器抛出的异常信息——排查失败原因的第一现场：

日志状态字典：运行中 / 成功 / 失败。查询区支持按处理器的名字、执行时间区间、任务状态筛选，并可「导出」。

同步任务

工具条「同步任务」：把数据库里的任务登记重新注册进调度器。改过调度器配置、或怀疑「状态是正常但到点没跑」时，先点它一次再观察。

字段说明

字段	必填	取值 / 校验	说明
任务名称	是	「任务名称不能为空」	给人看的说明
处理器的名字	是	「处理器的名字不能为空」；Bean 不存在报「定时任务的处理器 Bean 不存在，注意 Bean 默认首字母小写」；重复报「定时任务的处理器已经存在」	后端 JobHandler 的 Bean 名
处理器的参数	否	文本	传给处理器的入参
CRON 表达式	是	「CRON 表达式不能为空」；格式错报「CRON 表达式不正确」	触发时间点
重试次数	是	「重试次数不能为空」	失败后自动重试次数
重试间隔	是	「重试间隔不能为空」	两次重试间的间隔
监控超时时间	否	毫秒	留空 = 不监控超时

视角对照

视角	看到什么
超管 admin / 租户管理员 docadmin	全部任务，可增删改、启停、触发、看日志
套餐未含此菜单的租户	侧边栏没有「定时任务」；后台任务仍按调度器登记运行，不受菜单影响
普通员工	无此菜单。定时任务是运维向功能，不面向业务用户

进阶

• CRON 速查（秒 分 时 日 月 周）：0 0 0 * * ? 每天零点；0 0 2 * * ? 每天凌晨 2 点；0 0/5 * * * ? 每 5 分钟；0 0 1 ? * MON 每周一凌晨 1 点。改完用「任务详细」的后续执行时间核对；
• 清理类任务的参数通常是要保留的天数，改参数即改清理范围，动之前确认业务能接受；
• 失败排查路径：调度日志 → 失败行「详细」看执行结果异常 → 对照处理器代码；自动重试会体现在「第几次执行」上。

常见问题

Q：新建的任务为什么到点没跑？ A：新建默认不是「正常」态，需要行内「开启」。另注意本演示环境调度器未启用（见上方 warning），开启也会收到禁用报错。

Q：「执行一次」和「开启」有什么区别？ A：「执行一次」只立刻跑一遍，不改状态；「开启」是把任务交给调度器按 CRON 周期跑。验证新任务建议先「执行一次」看日志，没问题再「开启」。

Q：处理器的名字去哪找清单？ A：它是后端代码里注册的 JobHandler Bean 名（如 accessLogCleanJob、jobLogCleanJob），列表里现有任务可参考；新增处理器由开发提供 Bean 名。

Q：任务失败会自动重试吗？ A：会，按表单里的「重试次数 / 重试间隔」；重试也失败则日志记为失败，异常进「执行结果」。

Q：调度日志会一直留着吗？ A：平台自带日志清理任务（列表里的「访问日志清理 Job」等）按保留天数周期清理；保留策略由对应任务的参数决定。

Q：改了 CRON 但「后续执行时间」没变？ A：先确认表单已保存成功；仍不一致时点工具条「同步任务」把登记重新注册进调度器，再回「任务详细」查看。