ScyllaDB nodetool dropquarantinedsstables 命令详解清理隔离 SSTable 的完整指南【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb导读nodetool dropquarantinedsstables是 ScyllaDB 提供的运维命令用于删除指定 keyspace 与表table中处于隔离quarantine状态的 SSTable或在不指定 keyspace 时删除集群中所有 keyspace 的隔离 SSTable。本文以仓库中的官方文档 dropquarantinedsstables.rst 为主线结合 scylla-nodetool.cc、storage_service.cc、table.cc 等源码与测试用例讲解命令参数、四种典型用法、隔离机制的前因后果以及底层执行链路。读完本文你将能够独立完成发现损坏 SSTable → 隔离 → 备份取证 → 安全清除的完整运维闭环。命令概述dropquarantinedsstables- 从指定的 keyspace 和表删除隔离的 SSTable如果未指定 keyspace则从所有 keyspace 中删除。隔离quarantine是 ScyllaDB 处理损坏 SSTable 的关键机制当nodetool scrub以默认的VALIDATE模式发现损坏 SSTable 时会将其移动change_state到该表数据目录下的quarantine子目录中使其不再参与 compaction从而避免损坏在压实过程中扩散或陷入失败-重试循环。dropquarantinedsstables就是与这一机制配套的最终清理命令。从磁盘目录布局看每个表的数据目录下都存在quarantine子目录与staging、upload、snapshots、pending_delete并列这一点在 sstables-directory-structure.md 的目录树中可以直接看到├── cf-7ec943202fc611e9a130000000000000 │ ├── snapshots │ ├── staging │ ├── quarantine │ └── upload在源码层面隔离状态是 SSTable 生命周期状态机sstable_state中的一个正式状态。定义于 sstables.hhconstexpr const char* normal_dir ; constexpr const char* staging_dir staging; constexpr const char* upload_dir upload; constexpr const char* snapshots_dir snapshots; constexpr const char* quarantine_dir quarantine; constexpr const char* pending_delete_dir pending_delete;并通过is_quarantined()判定bool is_quarantined() const noexcept { return _state sstable_state::quarantine; }dropquarantinedsstables命令正是按此状态标记筛选并删除 SSTable只有状态为quarantine的 SSTable 才会被选中清理。参数说明OPTIONS参数说明[keyspace]可选。要从中删除隔离 SSTable 的 keyspace。若未指定则作用于所有 keyspace。[table...]可选。一个或多个要删除隔离 SSTable 的表。若未指定则作用于该 keyspace 下的所有表。从 scylla-nodetool.cc 的命令注册定义可以确认这两个参数的语义与数量约束{ dropquarantinedsstables, Drop quarantined SSTables, R(Drop quarantined SSTables from the specified keyspace and table(s), or from all keyspaces if no keyspace is specified.), {}, { typed_optionsstring(keyspace, The keyspace to drop quarantined SSTables from, if missing, all keyspaces will be affected, 1), typed_optionstd::vectorsstring(table, The table(s) to drop quarantined SSTables from, if missing, all tables will be affected, -1), } },其中keyspace位置参数的数量上限为 1table位置参数数量为 -1即不限数量因此一条命令可以一次性删除多个指定表的隔离 SSTable。参数校验行为测试文件 test_dropquarantinedsstables.py 验证了不存在的 keyspace 会触发明确报错nodetool: Keyspace [non_existent_ks] does not exist. error processing arguments: keyspace non_existent_ks does not exist说明该命令会先通过GET /storage_service/keyspaces校验 keyspace 是否存在再进行删除操作。使用示例Examples示例 1删除所有 keyspace 和表中隔离的 SSTable nodetool dropquarantinedsstables不携带任何参数时命令作用于全部 keyspace 与全部表。从实现看此时 nodetool 不会附加任何查询参数直接向 REST API 发起 POST 请求由服务端遍历所有表执行删除。示例 2删除某个 keyspacemykeyspace下所有表的隔离 SSTable nodetool dropquarantinedsstables mykeyspace指定 keyspace 后该 keyspace 下所有表都会被扫描并清理未指定的表不受影响。示例 3删除某个 keyspacemykeyspace中指定表mytable的隔离 SSTable nodetool dropquarantinedsstables mykeyspace mytable精确到单表清理适用于只想处理某张出问题表的场景。示例 4删除某个 keyspacemykeyspace中多个指定表mytable1、mytable2的隔离 SSTable nodetool dropquarantinedsstables mykeyspace mytable1 mytable2一次命令同时清理多张表的隔离 SSTable。在 nodetool 侧这些表名会被拼接为逗号分隔的tables参数如tbl1,tbl2,tbl3最终传给 REST API这一点在 scylla-nodetool.cc 与测试用例 test_dropquarantinedsstables_multiple_tables 中均有体现。提示位置参数同时支持--keyspace/--table长选项形式。例如nodetool dropquarantinedsstables --keyspace ks1 --table tbl1与位置参数写法等价相关验证同样位于上述测试文件中。底层执行链路从 nodetool 到磁盘删除理解该命令的完整调用链有助于在生产环境准确判断其行为与影响范围第一步nodetool 组装请求tools/scylla-nodetool.cc 中的dropquarantinedsstables_operation负责解析参数并发起 REST 调用void dropquarantinedsstables_operation(scylla_rest_client client, const bpo::variables_map vm) { std::unordered_mapsstring, sstring params; if (vm.contains(keyspace)) { const auto [keyspace, tables] parse_keyspace_and_tables(client, vm); params[keyspace] keyspace; if (!tables.empty()) { params[tables] fmt::to_string(fmt::join(tables.begin(), tables.end(), ,)); } } client.post(/storage_service/drop_quarantined_sstables, std::move(params)); }注意命令名dropquarantinedsstables对应的 REST 端点为/storage_service/drop_quarantined_sstables下划线分隔。第二步REST API 分发到各表api/storage_service.cc 中的rest_drop_quarantined_sstables处理该端点请求指定了 keyspace 时校验 keyspace 存在解析表列表然后invoke_on_all在数据库的所有 shard 上并行调用每张表的drop_quarantined_sstables()未指定 keyspace 时遍历db.get_tables_metadata()中的所有表逐一调用drop_quarantined_sstables()。} else { co_await ctx.db.invoke_on_all([](replica::database db) - future { return db.get_tables_metadata().parallel_for_each_table([](table_id, lw_shared_ptrreplica::table t) - future { return t-drop_quarantined_sstables(); }); }); }第三步表级删除实现replica/table.cc 中的table::drop_quarantined_sstables()是真正的执行者。其核心流程如下递增pending_sstable_deletions统计获取 SSTable 列表操作许可get_sstable_list_permit通过quarantine_removal_updater一个row_cache::external_updater_impl子类在prepare()中遍历该表所有 compaction group 的main_sstables()与maintenance_sstables()凡是is_quarantined()为真的 SSTable 都被收集进removed列表其余 SSTable 保留并重建新的 sstable_set通过_cache.invalidate(std::move(updater))以原子方式应用变更将隔离 SSTable 从表的主集合与维护集合中摘除并刷新 row cache 快照调用rebuild_statistics()重建表统计信息若存在已提交的atomic_deletion执行deletion-execute()完成 SSTable 物理文件的原子删除。从该实现可以推断命令不仅删除文件还会同步更新内存中的 sstable_set、缓存与统计信息保证删除后读取路径立即生效无需重启节点。隔离机制详解什么情况下会用到本命令隔离 SSTable 并非凭空产生理解其来源才能正确规划清理时机。根据 scrub.rst 的说明默认的VALIDATE模式 scrub 会将损坏 SSTable 移入quarantine目录。隔离后的 SSTable 行为有明确定义参与读取reads参与流式传输与 tablet 迁移streaming / file streaming参与修复repair不参与compaction但参与 tombstone-gc 目的的 overlap 检查。隔离的意义在于把损坏 SSTable 挡在 compaction 之外防止压实过程扩散损坏或陷入失败重试循环同时让损坏文件易于定位和取回分析。官方推荐的清理流程Method 1隔离并删除针对损坏 SSTable 的运维场景scrub.rst 给出了与本命令直接配套的标准操作流程Step 1以VALIDATE模式运行 scrub识别并隔离损坏 SSTable nodetool scrub keyspace_name table_nameStep 2可选强烈建议在永久删除前将隔离的 SSTable 复制到 ScyllaDB 数据目录之外的位置以便后续交给研发团队定位损坏根因# 将隔离 SSTable 复制到备份位置以供分析 cp -r /path/to/data/keyspace_name/table_dir/quarantine /path/to/backup/location/Step 3使用nodetool dropquarantinedsstables删除隔离 SSTable即本文命令 nodetool dropquarantinedsstables keyspace_name table_name这一步会永久删除指定表中所有隔离的 SSTable删除前务必确认已保留取证所需的数据。提示若不想在 scrub 时产生隔离文件可通过nodetool scrub --quarantine-invalid-sstablesfalse显式关闭自动隔离默认值为 true。相关选项定义同样见 scrub.rst。scrub 的 quarantine 模式与范围控制当需要精细控制隔离文件处理范围时scrub 还提供--quarantine-mode-q选项定义于 scrub.rst模式说明INCLUDE同时处理常规与隔离的 SSTable默认EXCLUDE只处理常规非隔离SSTableONLY只处理隔离的 SSTable这意味着你也可以先用nodetool scrub -q ONLY单独重新验证隔离目录中的文件确认哪些确实损坏、哪些可能是误判再决定是否执行dropquarantinedsstables。安全注意事项删除不可逆dropquarantinedsstables执行的是物理删除一旦执行无法恢复。执行前务必确认隔离目录中不再有需要保留用于分析的文件。作用域确认不带任何参数执行时影响范围是全部 keyspace 与全部表属于全集群范围的清理操作建议先在单 keyspace / 单表范围内验证效果。隔离文件仍参与读取与修复隔离状态不等于不可见因此在删除前它们仍可能被读取路径访问删除动作通过表级原子更新完成无需停机。测试与验证仓库在 test/nodetool/test_dropquarantinedsstables.py 中提供了完整的 nodetool 集成测试覆盖了以下场景可作为理解命令行为的权威参照全部 keyspace仅发送POST /storage_service/drop_quarantined_sstables无附加参数单 keyspace先GET /storage_service/keyspaces校验再携带keyspace参数 POST单表携带keyspace与tables参数多表tables参数为逗号拼接的表名列表位置参数与长选项--keyspace/--table两种写法等价不存在的 keyspace 会报错并拒绝执行。此外api/api-doc/storage_service.json 定义了该 REST 端点的完整契约REST 层面的行为还可参考 test/rest_api/test_storage_service.pySSTable 状态切换与change_state的实现位于 sstables.hh。对隔离机制更深入的背景可继续阅读 scrub.rst 与 sstables-directory-structure.md。总结nodetool dropquarantinedsstables是 ScyllaDB 损坏 SSTable 治理链路中的最终清理环节先由scrub的VALIDATE模式将损坏文件隔离到quarantine目录经人工取证分析后再由本命令按 keyspace/表粒度安全、原子地完成物理删除。其实现贯穿 nodetool 客户端、REST API 服务端与 replica 层表级更新三个层次并配有完整的自动化测试是生产环境处理 SSTable 损坏问题时必须掌握的命令之一。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考