ScyllaDB Nodetool tasks 超级命令全指南：任务管理器（Task Manager）的观测与控制

导读

ScyllaDB 的任务管理器（Task Manager）是一套基于 API 的机制，用于跟踪修复（repair）、压缩（compaction）等长时间运行的后台操作，使这些任务变得可观测、可控制，并且按节点（per node）独立运行。nodetool tasks 是操作任务管理器的超级命令（supercommand），聚合了 abort、drain、user-ttl、list、modules、status、tree、ttl、wait 共 9 个子操作。阅读本文后，你将掌握：任务状态如何按 TTL 保留、每个子命令的完整语法与选项、如何定位并中止任务、如何以脚本友好的退出码等待任务完成，以及如何通过 scylla.yaml 配置 task_ttl_in_seconds 与 user_task_ttl_in_seconds 控制任务留存时间。

本文主体基于仓库文档 tasks/index.rst 及其九个子页面，并结合 conf/scylla.yaml、db/config.cc 与 service/task_manager_module.cc 等源码补充实现细节。

任务管理器是什么

任务管理器是 ScyllaDB 中一个基于 API 的组件，用于跟踪并暴露长时间运行的后台操作（如 repair、compaction）的状态，让这些任务可观测、可控制。其两个核心特征：

• 可观测：任务从创建、运行到完成、失败的完整生命周期都可以通过 nodetool tasks 查询；
• 可控制：支持对可中止（abortable）的任务发起中止，也支持等待任务结束；
• 按节点运行：任务管理器在每个节点上独立运作，nodetool tasks 查询的是你所连接节点的任务视图。

从源码结构看，任务管理器的模块化框架位于 service/task_manager_module.hh 与 service/task_manager_module.cc，每个功能域（如 repair、compaction）通过注册为独立模块来接入任务管理器；任务的状态机、进度单位（如 ranges）、子任务关系等均在其中建模。

任务状态保留（Task Status Retention）

任务管理器对已完成任务的状态采用临时保留 + TTL 过期策略：

• 任务完成（done）后，其状态会暂时保存在执行该任务的节点上；
• 状态信息最多保留 task_ttl_in_seconds 秒（配置项默认值见下文）。

这意味着：如果一个任务早已完成并且超过 TTL 窗口，其状态将不再可查询，此时需要通过其它途径（如任务开始前的记录）确认结果。TTL 同时存在两个维度：

配置项	含义	默认值（见 conf/scylla.yaml）
task_ttl_in_seconds	任务完成后在任务管理器中保留的秒数（所有任务，含内部任务）	0（任务完成后立即注销）
user_task_ttl_in_seconds	用户发起（user-initiated）的任务完成后保留的秒数	3600（1 小时）

上述默认值可在 conf/scylla.yaml 第 695、698 行附近查看，对应配置解析在 db/config.cc 中完成。当 TTL 为 0 时，任务在结束后会立即从任务管理器注销，状态即刻不可查。

任务类型与模块

nodetool tasks modules 的示例输出展示了两个内置模块：

repair
compaction

从任务列表/状态输出中可以看到更细的任务类型（type），例如：

• repair：修复任务；
• offstrategy compaction：脱策略压缩（通常在流式传输或特殊操作后执行）。

每个任务拥有唯一的 task_id（UUID），例如 ef1b7a61-66c8-494c-bb03-6f65724e6eee，所有子命令都围绕该 ID 展开。

tasks 子命令速览

子命令	作用
tasks abort	中止指定的可中止任务
tasks drain	注销指定模块（或全部模块）中所有已完成的本机任务
tasks user-ttl	读取或设置 user_task_ttl 值
tasks list	列出指定模块中的任务，可重复执行
tasks modules	列出任务管理器支持的所有模块
tasks status	查询单个任务的状态
tasks tree	以 BFS 顺序输出任务及其所有后代的状态
tasks ttl	读取或设置 task_ttl 值
tasks wait	等待任务完成并获取其状态

以下各节按子命令逐一展开语法、选项与示例。

1. abort 中止任务

作用：中止指定 ID 的任务。仅当任务**可中止（abortable）**时才会真正中止；如果任务不可中止，会打印带失败原因的提示信息。

语法：

nodetool tasks abort <task_id>

示例：

> nodetool tasks abort ef1b7a61-66c8-494c-bb03-6f65724e6eee

