ScyllaDB nodetool tasks user-ttl 命令详解：用户任务在任务管理器中的保留时长（TTL）管理

导读

nodetool tasks user-ttl 是 ScyllaDB 任务管理器（Task Manager）的运维命令之一，用于查询或动态修改用户发起任务的保留时长（user_task_ttl），即用户通过客户端/API 发起的后台任务（如 repair、compaction 等）在任务管理器中被保留的时间。本文以官方文档 docs/operating-scylla/nodetool-commands/tasks/user-ttl.rst 为主体，结合仓库中的配置、REST API 与任务管理器源码，说明该命令的语法、底层机制、与 tasks ttl 的区别以及持久化配置方法，帮助读者在真实集群中正确管理与清理任务状态信息。

一、背景：任务管理器与 user TTL 的语义

任务管理器（Task Manager）是 ScyllaDB 提供的、基于 API 的、用于跟踪长时间运行后台操作（如 repair、compaction）的工具，使这些操作可被观测和控制，任务管理器按节点（per node）运行，见 tasks/index.rst。

从开发者文档 docs/dev/task_manager.md 可以梳理出与 TTL 直接相关的语义：

• 任务管理器按模块（module）组织，例如 repair 模块、compaction 模块；每个操作由任务（task）跟踪，一个操作覆盖为任务树（tree of tasks），例如全局 repair 任务是父任务，其下是 keyspace 级任务，再往下是表级任务。
• 任务分为**常规任务（regular task）与虚拟任务（virtual task）**两类：常规任务覆盖本地操作，虚拟任务覆盖集群级全局操作。
• **只有常规根任务（root task）**在结束后按 TTL 保留：如果任务由用户发起，则保留 user_task_ttl 时间；否则保留 task_ttl 时间。
• 非根任务在结束后立即从任务管理器注销，其状态被"折叠"进父任务；子任务信息在折叠时丢失（除非子任务或其子孙失败）。
• 标记为 internal 的内部任务不默认列出，且应在结束后立即注销。
• 虚拟任务在任务管理器中展示的时长取决于具体实现。

因此，nodetool tasks user-ttl 管理的正是"由用户发起的根任务"在完成后仍可被查询状态的时间窗口。

二、命令语法与选项

命令完整语法如下：

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

选项	说明
--set	将 user_task_ttl 设置为指定的秒数值

不带 --set 时，命令返回当前 user_task_ttl 值；带 --set 时，命令先返回修改前的旧值，再设置新值（这一行为对应 REST API 的"get and update"语义，见下文源码分析）。

查询当前 user_task_ttl 值

> nodetool tasks user-ttl

将 user_task_ttl 设置为 10 秒

> nodetool tasks user-ttl --set 10

三、关键行为与限制

原文档明确了以下三点必须注意的行为：

1. 仅内存生效：通过 --set 修改的新值只写入当前节点内存，不会写入配置文件。要持久化修改，需要编辑 conf/scylla.yaml 中的 user_task_ttl_in_seconds 配置项（默认值注释为 3600 秒，见 conf/scylla.yaml）。
2. 启动参数替代方案：也可以在启动 Scylla 时通过命令行参数 --user-task-ttl-in-seconds 指定初始值。
3. 零值语义：如果 user_task_ttl == 0，任务在结束后立即从任务管理器注销，不再保留任何状态信息。

需要特别指出的是，由于该值是按节点、按内存生效的，在集群环境中若要通过命令调整，需要对每个节点执行；而通过 scylla.yaml 配置则可在重启后保持。

四、与 tasks ttl 的区别

tasks ttl（见 ttl.rst）管理的对象是非用户发起（即系统内部发起）的任务保留时间，对应配置项 task_ttl_in_seconds（默认值注释为 0，见 conf/scylla.yaml），对应启动参数 --task-ttl-in-seconds。

两者的分工由源码确认：在任务完成后的保留逻辑中，任务管理器会根据任务是否由用户发起（is_user_task()）来选择使用哪个 TTL 值，见 tasks/task_manager.cc：

auto user_task = is_user_task();
bool drop_after_complete = (get_parent_id() && _impl->_parent_kind == task_kind::node) || is_internal();
(void)done().finally([module, drop_after_complete, user_task] {
    if (drop_after_complete) {
        return make_ready_future<>();
    }
    return sleep_abortable(user_task ? module->get_task_manager().get_user_task_ttl() : module->get_task_manager().get_task_ttl(), module->abort_source());
}).then_wrapped([module, id = id()] (auto f) {
    f.ignore_ready_future();
    module->unregister_task(id);
});

