定时任务(Jobs)
菜单:开发 → 定时任务
深链:/_Admin/development/jobs?SiteId={站点GUID}
定时任务用于在 Kooboo 服务端按计划执行 KScript / TypeScript 代码:可配置 单次 或 重复 调度,适合定时同步、清理缓存、批量通知等后台逻辑。任务脚本在站点服务端脚本上下文中运行,可使用 k.content、k.DB、k.mail 等 API(与 开发 → 代码 中的 Code 资源类似,但由调度器触发而非 HTTP 请求)。
权限
查看任务列表与日志:job(查看)。添加任务、编辑、保存、运行 需 job·edit;多选 删除 需 job·delete。
与模块任务、邮件任务的区别
| 开发 → 定时任务 | 模块 module.config 的 task | 邮件迁移等 | |
|---|---|---|---|
| 配置 | 本页 Monaco 内联脚本 | 模块包内 task 定义 | 其它后台功能内置 |
| 作用域 | 当前站点 | 模块上下文 | 邮件站点 |
| 脚本触发 | k.site.runJob(见 k.site.runJob) | 模块事件 | — |
站点须 已发布(Published)后调度器才会自动执行;未发布时仅可 手动运行 调试。
如何打开
- 在 编辑菜单 中勾选 开发 → 定时任务。
- 左侧 开发 → 定时任务。

页签
| 页签 | 说明 |
|---|---|
| 任务列表 | 当前站点所有 SiteJob 定义,可新建、编辑、手动运行、删除 |
| 已完成 | 最近执行 成功 的日志(最多约 100 条) |
| 失败 | 最近执行 失败 的日志 |
日志由中心库 JobLog 记录,包含任务名、说明、执行时间、返回消息或异常堆栈。
任务列表
工具栏
| 按钮 | 权限 | 说明 |
|---|---|---|
| 添加任务 | job·edit | 打开 任务编辑弹窗(新建) |

列表表格
| 列 | 说明 |
|---|---|
| 名称 | 任务唯一名;创建后不可在弹窗中改名 |
| 状态 | 运行中 / 已完成(单次且已触发)/ 启用(active)/ 禁用 |
| 开始时间 | 首次调度参考时间(UTC 存储,界面按本地显示) |
| 重复 | 是否周期任务 |
| 间隔 | 重复时显示「每 N 秒/分钟/小时/天/周/月」 |
| 行末 编辑 | 打开弹窗修改脚本与调度 |
| 多选 运行 | 选中一条时工具栏 运行,立即异步执行一次 |
| 多选 删除 | job·delete |

任务编辑弹窗
| 字段 | 说明 |
|---|---|
| 名称 | 新建必填、1~50 字符、站点内唯一;编辑时禁用 |
| 开始时间 | 调度起点;单次任务在到达该时间且站点已发布后执行一次 |
| 启用 | active:关闭后调度器跳过,仍可手动 运行 |
| 重复 | 开启后按间隔循环;关闭则为 单次 任务 |
| 每 | 重复时:frequenceUnit(正整数)+ 单位(秒 / 分钟 / 小时 / 天 / 周 / 月) |
| 执行代码 | Monaco 编辑器,KScript;保存到 SiteJob.Code,非引用「开发 → 代码」里的 Code 条目 |
保存走 Job/post:新建写入完整模型;更新时刷新 code、调度字段,并将 finish 置为 false 以便单次任务可再次调度(若需重新触发须调整开始时间或手动运行)。

示例脚本(弹窗内默认注释):
typescript
// const log = "Execute at " + new Date().toString()
// k.response.write(log)实际执行时由 JobService 以 长任务 模式编译运行该段代码;返回值或输出会写入日志的 消息 字段。
调度行为(服务端)
Kooboo 后台 JobService 每秒扫描内存中的任务记录:
| 类型 | 条件 | 行为 |
|---|---|---|
| 重复 | active、已过 startTime、距上次执行已超过间隔、站点 已发布、当前未在运行 | 自动执行,并更新上次执行时间 |
| 单次 | 已过 startTime、未 finish、站点 已发布 | 将 finish 标为 true 后执行一次 |
手动运行(列表 运行 或 k.site.runJob)不校验「已发布」,但仍异步执行,日志说明为手动触发。
间隔与后台 RepeatFrequence 对应:天、小时、分钟、周(×7 天)、月(×30 天)、秒。
已完成 / 失败日志
两页签表格列一致:
| 列 | 说明 |
|---|---|
| 任务名称 | jobName |
| 说明 | 如自动调度、手动触发用户名 |
| 执行时间 | |
| 消息 | 成功时为脚本返回值;失败时为异常信息 |
| 详情 | 弹窗展示完整 message |

典型工作流
- 添加任务,填写名称、开始时间与 执行代码。
- 需要周期则开启 重复 并设置间隔;否则保持单次。
- 保存后 运行 一次验证日志(失败 页签查看堆栈)。
- 确认站点 已发布,等待自动调度,或在其它 Code 中调用
k.site.runJob('任务名')。 - 调整逻辑后 编辑 保存;不再需要则多选 删除。
相关
| 文档 | 说明 |
|---|---|
| k.site.runJob | 脚本手动触发 |
| 代码 | 可复用的 Code 资源(任务内联脚本与之独立) |
| 模块 | 模块 task 与 k.module |
| 运维 · 操作日志 | 站点对象变更历史(非任务执行日志) |