任务是否可中止可以从 status / tree 输出的 is_abortable 字段判断。结合源码 service/task_manager_module.cc 可以推断，中止请求最终由任务管理器传递给对应模块的任务实现，由任务自身的 abort 逻辑决定如何安全停止（例如取消正在处理的 range）。

提示：先执行 nodetool tasks list repair 找到目标任务 ID，再用 abort 中止；不可中止的任务（如某些原子性操作）会返回失败原因，不会产生副作用。

2. drain 注销已完成任务

作用：从模块中注销（unregister）所有已完成的本机任务。如果不指定模块，则注销所有模块中已完成的任务。

语法：

nodetool tasks drain [--module <module>]

选项：

• --module：若设置，仅注销指定模块的任务。

示例：

> nodetool tasks drain --module repair

该命令在任务 TTL 尚未到期、但希望提前清理已完成任务、释放任务管理器内存时非常有用。未完成任务不受影响。

3. user-ttl 读写用户任务 TTL

作用：读取或设置 user_task_ttl 值（单位：秒），即用户发起的任务在完成后于任务管理器中保留的时间。

关键语义：

• 新值仅在内存中生效；要持久化修改配置，需修改 scylla.yaml 中的 user_task_ttl_in_seconds；
• 也可以使用启动参数 --user-task-ttl-in-seconds 运行 Scylla 指定该值；
• 若 user_task_ttl == 0，用户任务在结束后会立即从任务管理器注销。

语法：

nodetool tasks user-ttl [--set <time_in_seconds>]

选项：

• --set：将 user_task_ttl 设置为指定值（秒）。

示例：

查询当前值：

> nodetool tasks user-ttl

设置为 10 秒：

> nodetool tasks user-ttl --set 10

注意：nodetool tasks user-ttl --set 10 只影响当前节点内存中的值，重启后失效；如需永久生效，请修改 conf/scylla.yaml 中的 user_task_ttl_in_seconds（默认 3600）。

4. list 列出模块内任务

作用：获取指定模块中的任务列表；可以设置相应标志让操作周期性重复执行（常用于监控任务进度变化）。

语法：

nodetool tasks list <module> [--internal] [(--keyspace <keyspace> | -ks <keyspace>)]
[(--table <table> | -t <table>)] [--interval <time_in_seconds>] [(--iterations <number> | -i <number>)]

选项：

• --internal：若设置，同时列出内部任务。内部任务指那些有父任务（parent）或覆盖了内部调用的操作的任务。默认只列出非内部（顶层/用户可见）任务；
• --keyspace / -ks：仅显示指定 keyspace 上的任务；
• --table / -t：仅显示指定表上的任务；
• --interval：按指定时间间隔（秒）周期性重复执行；
• --iterations / -i：重复执行指定次数。

示例：

显示 keyspace myks、表 mytable 上的全部 repair 任务（含内部任务）：

> nodetool tasks list repair --internal -ks myks --table mytable

每 5 秒执行一次、共执行 3 次，显示所有非内部 compaction 任务：

> nodetool tasks list compaction --interval 5 --i 3

示例输出（单次查询）：

task_id                              type   kind scope    state sequence_number keyspace table entity shard start_time           end_time
5116ddb6-85b5-4c3e-94fb-72128f15d7b4 repair node keyspace done  3               abc                   0     2025-01-16T16:12:11Z 2025-01-16T16:12:13Z

示例输出（带重复执行，第一次查询）：

task_id                              type   kind scope    state   sequence_number keyspace table entity shard start_time           end_time
d8926ee7-0faf-47b7-bfeb-82477e0c7b33 repair node keyspace running 5               abc                   0     2025-01-16T16:12:57Z
1e028cb8-31a3-45ed-8728-af7a1ab586f6 repair node keyspace done    4               abc                   0     2025-01-16T16:12:45Z 2025-01-16T16:12:47Z

示例输出（带重复执行，第二次查询，可见新任务 created）：

task_id                              type   kind scope    state   sequence_number keyspace table entity shard start_time           end_time
1e535f9b-97fa-4788-a956-8f3216a6ea8d repair node keyspace created 6               abc                   0
d8926ee7-0faf-47b7-bfeb-82477e0c7b33 repair node keyspace running 5               abc                   0     2025-01-16T16:12:57Z
1e028cb8-31a3-45ed-8728-af7a1ab586f6 repair node keyspace done    4               abc                   0     2025-01-16T16:12:45Z 2025-01-16T16:12:47Z

