ScyllaDB Nodetool tasks wait 详解：等待后台任务完成并获取任务状态

nodetool tasks wait 是 ScyllaDB 任务管理器（Task Manager）系列命令中的一个核心子命令，用于阻塞等待某个任务管理器任务运行结束，并获取该任务的最终状态。它适用于 repair、compaction 等长时运行的后台操作——在脚本或自动化流程中，你往往需要等一个任务真正做完（而不是仅仅发起任务）才能继续下一步。读完本文，你将掌握 tasks wait 的完整语法、全部参数、退出码语义、输出字段含义，以及它与其他 nodetool tasks 子命令（status / list / tree / abort）的配合方式。

命令概览与适用场景

任务管理器（Task Manager）是 ScyllaDB 提供的、基于 API 的可观测与控制机制，用于跟踪 repair、compaction 等长时运行的后台操作，使其"可观察、可控制"，并且按节点（per node）运行（参见 tasks/index.rst）。

nodetool tasks wait <task_id> 的作用正如其名——"等待"：它会一直等到指定任务完成，然后把任务的完整状态打印出来。如果设置了超时（timeout）且超时到期，命令会打印带有失败原因的提示消息。

典型使用场景：

• 脚本化运维：提交一个 nodetool repair 后，紧接着调用 nodetool tasks wait <task_id>，让脚本在任务真正结束后再继续执行后续逻辑（如备份、验证、下一轮操作）。
• CI/CD 流水线：用 --quiet 模式配合退出码，将任务结果直接映射为流水线的成功/失败判定。
• 故障排查：结合 tasks status 与 tasks tree，先定位任务 ID，再等待并观察其最终状态与子任务信息。

语法与参数

nodetool tasks wait 的标准语法如下（来源：tasks/wait.rst）：

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

参数	缩写	含义
<task_id>	—	要等待的任务的唯一标识（UUID），例如 ef1b7a61-66c8-494c-bb03-6f65724e6eee
--quiet	-q	不打印任务状态，改为通过进程退出码反映结果（详见下文退出码语义）
--timeout <time_in_second>	—	等待超时时间（秒）。超时到期后，命令会打印带失败原因的消息并终止

退出码语义（--quiet 模式）

当指定 --quiet（或 -q）时，命令不再输出任务状态文本，而是返回以下退出码，方便脚本直接判断结果：

退出码	含义
0	任务成功完成
123	任务失败
124	请求超时
125	发生错误，任务状态无法确定

这套退出码设计与 timeout 命令的退出码约定保持一致（124 表示超时），便于运维人员直觉理解。在 shell 脚本中可以直接用 if nodetool tasks wait <task_id> -q; then ... 这样的写法判断任务成败。

使用示例

基础用法：等待并查看状态

最简单的用法是不带任何额外参数，等待任务结束并打印其完整状态：

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

带超时等待

如果任务可能运行很长时间，建议显式设置超时，避免命令无限期阻塞：

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

超时以秒为单位。超时到期后，命令会打印带有失败原因的消息（例如与 HTTP 请求超时对应的错误信息）。

静默模式（脚本友好）

在自动化脚本中，通常只需要结果而不需要冗长的状态输出：

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

配合退出码使用：

nodetool tasks wait "$TASK_ID" -q
rc=$?
case $rc in
  0)   echo "task succeeded" ;;
  123) echo "task failed" ;;
  124) echo "task timed out" ;;
  125) echo "task status undetermined" ;;
esac

输出字段逐项解读

nodetool tasks wait 成功完成后会打印任务的完整状态信息。以下是文档中的示例输出（来源：tasks/wait.rst）：

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 }]

各字段含义如下：

字段	含义
id	任务唯一标识（UUID）
type	任务类型，如 repair、compaction（offstrategy compaction 等）
kind	任务层级，node 表示节点级任务，shard 表示分片级子任务
scope	任务作用域，如 keyspace（键空间级）、shard（分片级）
state	任务状态：created（已创建）、running（运行中）、done（已完成）、failed（失败）等
is_abortable	该任务是否可中止（决定 nodetool tasks abort 是否可用）
start_time / end_time	任务开始 / 结束时间（ISO 8601 格式，UTC）。未结束时 end_time 为空
error	失败原因；为空表示无错误
parent_id	父任务 ID；顶层任务为 none
sequence_number	任务在节点上的序号（同一模块内递增）
shard	任务所在 CPU 分片编号
keyspace / table / entity	任务作用的键空间、表、实体
progress_units	进度单位，如 ranges（范围数）
progress_total / progress_completed	总工作量 / 已完成工作量，可用于计算进度百分比
children_ids	子任务列表（含 task_id 与所在节点），体现任务的父子层级

一个状态输出中的父子层级

从上述示例可以看到，一个 repair 节点级任务（scope 为 keyspace）会派生出两个 shard 级子任务，分别落在 127.0.0.1 节点的 shard 0 与 shard 1 上。这与 tasks/tree.rst 中展示的结构一致——tasks tree 会按 BFS 顺序列出任务及其全部后代的状态，而 tasks wait 只聚焦你指定的那一个任务。

底层实现：任务状态从哪里来

nodetool tasks wait 最终通过 ScyllaDB 的 HTTP API 与任务管理器交互。在源码中，对应的 REST 端点是 wait_task，实现在 api/task_manager.cc：

