@kne/fastify-task 3.0.0-alpha.6 → 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 +399 -309
- package/index.js +47 -6
- package/libs/controllers/main.js +1 -2
- package/libs/models/task.js +2 -2
- package/libs/services/main.js +296 -356
- package/libs/services/statistics.js +18 -27
- package/package.json +1 -1
- package/libs/utils/cache-manager.js +0 -162
- package/libs/utils/config.js +0 -326
- package/libs/utils/errors.js +0 -191
- package/libs/utils/modules/task-executor.js +0 -196
- package/libs/utils/modules/task-processor.js +0 -185
- package/libs/utils/security-validator.js +0 -203
package/README.md
CHANGED
|
@@ -12,66 +12,89 @@ npm i --save @kne/fastify-task
|
|
|
12
12
|
|
|
13
13
|
### 概述
|
|
14
14
|
|
|
15
|
-
|
|
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
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
-
|
|
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`
|
|
42
|
-
| `running`
|
|
43
|
-
| `waiting`
|
|
44
|
-
| `success`
|
|
45
|
-
| `failed`
|
|
46
|
-
| `canceled` | 已取消
|
|
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
|
-
| 模式
|
|
51
|
-
|
|
52
|
-
| 系统自动 | `system`
|
|
53
|
-
| 手动执行 | `manual`
|
|
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
|
-
| 多种执行模式
|
|
61
|
-
| 定时任务调度
|
|
62
|
-
| 任务状态追踪
|
|
63
|
-
| 异步回调支持
|
|
64
|
-
| 日志记录
|
|
65
|
-
| 优先级与依赖
|
|
66
|
-
| 自动重试
|
|
67
|
-
| 超时控制
|
|
68
|
-
|
|
|
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
|
-
```
|
|
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
|
-
```
|
|
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
|
-
```
|
|
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)`
|
|
144
|
-
| `polling(callback, options)` | 轮询外部服务直到完成
|
|
145
|
-
| `next(context)`
|
|
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`
|
|
160
|
-
| `data`
|
|
161
|
-
| `message`
|
|
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`
|
|
171
|
-
| `result`
|
|
172
|
-
| `context` | object
|
|
191
|
+
| 参数名 | 类型 | 说明 |
|
|
192
|
+
|-----------|-----------------|----------------------|
|
|
193
|
+
| `task` | Task | 任务实例 |
|
|
194
|
+
| `result` | object / string | 任务输出结果 |
|
|
195
|
+
| `context` | object | 任务上下文(`next` 时设置的数据) |
|
|
173
196
|
|
|
174
197
|
#### 运行时动态添加
|
|
175
198
|
|
|
176
|
-
```
|
|
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
|
-
```
|
|
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
|
-
| 接口
|
|
209
|
-
|
|
210
|
-
| `processNext`
|
|
211
|
-
| `logWithSignature`
|
|
232
|
+
| 接口 | data 格式 |
|
|
233
|
+
|-------------------------|------------------------------|
|
|
234
|
+
| `processNext` | `result` 字符串(JSON 格式结果) |
|
|
235
|
+
| `logWithSignature` | `{ data, message }` 对象 |
|
|
212
236
|
| `callbackWithSignature` | `{ code, data, message }` 对象 |
|
|
213
237
|
|
|
214
|
-
```
|
|
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`
|
|
247
|
-
| `prefix`
|
|
248
|
-
| `name`
|
|
249
|
-
| `limit`
|
|
250
|
-
| `dir`
|
|
251
|
-
| `dirs`
|
|
252
|
-
| `cronTime`
|
|
253
|
-
| `scriptName`
|
|
254
|
-
| `maxPollTimes`
|
|
255
|
-
| `pollInterval`
|
|
256
|
-
| `taskTimeout`
|
|
257
|
-
| `
|
|
258
|
-
| `
|
|
259
|
-
| `
|
|
260
|
-
| `
|
|
261
|
-
|
|
262
|
-
|
|
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
|
|
273
|
-
| targetId
|
|
274
|
-
| targetType
|
|
275
|
-
| input
|
|
276
|
-
| runnerType
|
|
277
|
-
| delay
|
|
278
|
-
| scriptName
|
|
279
|
-
| priority
|
|
280
|
-
| parentTaskId | string | 否
|
|
281
|
-
| maxRetries
|
|
282
|
-
| timeout
|
|
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
|
-
|
|
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
|
|
297
|
-
| currentPage
|
|
298
|
-
| filter.id
|
|
299
|
-
| filter.targetId
|
|
300
|
-
| filter.targetName
|
|
301
|
-
| filter.type
|
|
302
|
-
| filter.status
|
|
303
|
-
| filter.runnerType
|
|
304
|
-
| filter.createdAt.startTime
|
|
305
|
-
| filter.createdAt.endTime
|
|
306
|
-
| filter.completedAt.startTime | string | 否
|
|
307
|
-
| filter.completedAt.endTime
|
|
308
|
-
| sort
|
|
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
|
-
|
|
315
|
-
|
|
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
|
|
324
|
-
| status | string | 是
|
|
325
|
-
| error
|
|
326
|
-
| msg
|
|
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
|
|
336
|
-
| targetId
|
|
337
|
-
| targetType | string | 否
|
|
338
|
-
| type
|
|
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
|
|
347
|
-
| taskIds |
|
|
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
|
|
356
|
-
| signature | string | 否
|
|
357
|
-
| result
|
|
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
|
|
366
|
-
| taskId
|
|
367
|
-
| data
|
|
368
|
-
| message
|
|
369
|
-
| signature | string | 否
|
|
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
|
|
378
|
-
| taskId
|
|
379
|
-
| code
|
|
380
|
-
| data
|
|
381
|
-
| message
|
|
382
|
-
| signature | string | 否
|
|
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
|
|
391
|
-
| timezone
|
|
392
|
-
| type
|
|
393
|
-
| runnerType | string | 否
|
|
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
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
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
|
|
419
|
-
| timezone
|
|
420
|
-
| type
|
|
421
|
-
| runnerType | string | 否
|
|
422
|
-
| interval
|
|
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 })`
|
|
434
|
-
| `services.list({ filter, perPage, currentPage, sort })`
|
|
435
|
-
| `services.complete({ id, userId, status, output, error })`
|
|
436
|
-
| `services.cancel({ id, targetId, targetType, type })`
|
|
437
|
-
| `services.retry({ id, taskIds })`
|
|
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
|
|
445
|
-
| input
|
|
446
|
-
| type
|
|
447
|
-
| targetId
|
|
448
|
-
| targetType
|
|
449
|
-
| runnerType
|
|
450
|
-
| delay
|
|
451
|
-
| scriptName
|
|
452
|
-
| priority
|
|
453
|
-
| parentTaskId | string | 否
|
|
454
|
-
| maxRetries
|
|
455
|
-
| timeout
|
|
456
|
-
| options
|
|
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
|
|
463
|
-
| pollInterval | number | 否
|
|
464
|
-
| maxPollTimes | number | 否
|
|
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 })`
|
|
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()`
|
|
481
|
-
| `services.
|
|
482
|
-
| `services.
|
|
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
|
|
496
|
-
| timezone
|
|
497
|
-
| type
|
|
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
|
|
505
|
-
| timezone
|
|
506
|
-
| type
|
|
507
|
-
| runnerType | string | 否
|
|
508
|
-
| interval
|
|
509
|
-
| 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
|
|
518
|
-
| scriptName
|
|
519
|
-
| targetId
|
|
520
|
-
| targetType
|
|
521
|
-
| runnerType
|
|
522
|
-
| priority
|
|
523
|
-
| parentTaskId
|
|
524
|
-
| retryCount
|
|
525
|
-
| maxRetries
|
|
526
|
-
| timeout
|
|
527
|
-
| startTime
|
|
528
|
-
| startedAt
|
|
529
|
-
| completedAt
|
|
530
|
-
| completedUserId |
|
|
531
|
-
| input
|
|
532
|
-
| output
|
|
533
|
-
| error
|
|
534
|
-
| status
|
|
535
|
-
| context
|
|
536
|
-
| pollResults
|
|
537
|
-
| pollCount
|
|
538
|
-
| progress
|
|
539
|
-
| msg
|
|
540
|
-
| options
|
|
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`
|
|
622
|
+
| 关联 | 外键 | 说明 |
|
|
623
|
+
|----------------|-------------------|---------------------------|
|
|
624
|
+
| belongsTo User | `userId` | 创建人,`as: 'createdUser'` |
|
|
547
625
|
| belongsTo User | `completedUserId` | 完成人,`as: 'completedUser'` |
|
|
548
|
-
| belongsTo Task | `parentTaskId`
|
|
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
|
-
| 接口
|
|
571
|
-
|
|
572
|
-
| `processNext`
|
|
573
|
-
| `logWithSignature`
|
|
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`
|
|
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
|
|
674
|
+
当前时间 - startedAt > timeout → 标记为 failed
|
|
597
675
|
```
|
|
598
676
|
|
|
599
|
-
> **关键设计**:`taskTimeout`(全局配置)和 `timeout
|
|
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`
|
|
608
|
-
| `manual`
|
|
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
|
|
619
|
-
| success / failed / canceled | count | 按状态计数
|
|
620
|
-
| waitingTime
|
|
621
|
-
| executionTime
|
|
622
|
-
| totalTime
|
|
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) |
|