从输出字段可以看到任务生命周期中的几种状态：created（已创建未开始）、running（运行中）、done（已完成）。sequence_number 反映任务在该 keyspace 上的执行序号，shard 标识任务执行的 Seastar 分片。--interval/--iterations 组合非常适合在修复或压缩执行期间持续观察进度。

5. modules 列出支持模块

作用：列出任务管理器支持的所有模块。

语法：

nodetool tasks modules

示例输出：

repair
compaction

从仓库源码看，模块即任务类型的注册单元：repair 与 compaction 等模块通过任务管理器的模块注册机制接入（参见 service/task_manager_module.cc），这解释了为什么 list 命令的第一个参数 <module> 通常取值为 repair 或 compaction。

6. status 查询任务状态

作用：获取单个任务的状态详情。

语法：

nodetool tasks status <task_id>

示例：

> nodetool tasks status ef1b7a61-66c8-494c-bb03-6f65724e6eee

示例输出：

id: 52b69817-aac7-47bf-9d8d-0b487dd6866a
type: repair
kind: node
scope: keyspace
state: running
is_abortable: true
start_time: 2024-07-29T15:48:55Z
end_time:
error:
parent_id: none
sequence_number: 5
shard: 0
keyspace: abc
table:
entity:
progress_units: ranges
progress_total: 4
progress_completed: 4
children_ids: [{task_id: 9de80fd8-296e-432b-837e-63daf7c93e17, node: 127.0.0.1 }, {task_id: fa1c1338-abd1-4f0c-8ce1-8a806486e5c3, node: 127.0.0.1 }]

字段解读：

• id / type / kind / scope：任务身份与粒度描述。kind 表示任务级别（如 node），scope 表示作用域（如 keyspace、shard）；
• state：任务状态（created / running / done / 失败等）；
• is_abortable：是否可被 tasks abort 中止；
• start_time / end_time：开始与结束时间（end_time 为空表示仍在运行或尚未完成）；
• error：失败时的错误信息；
• parent_id：父任务 ID，none 表示顶层任务；
• sequence_number：任务序号；
• shard：执行任务的 Seastar 分片编号；
• keyspace / table / entity：任务作用的对象；
• progress_units / progress_total / progress_completed：进度单位（如 ranges）与完成进度，可用于估算剩余工作量；
• children_ids：子任务 ID 列表（含所在节点），体现了任务的树状分解结构。

7. tree 查询任务及其后代状态

作用：获取任务及其所有后代（descendants）的状态，输出按 BFS（广度优先）顺序排列。如果不指定 task_id，则打印所有非内部任务的树（内部任务指有父任务或覆盖内部调用操作的任务）。

语法：

nodetool tasks tree [<task_id>]

示例：

> nodetool tasks tree 2ef0a5b6-f243-4c01-876f-54539b453766

示例输出（单个任务树，父任务 + 两个子任务）：

id                                   type   kind scope    state is_abortable start_time           end_time             error parent_id                            sequence_number shard keyspace table entity progress_units total completed children_ids
be5559ea-bc5a-428c-b8ce-d14eac7a1765 repair node keyspace done  true         2024-07-29T16:06:46Z 2024-07-29T16:06:46Z       none                                 1               0     abc                   ranges         4     4         [{task_id: 542e38cb-9ad4-40aa-9010-de2630004e55, node: 127.0.0.1 }, {task_id: 8974ebcc-1e87-4040-88fe-f2438261f7fb, node: 127.0.0.1 }]
  542e38cb-9ad4-40aa-9010-de2630004e55 repair node shard    done  false        2024-07-29T16:06:46Z 2024-07-29T16:06:46Z       be5559ea-bc5a-428c-b8ce-d14eac7a1765 1               0     abc                   ranges         2     2         []
  8974ebcc-1e87-4040-88fe-f2438261f7fb repair node shard    done  false        2024-07-29T16:06:46Z 2024-07-29T16:06:46Z       be5559ea-bc5a-428c-b8ce-d14eac7a1765 1               1     abc                   ranges         2     2         []

示例输出（所有非内部任务，可见 repair 与 offstrategy compaction 两类树的并列输出）：

