## 后台任务 (`tasks`)

异步操作的任务队列;可查看、取消待执行任务、重试失败任务。

鉴权: 仅管理员 · 文档: https://www.gocdn888.com/zh/docs/api/tasks

### GET `/api/v2/tasks`

列出后台任务 · 鉴权: 用户（部分参数仅管理员）

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | integer |  | 页码,从 1 开始。 默认: 1 |
| `page_size` | integer |  | 每页条数。 默认: 20 |
| `sort` | string |  | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
| `tenant_id` | integer |  | 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。 |
| `status` | TaskStatus |  | 按状态过滤。 可选值: ["pending","running","done","failed"] |
| `ids` | string |  | 只列这些 id:逗号分隔的正整数,去重后至多 200 个(同 page_size 上限,超了或格式错 422);空串等同不传。与其他条件取交集;看不到的 id 不返回也不报错。分页照旧,一次取回要把 page_size 设成不少于 id 个数。 |
| `type` | string |  | 按任务类型过滤。 |
| `types` | string |  | 只看这些显示类型(Task.subject):逗号分隔,去重后至多 200 个、每项至多 64 个字符(超了 422),命中其中任一个;node.cmd 匹配全部节点指令(node.cmd:*)。与 type 同给取交集。 |
| `q` | string |  | 搜索:#123 或纯数字匹配任务 ID 与 ID 为它的站点/节点/证书;IP 或 CIDR 匹配该 IP 对象;其它文字按节点名、站点名、站点域名、证书名模糊匹配。租户凭据不匹配节点。迁移前的旧任务搜不到。 |
| `routine` | boolean |  | 例行任务(定时、只读查询):false 只看非例行,true 只看例行;不给为全部。 |
| `open_failed` | boolean |  | false 时排除「待处理失败」(失败、未取消、未忽略、未自动恢复;这些由 GET /tasks/fail-groups 分组列出);不给或 true 不排除。 |

```sh
curl "https://panel.example.com/api/v2/tasks" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/tasks/{id}`

获取后台任务 · 鉴权: 用户（部分参数仅管理员）

```sh
curl "https://panel.example.com/api/v2/tasks/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

后台任务对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `attempts` | integer |  | 已尝试次数。 |
| `auto_recovered` | integer |  | 同样筛选条件下已自动恢复的失败数。 |
| `cancelled` | boolean |  | 已取消(状态为失败且 last_error 为 cancelled)。 |
| `created_at` | string |  | 创建时间 |
| `done` | integer[] |  | 处理成功的任务 ID。 |
| `duration_s` | number |  | 耗时秒数(结束时间 − 开始时间,不足 1 秒照实给小数);只有成功或失败且有开始时间时给,否则为 null。 |
| `finished_at` | string |  | 结束时间;未结束为 null。 |
| `groups` | TaskFailGroup[] |  | 分组,按最近一次失败时刻降序。 |
| `id` | integer |  | 记录 ID |
| `ids` | integer[] | 有 | 任务 ID。 |
| `ignored` | boolean |  | 失败已被忽略。 |
| `last_error` | string |  | 最近一次错误 |
| `max_attempts` | integer |  | 最多尝试次数。 |
| `object` | TaskObject |  | 任务作用的对象;租户凭据看不到节点项。 |
| `progress` | TaskProgress |  | 进度;只有执行中的任务给,其它为 null。 |
| `reason` | TaskReason |  | 结构化失败原因;只有失败且未取消的任务给,其它为 null。 |
| `recovered` | boolean |  | 失败已自动恢复(之后同类型同对象的任务成功了)。 |
| `retryable` | boolean |  | 能否重试:白名单类型(封禁、解封、清缓存、预热)、非例行、失败(含已取消)、未自动恢复;是否已过时只在重试时检查。 |
| `routine` | boolean |  | 例行任务(定时、只读查询),面板默认隐藏。 |
| `run_after` | string |  | 最早可执行时间。 |
| `skipped` | TaskBatchSkip[] |  | 跳过的任务与原因。 |
| `started_at` | string |  | 最近一次开始执行的时间;没执行过或升级前的旧任务为 null。 |
| `status` | TaskStatus |  | 任务状态:pending 待执行、running 执行中、done 完成、failed 失败。 可选值: ["pending","running","done","failed"] |
| `subject` | string |  | 显示类型:队列 kind;节点指令为 node.cmd:<指令名>。 |
| `tenant_id` | integer |  | 发起任务的租户;系统任务为 null。 |
| `title` | string |  | 发起方给的简短说明。 |
| `truncated` | boolean |  | 待处理失败超过 2000 条,只按最新的 2000 条分组。 |
| `type` | string |  | 任务类型(队列 kind)。 |
| `updated_at` | string |  | 更新时间 |