tm::wait_task.set(r, [&tm, &gossiper] (std::unique_ptr<http::request> req) -> future<json::json_return_type> {
    auto id = tasks::task_id{utils::UUID{req->get_path_param("task_id")}};
    tasks::task_status status;
    std::optional<std::chrono::seconds> timeout = std::nullopt;
    if (auto param = req->get_query_param("timeout"); !param.empty()) {
        timeout = std::chrono::seconds(boost::lexical_cast<uint32_t>(param));
    }
    try {
        auto task = tasks::task_handler{tm.local(), id};
        status = co_await task.wait_for_task(timeout);
    } catch (tasks::task_manager::task_not_found& e) {
        throw bad_param_exception(e.what());
    } catch (timed_out_error& e) {
        throw httpd::base_exception{e.what(), http::reply::status_type::request_timeout};
    }
    co_return make_status(status, gossiper);
});

从源码可以看出几个关键实现事实：

• 超时参数解析：timeout 查询参数通过 boost::lexical_cast<uint32_t> 解析为秒；未传时 timeout 为 std::nullopt，即无限等待。
• 任务不存在：若传入的 task_id 不存在，会抛出 task_manager::task_not_found，对应 HTTP 400（bad_param_exception）。
• 超时处理：wait_for_task(timeout) 超时后抛出 timed_out_error，映射为 HTTP 408（request_timeout）——这与 nodetool 侧 --quiet 模式下退出码 124（超时）的语义一一对应。
• 状态序列化：最终通过 make_status(status, gossiper) 生成包含节点信息（children_ids 中的 node 字段即来自 gossiper）的完整状态。

类似地，api/task_manager.cc 中的 abort_task 端点实现了 nodetool tasks abort 的底层逻辑：调用 task.abort()，若任务不可中止则抛出 task_not_abortable，映射为 HTTP 403。

状态保留时间与相关配置

任务完成后，其状态不会永久保存在节点上。根据 tasks/index.rst 的说明：

• 任务完成时，其状态会临时存储在执行该任务的节点上；
• 状态信息最多保留 task_ttl_in_seconds 秒。

在 db/config.cc 中可以找到该配置的默认值定义：

, task_ttl_seconds(this, "task_ttl_in_seconds", liveness::LiveUpdate, value_status::Used, 0, "Time for which information about finished task started internally stays in memory.")
, user_task_ttl_seconds(this, "user_task_ttl_in_seconds", liveness::LiveUpdate, value_status::Used, 3600, "Time for which information about finished task started by user stays in memory.")

即：

• task_ttl_in_seconds：内部任务完成后的保留时间，默认 0（立即注销）；
• user_task_ttl_in_seconds：用户发起的任务完成后的保留时间，默认 3600 秒（1 小时）。

两者均为 LiveUpdate 属性，可在线更新。相关运行时查看/修改方式参见 tasks/ttl.rst 与 tasks/user-ttl.rst：

# 查看当前内部任务保留时长
nodetool tasks ttl

# 将内部任务保留时长设为 10 秒（仅内存生效，不持久化）
nodetool tasks ttl --set 10

需要注意：nodetool tasks ttl --set 只在内存中生效，要永久修改需调整 scylla.yaml 中的 task_ttl_in_seconds，或在启动 Scylla 时使用 --task-ttl-in-seconds 参数。

对 tasks wait 的实际影响：如果在任务完成之前、任务状态已因 TTL 到期被注销，wait_for_task 会抛出 task_not_found。因此在使用 tasks wait 等待长任务时，应确保任务尚在保留期内，或合理配置 TTL 值。

与其它 tasks 子命令的配合

tasks wait 是整个任务管理器命令家族的一员（完整列表见 tasks/index.rst），在实践中常与以下命令组合使用：

子命令	作用	配合场景
tasks list <module>	列出某模块（如 repair、compaction）下的任务	先列出任务拿到 task_id，再用 tasks wait 等待目标任务。modules 子命令可查看支持的模块列表
tasks status <task_id>	获取单个任务当前状态（不等待）	任务还在运行时，轮询其状态；或任务已完成但未记录结束时间时核实
tasks tree [<task_id>]	获取任务及其全部后代状态（BFS 顺序）	分析父任务与 shard 子任务的整体完成情况
tasks abort <task_id>	中止可中止（is_abortable: true）的任务	等太久不想等了，先中止再配合 tasks wait 确认状态
tasks drain [--module <module>]	注销模块中所有已完成的本地任务	清理陈旧任务状态，释放内存

典型的"提交 → 等待 → 验证"工作流如下：

# 1. 查看支持的模块
nodetool tasks modules
# 输出示例：repair / compaction

# 2. 列出 repair 模块的任务，找到目标 task_id
nodetool tasks list repair --internal -ks myks --table mytable

# 3. 等待该任务完成（静默模式，按退出码判断结果）
nodetool tasks wait <task_id> --quiet

# 4. 若超时或失败，可中止任务并用 tree 检查整体状态
nodetool tasks abort <task_id>
nodetool tasks tree <task_id>

tasks list 的常用过滤参数（详见 tasks/list.rst）包括：--internal（列出内部任务）、--keyspace/-ks、--table/-t、--interval（周期性重复列出）与 --iterations/-i（重复次数）。例如每 5 秒重复列出 compaction 任务 3 次：

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

小结

nodetool tasks wait 是 ScyllaDB 任务管理器中面向"确定性结果"的关键工具：它把"任务是否真正完成"从人工轮询 tasks status 中解放出来，通过一次调用即可阻塞等待并返回最终状态；--quiet 模式下的退出码约定（0/123/124/125）使其天然适合嵌入 shell 脚本与自动化流水线。配合 tasks list 定位任务、tasks tree 观察层级、tasks abort 中止失控任务，以及 task_ttl_in_seconds / user_task_ttl_in_seconds 的保留期配置，运维人员可以完整地掌控 repair、compaction 等长时后台任务的整个生命周期。