id                                   type                   kind    scope    state is_abortable start_time           end_time             error parent_id                            sequence_number shard keyspace table entity progress_units total completed children_ids
16eafb1e-8b2e-48e6-bd7a-432ca3d8b9fc repair                 node    keyspace done  true         2024-07-29T16:34:46Z 2024-07-29T16:34:46Z       none                                 1               0     abc                   ranges         4     4         [{task_id: e0aa1aa4-58ca-4bfb-b3e6-74e5f3a0f6ee, node: 127.0.0.1 }, {task_id: 49eb5797-b67e-46b0-9365-4460f7cf988a, node: 127.0.0.1 }]
  e0aa1aa4-58ca-4bfb-b3e6-74e5f3a0f6ee repair                 node    shard    done  false        2024-07-29T16:34:46Z 2024-07-29T16:34:46Z       16eafb1e-8b2e-48e6-bd7a-432ca3d8b9fc 1               0     abc                   ranges         2     2         []
  49eb5797-b67e-46b0-9365-4460f7cf988a repair                 node    shard    done  false        2024-07-29T16:34:46Z 2024-07-29T16:34:46Z       16eafb1e-8b2e-48e6-bd7a-432ca3d8b9fc 1               1     abc                   ranges         2     2         []
  82d7b2a4-146e-4a72-ba93-c66d5b4e9867 offstrategy compaction node    keyspace done  true         2024-07-29T16:34:16Z 2024-07-29T16:34:16Z       none                                 954             0     abc                                  1     1         [{task_id: 9818277b-238d-4298-a56b-c0d2153bf140, node: 127.0.0.1 }, {task_id: c1eb0701-ad7a-45ff-956f-7b8d671fc5db, node: 127.0.0.1 }]
  9818277b-238d-4298-a56b-c0d2153bf140 offstrategy compaction node    shard    done  false        2024-07-29T16:34:16Z 2024-07-29T16:34:16Z       82d7b2a4-146e-4a72-ba93-c66d5b4e9867 954             0     abc                                  1     1         []
  c1eb0701-ad7a-45ff-956f-7b8d671fc5db offstrategy compaction node    shard    done  false        2024-07-29T16:34:16Z 2024-07-29T16:34:16Z       82d7b2a4-146e-4a72-ba93-c66d5b4e9867 954             1     abc                                  1     1         []

关键观察：

• 顶层任务（如 keyspace 级 repair）的 parent_id 为 none，其子任务（shard 级）的 parent_id 指向父任务 ID，且子任务 is_abortable 通常为 false（只随父任务整体受控）；
• 同一棵树内子任务分别运行在不同的 shard（如 0、1），progress_units 均为 ranges，父任务进度为各子任务进度的汇总（如父 4/4，各子 2/2）；
• sequence_number 在不同任务树间并非从 1 开始（如 compaction 树的 954），仅在同一执行上下文中单调递增。

8. ttl 读写任务 TTL

作用：读取或设置 task_ttl 值（单位：秒），即任务完成后在任务管理器中保留的时间（适用于所有任务，包括内部任务）。

关键语义：

• 新值仅在内存中生效；要持久化修改配置，需修改 scylla.yaml 中的 task_ttl_in_seconds；
• 也可以使用启动参数 --task-ttl-in-seconds 运行 Scylla 指定该值；
• 若 task_ttl == 0，任务在结束后会立即从任务管理器注销（这也是该配置项的默认值，见 conf/scylla.yaml 第 695 行）。

语法：

nodetool tasks ttl [--set <time_in_seconds>]

选项：

• --set：将 task_ttl 设置为指定值（秒）。

示例：

查询当前值：

> nodetool tasks ttl

设置为 10 秒：

> nodetool tasks ttl --set 10

ttl 与 user-ttl 的差异

对比项	tasks ttl	tasks user-ttl
对应配置	task_ttl_in_seconds	user_task_ttl_in_seconds
默认值	0（完成后立即注销）	3600（1 小时）
作用对象	所有任务（含内部任务）	仅用户发起的任务
启动参数	--task-ttl-in-seconds	--user-task-ttl-in-seconds

生产环境中，建议保留较长的 user_task_ttl_in_seconds（如默认 3600），以便在修复/压缩完成后仍有窗口可以查询其最终状态与错误信息；同时可按需通过 nodetool tasks drain 主动清理。

