@kne/fastify-task 3.0.0-alpha.3 → 3.0.0-alpha.4
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 +548 -274
- package/libs/controllers/main.js +4 -0
- package/libs/controllers/statistics.js +5 -2
- package/libs/models/task.js +5 -0
- package/libs/services/main.js +67 -13
- package/libs/services/statistics.js +473 -339
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -14,335 +14,609 @@ npm i --save @kne/fastify-task
|
|
|
14
14
|
|
|
15
15
|
@kne/fastify-task 是一个 Fastify 插件,用于任务编排、追踪任务执行状态和结果。支持系统自动执行和手动执行两种模式,提供完整的任务生命周期管理。
|
|
16
16
|
|
|
17
|
-
###
|
|
18
|
-
|
|
19
|
-
- **任务创建与管理**:支持创建、取消、重试、完成任务
|
|
20
|
-
- **多种执行模式**:支持系统自动执行(system)和手动执行(manual)
|
|
21
|
-
- **定时任务调度**:基于 cron 表达式的定时任务执行
|
|
22
|
-
- **任务状态追踪**:实时追踪任务进度、轮询结果
|
|
23
|
-
- **异步回调支持**:支持外部系统回调通知任务完成
|
|
24
|
-
- **日志记录**:支持任务执行日志记录,最多保留100条
|
|
17
|
+
### 核心架构与流程
|
|
25
18
|
|
|
26
|
-
|
|
19
|
+
```
|
|
20
|
+
创建任务 (create)
|
|
21
|
+
↓
|
|
22
|
+
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
|
|
31
|
+
```
|
|
27
32
|
|
|
28
|
-
|
|
29
|
-
- 第三方 API 调用后异步回调处理
|
|
30
|
-
- 定时批量数据处理
|
|
31
|
-
- 需要追踪进度和状态的长时任务
|
|
33
|
+
> **关键设计**:cron 每次触发 `runner` 时,先执行 `checkTimeout` 检测超时任务,再按 **优先级降序 + startTime 升序** 取待执行系统任务,受 `limit` 并发上限控制。
|
|
32
34
|
|
|
33
|
-
###
|
|
35
|
+
### 核心概念详解
|
|
34
36
|
|
|
35
|
-
|
|
36
|
-
|----------|--------|
|
|
37
|
-
| pending | 待执行 |
|
|
38
|
-
| running | 执行中 |
|
|
39
|
-
| waiting | 等待外部回调 |
|
|
40
|
-
| success | 执行成功 |
|
|
41
|
-
| failed | 执行失败 |
|
|
42
|
-
| canceled | 已取消 |
|
|
37
|
+
#### 任务状态
|
|
43
38
|
|
|
44
|
-
|
|
39
|
+
| 状态 | 说明 | 可流转到 |
|
|
40
|
+
|------|------|----------|
|
|
41
|
+
| `pending` | 待执行 | `running`、`canceled` |
|
|
42
|
+
| `running` | 执行中 | `success`、`failed`、`waiting`、`pending`(重试) |
|
|
43
|
+
| `waiting` | 等待外部回调 | `success`、`failed` |
|
|
44
|
+
| `success` | 执行成功 | 终态 |
|
|
45
|
+
| `failed` | 执行失败 | `pending`(重试) |
|
|
46
|
+
| `canceled` | 已取消 | `pending`(重试) |
|
|
45
47
|
|
|
46
|
-
|
|
48
|
+
#### 执行模式
|
|
47
49
|
|
|
48
|
-
|
|
50
|
+
| 模式 | runnerType | 触发方式 | 说明 |
|
|
51
|
+
|------|-----------|----------|------|
|
|
52
|
+
| 系统自动 | `system` | cron 定时调度 `runner` | 按优先级和 startTime 自动执行 |
|
|
53
|
+
| 手动执行 | `manual` | 用户通过 `complete` 接口完成 | 任务创建后等待人工操作 |
|
|
49
54
|
|
|
50
|
-
|
|
51
|
-
const crypto = require('node:crypto');
|
|
52
|
-
|
|
53
|
-
function generateSignature({ secret, id, data }) {
|
|
54
|
-
// data 可以是字符串或对象
|
|
55
|
-
const dataStr = typeof data === 'string' ? data : JSON.stringify(data);
|
|
56
|
-
const dataToSign = `${id}|${dataStr}`;
|
|
57
|
-
const hmac = crypto.createHmac('sha256', secret);
|
|
58
|
-
hmac.update(dataToSign);
|
|
59
|
-
return hmac.digest('hex');
|
|
60
|
-
}
|
|
61
|
-
```
|
|
55
|
+
### 主要特性
|
|
62
56
|
|
|
63
|
-
|
|
57
|
+
| 特性 | 说明 |
|
|
58
|
+
|------|------|
|
|
59
|
+
| 任务创建与管理 | 支持创建、取消、重试、完成任务 |
|
|
60
|
+
| 多种执行模式 | system 自动执行 / manual 手动执行 |
|
|
61
|
+
| 定时任务调度 | 基于 cron 表达式定时执行系统任务 |
|
|
62
|
+
| 任务状态追踪 | 实时追踪进度、轮询结果 |
|
|
63
|
+
| 异步回调支持 | 支持 `next` → `processNext`/`callback` 回调链路 |
|
|
64
|
+
| 日志记录 | 任务执行日志,最多保留 100 条 |
|
|
65
|
+
| 优先级与依赖 | 优先级排序 + 父子任务链式执行 |
|
|
66
|
+
| 自动重试 | 指数退避重试策略 |
|
|
67
|
+
| 超时控制 | 任务级别超时设置,超时自动标记 failed |
|
|
68
|
+
| 统计面板 | 任务统计数据查询 + SSE 实时推送 |
|
|
64
69
|
|
|
65
|
-
|
|
66
|
-
|----------------------|----------------------------------|
|
|
67
|
-
| processNext | `result` 字符串(JSON格式结果) |
|
|
68
|
-
| logWithSignature | `{ data, message }` 对象 |
|
|
69
|
-
| callbackWithSignature| `{ code, data, message }` 对象 |
|
|
70
|
+
### 使用方法
|
|
70
71
|
|
|
71
|
-
####
|
|
72
|
+
#### 插件注册与配置
|
|
72
73
|
|
|
73
74
|
```javascript
|
|
74
|
-
//
|
|
75
|
-
const
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
// logWithSignature 签名
|
|
79
|
-
const signature = generateSignature({
|
|
80
|
-
secret: 'your-secret',
|
|
81
|
-
id: 'task-1',
|
|
82
|
-
data: { data: { key: 'value' }, message: '日志消息' }
|
|
75
|
+
// 基础注册
|
|
76
|
+
const fastify = require('fastify')();
|
|
77
|
+
fastify.register(require('@kne/fastify-task'), {
|
|
78
|
+
// 可选配置项,参见 api.md 配置项章节
|
|
83
79
|
});
|
|
80
|
+
```
|
|
84
81
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
82
|
+
```javascript
|
|
83
|
+
// 带任务类型处理函数的注册
|
|
84
|
+
fastify.register(require('@kne/fastify-task'), {
|
|
85
|
+
task: {
|
|
86
|
+
'export-excel': async ({ task, result, context }) => {
|
|
87
|
+
console.log('导出任务完成:', result);
|
|
88
|
+
},
|
|
89
|
+
'send-email': async ({ task, result }) => {
|
|
90
|
+
// 发送邮件完成后的处理
|
|
91
|
+
}
|
|
92
|
+
}
|
|
90
93
|
});
|
|
91
94
|
```
|
|
92
95
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
### API
|
|
96
|
-
|
|
97
|
-
### 插件配置
|
|
98
|
-
|
|
99
|
-
| 属性名 | 类型 | 默认值 | 说明 |
|
|
100
|
-
|-------------------|----------|----------------|----------------------|
|
|
101
|
-
| dbTableNamePrefix | string | 't_' | 数据库表名前缀 |
|
|
102
|
-
| prefix | string | '/api/task' | API 路由前缀 |
|
|
103
|
-
| name | string | 'task' | 命名空间名称 |
|
|
104
|
-
| limit | number | 10 | 并发执行任务数上限 |
|
|
105
|
-
| dir | string | 'libs/tasks' | 任务脚本目录 |
|
|
106
|
-
| cronTime | string | '*/10 * * * *' | cron 执行周期,设为 null 禁用 |
|
|
107
|
-
| scriptName | string | 'index' | 默认任务脚本名称 |
|
|
108
|
-
| maxPollTimes | number | 20 | 最大轮询次数 |
|
|
109
|
-
| pollInterval | number | 10000 | 轮询间隔(毫秒) |
|
|
110
|
-
| getUserModel | function | - | 获取用户模型的函数 |
|
|
111
|
-
| getAuthenticate | function | - | 获取认证中间件的函数 |
|
|
112
|
-
| task | object | {} | 任务类型处理函数映射 |
|
|
113
|
-
|
|
114
|
-
### HTTP API
|
|
115
|
-
|
|
116
|
-
#### 获取任务列表
|
|
117
|
-
|
|
118
|
-
**GET** `{prefix}/list`
|
|
119
|
-
|
|
120
|
-
| 参数名 | 类型 | 默认值 | 说明 |
|
|
121
|
-
|------------------------------|--------|-----|------------|
|
|
122
|
-
| perPage | number | 20 | 每页数量 |
|
|
123
|
-
| currentPage | number | 1 | 当前页码 |
|
|
124
|
-
| filter.id | string | - | 任务ID |
|
|
125
|
-
| filter.targetId | string | - | 目标对象ID |
|
|
126
|
-
| filter.targetName | string | - | 目标名称(模糊匹配) |
|
|
127
|
-
| filter.type | string | - | 任务类型 |
|
|
128
|
-
| filter.status | string | - | 任务状态 |
|
|
129
|
-
| filter.runnerType | string | - | 执行者类型 |
|
|
130
|
-
| filter.createdAt.startTime | string | - | 创建时间起始 |
|
|
131
|
-
| filter.createdAt.endTime | string | - | 创建时间结束 |
|
|
132
|
-
| filter.completedAt.startTime | string | - | 完成时间起始 |
|
|
133
|
-
| filter.completedAt.endTime | string | - | 完成时间结束 |
|
|
134
|
-
| sort | object | - | 排序规则 |
|
|
135
|
-
|
|
136
|
-
**返回值**
|
|
137
|
-
|
|
138
|
-
| 属性名 | 类型 | 说明 |
|
|
139
|
-
|------------|--------|------|
|
|
140
|
-
| pageData | array | 任务列表 |
|
|
141
|
-
| totalCount | number | 总数量 |
|
|
142
|
-
|
|
143
|
-
#### 手动完成任务
|
|
96
|
+
#### 任务脚本开发
|
|
144
97
|
|
|
145
|
-
|
|
98
|
+
在 `dirs` 配置的目录下创建任务脚本,目录结构:
|
|
146
99
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
| msg | string | 否 | 消息 |
|
|
153
|
-
| output | object | 否 | 输出数据 |
|
|
154
|
-
|
|
155
|
-
#### 取消任务
|
|
156
|
-
|
|
157
|
-
**POST** `{prefix}/cancel`
|
|
158
|
-
|
|
159
|
-
| 参数名 | 类型 | 必填 | 说明 |
|
|
160
|
-
|-----|--------|----|------|
|
|
161
|
-
| id | string | 是 | 任务ID |
|
|
162
|
-
|
|
163
|
-
#### 重试任务
|
|
164
|
-
|
|
165
|
-
**POST** `{prefix}/retry`
|
|
100
|
+
```
|
|
101
|
+
libs/tasks/
|
|
102
|
+
└── <任务类型>/
|
|
103
|
+
└── <scriptName>.js # 默认 scriptName 为 'index'
|
|
104
|
+
```
|
|
166
105
|
|
|
167
|
-
|
|
168
|
-
|---------|----------|----|--------|
|
|
169
|
-
| id | string | 否 | 单个任务ID |
|
|
170
|
-
| taskIds | string[] | 否 | 任务ID数组 |
|
|
106
|
+
**脚本模板:**
|
|
171
107
|
|
|
172
|
-
|
|
108
|
+
```javascript
|
|
109
|
+
module.exports = async (fastify, options, { task, updateProgress, polling, next, log }) => {
|
|
110
|
+
const { input } = task;
|
|
111
|
+
|
|
112
|
+
// 更新进度 (0-100)
|
|
113
|
+
await updateProgress(50);
|
|
114
|
+
|
|
115
|
+
// 轮询外部服务
|
|
116
|
+
const result = await polling(async () => {
|
|
117
|
+
const res = await fetch('external-api');
|
|
118
|
+
return {
|
|
119
|
+
result: 'success | failed | pending',
|
|
120
|
+
data: res.data,
|
|
121
|
+
message: '消息',
|
|
122
|
+
progress: 80
|
|
123
|
+
};
|
|
124
|
+
}, {
|
|
125
|
+
maxPollTimes: 20,
|
|
126
|
+
pollInterval: 10000
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
// 等待外部回调(任务状态变为 waiting)
|
|
130
|
+
await next({
|
|
131
|
+
secret: '签名密钥',
|
|
132
|
+
// 其他上下文数据,回调时可在 context 中获取
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
return { /* 返回结果 */ };
|
|
136
|
+
};
|
|
137
|
+
```
|
|
173
138
|
|
|
174
|
-
|
|
139
|
+
#### executor 辅助方法
|
|
175
140
|
|
|
176
|
-
|
|
|
177
|
-
|
|
178
|
-
|
|
|
179
|
-
|
|
|
180
|
-
|
|
|
141
|
+
| 方法签名 | 说明 |
|
|
142
|
+
|----------|------|
|
|
143
|
+
| `updateProgress(progress)` | 更新任务进度 (0-100) |
|
|
144
|
+
| `polling(callback, options)` | 轮询外部服务直到完成 |
|
|
145
|
+
| `next(context)` | 设置任务为 waiting 状态,返回 `false` 暂停执行 |
|
|
146
|
+
| `log({ data, message })` | 记录任务执行日志 |
|
|
181
147
|
|
|
182
|
-
|
|
148
|
+
**polling options 参数:**
|
|
183
149
|
|
|
184
|
-
|
|
150
|
+
| 参数名 | 类型 | 默认值 | 说明 |
|
|
151
|
+
|--------|------|--------|------|
|
|
152
|
+
| `maxPollTimes` | number | `20` | 最大轮询次数 |
|
|
153
|
+
| `pollInterval` | number | `10000` | 轮询间隔(毫秒) |
|
|
185
154
|
|
|
186
|
-
|
|
187
|
-
|-----------|--------|----|----------------------------------------|
|
|
188
|
-
| id | string | 是 | 任务ID(body) |
|
|
189
|
-
| taskId | string | 是 | 任务ID(query) |
|
|
190
|
-
| data | object | 否 | 日志数据 |
|
|
191
|
-
| message | string | 否 | 日志消息 |
|
|
192
|
-
| signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
|
|
155
|
+
**polling callback 返回格式:**
|
|
193
156
|
|
|
194
|
-
|
|
157
|
+
| 字段 | 类型 | 说明 |
|
|
158
|
+
|------|------|------|
|
|
159
|
+
| `result` | string | `'success'` / `'failed'` / `'pending'` |
|
|
160
|
+
| `data` | object | 成功时返回的数据 |
|
|
161
|
+
| `message` | string | 消息 |
|
|
162
|
+
| `progress` | number | 当前进度 |
|
|
195
163
|
|
|
196
|
-
|
|
164
|
+
#### 任务类型处理函数
|
|
197
165
|
|
|
198
|
-
|
|
199
|
-
|-----------|--------|----|----------------------------------------|
|
|
200
|
-
| id | string | 是 | 任务ID(body) |
|
|
201
|
-
| taskId | string | 是 | 任务ID(query) |
|
|
202
|
-
| code | number | 是 | 状态码,0为成功 |
|
|
203
|
-
| data | object | 否 | 回调数据 |
|
|
204
|
-
| message | string | 否 | 回调消息 |
|
|
205
|
-
| signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
|
|
166
|
+
任务完成后自动调用对应 `task[type]` 处理函数,接收参数:
|
|
206
167
|
|
|
207
|
-
|
|
168
|
+
| 参数名 | 类型 | 说明 |
|
|
169
|
+
|--------|------|------|
|
|
170
|
+
| `task` | Task | 任务实例 |
|
|
171
|
+
| `result` | object / string | 任务输出结果 |
|
|
172
|
+
| `context` | object | 任务上下文(`next` 时设置的数据) |
|
|
208
173
|
|
|
209
|
-
####
|
|
174
|
+
#### 运行时动态添加
|
|
210
175
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
176
|
+
```javascript
|
|
177
|
+
// 通过 append 方法运行时添加任务目录和类型
|
|
178
|
+
const result = await fastify.task.services.append({
|
|
179
|
+
dirs: ['/path/to/tasks'],
|
|
180
|
+
tasks: {
|
|
181
|
+
'new-type': async ({ task, result }) => { /* 处理逻辑 */ }
|
|
182
|
+
}
|
|
183
|
+
});
|
|
184
|
+
// result.dirs → 实际添加的目录列表
|
|
185
|
+
// result.tasks → 实际添加的类型列表
|
|
186
|
+
```
|
|
222
187
|
|
|
223
|
-
|
|
188
|
+
#### 签名验证
|
|
224
189
|
|
|
225
|
-
|
|
190
|
+
当任务通过 `next({ secret: '密钥' })` 设置了密钥时,外部回调需提供 HMAC-SHA256 签名。
|
|
226
191
|
|
|
227
|
-
|
|
228
|
-
|-----|--------|----|------|
|
|
229
|
-
| id | string | 是 | 任务ID |
|
|
192
|
+
**签名生成方法:**
|
|
230
193
|
|
|
231
|
-
|
|
194
|
+
```javascript
|
|
195
|
+
const crypto = require('node:crypto');
|
|
232
196
|
|
|
233
|
-
|
|
197
|
+
function generateSignature({ secret, id, data }) {
|
|
198
|
+
const dataStr = typeof data === 'string' ? data : JSON.stringify(data);
|
|
199
|
+
const dataToSign = `${id}|${dataStr}`;
|
|
200
|
+
const hmac = crypto.createHmac('sha256', secret);
|
|
201
|
+
hmac.update(dataToSign);
|
|
202
|
+
return hmac.digest('hex');
|
|
203
|
+
}
|
|
204
|
+
```
|
|
234
205
|
|
|
235
|
-
|
|
206
|
+
**各接口签名数据格式:**
|
|
236
207
|
|
|
237
|
-
|
|
208
|
+
| 接口 | data 格式 |
|
|
209
|
+
|------|-----------|
|
|
210
|
+
| `processNext` | `result` 字符串(JSON 格式结果) |
|
|
211
|
+
| `logWithSignature` | `{ data, message }` 对象 |
|
|
212
|
+
| `callbackWithSignature` | `{ code, data, message }` 对象 |
|
|
238
213
|
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
| output | object | 否 | 输出数据 |
|
|
244
|
-
| status | string | 是 | 状态:success/failed |
|
|
245
|
-
| error | string | 否 | 错误信息 |
|
|
214
|
+
```javascript
|
|
215
|
+
// processNext 签名
|
|
216
|
+
const result = JSON.stringify({ code: 0, data: { output: 'done' } });
|
|
217
|
+
const signature = generateSignature({ secret: 'your-secret', id: 'task-1', data: result });
|
|
246
218
|
|
|
247
|
-
|
|
219
|
+
// callbackWithSignature 签名
|
|
220
|
+
const signature = generateSignature({
|
|
221
|
+
secret: 'your-secret', id: 'task-1',
|
|
222
|
+
data: { code: 0, data: { result: 'done' }, message: '成功' }
|
|
223
|
+
});
|
|
224
|
+
```
|
|
248
225
|
|
|
249
|
-
|
|
250
|
-
|------------|--------|----|--------------|
|
|
251
|
-
| id | string | 否 | 任务ID |
|
|
252
|
-
| targetId | string | 否 | 目标对象ID(批量取消) |
|
|
253
|
-
| targetType | string | 否 | 目标对象类型(批量取消) |
|
|
254
|
-
| type | string | 否 | 任务类型(批量取消) |
|
|
226
|
+
> **关键设计**:未设置 `context.secret` 时签名验证自动跳过,不阻塞无密钥任务的回调。
|
|
255
227
|
|
|
256
|
-
####
|
|
228
|
+
#### 插件依赖
|
|
257
229
|
|
|
258
|
-
|
|
|
259
|
-
|
|
260
|
-
|
|
|
261
|
-
|
|
|
230
|
+
| 依赖 | 说明 |
|
|
231
|
+
|------|------|
|
|
232
|
+
| `fastify-cron` | 定时任务支持 |
|
|
233
|
+
| `@kne/fastify-namespace` | 命名空间模块化 |
|
|
234
|
+
| `@kne/fastify-statistics` | 统计数据采集 |
|
|
235
|
+
| `fastify-sequelize` | 数据库模型支持 |
|
|
262
236
|
|
|
263
|
-
#### log - 记录日志(内部调用)
|
|
264
237
|
|
|
265
|
-
|
|
238
|
+
### 示例
|
|
266
239
|
|
|
267
|
-
|
|
268
|
-
|-----------|--------|----|-----------------|
|
|
269
|
-
| id | string | 是 | 任务ID |
|
|
270
|
-
| taskId | string | 是 | 任务ID(id的别名) |
|
|
271
|
-
| data | object | 否 | 日志数据 |
|
|
272
|
-
| message | string | 否 | 日志消息 |
|
|
240
|
+
### API
|
|
273
241
|
|
|
274
|
-
|
|
242
|
+
### 配置项
|
|
243
|
+
|
|
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` 首位,保证向后兼容。
|
|
263
|
+
|
|
264
|
+
### HTTP 接口
|
|
265
|
+
|
|
266
|
+
#### POST `{prefix}/create`
|
|
267
|
+
|
|
268
|
+
创建任务,需 `write` 权限。
|
|
269
|
+
|
|
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 表示不超时 |
|
|
283
|
+
|
|
284
|
+
返回值:
|
|
285
|
+
|
|
286
|
+
| 属性名 | 类型 | 说明 |
|
|
287
|
+
|--------|------|------|
|
|
288
|
+
| id | string | 任务ID |
|
|
289
|
+
|
|
290
|
+
#### GET `{prefix}/list`
|
|
291
|
+
|
|
292
|
+
获取任务列表,需 `read` 权限。
|
|
293
|
+
|
|
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`) |
|
|
309
|
+
|
|
310
|
+
返回值:
|
|
311
|
+
|
|
312
|
+
| 属性名 | 类型 | 说明 |
|
|
313
|
+
|--------|------|------|
|
|
314
|
+
| pageData | array | 任务列表 |
|
|
315
|
+
| totalCount | number | 总数量 |
|
|
316
|
+
|
|
317
|
+
#### POST `{prefix}/complete`
|
|
318
|
+
|
|
319
|
+
手动完成任务,需 `write` 权限。
|
|
320
|
+
|
|
321
|
+
| 参数名 | 类型 | 必填 | 说明 |
|
|
322
|
+
|--------|------|------|------|
|
|
323
|
+
| id | string | 是 | 任务ID |
|
|
324
|
+
| status | string | 是 | 完成状态:`success` / `failed` |
|
|
325
|
+
| error | string | 否 | 错误信息 |
|
|
326
|
+
| msg | string | 否 | 消息 |
|
|
327
|
+
| output | object | 否 | 输出数据 |
|
|
328
|
+
|
|
329
|
+
#### POST `{prefix}/cancel`
|
|
330
|
+
|
|
331
|
+
取消任务,需 `write` 权限。支持单个取消(`id`)或批量取消(`targetId` + `targetType` + `type`)。
|
|
332
|
+
|
|
333
|
+
| 参数名 | 类型 | 必填 | 说明 |
|
|
334
|
+
|--------|------|------|------|
|
|
335
|
+
| id | string | 否 | 任务ID(单个取消) |
|
|
336
|
+
| targetId | string | 否 | 目标对象ID(批量取消,需配合 `targetType` 和 `type`) |
|
|
337
|
+
| targetType | string | 否 | 目标对象类型(批量取消) |
|
|
338
|
+
| type | string | 否 | 任务类型(批量取消) |
|
|
339
|
+
|
|
340
|
+
#### POST `{prefix}/retry`
|
|
341
|
+
|
|
342
|
+
重试任务,需 `write` 权限。仅允许重试 `failed` 或 `canceled` 状态的任务。
|
|
343
|
+
|
|
344
|
+
| 参数名 | 类型 | 必填 | 说明 |
|
|
345
|
+
|--------|------|------|------|
|
|
346
|
+
| id | string | 否 | 单个任务ID |
|
|
347
|
+
| taskIds | string[] | 否 | 任务ID数组 |
|
|
348
|
+
|
|
349
|
+
#### POST `{prefix}/next`
|
|
350
|
+
|
|
351
|
+
处理等待回调的任务,无需认证。当任务设置了 `context.secret` 时需提供签名。
|
|
352
|
+
|
|
353
|
+
| 参数名 | 类型 | 必填 | 说明 |
|
|
354
|
+
|--------|------|------|------|
|
|
355
|
+
| id | string | 是 | 任务ID |
|
|
356
|
+
| signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
|
|
357
|
+
| result | string | 是 | JSON 格式结果字符串 |
|
|
358
|
+
|
|
359
|
+
#### POST `{prefix}/log`
|
|
360
|
+
|
|
361
|
+
记录任务日志,无需认证。当任务设置了 `context.secret` 时需提供签名。
|
|
362
|
+
|
|
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` 存在时必填) |
|
|
370
|
+
|
|
371
|
+
#### POST `{prefix}/callback`
|
|
372
|
+
|
|
373
|
+
任务回调,无需认证。当任务设置了 `context.secret` 时需提供签名。
|
|
374
|
+
|
|
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` 存在时必填) |
|
|
383
|
+
|
|
384
|
+
#### GET `{prefix}/statistics`
|
|
385
|
+
|
|
386
|
+
获取任务统计概览,需 `statistics` 权限。
|
|
387
|
+
|
|
388
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
389
|
+
|--------|------|------|--------|------|
|
|
390
|
+
| range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
|
|
391
|
+
| timezone | string | 否 | 服务器时区 | 时区,如 `Asia/Shanghai` |
|
|
392
|
+
| type | string | 否 | - | 按任务类型筛选 |
|
|
393
|
+
| runnerType | string | 否 | - | 按执行方式筛选 `manual` / `system` |
|
|
394
|
+
|
|
395
|
+
返回值:
|
|
396
|
+
|
|
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 | 小时级完成详情趋势 |
|
|
411
|
+
|
|
412
|
+
#### GET `{prefix}/statistics/sse`
|
|
413
|
+
|
|
414
|
+
SSE 实时推送任务统计数据,需 `statistics` 权限。
|
|
415
|
+
|
|
416
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
417
|
+
|--------|------|------|--------|------|
|
|
418
|
+
| range | string | 否 | `'7d'` | 时间范围 |
|
|
419
|
+
| timezone | string | 否 | 服务器时区 | 时区 |
|
|
420
|
+
| type | string | 否 | - | 按任务类型筛选 |
|
|
421
|
+
| runnerType | string | 否 | - | 按执行方式筛选 |
|
|
422
|
+
| interval | number | 否 | `5` | 推送间隔时间(秒),最小 1 秒 |
|
|
423
|
+
|
|
424
|
+
### 程序化 API
|
|
425
|
+
|
|
426
|
+
通过 `fastify.task.services` 访问。
|
|
427
|
+
|
|
428
|
+
#### 任务管理
|
|
429
|
+
|
|
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 })` | 等待任务完成(轮询),返回任务输出数据 |
|
|
439
|
+
|
|
440
|
+
**services.create 参数:**
|
|
441
|
+
|
|
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 | 否 | - | 扩展选项 |
|
|
457
|
+
|
|
458
|
+
**services.waitingComplete 参数:**
|
|
459
|
+
|
|
460
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
461
|
+
|--------|------|------|--------|------|
|
|
462
|
+
| id | string | 是 | - | 任务ID |
|
|
463
|
+
| pollInterval | number | 否 | `1000` | 轮询间隔(毫秒) |
|
|
464
|
+
| maxPollTimes | number | 否 | `20` | 最大轮询次数 |
|
|
465
|
+
|
|
466
|
+
#### 回调与日志
|
|
467
|
+
|
|
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 })` | 记录日志(外部调用,需签名验证) |
|
|
475
|
+
|
|
476
|
+
#### 系统调度
|
|
477
|
+
|
|
478
|
+
| 方法签名 | 说明 |
|
|
479
|
+
|----------|------|
|
|
480
|
+
| `services.runner()` | 执行系统任务,由 cron 定时调用 |
|
|
481
|
+
| `services.resetAll()` | 重置所有 running 任务为 pending |
|
|
482
|
+
| `services.append({ dirs, tasks })` | 运行时动态添加任务目录和类型,返回 `{ dirs, tasks }` |
|
|
483
|
+
|
|
484
|
+
#### 统计查询
|
|
485
|
+
|
|
486
|
+
| 方法签名 | 说明 |
|
|
487
|
+
|----------|------|
|
|
488
|
+
| `services.queryStatistics({ range, timezone, type, runnerType })` | 查询任务统计数据 |
|
|
489
|
+
| `services.sseStatistics({ range, timezone, type, runnerType, interval }, reply)` | SSE 实时推送统计数据 |
|
|
490
|
+
|
|
491
|
+
**services.queryStatistics 参数:**
|
|
492
|
+
|
|
493
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
494
|
+
|--------|------|------|--------|------|
|
|
495
|
+
| range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
|
|
496
|
+
| timezone | string | 否 | 服务器时区 | 时区 |
|
|
497
|
+
| type | string | 否 | - | 按任务类型筛选 |
|
|
498
|
+
| runnerType | string | 否 | - | 按执行方式筛选 |
|
|
499
|
+
|
|
500
|
+
**services.sseStatistics 参数:**
|
|
501
|
+
|
|
502
|
+
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
|
503
|
+
|--------|------|------|--------|------|
|
|
504
|
+
| range | string | 否 | `'7d'` | 时间范围 |
|
|
505
|
+
| timezone | string | 否 | 服务器时区 | 时区 |
|
|
506
|
+
| type | string | 否 | - | 按任务类型筛选 |
|
|
507
|
+
| runnerType | string | 否 | - | 按执行方式筛选 |
|
|
508
|
+
| interval | number | 否 | `5` | 推送间隔(秒) |
|
|
509
|
+
| reply | object | 是 | - | Fastify reply 对象(第二个参数) |
|
|
510
|
+
|
|
511
|
+
### 数据模型
|
|
512
|
+
|
|
513
|
+
#### Task
|
|
514
|
+
|
|
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` 日志数组) |
|
|
541
|
+
|
|
542
|
+
**关联关系:**
|
|
543
|
+
|
|
544
|
+
| 关联 | 外键 | 说明 |
|
|
545
|
+
|------|------|------|
|
|
546
|
+
| belongsTo User | `userId` | 创建人,`as: 'createdUser'` |
|
|
547
|
+
| belongsTo User | `completedUserId` | 完成人,`as: 'completedUser'` |
|
|
548
|
+
| belongsTo Task | `parentTaskId` | 父任务,`as: 'parentTask'` |
|
|
549
|
+
|
|
550
|
+
**索引:**
|
|
551
|
+
|
|
552
|
+
| 索引字段 |
|
|
553
|
+
|----------|
|
|
554
|
+
| `created_at` |
|
|
555
|
+
| `status` |
|
|
556
|
+
| `type` |
|
|
557
|
+
| `runner_type` |
|
|
558
|
+
| `type, status` |
|
|
559
|
+
| `runner_type, status` |
|
|
560
|
+
| `target_id, target_type, type` |
|
|
561
|
+
| `parent_task_id` |
|
|
562
|
+
| `priority` |
|
|
563
|
+
|
|
564
|
+
### 机制说明
|
|
565
|
+
|
|
566
|
+
#### 签名验证
|
|
567
|
+
|
|
568
|
+
使用 HMAC-SHA256 算法,签名数据格式为 `{id}|{data}`,其中 `data` 为 JSON 字符串或原始字符串。
|
|
569
|
+
|
|
570
|
+
| 接口 | 签名 data 内容 |
|
|
571
|
+
|------|----------------|
|
|
572
|
+
| `processNext` | `result` 参数值(原始 JSON 字符串) |
|
|
573
|
+
| `logWithSignature` | `{ data, message }` 对象的 JSON 序列化 |
|
|
574
|
+
| `callbackWithSignature` | `{ code, data, message }` 对象的 JSON 序列化 |
|
|
575
|
+
|
|
576
|
+
> **关键设计**:未设置 `context.secret` 时 `verifySignature` 直接返回 `true`,不阻塞无密钥任务的回调。
|
|
577
|
+
|
|
578
|
+
#### 重试策略
|
|
579
|
+
|
|
580
|
+
任务执行失败时,判断是否满足自动重试条件(`retryCount < maxRetries`):
|
|
581
|
+
|
|
582
|
+
| 条件 | 行为 |
|
|
583
|
+
|------|------|
|
|
584
|
+
| `retryCount < maxRetries` | 重置为 `pending`,`startTime` 设为当前时间 + 退避延迟 |
|
|
585
|
+
| `retryCount >= maxRetries` | 标记为 `failed`,记录错误信息 |
|
|
586
|
+
|
|
587
|
+
退避公式:`delay = retryBaseDelay × 2^(retryCount - 1)`
|
|
588
|
+
|
|
589
|
+
> **关键设计**:手动调用 `retry` 接口会重置 `retryCount` 为 0,重新开始重试计数。
|
|
590
|
+
|
|
591
|
+
#### 超时检测
|
|
592
|
+
|
|
593
|
+
每次 `runner` 执行时先调用 `checkTimeout`,扫描所有 `running` / `waiting` 且 `timeout > 0` 的任务:
|
|
275
594
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|-----------|--------|----|----------------------------------------|
|
|
280
|
-
| id | string | 是 | 任务ID |
|
|
281
|
-
| taskId | string | 是 | 任务ID(id的别名) |
|
|
282
|
-
| data | object | 否 | 日志数据 |
|
|
283
|
-
| message | string | 否 | 日志消息 |
|
|
284
|
-
| signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
|
|
285
|
-
|
|
286
|
-
#### callback - 任务回调(内部调用)
|
|
287
|
-
|
|
288
|
-
> 内部调用方法,不需要签名验证
|
|
289
|
-
|
|
290
|
-
| 参数名 | 类型 | 必填 | 说明 |
|
|
291
|
-
|-----------|--------|----|-----------|
|
|
292
|
-
| id | string | 是 | 任务ID |
|
|
293
|
-
| code | number | 是 | 状态码,0为成功 |
|
|
294
|
-
| data | object | 否 | 回调数据 |
|
|
295
|
-
| message | string | 否 | 回调消息 |
|
|
296
|
-
|
|
297
|
-
#### callbackWithSignature - 任务回调(外部调用)
|
|
298
|
-
|
|
299
|
-
> 外部调用方法,需要签名验证(HTTP API使用)
|
|
300
|
-
|
|
301
|
-
| 参数名 | 类型 | 必填 | 说明 |
|
|
302
|
-
|-----------|--------|----|----------------------------------------|
|
|
303
|
-
| id | string | 是 | 任务ID |
|
|
304
|
-
| code | number | 是 | 状态码,0为成功 |
|
|
305
|
-
| data | object | 否 | 回调数据 |
|
|
306
|
-
| message | string | 否 | 回调消息 |
|
|
307
|
-
| signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
|
|
595
|
+
```
|
|
596
|
+
当前时间 - startedAt > timeout × 60 × 1000 → 标记为 failed
|
|
597
|
+
```
|
|
308
598
|
|
|
309
|
-
|
|
599
|
+
> **关键设计**:`taskTimeout`(全局配置)和 `timeout`(任务级别,单位分钟)是两个不同概念。全局 `taskTimeout` 在 executor 执行时通过 `Promise.race` 控制;任务 `timeout` 字段在 cron 轮询时检测。
|
|
310
600
|
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
#### resetAll - 重置所有运行中任务
|
|
601
|
+
#### 父子任务依赖
|
|
314
602
|
|
|
315
|
-
|
|
603
|
+
当父任务执行成功后,自动激活 `parentTaskId` 指向该父任务且状态为 `pending` 的子任务:
|
|
316
604
|
|
|
317
|
-
|
|
605
|
+
| 子任务 runnerType | 激活行为 |
|
|
606
|
+
|-------------------|----------|
|
|
607
|
+
| `system` | 立即调用 `processSystemTask` 执行 |
|
|
608
|
+
| `manual` | 保持 `pending`,等待手动执行 |
|
|
318
609
|
|
|
319
|
-
|
|
320
|
-
|--------------|--------|------|----------|
|
|
321
|
-
| id | string | - | 任务ID |
|
|
322
|
-
| pollInterval | number | 1000 | 轮询间隔(毫秒) |
|
|
323
|
-
| maxPollTimes | number | 20 | 最大轮询次数 |
|
|
610
|
+
> **关键设计**:只有父任务 **成功** 后才触发子任务,失败或取消不会激活子任务。
|
|
324
611
|
|
|
325
|
-
|
|
612
|
+
#### 统计数据采集
|
|
326
613
|
|
|
327
|
-
|
|
614
|
+
任务完成时通过 `@kne/fastify-statistics` 采集数据,channel 格式为 `{type}:{runnerType}:{completedHour}`,采集维度:
|
|
328
615
|
|
|
329
|
-
|
|
|
330
|
-
|
|
331
|
-
|
|
|
332
|
-
|
|
|
333
|
-
|
|
|
334
|
-
|
|
|
335
|
-
|
|
|
336
|
-
| runnerType | enum | 执行者类型:manual/system |
|
|
337
|
-
| startTime | date | 最早执行时间 |
|
|
338
|
-
| completedAt | date | 完成时间 |
|
|
339
|
-
| input | json | 输入数据 |
|
|
340
|
-
| output | json | 输出数据 |
|
|
341
|
-
| error | json | 错误信息 |
|
|
342
|
-
| status | enum | 任务状态 |
|
|
343
|
-
| context | json | 上下文信息 |
|
|
344
|
-
| pollResults | json | 轮询结果记录 |
|
|
345
|
-
| pollCount | number | 轮询次数 |
|
|
346
|
-
| progress | number | 进度(0-100) |
|
|
347
|
-
| msg | text | 消息 |
|
|
348
|
-
| options | json | 扩展选项 |
|
|
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) |
|