@kne/fastify-task 3.0.0-alpha.5 → 3.0.0-alpha.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,66 +12,89 @@ npm i --save @kne/fastify-task
12
12
 
13
13
  ### 概述
14
14
 
15
- @kne/fastify-task 是一个 Fastify 插件,用于任务编排、追踪任务执行状态和结果。支持系统自动执行和手动执行两种模式,提供完整的任务生命周期管理。
15
+ `@kne/fastify-task` 是一个 Fastify 插件,用于任务编排、执行状态追踪、结果回调、日志记录和统计分析。插件支持 **system 自动执行
16
+ ** 与 **manual 手动完成** 两种模式,适合处理导出、同步、通知、外部异步回调等后台任务场景。
16
17
 
17
18
  ### 核心架构与流程
18
19
 
19
20
  ```
20
- 创建任务 (create)
21
+ 创建任务 (services.create)
21
22
  ↓
22
23
  pending(待执行)
23
- ↓ (cron 调度 runner / 手动 complete)
24
- running(执行中)
25
- ├→ executor 执行任务脚本
26
- │ ├→ 正常完成 → success
27
- │ ├→ 调用 next() → waiting(等待外部回调)
28
- │ └→ 异常失败 → 判断重试 → pending / failed
29
- ├→ waiting → processNext / callbackWithSignature → success / failed
30
- └→ 超时检测 (checkTimeout) → failed
24
+ ├→ manual:services.complete → success / failed
25
+ └→ system:cron 触发 runner
26
+ ↓
27
+ checkTimeout(检测 running / waiting 超时任务)
28
+ ↓
29
+ claimPendingTasks(按优先级与 startTime 原子认领)
30
+ ↓
31
+ running(执行中)
32
+ ├→ executor 正常完成 → success
33
+ ├→ executor 调用 next() → waiting
34
+ ├→ executor 异常 → retry / failed
35
+ └→ waiting → processNext / callbackWithSignature → success / failed
31
36
  ```
32
37
 
33
- > **关键设计**:cron 每次触发 `runner` 时,先执行 `checkTimeout` 检测超时任务,再按 **优先级降序 + startTime 升序** 取待执行系统任务,受 `limit` 并发上限控制。
38
+ | 节点 | 说明 |
39
+ |-------------------------|-----------------------------------------------------|
40
+ | `checkTimeout` | 每次调度前检测 `running` / `waiting` 中已超过任务级 `timeout` 的任务 |
41
+ | `claimPendingTasks` | 使用带状态条件的更新将 `pending` 原子认领为 `running`,避免多实例重复执行 |
42
+ | `processSystemTask` | 执行任务脚本,并根据结果、异常、重试次数和回调状态更新任务 |
43
+ | `collectTaskStatistics` | 任务进入终态后采集数量和耗时指标 |
44
+
45
+ > **关键设计**:cron 每次触发 `runner` 时先检测超时任务,再按 **优先级降序 + startTime 升序** 认领待执行系统任务。认领通过条件更新完成,只有仍处于
46
+ `pending` 的任务会被当前实例执行。
34
47
 
35
48
  ### 核心概念详解
36
49
 
37
50
  #### 任务状态
38
51
 
39
- | 状态 | 说明 | 可流转到 |
40
- |------|------|----------|
41
- | `pending` | 待执行 | `running`、`canceled` |
42
- | `running` | 执行中 | `success`、`failed`、`waiting`、`pending`(重试) |
43
- | `waiting` | 等待外部回调 | `success`、`failed` |
44
- | `success` | 执行成功 | 终态 |
45
- | `failed` | 执行失败 | `pending`(重试) |
46
- | `canceled` | 已取消 | `pending`(重试) |
52
+ | 状态 | 说明 | 可流转到 |
53
+ |------------|--------|--------------------------------------------|
54
+ | `pending` | 待执行 | `running`、`canceled` |
55
+ | `running` | 执行中 | `success`、`failed`、`waiting`、`pending`(重试) |
56
+ | `waiting` | 等待外部回调 | `success`、`failed` |
57
+ | `success` | 执行成功 | 终态 |
58
+ | `failed` | 执行失败 | `pending`(重试) |
59
+ | `canceled` | 已取消 | `pending`(重试) |
47
60
 
48
61
  #### 执行模式
49
62
 
50
- | 模式 | runnerType | 触发方式 | 说明 |
51
- |------|-----------|----------|------|
52
- | 系统自动 | `system` | cron 定时调度 `runner` | 按优先级和 startTime 自动执行 |
53
- | 手动执行 | `manual` | 用户通过 `complete` 接口完成 | 任务创建后等待人工操作 |
63
+ | 模式 | runnerType | 触发方式 | 说明 |
64
+ |------|------------|----------------------|----------------------|
65
+ | 系统自动 | `system` | cron 定时调度 `runner` | 按优先级和 startTime 自动执行 |
66
+ | 手动执行 | `manual` | 用户通过 `complete` 接口完成 | 任务创建后等待人工操作 |
67
+
68
+ #### 调度与恢复
69
+
70
+ | 机制 | 触发时机 | 说明 |
71
+ |------|--------------------------|-------------------------------------------------------------------|
72
+ | 并发上限 | 每次 `runner()` 执行 | 当前 `running` 系统任务数达到 `limit` 时不再认领新任务 |
73
+ | 原子认领 | 查询到候选 `pending` 任务后 | 通过 `id + runnerType + status + startTime` 条件更新为 `running`,认领失败则跳过 |
74
+ | 启动恢复 | Fastify `onReady` | 默认只将超过 `recoverRunningTaskAfter` 的陈旧 `running` 任务恢复为 `pending` |
75
+ | 手动重置 | 调用 `services.resetAll()` | 不传 `staleOnly` 时会将所有 `running` 任务重置为 `pending` |
54
76
 
55
77
  ### 主要特性
56
78
 
57
- | 特性 | 说明 |
58
- |------|------|
59
- | 任务创建与管理 | 支持创建、取消、重试、完成任务 |
60
- | 多种执行模式 | system 自动执行 / manual 手动执行 |
61
- | 定时任务调度 | 基于 cron 表达式定时执行系统任务 |
62
- | 任务状态追踪 | 实时追踪进度、轮询结果 |
63
- | 异步回调支持 | 支持 `next` → `processNext`/`callback` 回调链路 |
64
- | 日志记录 | 任务执行日志,最多保留 100 条 |
65
- | 优先级与依赖 | 优先级排序 + 父子任务链式执行 |
66
- | 自动重试 | 指数退避重试策略 |
67
- | 超时控制 | 任务级别超时设置,超时自动标记 failed |
68
- | 统计面板 | 任务统计数据查询 + SSE 实时推送 |
79
+ | 特性 | 说明 |
80
+ |---------|-------------------------------------------|
81
+ | 任务创建与管理 | 支持创建、取消、重试、完成任务 |
82
+ | 多种执行模式 | system 自动执行 / manual 手动执行 |
83
+ | 定时任务调度 | 基于 cron 表达式定时执行系统任务 |
84
+ | 任务状态追踪 | 实时追踪进度、轮询结果 |
85
+ | 异步回调支持 | 支持 `next` → `processNext`/`callback` 回调链路 |
86
+ | 日志记录 | 任务执行日志,最多保留 100 条 |
87
+ | 优先级与依赖 | 优先级排序 + 父子任务链式执行 |
88
+ | 自动重试 | 指数退避重试策略 |
89
+ | 超时控制 | 全局执行超时和任务级超时均使用毫秒,超时自动标记 failed |
90
+ | 多实例调度 | 待执行任务通过原子认领进入 running,降低重复执行风险 |
91
+ | 统计面板 | 任务统计数据查询 + SSE 实时推送 |
69
92
 
70
93
  ### 使用方法
71
94
 
72
95
  #### 插件注册与配置
73
96
 
74
- ```javascript
97
+ ```js
75
98
  // 基础注册
76
99
  const fastify = require('fastify')();