9. wait 等待任务结束

作用：等待指定任务完成，然后获取其状态。如果设置了超时且超时到期，会打印带失败原因的提示信息。

语法：

nodetool tasks wait <task_id> [(--quiet|-q)] [--timeout <time_in_second>]

选项：

• --quiet / -q：不打印任务状态，改为返回脚本友好的退出码：
  • 0 —— 任务成功完成；
  • 123 —— 任务失败；
  • 124 —— 请求超时；
  • 125 —— 发生错误，任务状态无法确定（undetermined）；
• --timeout：超时时间（秒）。

示例：

> nodetool tasks wait ef1b7a61-66c8-494c-bb03-6f65724e6eee

示例输出：

id : 29dd6552-1e9a-4f17-b2c9-231d088fbee6
type : repair
kind : node
scope : keyspace
state : done
is_abortable : true
start_time : 2024-07-29T17:00:53Z
end_time : 2024-07-29T17:00:53Z
error :
parent_id : none
sequence_number : 2
shard : 0
keyspace : abc
table :
entity :
progress_units : ranges
progress_total : 4
progress_completed : 4
children_ids : [{task_id: 5d74a62e-aaf6-4993-b0f1-973899d89cd0, node: 127.0.0.1 }, {task_id: 055d5a59-d97c-45a8-a7e6-dcad39ed61ca, node: 127.0.0.1 }]

脚本化用法示例（基于文档给出的退出码约定）：

nodetool tasks wait <task_id> --quiet --timeout 300
case $? in
  0)   echo "task finished successfully";;
  123) echo "task failed";;
  124) echo "request timed out";;
  125) echo "error occurred, task status undetermined";;
esac

--quiet 模式与固定退出码的组合，使 nodetool tasks wait 可以直接嵌入 CI/CD 或运维脚本，作为修复/压缩等操作的同步屏障。

综合实战：一次完整的修复任务生命周期

结合以上子命令，一个典型流程如下：

1. 查看任务管理器支持哪些模块，确认 repair 可用：

   nodetool tasks modules
   

2. 周期性地观察某个 keyspace 上的修复任务（含内部任务，每 10 秒一次、共 6 次）：

   nodetool tasks list repair --internal -ks myks --interval 10 --iterations 6
   

3. 从列表中取到目标 task_id，查看单个任务详情：

   nodetool tasks status <task_id>
   

4. 若需要观察父子任务整体进展（BFS 顺序）：

   nodetool tasks tree <task_id>
   

5. 若任务运行异常且 is_abortable 为 true，中止它：

   nodetool tasks abort <task_id>
   

6. 若希望脚本阻塞直到任务结束（或超时）：

   nodetool tasks wait <task_id> --quiet --timeout 3600
   

7. 任务全部结束后，提前清理已完成任务、释放内存：

   nodetool tasks drain
   

配置建议与注意事项

• TTL 双配置：task_ttl_in_seconds（默认 0，所有任务）与 user_task_ttl_in_seconds（默认 3600，用户任务）均可通过 nodetool tasks ttl / nodetool tasks user-ttl 在内存中临时调整，或通过修改 conf/scylla.yaml 持久化（对应启动参数 --task-ttl-in-seconds、--user-task-ttl-in-seconds）；
• 内存优先、重启失效：nodetool tasks ttl --set 与 user-ttl --set 只修改运行中节点的内存值，重启后恢复为配置文件/启动参数指定值；
• 按节点查询：任务管理器按节点运行，nodetool tasks 连接到哪个节点，看到的就是该节点上的任务视图；
• 内部任务默认隐藏：list 与 tree 默认不显示内部任务（有父任务或覆盖内部调用操作的任务），需要时显式加 --internal；
• 等待退出码语义：wait --quiet 的退出码 0/123/124/125 与常规命令不同（123 表示失败、124 表示超时），脚本中勿用通用 $? != 0 判断。

延伸阅读

• 任务管理器更完整的架构与 API 说明见 docs/operating-scylla/admin-tools/task-manager.rst；
• 任务模块框架实现：service/task_manager_module.hh、service/task_manager_module.cc；
• TTL 配置解析：db/config.cc；
• 配置默认值：conf/scylla.yaml；
• 各子命令文档：abort、drain、user-ttl、list、modules、status、tree、ttl、wait。