ScyllaDB nodetool clearsnapshot 完全指南：快照删除命令的用法、参数与底层原理
【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb
nodetool clearsnapshot是 ScyllaDB 用于删除本地节点上快照的核心运维命令，可一次清理全部快照，也可通过 tag 与 keyspace 精确指定删除范围。本文以官方文档 clearsnapshot.rst 为骨架，结合 scylla-nodetool.cc 命令实现、snapshot-ctl.cc 快照控制器与 database.cc 目录清理逻辑，讲解命令语法、参数语义、REST 调用链与磁盘目录结构，帮助读者安全、精准地管理快照存储空间。
命令概览与语法
clearsnapshot的完整语法为：
nodetool clearsnapshot [-t tag] [<keyspace>...]- 不携带任何参数时，删除当前节点上的全部快照（所有 keyspace、所有表）；
- 携带
-t <tag>（即 snapshot name / 快照标签）时，只删除该标签对应的快照； - 携带一个或多个 keyspace 名时，只删除这些 keyspace 下的快照，可与
-t组合使用。
官方文档 clearsnapshot.rst 给出的两个基本示例：
# 删除所有快照 nodetool clearsnapshot # 删除指定名称（tag）的快照 nodetool clearsnapshot -t <snapshot_name>在 tools/scylla-nodetool.cc#L4102-L4121 中可以看到该子命令的注册定义：命令描述为 “Remove snapshots”，声明了-t/--tag（"The snapshot to remove"）与可重复出现的--keyspaces位置参数，帮助文本明确写着 “By default all snapshots are removed for all keyspaces.”（默认情况下会删除所有 keyspace 的所有快照）。
参数详解
-t, --tag <snapshot_name>：按快照标签精确删除
tag是在执行nodetool snapshot时为快照指定的标签，也常被文档称为 snapshot name。它相当于给一次快照操作起的名字，用于区分不同时间点或不同用途的快照。当且仅当快照目录名与 tag 完全匹配时才会被删除（详见下文目录遍历逻辑）。
值得注意：ScyllaDB 的tag与 Apache Cassandra 原生的snapshot_name语义一致，命令设计上兼容 Cassandra 运维习惯。若未指定 tag，则删除目标 keyspace（或全部 keyspace）下所有快照目录。
位置参数<keyspace>...：按 keyspace 范围限定删除
可传入一个或多个 keyspace 名，将删除范围限制在这些 keyspace 内。官方文档还提供了 nodetool 命令索引 便于速查。
需要特别强调的是：当前仓库实现的 clearsnapshot 并不支持指定单个表（column family）。虽然 snapshot-ctl.cc 内部的clear_snapshot接口带有cf_name参数，但从 tools/scylla-nodetool.cc 的命令定义看，clearsnapshot只暴露了tag与keyspaces两类参数，删除粒度是 keyspace 级（可叠加 tag 缩小到某个快照）。
组合用法示例
以下用法均可在 test/nodetool/test_snapshot.py#L14-L64 的测试用例中得到验证：
# 1. 删除所有 keyspace 的所有快照 nodetool clearsnapshot # 2. 删除指定 keyspace 的所有快照 nodetool clearsnapshot ks1 # 3. 删除多个 keyspace 的所有快照 nodetool clearsnapshot ks1 ks2 # 4. 删除所有 keyspace 中指定 tag 的快照 nodetool clearsnapshot -t snapshot_name # 5. 删除指定 keyspace 中指定 tag 的快照（最精确的组合） nodetool clearsnapshot -t snapshot_name ks1 # 6. 删除多个 keyspace 中指定 tag 的快照 nodetool clearsnapshot -t snapshot_name ks1 ks2官方备份/恢复手册 delete-snapshot.rst 给出了贴近实际运维的示例：
$ nodetool clearsnapshot mykeyspace Requested clearing snapshot(s) for [mykeyspace]源码级原理：从命令到磁盘删除的完整链路
1. 参数校验与 REST 请求构造
clearsnapshot_operation定义在 tools/scylla-nodetool.cc#L562-L585，其行为要点：
- 若传入了 keyspace，会先调用
get_keyspaces(client)拉取集群现有 keyspace 列表做存在性校验，不存在的 keyspace 直接抛出keyspace {} does not exist异常（测试test_clearnapshot_nonexistent_keyspaces验证了这一点）； - 校验通过后，将 keyspace 列表以逗号拼接写入
kn参数，tag 写入tag参数； - 最终通过
client.del("/storage_service/snapshots", params)发起HTTP DELETE请求，即该命令实际是一个对storage_serviceREST API 的封装。
2. 快照控制器：并发安全与索引名解析
REST 请求进入 snapshot-ctl.cc#L230-L256 的snapshot_ctl::clear_snapshot：
- 先调用
cancel_expiration取消对应快照的过期定时器（ScyllaDB 支持带过期时间的快照）； - 随后通过
run_snapshot_modify_operation串行化快照修改操作，保证并发安全； - 当同时指定了表名（cf_name）时，会调用
resolve_table_name将逻辑索引名解析为实际 backing table 名（如二级索引对应的物理表），并在每个 keyspace 中分别解析，避免跨 keyspace 解析结果不一致导致误删。
3. 数据库层：目录遍历与递归删除
真正执行磁盘清理的是 database.cc#L3379-L3458 的database::clear_snapshot。它遍历data_file_directories配置指定的每个数据目录，目录结构如下（源码注释原文整理）：
<data dir> |- <keyspace name1> | |- <column family name1> | |- snapshots | |- <snapshot name1> | |- <snapshot file1> | |- <snapshot file2> | |- ... | |- <snapshot name2> | |- ... | |- <column family name2> | |- ... |- <keyspace name2> |- ...三层过滤逻辑：
- keyspace 过滤：若指定了 keyspace 集合，只进入匹配的 keyspace 目录；
- 表过滤：若指定了表名，只处理前缀匹配的表目录（
get_snapshot_table_dir_prefix）； - 快照目录匹配：若指定了 tag，只删除名称与 tag 完全相等的快照目录；未指定 tag 时，删除整个
snapshots目录。
删除动作使用recursive_remove_directory递归移除快照目录；同时，若某表目录在清理后已无任何快照且该表已被 drop，还会顺带清理残留的表目录（"zap the table directory if the table is dropped and has no remaining snapshots"）。每步操作都留有dblog.info("Removing {}", ...)形式的日志，可在系统日志中核对删除行为。
与快照创建、列举命令的配合
快照管理是一个完整闭环，clearsnapshot通常与以下命令配合使用：
- 创建快照：
nodetool snapshot -t <tag> <keyspace>； - 列举快照：
nodetool listsnapshots，展示每个快照 tag 及所属 keyspace/表（test_snapshot.py#L67-L75 展示了其返回结构）； - 删除快照：
nodetool clearsnapshot [-t <tag>] [<keyspace>...]； - 查询快照占用：可通过 REST 接口
GET /storage_service/snapshots/size/true获取真实快照大小（见 storage_service.cc 中true_snapshots_size相关处理），用于评估清理收益。
关于快照存储机制的更多背景，可参阅 docs/kb/snapshots.rst 与 docs/dev/snapshot_sstables.md。
安全注意事项与最佳实践
delete-snapshot.rst 与 kb/snapshots.rst#L81-L91 给出了以下关键提醒：
- 快照不会自动覆盖：拍摄新快照不会删除旧快照，旧快照必须显式清理以释放磁盘空间；
- 务必谨慎使用无参数形式：
nodetool clearsnapshot（不带 keyspace 与 tag）不仅会删除nodetool listsnapshots列出的快照，还会删除节点存储上包括已 drop 表/keyspace 残留快照在内的所有快照，风险最高； - 删前确认备份：确保快照数据已经备份到安全位置再执行删除，删除操作不可恢复；
- 自动化需配套：若用自动化脚本定期拍摄快照，建议配套自动化清理逻辑，避免磁盘被历史快照占满。
小结
nodetool clearsnapshot通过 tag + keyspace 的组合，可以在“全量清理”与“精准删除”之间灵活切换。理解其背后 REST 调用链（DELETE /storage_service/snapshots）与三层目录过滤机制，能帮助运维人员准确预判命令的删除范围，规避误删风险；配合snapshot、listsnapshots及快照大小查询接口，即可形成一套可审计、可自动化的快照生命周期管理方案。
【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