77
100
  fastify.register(require('@kne/fastify-task'), {
@@ -79,7 +102,7 @@ fastify.register(require('@kne/fastify-task'), {
79
102
  });
80
103
  ```
81
104
 
82
- ```javascript
105
+ ```js
83
106
  // 带任务类型处理函数的注册
84
107
  fastify.register(require('@kne/fastify-task'), {
85
108
  task: {
@@ -105,7 +128,7 @@ libs/tasks/
105
128
 
106
129
  **脚本模板:**
107
130
 
108
- ```javascript
131
+ ```js
109
132
  module.exports = async (fastify, options, { task, updateProgress, polling, next, log }) => {
110
133
  const { input } = task;
111
134
 
@@ -138,47 +161,48 @@ module.exports = async (fastify, options, { task, updateProgress, polling, next,
138
161
 
139
162
  #### executor 辅助方法
140
163
 
141
- | 方法签名 | 说明 |
142
- |----------|------|
143
- | `updateProgress(progress)` | 更新任务进度 (0-100) |
144
- | `polling(callback, options)` | 轮询外部服务直到完成 |
145
- | `next(context)` | 设置任务为 waiting 状态,返回 `false` 暂停执行 |
146
- | `log({ data, message })` | 记录任务执行日志 |
164
+ | 方法签名 | 说明 |
165
+ |------------------------------|----------------------------------|
166
+ | `updateProgress(progress)` | 更新任务进度 (0-100) |
167
+ | `polling(callback, options)` | 轮询外部服务直到完成 |
168
+ | `next(context)` | 设置任务为 waiting 状态,返回 `false` 暂停执行 |
169
+ | `log({ data, message })` | 记录任务执行日志 |
147
170
 
148
171
  **polling options 参数:**
149
172
 
150
- | 参数名 | 类型 | 默认值 | 说明 |
151
- |--------|------|--------|------|
152
- | `maxPollTimes` | number | `20` | 最大轮询次数 |
173
+ | 参数名 | 类型 | 默认值 | 说明 |
174
+ |----------------|--------|---------|----------|
175
+ | `maxPollTimes` | number | `20` | 最大轮询次数 |
153
176
  | `pollInterval` | number | `10000` | 轮询间隔(毫秒) |
154
177
 
155
178
  **polling callback 返回格式:**
156
179
 
157
- | 字段 | 类型 | 说明 |
158
- |------|------|------|
159
- | `result` | string | `'success'` / `'failed'` / `'pending'` |
160
- | `data` | object | 成功时返回的数据 |
161
- | `message` | string | 消息 |
162
- | `progress` | number | 当前进度 |
180
+ | 字段 | 类型 | 说明 |
181
+ |------------|--------|----------------------------------------|
182
+ | `result` | string | `'success'` / `'failed'` / `'pending'` |
183
+ | `data` | object | 成功时返回的数据 |
184
+ | `message` | string | 消息 |
185
+ | `progress` | number | 当前进度 |
163
186
 
164
187
  #### 任务类型处理函数
165
188
 
166
189
  任务完成后自动调用对应 `task[type]` 处理函数,接收参数:
167
190
 
168
- | 参数名 | 类型 | 说明 |
169
- |--------|------|------|
170
- | `task` | Task | 任务实例 |
171
- | `result` | object / string | 任务输出结果 |
172
- | `context` | object | 任务上下文(`next` 时设置的数据) |
191
+ | 参数名 | 类型 | 说明 |
192
+ |-----------|-----------------|----------------------|
193
+ | `task` | Task | 任务实例 |
194
+ | `result` | object / string | 任务输出结果 |
195
+ | `context` | object | 任务上下文(`next` 时设置的数据) |
173
196
 
174
197
  #### 运行时动态添加
175
198
 
176
- ```javascript
199
+ ```js
177
200
  // 通过 append 方法运行时添加任务目录和类型
178
201
  const result = await fastify.task.services.append({
179
202
  dirs: ['/path/to/tasks'],
180
203
  tasks: {
181
- 'new-type': async ({ task, result }) => { /* 处理逻辑 */ }
204
+ 'new-type': async ({ task, result }) => { /* 处理逻辑 */
205
+ }
182
206
  }
183
207
  });
184
208
  // result.dirs → 实际添加的目录列表
@@ -191,7 +215,7 @@ const result = await fastify.task.services.append({
191
215
 
192
216
  **签名生成方法:**
193
217
 
194
- ```javascript
218
+ ```js
195
219
  const crypto = require('node:crypto');
196
220
 
197
221
  function generateSignature({ secret, id, data }) {
@@ -205,13 +229,13 @@ function generateSignature({ secret, id, data }) {
205
229
 
206
230
  **各接口签名数据格式:**
207
231
 
208
- | 接口 | data 格式 |
209
- |------|-----------|
210
- | `processNext` | `result` 字符串(JSON 格式结果) |
211
- | `logWithSignature` | `{ data, message }` 对象 |
232
+ | 接口 | data 格式 |
233
+ |-------------------------|------------------------------|
234
+ | `processNext` | `result` 字符串(JSON 格式结果) |
235
+ | `logWithSignature` | `{ data, message }` 对象 |
212
236
  | `callbackWithSignature` | `{ code, data, message }` 对象 |
213
237
 
214
- ```javascript
238
+ ```js
215
239
  // processNext 签名
216
240
  const result = JSON.stringify({ code: 0, data: { output: 'done' } });
217
241
  const signature = generateSignature({ secret: 'your-secret', id: 'task-1', data: result });
@@ -227,12 +251,12 @@ const signature = generateSignature({
227
251
 
228
252
  #### 插件依赖
229
253
 
230
- | 依赖 | 说明 |
231
- |------|------|
232
- | `fastify-cron` | 定时任务支持 |
233
- | `@kne/fastify-namespace` | 命名空间模块化 |
234
- | `@kne/fastify-statistics` | 统计数据采集 |
235
- | `fastify-sequelize` | 数据库模型支持 |
254
+ | 依赖 | 说明 |
255
+ |---------------------------|---------|
256
+ | `fastify-cron` | 定时任务支持 |
257
+ | `@kne/fastify-namespace` | 命名空间模块化 |
258
+ | `@kne/fastify-statistics` | 统计数据采集 |
259
+ | `fastify-sequelize` | 数据库模型支持 |
236
260
 
237
261
 
238
262
  ### 示例
@@ -241,25 +265,30 @@ const signature = generateSignature({
241
265
 
242
266
  ### 配置项
243
267
 
244
- | 属性名 | 类型 | 必填 | 默认值 | 说明 |
245
- |--------|------|------|--------|------|
246
- | `dbTableNamePrefix` | string | 否 | `'t_'` | 数据库表名前缀 |
247
- | `prefix` | string | 否 | `'/api/task'` | API 路由前缀 |
248
- | `name` | string | 否 | `'task'` | 插件命名空间名称 |
249
- | `limit` | number | 否 | `10` | 系统任务并发执行上限 |
250
- | `dir` | string | 否 | `'libs/tasks'` | 任务脚本目录(向后兼容,优先级高于 dirs) |
251
- | `dirs` | array | 否 | `null` | 任务脚本目录列表,运行时可通过 `append` 动态添加 |
252
- | `cronTime` | string | 否 | `'*/10 * * * *'` | 定时任务 Cron 表达式 |
253
- | `scriptName` | string | 否 | `'index'` | 默认任务脚本名称 |
254
- | `maxPollTimes` | number | 否 | `20` | 最大轮询次数 |
255
- | `pollInterval` | number | 否 | `10000` | 轮询间隔(毫秒) |
256
- | `taskTimeout` | number | 否 | `1800000` | 任务执行超时时间(毫秒),0 表示不超时,默认 30 分钟 |
257
- | `retryBaseDelay` | number | 否 | `5000` | 重试基础延迟(毫秒),实际延迟 = `retryBaseDelay * 2^(retryCount-1)` |
258
- | `getUserModel` | function | 否 | - | 获取用户 Model 的函数 |
259
- | `getAuthenticate` | function | 否 | - | 获取认证中间件的函数 |
260
- | `task` | object | 否 | `{}` | 任务类型处理函数配置,`{ [type]: handler }` |
261
-
262
- > **关键设计**:`dirs` 初始化逻辑 — 优先使用用户传入的 `dirs`,否则以 `dir` 为默认值;若 `dirs` 中不包含 `dir`,则将 `dir` 插入 `dirs` 首位,保证向后兼容。
268
+ | 属性名 | 类型 | 必填 | 默认值 | 说明 |
269
+ |------------------------------|---------------|----|------------------|--------------------------------------------------------------------------------|
270
+ | `dbTableNamePrefix` | string | 否 | `'t_'` | 数据库表名前缀 |
271
+ | `prefix` | string | 否 | `'/api/task'` | API 路由前缀 |
272
+ | `name` | string | 否 | `'task'` | 插件命名空间名称 |
273
+ | `limit` | number | 否 | `10` | 系统任务并发执行上限 |
274
+ | `dir` | string | 否 | `'libs/tasks'` | 任务脚本目录(向后兼容,优先级高于 dirs) |
275
+ | `dirs` | array | 否 | `null` | 任务脚本目录列表,运行时可通过 `append` 动态添加 |
276
+ | `cronTime` | string | 否 | `'*/10 * * * *'` | 定时任务 Cron 表达式 |
277
+ | `scriptName` | string | 否 | `'index'` | 默认任务脚本名称 |
278
+ | `maxPollTimes` | number | 否 | `20` | 最大轮询次数 |
279
+ | `pollInterval` | number | 否 | `10000` | 轮询间隔(毫秒) |
280
+ | `taskTimeout` | number | 否 | `1800000` | 任务执行超时时间(毫秒),0 表示不超时 |
281
+ | `recoverRunningTaskAfter` | number / null | 否 | `null` | 启动恢复 running 任务的陈旧阈值(毫秒);未传时使用 `taskTimeout`,若 `taskTimeout` 为 0 则使用 `1800000` |
282
+ | `recoverRunningTasksOnStart` | boolean | 否 | `true` | 启动时是否恢复陈旧 running 任务 |
283
+ | `retryBaseDelay` | number | 否 | `5000` | 重试基础延迟(毫秒),实际延迟 = `retryBaseDelay * 2^(retryCount-1)` |
284
+ | `getUserModel` | function | 否 | - | 获取用户 Model 的函数 |
285
+ | `getAuthenticate` | function | 否 | - | 获取认证中间件的函数 |
286
+ | `task` | object | 否 | `{}` | 任务类型处理函数配置,`{ [type]: handler }` |
287
+
288
+ > **关键设计**:`dirs` 初始化逻辑 — 优先使用用户传入的 `dirs`,否则以 `dir` 为默认值;若 `dirs` 中不包含 `dir`,则将 `dir`
289
+ > 插入 `dirs` 首位,保证向后兼容。
290
+
291
+ > **关键设计**:`recoverRunningTasksOnStart` 只恢复陈旧 `running` 任务,避免多实例部署时某个实例重启误重置其他实例正在执行的任务。
263
292
 
264
293
  ### HTTP 接口
265
294
 
@@ -267,159 +296,206 @@ const signature = generateSignature({
267
296
 
268
297
  创建任务,需 `write` 权限。
269
298
 
270
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
271
- |--------|------|------|--------|------|
272
- | type | string | 是 | - | 任务类型,必须在 `task` 配置中声明 |
273
- | targetId | string | 是 | - | 目标对象ID |
274
- | targetType | string | 是 | - | 目标对象类型 |
275
- | input | object | 否 | - | 输入数据 |
276
- | runnerType | string | 否 | - | 执行者类型:`manual` / `system` |
277
- | delay | number | 否 | `0` | 延迟执行秒数 |
278
- | scriptName | string | 否 | - | 任务脚本名称 |
279
- | priority | number | 否 | `0` | 优先级,数值越大越优先 |
280
- | parentTaskId | string | 否 | - | 父任务ID,用于任务依赖 |
281
- | maxRetries | number | 否 | `0` | 最大自动重试次数 |
282
- | timeout | number | 否 | `60` | 任务超时时间(分钟),0 表示不超时 |
299
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
300
+ |--------------|--------|----|-----------|---------------------------|
301
+ | type | string | 是 | - | 任务类型,必须在 `task` 配置中声明 |
302
+ | targetId | string | 是 | - | 目标对象ID |
303
+ | targetType | string | 是 | - | 目标对象类型 |
304
+ | input | object | 否 | - | 输入数据 |
305
+ | runnerType | string | 否 | - | 执行者类型:`manual` / `system` |
306
+ | delay | number | 否 | `0` | 延迟执行秒数 |
307
+ | scriptName | string | 否 | - | 任务脚本名称 |
308
+ | priority | number | 否 | `0` | 优先级,数值越大越优先 |
309
+ | parentTaskId | string | 否 | - | 父任务ID,用于任务依赖 |
310
+ | maxRetries | number | 否 | `0` | 最大自动重试次数 |
311
+ | timeout | number | 否 | `3600000` | 任务超时时间(毫秒),0 表示不超时 |
283
312
 
284
313
  返回值:
285
314
 
286
- | 属性名 | 类型 | 说明 |
287
- |--------|------|------|
288
- | id | string | 任务ID |
315
+ ```json
316
+ {
317
+ "id": "task-1"
318
+ }
319
+ ```
289
320
 
290
321
  #### GET `{prefix}/list`
291
322
 
292
323
  获取任务列表,需 `read` 权限。
293
324
 
294
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
295
- |--------|------|------|--------|------|
296
- | perPage | number | 否 | `20` | 每页数量 |
297
- | currentPage | number | 否 | `1` | 当前页码 |
298
- | filter.id | string | 否 | - | 任务ID |
299
- | filter.targetId | string | 否 | - | 目标对象ID |
300
- | filter.targetName | string | 否 | - | 目标名称(模糊匹配 `input.name`) |
301
- | filter.type | string | 否 | - | 任务类型 |
302
- | filter.status | string | 否 | - | 任务状态 |
303
- | filter.runnerType | string | 否 | - | 执行者类型 |
304
- | filter.createdAt.startTime | string | 否 | - | 创建时间起始 |
305
- | filter.createdAt.endTime | string | 否 | - | 创建时间结束 |
306
- | filter.completedAt.startTime | string | 否 | - | 完成时间起始 |
307
- | filter.completedAt.endTime | string | 否 | - | 完成时间结束 |
308
- | sort | object | 否 | - | 排序规则(支持 `completedAt`、`updatedAt` 等字段,`ASC`/`DESC`) |
325
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
326
+ |------------------------------|--------|----|------|-----------------------------------------------------|
327
+ | perPage | number | 否 | `20` | 每页数量 |
328
+ | currentPage | number | 否 | `1` | 当前页码 |
329
+ | filter.id | string | 否 | - | 任务ID |
330
+ | filter.targetId | string | 否 | - | 目标对象ID |
331
+ | filter.targetName | string | 否 | - | 目标名称(模糊匹配 `input.name`) |
332
+ | filter.type | string | 否 | - | 任务类型 |
333
+ | filter.status | string | 否 | - | 任务状态 |
334
+ | filter.runnerType | string | 否 | - | 执行者类型 |
335
+ | filter.createdAt.startTime | string | 否 | - | 创建时间起始 |
336
+ | filter.createdAt.endTime | string | 否 | - | 创建时间结束 |
337
+ | filter.completedAt.startTime | string | 否 | - | 完成时间起始 |
338
+ | filter.completedAt.endTime | string | 否 | - | 完成时间结束 |
339
+ | sort | object | 否 | - | 排序规则(支持 `completedAt`、`updatedAt` 等字段,`ASC`/`DESC`) |
309
340
 
310
341
  返回值:
311
342
 
312
- | 属性名 | 类型 | 说明 |
313
- |--------|------|------|
314
- | pageData | array | 任务列表 |
315
- | totalCount | number | 总数量 |
343
+ ```json
344
+ {
345
+ "pageData": [],
346
+ "totalCount": 0
347
+ }
348
+ ```
316
349
 
317
350
  #### POST `{prefix}/complete`
318
351
 
319
352
  手动完成任务,需 `write` 权限。
320
353
 
321
- | 参数名 | 类型 | 必填 | 说明 |
322
- |--------|------|------|------|
323
- | id | string | 是 | 任务ID |
324
- | status | string | 是 | 完成状态:`success` / `failed` |
325
- | error | string | 否 | 错误信息 |
326
- | msg | string | 否 | 消息 |
327
- | output | object | 否 | 输出数据 |
354
+ | 参数名 | 类型 | 必填 | 说明 |
355
+ |--------|--------|----|---------------------------|
356
+ | id | string | 是 | 任务ID |
357
+ | status | string | 是 | 完成状态:`success` / `failed` |
358
+ | error | string | 否 | 错误信息 |
359
+ | msg | string | 否 | 消息 |
360
+ | output | object | 否 | 输出数据 |
361
+
362
+ 返回空对象:
363
+
364
+ ```json
365
+ {}
366
+ ```
328
367
 
329
368
  #### POST `{prefix}/cancel`
330
369
 
331
370
  取消任务,需 `write` 权限。支持单个取消(`id`)或批量取消(`targetId` + `targetType` + `type`)。
332
371
 
333
- | 参数名 | 类型 | 必填 | 说明 |
334
- |--------|------|------|------|
335
- | id | string | 否 | 任务ID(单个取消) |
336
- | targetId | string | 否 | 目标对象ID(批量取消,需配合 `targetType` 和 `type`) |
337
- | targetType | string | 否 | 目标对象类型(批量取消) |
338
- | type | string | 否 | 任务类型(批量取消) |
372
+ | 参数名 | 类型 | 必填 | 说明 |
373
+ |------------|--------|----|----------------------------------------|
374
+ | id | string | 否 | 任务ID(单个取消) |
375
+ | targetId | string | 否 | 目标对象ID(批量取消,需配合 `targetType` 和 `type`) |
376
+ | targetType | string | 否 | 目标对象类型(批量取消) |
377
+ | type | string | 否 | 任务类型(批量取消) |
378
+
379
+ 返回空对象:
380
+
381
+ ```json
382
+ {}
383
+ ```
339
384
 
340
385
  #### POST `{prefix}/retry`
341
386
 
342
387
  重试任务,需 `write` 权限。仅允许重试 `failed` 或 `canceled` 状态的任务。
343
388
 
344
- | 参数名 | 类型 | 必填 | 说明 |
345
- |--------|------|------|------|
346
- | id | string | 否 | 单个任务ID |
347
- | taskIds | string[] | 否 | 任务ID数组 |
389
+ | 参数名 | 类型 | 必填 | 说明 |
390
+ |---------|----------|----|--------|
391
+ | id | string | 否 | 单个任务ID |
392
+ | taskIds | array | 否 | 任务ID数组 |
393
+
394
+ 返回空对象:
395
+
396
+ ```json
397
+ {}
398
+ ```
348
399
 
349
400
  #### POST `{prefix}/next`
350
401
 
351
402
  处理等待回调的任务,无需认证。当任务设置了 `context.secret` 时需提供签名。
352
403
 
353
- | 参数名 | 类型 | 必填 | 说明 |
354
- |--------|------|------|------|
355
- | id | string | 是 | 任务ID |
356
- | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
357
- | result | string | 是 | JSON 格式结果字符串 |
404
+ | 参数名 | 类型 | 必填 | 说明 |
405
+ |-----------|--------|----|------------------------------------------|
406
+ | id | string | 是 | 任务ID |
407
+ | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
408
+ | result | string | 是 | JSON 格式结果字符串 |
409
+
410
+ 成功处理时返回空对象:
411
+
412
+ ```json
413
+ {}
414
+ ```
358
415
 
359
416
  #### POST `{prefix}/log`
360
417
 
361
418
  记录任务日志,无需认证。当任务设置了 `context.secret` 时需提供签名。
362
419
 
363
- | 参数名 | 类型 | 必填 | 说明 |
364
- |--------|------|------|------|
365
- | id | string | 否 | 任务ID(body) |
366
- | taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
367
- | data | object | 否 | 日志数据 |
368
- | message | string | 否 | 日志消息 |
369
- | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
420
+ | 参数名 | 类型 | 必填 | 说明 |
421
+ |-----------|--------|----|------------------------------------------|
422
+ | id | string | 否 | 任务ID(body) |
423
+ | taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
424
+ | data | object | 否 | 日志数据 |
425
+ | message | string | 否 | 日志消息 |
426
+ | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
427
+
428
+ 返回更新后的 Task 实例:
429
+
430
+ ```json
431
+ {
432
+ "id": "task-1",
433
+ "options": {
434
+ "logs": []
435
+ }
436
+ }
437
+ ```
370
438
 
371
439
  #### POST `{prefix}/callback`
372
440
 
373
441
  任务回调,无需认证。当任务设置了 `context.secret` 时需提供签名。
374
442
 
375
- | 参数名 | 类型 | 必填 | 说明 |
376
- |--------|------|------|------|
377
- | id | string | 否 | 任务ID(body) |
378
- | taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
379
- | code | number | 是 | 状态码,0 为成功 |
380
- | data | object | 否 | 回调数据 |
381
- | message | string | 否 | 回调消息 |
382
- | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
443
+ | 参数名 | 类型 | 必填 | 说明 |
444
+ |-----------|--------|----|------------------------------------------|
445
+ | id | string | 否 | 任务ID(body) |
446
+ | taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
447
+ | code | number | 是 | 状态码,0 为成功 |
448
+ | data | object | 否 | 回调数据 |
449
+ | message | string | 否 | 回调消息 |
450
+ | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
451
+
452
+ 成功处理时返回空对象:
453
+
454
+ ```json
455
+ {}
456
+ ```
383
457
 
384
458
  #### GET `{prefix}/statistics`
385
459
 
386
460
  获取任务统计概览,需 `statistics` 权限。
387
461
 
388
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
389
- |--------|------|------|--------|------|
390
- | range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
391
- | timezone | string | 否 | 服务器时区 | 时区,如 `Asia/Shanghai` |
392
- | type | string | 否 | - | 按任务类型筛选 |
393
- | runnerType | string | 否 | - | 按执行方式筛选 `manual` / `system` |
462
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
463
+ |------------|--------|----|--------|--------------------------------|
464
+ | range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
465
+ | timezone | string | 否 | 服务器时区 | 时区,如 `Asia/Shanghai` |
466
+ | type | string | 否 | - | 按任务类型筛选 |
467
+ | runnerType | string | 否 | - | 按执行方式筛选 `manual` / `system` |
394
468
 
395
469
  返回值:
396
470
 
397
- | 属性名 | 类型 | 说明 |
398
- |--------|------|------|
399
- | range | string | 时间范围标识 |
400
- | rangeLabel | string | 时间范围中文描述 |
401
- | totalTasks | number | 任务总数 |
402
- | byStatus | object | 按状态统计 `{ success, failed, canceled }` |
403
- | byType | object | 按类型统计 |
404
- | byRunnerType | object | 按执行方式统计 |
405
- | recentTrend | array | 近期每日趋势 `[{ date, count }]` |
406
- | recentTrendByStatus | array | 近期每日按状态趋势 |
407
- | recentTrendByType | array | 近期每日按类型趋势 |
408
- | durationTrend | array | 按日时长趋势 |
409
- | hourlyTrend | array | 小时级完成趋势 |
410
- | hourlyCompletionTrend | array | 小时级完成详情趋势 |
471
+ ```json
472
+ {
473
+ "range": "7d",
474
+ "rangeLabel": "最近7天",
475
+ "totalTasks": 0,
476
+ "byStatus": {},
477
+ "byType": {},
478
+ "byRunnerType": {},
479
+ "recentTrend": [],
480
+ "recentTrendByStatus": [],
481
+ "recentTrendByType": [],
482
+ "durationTrend": [],
483
+ "hourlyTrend": [],
484
+ "hourlyCompletionTrend": []
485
+ }
486
+ ```
411
487
 
412
488
  #### GET `{prefix}/statistics/sse`
413
489
 
414
490
  SSE 实时推送任务统计数据,需 `statistics` 权限。
415
491
 
416
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
417
- |--------|------|------|--------|------|
418
- | range | string | 否 | `'7d'` | 时间范围 |
419
- | timezone | string | 否 | 服务器时区 | 时区 |
420
- | type | string | 否 | - | 按任务类型筛选 |
421
- | runnerType | string | 否 | - | 按执行方式筛选 |
422
- | interval | number | 否 | `5` | 推送间隔时间(秒),最小 1 秒 |
492
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
493
+ |------------|--------|----|--------|------------------|
494
+ | range | string | 否 | `'7d'` | 时间范围 |
495
+ | timezone | string | 否 | 服务器时区 | 时区 |
496
+ | type | string | 否 | - | 按任务类型筛选 |
497
+ | runnerType | string | 否 | - | 按执行方式筛选 |
498
+ | interval | number | 否 | `5` | 推送间隔时间(秒),最小 1 秒 |
423
499
 
424
500
  ### 程序化 API
425
501
 
@@ -427,139 +503,141 @@ SSE 实时推送任务统计数据,需 `statistics` 权限。
427
503
 
428
504
  #### 任务管理
429
505
 
430
- | 方法签名 | 说明 |
431
- |----------|------|
432
- | `services.create({ userId, input, type, targetId, targetType, runnerType, delay, scriptName, priority, parentTaskId, maxRetries, timeout, options })` | 创建任务,返回 Task 实例 |
433
- | `services.detail({ id })` | 获取任务详情,返回 Task 实例 |
434
- | `services.list({ filter, perPage, currentPage, sort })` | 获取任务列表,返回 `{ pageData, totalCount }` |
435
- | `services.complete({ id, userId, status, output, error })` | 手动完成任务 |
436
- | `services.cancel({ id, targetId, targetType, type })` | 取消任务,支持单个或批量 |
437
- | `services.retry({ id, taskIds })` | 重试任务,仅允许 `failed`/`canceled` 状态 |
438
- | `services.waitingComplete({ id, pollInterval, maxPollTimes })` | 等待任务完成(轮询),返回任务输出数据 |
506
+ | 方法签名 | 说明 |
507
+ |-------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
508
+ | `services.create({ userId, input, type, targetId, targetType, runnerType, delay, scriptName, priority, parentTaskId, maxRetries, timeout, options })` | 创建任务,返回 Task 实例 |
509
+ | `services.detail({ id })` | 获取任务详情,返回 Task 实例 |
510
+ | `services.list({ filter, perPage, currentPage, sort })` | 获取任务列表,返回 `{ pageData, totalCount }` |
511
+ | `services.complete({ id, userId, status, output, error })` | 手动完成任务 |
512
+ | `services.cancel({ id, targetId, targetType, type })` | 取消任务,支持单个或批量 |
513
+ | `services.retry({ id, taskIds })` | 重试任务,仅允许 `failed`/`canceled` 状态 |
514
+ | `services.waitingComplete({ id, pollInterval, maxPollTimes })` | 等待任务完成(轮询),返回任务输出数据 |
439
515
 
440
516
  **services.create 参数:**
441
517
 
442
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
443
- |--------|------|------|--------|------|
444
- | userId | string | 否 | - | 用户ID |
445
- | input | object | 否 | - | 输入数据 |
446
- | type | string | 是 | - | 任务类型 |
447
- | targetId | string | 是 | - | 目标对象ID |
448
- | targetType | string | 是 | - | 目标对象类型 |
449
- | runnerType | string | 否 | - | 执行者类型 |
450
- | delay | number | 否 | `0` | 延迟执行秒数 |
451
- | scriptName | string | 否 | - | 脚本名称 |
452
- | priority | number | 否 | `0` | 优先级 |
453
- | parentTaskId | string | 否 | - | 父任务ID |
454
- | maxRetries | number | 否 | `0` | 最大重试次数 |
455
- | timeout | number | 否 | `60` | 超时时间(分钟) |
456
- | options | object | 否 | - | 扩展选项 |
518
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
519
+ |--------------|--------|----|-----------|----------|
520
+ | userId | string | 否 | - | 用户ID |
521
+ | input | object | 否 | - | 输入数据 |
522
+ | type | string | 是 | - | 任务类型 |
523
+ | targetId | string | 是 | - | 目标对象ID |
524
+ | targetType | string | 是 | - | 目标对象类型 |
525
+ | runnerType | string | 否 | - | 执行者类型 |
526
+ | delay | number | 否 | `0` | 延迟执行秒数 |
527
+ | scriptName | string | 否 | - | 脚本名称 |
528
+ | priority | number | 否 | `0` | 优先级 |
529
+ | parentTaskId | string | 否 | - | 父任务ID |
530
+ | maxRetries | number | 否 | `0` | 最大重试次数 |
531
+ | timeout | number | 否 | `3600000` | 超时时间(毫秒) |
532
+ | options | object | 否 | - | 扩展选项 |
457
533
 
458
534
  **services.waitingComplete 参数:**
459
535
 
460
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
461
- |--------|------|------|--------|------|
462
- | id | string | 是 | - | 任务ID |
463
- | pollInterval | number | 否 | `1000` | 轮询间隔(毫秒) |
464
- | maxPollTimes | number | 否 | `20` | 最大轮询次数 |
536
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
537
+ |--------------|--------|----|--------|----------|
538
+ | id | string | 是 | - | 任务ID |
539
+ | pollInterval | number | 否 | `1000` | 轮询间隔(毫秒) |
540
+ | maxPollTimes | number | 否 | `20` | 最大轮询次数 |
465
541
 
466
542
  #### 回调与日志
467
543
 
468
- | 方法签名 | 说明 |
469
- |----------|------|
470
- | `services.processNext({ id, signature, result })` | 处理等待回调的任务,需签名验证 |
471
- | `services.callback({ id, code, data, message })` | 任务回调(内部调用,无需签名) |
472
- | `services.callbackWithSignature({ id, code, data, message, signature })` | 任务回调(外部调用,需签名验证) |
473
- | `services.log({ id, taskId, data, message })` | 记录日志(内部调用,无需签名),最多 100 条 |
474
- | `services.logWithSignature({ id, taskId, data, message, signature })` | 记录日志(外部调用,需签名验证) |
544
+ | 方法签名 | 说明 |
545
+ |--------------------------------------------------------------------------|--------------------------|
546
+ | `services.processNext({ id, signature, result })` | 处理等待回调的任务,需签名验证 |
547
+ | `services.callback({ id, code, data, message })` | 任务回调(内部调用,无需签名) |
548
+ | `services.callbackWithSignature({ id, code, data, message, signature })` | 任务回调(外部调用,需签名验证) |
549
+ | `services.log({ id, taskId, data, message })` | 记录日志(内部调用,无需签名),最多 100 条 |
550
+ | `services.logWithSignature({ id, taskId, data, message, signature })` | 记录日志(外部调用,需签名验证) |
475
551
 
476
552
  #### 系统调度
477
553
 
478
- | 方法签名 | 说明 |
479
- |----------|------|
480
- | `services.runner()` | 执行系统任务,由 cron 定时调用 |
481
- | `services.resetAll()` | 重置所有 running 任务为 pending |
482
- | `services.append({ dirs, tasks })` | 运行时动态添加任务目录和类型,返回 `{ dirs, tasks }` |
554
+ | 方法签名 | 说明 |
555
+ |--------------------------------------------|------------------------------------------------------|
556
+ | `services.runner()` | 执行系统任务,由 cron 定时调用 |
557
+ | `services.claimPendingTasks(limit)` | 按优先级和开始时间认领待执行系统任务,返回已认领任务列表 |
558
+ | `services.processSystemTask(task, opts)` | 执行系统任务;`opts.claimed` 为 `true` 时跳过重复置为 running |
559
+ | `services.resetAll({ staleOnly, before })` | 重置 running 任务为 pending;`staleOnly` 为 `true` 时只恢复陈旧任务 |
560
+ | `services.append({ dirs, tasks })` | 运行时动态添加任务目录和类型,返回 `{ dirs, tasks }` |
483
561
 
484
562
  #### 统计查询
485
563
 
486
- | 方法签名 | 说明 |
487
- |----------|------|
488
- | `services.queryStatistics({ range, timezone, type, runnerType })` | 查询任务统计数据 |
564
+ | 方法签名 | 说明 |
565
+ |----------------------------------------------------------------------------------|--------------|
566
+ | `services.queryStatistics({ range, timezone, type, runnerType })` | 查询任务统计数据 |
489
567
  | `services.sseStatistics({ range, timezone, type, runnerType, interval }, reply)` | SSE 实时推送统计数据 |
490
568
 
491
569
  **services.queryStatistics 参数:**
492
570
 
493
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
494
- |--------|------|------|--------|------|
495
- | range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
496
- | timezone | string | 否 | 服务器时区 | 时区 |
497
- | type | string | 否 | - | 按任务类型筛选 |
498
- | runnerType | string | 否 | - | 按执行方式筛选 |
571
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
572
+ |------------|--------|----|--------|--------------------------------|
573
+ | range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
574
+ | timezone | string | 否 | 服务器时区 | 时区 |
575
+ | type | string | 否 | - | 按任务类型筛选 |
576
+ | runnerType | string | 否 | - | 按执行方式筛选 |
499
577
 
500
578
  **services.sseStatistics 参数:**
501
579
 
502
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
503
- |--------|------|------|--------|------|
504
- | range | string | 否 | `'7d'` | 时间范围 |
505
- | timezone | string | 否 | 服务器时区 | 时区 |
506
- | type | string | 否 | - | 按任务类型筛选 |
507
- | runnerType | string | 否 | - | 按执行方式筛选 |
508
- | interval | number | 否 | `5` | 推送间隔(秒) |
509
- | reply | object | 是 | - | Fastify reply 对象(第二个参数) |
580
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
581
+ |------------|--------|----|--------|-------------------------|
582
+ | range | string | 否 | `'7d'` | 时间范围 |
583
+ | timezone | string | 否 | 服务器时区 | 时区 |
584
+ | type | string | 否 | - | 按任务类型筛选 |
585
+ | runnerType | string | 否 | - | 按执行方式筛选 |
586
+ | interval | number | 否 | `5` | 推送间隔(秒) |
587
+ | reply | object | 是 | - | Fastify reply 对象(第二个参数) |
510
588
 
511
589
  ### 数据模型
512
590
 
513
591
  #### Task
514
592
 
515
- | 属性名 | 类型 | 说明 |
516
- |--------|------|------|
517
- | type | STRING | 任务类型 |
518
- | scriptName | STRING | 任务脚本名称 |
519
- | targetId | STRING | 任务目标对象ID |
520
- | targetType | STRING | 任务目标对象类型 |
521
- | runnerType | ENUM | 执行者类型 (`manual` / `system`),默认 `manual` |
522
- | priority | INTEGER | 任务优先级,数值越大越优先,默认 0 |
523
- | parentTaskId | STRING | 父任务ID,用于任务依赖 |
524
- | retryCount | INTEGER | 已重试次数,默认 0 |
525
- | maxRetries | INTEGER | 最大重试次数,0 表示不自动重试 |
526
- | timeout | INTEGER | 任务超时时间(分钟),0 表示不超时,默认 60 |
527
- | startTime | DATE | 任务最早执行时间 |
528
- | startedAt | DATE | 任务实际开始执行时间 |
529
- | completedAt | DATE | 任务完成时间 |
530
- | completedUserId | STRING | 完成任务的用户ID |
531
- | input | JSON | 输入数据 |
532
- | output | JSON | 输出数据 |
533
- | error | JSON | 错误信息 |
534
- | status | ENUM | 任务状态 (`pending` / `running` / `waiting` / `success` / `failed` / `canceled`),默认 `pending` |
535
- | context | JSON | 上下文信息 |
536
- | pollResults | JSON | 轮询执行结果 |
537
- | pollCount | INTEGER | 轮询次数,默认 0 |
538
- | progress | INTEGER | 任务进度 (0-100),默认 0 |
539
- | msg | TEXT | 任务消息 |
540
- | options | JSON | 任务扩展选项(含 `logs` 日志数组) |
593
+ | 属性名 | 类型 | 说明 |
594
+ |-----------------|-----------------|-----------------------------------------------------------------------------------------|
595
+ | type | string | 任务类型 |
596
+ | scriptName | string | 任务脚本名称 |
597
+ | targetId | string | 任务目标对象ID |
598
+ | targetType | string | 任务目标对象类型 |
599
+ | runnerType | string | 执行者类型:`manual` / `system`,默认 `manual` |
600
+ | priority | number | 任务优先级,数值越大越优先,默认 0 |
601
+ | parentTaskId | string | 父任务ID,用于任务依赖 |
602
+ | retryCount | number | 已重试次数,默认 0 |
603
+ | maxRetries | number | 最大重试次数,0 表示不自动重试 |
604
+ | timeout | number | 任务超时时间(毫秒),0 表示不超时,默认 3600000 |
605
+ | startTime | Date | 任务最早执行时间 |
606
+ | startedAt | Date | 任务实际开始执行时间 |
607
+ | completedAt | Date | 任务完成时间 |
608
+ | completedUserId | string | 完成任务的用户ID |
609
+ | input | object | 输入数据 |
610
+ | output | object | 输出数据 |
611
+ | error | string / object | 错误信息 |
612
+ | status | string | 任务状态:`pending` / `running` / `waiting` / `success` / `failed` / `canceled`,默认 `pending` |
613
+ | context | object | 上下文信息 |
614
+ | pollResults | array | 轮询执行结果 |
615
+ | pollCount | number | 轮询次数,默认 0 |
616
+ | progress | number | 任务进度 (0-100),默认 0 |
617
+ | msg | string | 任务消息 |
618
+ | options | object | 任务扩展选项(含 `logs` 日志数组) |
541
619
 
542
620
  **关联关系:**
543
621
 
544
- | 关联 | 外键 | 说明 |
545
- |------|------|------|
546
- | belongsTo User | `userId` | 创建人,`as: 'createdUser'` |
622
+ | 关联 | 外键 | 说明 |
623
+ |----------------|-------------------|---------------------------|
624
+ | belongsTo User | `userId` | 创建人,`as: 'createdUser'` |
547
625
  | belongsTo User | `completedUserId` | 完成人,`as: 'completedUser'` |
548
- | belongsTo Task | `parentTaskId` | 父任务,`as: 'parentTask'` |
626
+ | belongsTo Task | `parentTaskId` | 父任务,`as: 'parentTask'` |
549
627
 
550
628
  **索引:**
551
629
 
552
- | 索引字段 |
553
- |----------|
554
- | `created_at` |
555
- | `status` |
556
- | `type` |
557
- | `runner_type` |
558
- | `type, status` |
559
- | `runner_type, status` |
630
+ | 索引字段 |
631
+ |--------------------------------|
632
+ | `created_at` |
633
+ | `status` |
634
+ | `type` |
635
+ | `runner_type` |
636
+ | `type, status` |
637
+ | `runner_type, status` |
560
638
  | `target_id, target_type, type` |
561
- | `parent_task_id` |
562
- | `priority` |
639
+ | `parent_task_id` |
640
+ | `priority` |
563
641
 
564
642
  ### 机制说明
565
643
 
@@ -567,10 +645,10 @@ SSE 实时推送任务统计数据,需 `statistics` 权限。
567
645
 
568
646
  使用 HMAC-SHA256 算法,签名数据格式为 `{id}|{data}`,其中 `data` 为 JSON 字符串或原始字符串。
569
647
 
570
- | 接口 | 签名 data 内容 |
571
- |------|----------------|
572
- | `processNext` | `result` 参数值(原始 JSON 字符串) |
573
- | `logWithSignature` | `{ data, message }` 对象的 JSON 序列化 |
648
+ | 接口 | 签名 data 内容 |
649
+ |-------------------------|----------------------------------------|
650
+ | `processNext` | `result` 参数值(原始 JSON 字符串) |
651
+ | `logWithSignature` | `{ data, message }` 对象的 JSON 序列化 |
574
652
  | `callbackWithSignature` | `{ code, data, message }` 对象的 JSON 序列化 |
575
653
 
576
654
  > **关键设计**:未设置 `context.secret` 时 `verifySignature` 直接返回 `true`,不阻塞无密钥任务的回调。
@@ -579,10 +657,10 @@ SSE 实时推送任务统计数据,需 `statistics` 权限。
579
657
 
580
658
  任务执行失败时,判断是否满足自动重试条件(`retryCount < maxRetries`):
581
659
 
582
- | 条件 | 行为 |
583
- |------|------|
584
- | `retryCount < maxRetries` | 重置为 `pending`,`startTime` 设为当前时间 + 退避延迟 |
585
- | `retryCount >= maxRetries` | 标记为 `failed`,记录错误信息 |
660
+ | 条件 | 行为 |
661
+ |----------------------------|-----------------------------------------|
662
+ | `retryCount < maxRetries` | 重置为 `pending`,`startTime` 设为当前时间 + 退避延迟 |
663
+ | `retryCount >= maxRetries` | 标记为 `failed`,记录错误信息 |
586
664
 
587
665
  退避公式:`delay = retryBaseDelay × 2^(retryCount - 1)`
588
666
 
@@ -593,19 +671,31 @@ SSE 实时推送任务统计数据,需 `statistics` 权限。
593
671
  每次 `runner` 执行时先调用 `checkTimeout`,扫描所有 `running` / `waiting` 且 `timeout > 0` 的任务:
594
672
 
595
673
  ```
596
- 当前时间 - startedAt > timeout × 60 × 1000 → 标记为 failed
674
+ 当前时间 - startedAt > timeout → 标记为 failed
597
675
  ```
598
676
 
599
- > **关键设计**:`taskTimeout`(全局配置)和 `timeout`(任务级别,单位分钟)是两个不同概念。全局 `taskTimeout` 在 executor 执行时通过 `Promise.race` 控制;任务 `timeout` 字段在 cron 轮询时检测。
677
+ > **关键设计**:`taskTimeout`(全局配置)和 `timeout`(任务级别)均使用毫秒作为单位。全局 `taskTimeout` 在 executor 执行时通过
678
+ `Promise.race` 控制;任务 `timeout` 字段在 cron 轮询时检测。
679
+
680
+ #### 任务认领与启动恢复
681
+
682
+ | 机制 | 表达式 / 条件 | 说明 |
683
+ |------|-------------------------------------------------------------|-----------------------------------------------------|
684
+ | 认领候选 | `runnerType = system`、`status = pending`、`startTime <= now` | 按 `priority DESC`、`startTime ASC` 查询候选任务 |
685
+ | 原子认领 | `id + runnerType + status + startTime` 条件更新 | 只有更新影响 1 行的任务会被当前实例执行 |
686
+ | 启动恢复 | `resetAll({ staleOnly: true })` | 启动时只恢复超过 `recoverRunningTaskAfter` 的陈旧 `running` 任务 |
687
+ | 手动重置 | `resetAll()` | 不传 `staleOnly` 时会重置所有 `running` 任务 |
688
+
689
+ > **关键设计**:多实例部署时,任务执行前必须先认领;启动恢复默认只处理陈旧任务,避免误中断其他实例正在执行的任务。
600
690
 
601
691
  #### 父子任务依赖
602
692
 
603
693
  当父任务执行成功后,自动激活 `parentTaskId` 指向该父任务且状态为 `pending` 的子任务:
604
694
 
605
- | 子任务 runnerType | 激活行为 |
606
- |-------------------|----------|
607
- | `system` | 立即调用 `processSystemTask` 执行 |
608
- | `manual` | 保持 `pending`,等待手动执行 |
695
+ | 子任务 runnerType | 激活行为 |
696
+ |----------------|-----------------------------|
697
+ | `system` | 立即调用 `processSystemTask` 执行 |
698
+ | `manual` | 保持 `pending`,等待手动执行 |
609
699
 
610
700
  > **关键设计**:只有父任务 **成功** 后才触发子任务,失败或取消不会激活子任务。
611
701
 
@@ -613,10 +703,10 @@ SSE 实时推送任务统计数据,需 `statistics` 权限。
613
703
 
614
704
  任务完成时通过 `@kne/fastify-statistics` 采集数据,channel 格式为 `{type}:{runnerType}:{completedHour}`,采集维度:
615
705
 
616
- | 维度 | 单位 | 说明 |
617
- |------|------|------|
618
- | total | count | 总完成数 |
619
- | success / failed / canceled | count | 按状态计数 |
620
- | waitingTime | ms | 等待时长(startedAt - createdAt) |
621
- | executionTime | ms | 执行时长(completedAt - startedAt) |
622
- | totalTime | ms | 总时长(completedAt - createdAt) |
706
+ | 维度 | 单位 | 说明 |
707
+ |-----------------------------|-------|-------------------------------|
708
+ | total | count | 总完成数 |
709
+ | success / failed / canceled | count | 按状态计数 |
710
+ | waitingTime | ms | 等待时长(startedAt - createdAt) |
711
+ | executionTime | ms | 执行时长(completedAt - startedAt) |
712
+ | totalTime | ms | 总时长(completedAt - createdAt) |
package/index.js CHANGED
@@ -17,8 +17,12 @@ module.exports = fp(
17
17
  scriptName: 'index',
18
18
  maxPollTimes: 20,
19
19
  pollInterval: 10000,
20
- /** 任务执行超时时间(毫秒),0 表示不超时,默认 30 分钟 */
20
+ /** 任务执行超时时间(毫秒),0 表示不超时,默认 1800000ms */
21
21
  taskTimeout: 30 * 60 * 1000,
22
+ /** 启动时仅恢复超出该时间窗口的 running 任务,避免多实例重启误重置正在执行的任务 */
23
+ recoverRunningTaskAfter: null,
24
+ /** 是否在启动时恢复陈旧 running 任务 */
25
+ recoverRunningTasksOnStart: true,
22
26
  /** 重试基础延迟(毫秒),实际延迟 = retryBaseDelay * 2^(retryCount-1) */
23
27
  retryBaseDelay: 5000,
24
28
  getUserModel: () => {
@@ -32,6 +36,10 @@ module.exports = fp(
32
36
  options
33
37
  );
34
38
 
39
+ if (options.recoverRunningTaskAfter == null) {
40
+ options.recoverRunningTaskAfter = options.taskTimeout > 0 ? options.taskTimeout : 30 * 60 * 1000;
41
+ }
42
+
35
43
  // 初始化 dirs:优先使用用户传入的 dirs,否则以 dir 为默认值,保证向后兼容
36
44
  if (!options.dirs) {
37
45
  options.dirs = [options.dir];
@@ -72,9 +80,11 @@ module.exports = fp(
72
80
  },
73
81
  start: true
74
82
  });
75
- //启动时,将running状态的任务设置为pending
83
+ // 启动时只恢复陈旧 running 任务,避免多实例部署时重置其他实例正在执行的任务
76
84
  fastify.addHook('onReady', async () => {
77
- await fastify[options.name].services.resetAll();
85
+ if (options.recoverRunningTasksOnStart) {
86
+ await fastify[options.name].services.resetAll({ staleOnly: true });
87
+ }
78
88
  });
79
89
  }
80
90
  })
@@ -55,7 +55,7 @@ module.exports = fp(async (fastify, options) => {
55
55
  },
56
56
  timeout: {
57
57
  type: 'number',
58
- description: '任务超时时间(分钟),0表示不超时,默认60分钟'
58
+ description: '任务超时时间(毫秒),0表示不超时,默认3600000ms'
59
59
  }
60
60
  },
61
61
  required: ['type', 'targetId', 'targetType']
@@ -45,8 +45,8 @@ module.exports = ({ DataTypes, definePrimaryType, options }) => {
45
45
  },
46
46
  timeout: {
47
47
  type: DataTypes.INTEGER,
48
- comment: '任务超时时间(分钟),0表示不超时,默认60分钟',
49
- defaultValue: 60
48
+ comment: '任务超时时间(毫秒),0表示不超时,默认3600000ms',
49
+ defaultValue: 60 * 60 * 1000
50
50
  },
51
51
  startTime: {
52
52
  type: DataTypes.DATE,
@@ -67,7 +67,7 @@ module.exports = fp(async (fastify, options) => {
67
67
  return signature === expectedSignature;
68
68
  };
69
69
 
70
- const create = async ({ userId, input, type, targetId, targetType, runnerType, delay = 0, scriptName, priority = 0, parentTaskId, maxRetries = 0, timeout = 60, options: currentOptions }) => {
70
+ const create = async ({ userId, input, type, targetId, targetType, runnerType, delay = 0, scriptName, priority = 0, parentTaskId, maxRetries = 0, timeout = 60 * 60 * 1000, options: currentOptions }) => {
71
71
  if (typeof delay !== 'number' || delay < 0) {
72
72
  throw new Error('delay 必须为非负数');
73
73
  }
@@ -101,16 +101,22 @@ module.exports = fp(async (fastify, options) => {
101
101
  return task;
102
102
  };
103
103
 
104
- const resetAll = async () => {
105
- const runningTasks = await models.task.findAll({
106
- where: { status: 'running' },
107
- attributes: ['type', 'runnerType'],
108
- raw: true
109
- });
110
- await models.task.update(
111
- { status: 'pending' },
112
- { where: { status: 'running' } }
113
- );
104
+ const getRunningRecoveryBefore = () => {
105
+ const recoverAfter = Number.isInteger(options.recoverRunningTaskAfter) && options.recoverRunningTaskAfter >= 0 ? options.recoverRunningTaskAfter : 30 * 60 * 1000;
106
+ return new Date(Date.now() - recoverAfter);
107
+ };
108
+
109
+ const getRunningResetWhere = ({ staleOnly = false, before } = {}) => {
110
+ const where = { status: 'running' };
111
+ if (staleOnly) {
112
+ where[Op.or] = [{ startedAt: { [Op.lte]: before || getRunningRecoveryBefore() } }, { startedAt: null }];
113
+ }
114
+ return where;
115
+ };
116
+
117
+ const resetAll = async (props = {}) => {
118
+ const [affectedCount] = await models.task.update({ status: 'pending' }, { where: getRunningResetWhere(props) });
119
+ return affectedCount;
114
120
  };
115
121
 
116
122
  const executor = async ({ type, scriptName, ...props }) => {
@@ -223,31 +229,29 @@ module.exports = fp(async (fastify, options) => {
223
229
  collectTaskStatistics(task);
224
230
  };
225
231
 
226
- const processSystemTask = async task => {
227
- await task.update({
228
- status: 'running',
229
- startedAt: new Date(),
230
- progress: 0,
231
- error: null,
232
- output: null,
233
- pollCount: 0,
234
- pollResults: [],
235
- completedAt: null,
236
- context: {}
237
- });
232
+ const processSystemTask = async (task, { claimed = false } = {}) => {
233
+ if (!claimed) {
234
+ await task.update({
235
+ status: 'running',
236
+ startedAt: new Date(),
237
+ progress: 0,
238
+ error: null,
239
+ output: null,
240
+ pollCount: 0,
241
+ pollResults: [],
242
+ completedAt: null,
243
+ context: {}
244
+ });
245
+ }
238
246
  const addLog = props => {
239
247
  return log(Object.assign({}, props, { taskId: task.id }));
240
248
  };
241
249
 
242
250
  // #3: 任务超时自动失败
243
- const createTimeout = ms => new Promise((_, reject) =>
244
- setTimeout(() => reject(new Error(`任务执行超时(${ms}ms)`)), ms)
245
- );
251
+ const createTimeout = ms => new Promise((_, reject) => setTimeout(() => reject(new Error(`任务执行超时(${ms}ms)`)), ms));
246
252
 
247
253
  const executorPromise = executor({ type: task.type, scriptName: task.scriptName, task, log: addLog });
248
- const racePromise = options.taskTimeout > 0
249
- ? Promise.race([executorPromise, createTimeout(options.taskTimeout)])
250
- : executorPromise;
254
+ const racePromise = options.taskTimeout > 0 ? Promise.race([executorPromise, createTimeout(options.taskTimeout)]) : executorPromise;
251
255
 
252
256
  return racePromise
253
257
  .then(async result => {
@@ -325,7 +329,7 @@ module.exports = fp(async (fastify, options) => {
325
329
 
326
330
  const tasksToFail = timedOutTasks.filter(task => {
327
331
  const elapsed = now.getTime() - new Date(task.startedAt).getTime();
328
- return elapsed > task.timeout * 60 * 1000;
332
+ return elapsed > task.timeout;
329
333
  });
330
334
 
331
335
  if (tasksToFail.length === 0) return;
@@ -337,13 +341,66 @@ module.exports = fp(async (fastify, options) => {
337
341
  const prevStatus = task.status;
338
342
  await task.update({
339
343
  status: 'failed',
340
- error: `任务超时:已执行 ${Math.round(elapsed / 60000)} 分钟,超过设定的 ${task.timeout} 分钟超时时间`,
344
+ error: `任务超时:已执行 ${elapsed}ms,超过设定的 ${task.timeout}ms 超时时间`,
341
345
  completedAt: now
342
346
  });
343
347
  collectTaskStatistics(task);
344
348
  }
345
349
  };
346
350
 
351
+ const claimPendingTasks = async limit => {
352
+ if (limit <= 0) return [];
353
+ const now = new Date();
354
+ const pendingTasks = await models.task.findAll({
355
+ where: {
356
+ runnerType: 'system',
357
+ status: 'pending',
358
+ startTime: {
359
+ [Op.lte]: now
360
+ }
361
+ },
362
+ order: [
363
+ ['priority', 'DESC'],
364
+ ['startTime', 'ASC']
365
+ ],
366
+ limit: limit
367
+ });
368
+
369
+ const claimedTasks = [];
370
+ for (const task of pendingTasks) {
371
+ const [affectedCount] = await models.task.update(
372
+ {
373
+ status: 'running',
374
+ startedAt: now,
375
+ progress: 0,
376
+ error: null,
377
+ output: null,
378
+ pollCount: 0,
379
+ pollResults: [],
380
+ completedAt: null,
381
+ context: {}
382
+ },
383
+ {
384
+ where: {
385
+ id: task.id,
386
+ runnerType: 'system',
387
+ status: 'pending',
388
+ startTime: {
389
+ [Op.lte]: now
390
+ }
391
+ }
392
+ }
393
+ );
394
+ if (affectedCount === 1) {
395
+ const claimedTask = await models.task.findByPk(task.id);
396
+ if (claimedTask) {
397
+ claimedTasks.push(claimedTask);
398
+ }
399
+ }
400
+ }
401
+ return claimedTasks;
402
+ };
403
+
347
404
  const runner = async () => {
348
405
  // 检查超时任务
349
406
  await checkTimeout();
@@ -359,26 +416,11 @@ module.exports = fp(async (fastify, options) => {
359
416
  fastify.log.info(`当前运行中的系统任务数(${runningTaskCount})已达上限(${options.limit}),暂不执行新任务`);
360
417
  return;
361
418
  }
362
- // #1: 按优先级降序 + startTime 升序获取待处理任务
363
- const pendingTasks = await models.task.findAll({
364
- where: {
365
- runnerType: 'system',
366
- status: 'pending',
367
- startTime: {
368
- [Op.lte]: new Date()
369
- }
370
- },
371
- order: [
372
- ['priority', 'DESC'],
373
- ['startTime', 'ASC']
374
- ],
375
- limit: limit
376
- });
419
+ const pendingTasks = await claimPendingTasks(limit);
377
420
 
378
421
  if (pendingTasks.length > 0) {
379
422
  fastify.log.info(`本轮执行 ${pendingTasks.length} 个待处理的系统任务`);
380
- // #8: await processSystemTask 返回的 Promise,防止同任务重复执行
381
- await Promise.all(pendingTasks.map(async task => processSystemTask(task)));
423
+ await Promise.all(pendingTasks.map(async task => processSystemTask(task, { claimed: true })));
382
424
  }
383
425
  };
384
426
 
@@ -723,6 +765,7 @@ module.exports = fp(async (fastify, options) => {
723
765
  cancel,
724
766
  runner,
725
767
  resetAll,
768
+ claimPendingTasks,
726
769
  retry,
727
770
  log,
728
771
  logWithSignature,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kne/fastify-task",
3
- "version": "3.0.0-alpha.5",
3
+ "version": "3.0.0-alpha.7",
4
4
  "description": "一个 Fastify 插件,用于任务编排、追踪任务执行状态和结果。支持系统自动执行和手动执行两种模式,提供完整的任务生命周期管理",
5
5
  "main": "index.js",
6
6
  "scripts": {
@@ -56,7 +56,7 @@
56
56
  "sqlite3": "^5.1.7"
57
57
  },
58
58
  "dependencies": {
59
- "@kne/fastify-statistics": "^0.1.0-alpha.10",
59
+ "@kne/fastify-statistics": "^0.1.0",
60
60
  "dayjs": "^1.11.20",
61
61
  "fastify-cron": "^1.4.0",
62
62
  "fs-extra": "^11.3.0"