从这段源码可以推断：对于非根任务（有父节点且父节点为 node 类型）以及 internal 任务，完成后不经过 TTL 等待，直接注销；其余根任务则按"用户任务走 user_task_ttl、内部任务走 task_ttl"的方式 sleep 相应秒数后注销。

五、底层实现：配置、REST API 与 nodetool 客户端

1. 配置项声明

user_task_ttl 对应的持久化配置项在配置类中声明为：

named_value<uint32_t> task_ttl_seconds;
named_value<uint32_t> user_task_ttl_seconds;

见 db/config.hh。任务管理器在构造时从配置读取该值，并在日志中打印当前 TTL 与 USER TTL，见 tasks/task_manager.cc：

, _user_task_ttl(_cfg.user_task_ttl)
...
tmlogger.debug("Started task manager (TTL={}) (USER TTL={})", get_task_ttl(), get_user_task_ttl());

读取接口将底层 uint32 包装为 std::chrono::seconds 返回，见 tasks/task_manager.hh 与 tasks/task_manager.cc。

2. REST API 端点

nodetool 并非直接访问任务管理器，而是通过 ScyllaDB 的 REST API 完成操作。/task_manager/user_ttl 端点同时承担查询与更新功能，见 api/task_manager.cc：

tm::get_and_update_user_ttl.set(r, [&cfg] (std::unique_ptr<http::request> req) -> future<json::json_return_type> {
    uint32_t user_ttl = cfg.user_task_ttl_seconds();
    try {
        co_await cfg.user_task_ttl_seconds.set_value_on_all_shards(req->get_query_param("user_ttl"), utils::config_file::config_source::API);
    } catch (...) {
        throw bad_param_exception(fmt::format("{}", std::current_exception()));
    }
    co_return json::json_return_type(user_ttl);
});

tm::get_user_ttl.set(r, [&cfg] (std::unique_ptr<http::request> req) -> future<json::json_return_type> {
    uint32_t user_ttl = cfg.user_task_ttl_seconds();
    co_return json::json_return_type(ttl);
});

其中 set_value_on_all_shards(...) 会将新值广播到所有 shard，并将配置来源标记为 config_source::API（即内存级、非持久化），这正是"新值只存在内存中"这一行为的实现依据。相关 API 的完整说明可见 docs/dev/task_manager.md。

3. nodetool 客户端实现

nodetool tasks user-ttl 在客户端侧的实现位于 tools/scylla-nodetool.cc：

void tasks_user_ttl_operation(scylla_rest_client& client, const bpo::variables_map& vm) {
    if (!vm.contains("set")) {
        auto res = client.get("/task_manager/user_ttl");
        fmt::print("Current user ttl: {}\n", res);
        return;
    }
    auto new_ttl = vm["set"].as<uint32_t>();
    std::unordered_map<sstring, sstring> params = {{ "user_ttl", fmt::to_string(new_ttl) }};
    auto res = client.post("/task_manager/user_ttl", std::move(params));
}

即：

• 不带 --set：执行 GET /task_manager/user_ttl 并打印 Current user ttl: <值>；
• 带 --set <秒数>：执行 POST /task_manager/user_ttl，以表单参数 user_ttl=<秒数> 提交新值，并返回修改前的旧值。

六、实战建议

1. 临时调整场景：当节点上积累了大量已完成任务状态、希望尽快释放内存时，可将 TTL 临时调小，例如 nodetool tasks user-ttl --set 60，之后无需重启即可生效。
2. 彻底清理场景：设置 --set 0 可让用户任务在结束后立即注销，效果等同于"不保留用户任务状态"。
3. 持久化场景：若希望在重启后依然保持新策略，请修改 conf/scylla.yaml 中注释掉的 user_task_ttl_in_seconds: 3600，或在启动命令中加入 --user-task-ttl-in-seconds 参数。
4. 配套命令：TTL 之外的清理手段还有 nodetool tasks drain（注销所有已完成的本地任务）等，完整子命令列表见 tasks/index.rst；任务管理器的总体运维指南见 docs/operating-scylla/admin-tools/task-manager.rst。

七、小结

nodetool tasks user-ttl 是任务管理器运维体系中一个简单但关键的旋钮：它决定了用户发起的根任务在完成后还能被 tasks list、tasks status、tasks tree、tasks wait 等命令查询多久。理解其"仅内存生效、按节点生效、零值即立即注销"的行为边界，配合 scylla.yaml 中的 user_task_ttl_in_seconds 持久化配置，即可在"保留足够长的任务状态以便排查"与"及时释放内存资源"之间做出合理的权衡。