ScyllaDB nodetool listsnapshots 命令详解快照列表、True Size 与 Size on Disk 的精确解读【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladbnodetool listsnapshots是 ScyllaDB 中用于查看节点上所有快照清单及磁盘占用情况的运维命令它以表格形式输出每个快照的名称、所属 Keyspace、表Column Family、真实大小True Size与磁盘占用Size on Disk是备份与恢复backup/restore流程中核对快照是否创建成功、评估磁盘空间消耗的核心工具。阅读本文后你将掌握该命令的输出格式、各字段的准确定义与判定方法并能结合源码理解其底层数据来源与限制。命令概览与核心用途listsnapshots用于列出节点上所有快照以及每个快照在磁盘上的大小和真实大小。ScyllaDB 的快照是 SSTable 数据文件的硬链接hard link因此该命令展示的大小信息与普通文件占用有所不同详见下文字段详解。一个需要特别注意的限制是已删除dropped的表Column Family不会出现在listsnapshots的输出中。这一行为同时体现在官方文档与命令自身的帮助文本中见 tools/scylla-nodetool.cc 中命令注册时的描述Dropped tables (column family) will not be part of the listsnapshots.。基本用法与输出示例直接执行命令即可查看当前节点上的全部快照nodetool listsnapshots典型的输出如下沿用官方文档示例keyspace 为nba包含三张表Snapshot Details: Snapshot Name Keyspace Column Family True Size Size on Disk 5487138454987 nba player_name 0 bytes 308.66 MB 2157384283120 nba player_team 0 bytes 107.21 MB 4824891793663 nba player_stats 0 bytes 41.69 MB说明快照名称Snapshot Name默认是创建时的时间戳毫秒精度例如nodetool snapshot不带-t参数时即生成此类名称若创建时显式指定了--tag tag则此处显示为自定义标签。关于快照创建与命名可参考 nodetool snapshot 文档。输出中的隐藏汇总行从源码实现看命令输出并不止于上述表格。执行函数 listsnapshots_operation 在打印完整表格之后还会追加一行统计信息Total TrueDiskSpaceUsed: 923.08 KiB该行汇总了所有快照的 True Size 之和单位使用二进制前缀KiB / MiB / GiB与表格内各列使用的十进制前缀KB / MB / GB区分开。对应测试用例 test/nodetool/test_snapshot.py 对此输出格式有精确断言。无快照时的输出当节点上不存在任何快照时命令输出为There are no snapshots该行为由源码中snapshots.GetArray().Empty()分支直接打印并提前返回见 tools/scylla-nodetool.cc测试用例 test_listsnapshots_no_snapshots 中亦验证了该场景。输出字段详解官方文档为输出表格中的四个核心字段给出了如下定义下表完整保留并补充了来源依据字段说明Snapshot Name快照的名称默认是创建时间戳也可通过--tag自定义Keyspace快照所属的 Keyspace 名称Column Family快照所属的表Column Family / table名称True Size所有尚未备份到磁盘即未被主数据目录引用的 SSTable 的总大小Size on Disk快照在磁盘上的总大小需要注意的是表头在实际输出中会被规范化为更长的形式Snapshot name、Keyspace name、Column family name、True size、Size on disk源码中定义于 listsnapshots_operation。True Size 与 Size on Disk 的本质区别理解这两个字段的关键在于快照是 SSTable 文件的硬链接而 SSTable 本身是不可变的。当数据被 compaction、TRUNCATE、DROP TABLE 等操作重写后主数据目录中的原文件可能已被移除但快照硬链接仍指向旧文件此时该文件占用的空间仅由快照持有。官方文档给出了一个直观的 1TB 示例假设快照目录中存在一个 1TB 的文件若该文件同时也存在于主 Column Family 目录中即数据并未因 compaction 等操作从主目录消失则 Size on Disk 为 1TB而 True Size 为 0——因为该数据已经备份到磁盘上主目录仍在引用它快照没有额外持有任何独占数据。反之当 compaction 已经将数据合并进新的 SSTable、旧文件只存在于快照目录时该文件的体积就会计入 True Size——它代表的是移除快照后会真正释放的磁盘空间。从源码实现看这两个数值分别对应底层数据结构中的total与live字段total快照目录占用磁盘的总字节数对应输出中的 Size on Disklive快照独有的、尚未被主目录引用的字节数对应输出中的 True Size。REST API 层在 api/storage_service.cc 的/storage_service/snapshots端点中将每个快照条目序列化为ks、cf、live、total四个字段而listsnapshots_operation正是从该端点读取数据见 tools/scylla-nodetool.cc并分别以snapshot[live]和snapshot[total]填充 True Size 与 Size on Disk 两列见 tools/scylla-nodetool.cc。源码级解析命令是如何工作的listsnapshots并不直接扫描磁盘目录而是走nodetool → ScyllaDB REST API → snapshot_ctl → 数据库层的调用链。理解这条链路有助于排查为什么列表和磁盘上看到的文件不一致之类的疑问。1. nodetool 客户端的请求与格式化scylla-nodetool.cc 中的listsnapshots_operation函数完成两件事发起GET /storage_service/snapshots请求获取快照明细列表发起GET /storage_service/snapshots/size/true请求获取所有快照 True Size 的汇总值用于输出末尾的Total TrueDiskSpaceUsed行见 tools/scylla-nodetool.cc。随后该函数对每个快照条目做格式化字节数按 1024 进制自动选择bytes / KB / MB / GB / TB / PB / EB单位并省略.00的小数尾部同时根据各列内容动态计算列宽保证表格对齐见 tools/scylla-nodetool.cc。这也解释了为什么输出中会出现0 bytes、44 KB这类混合精度的数值。2. REST API 端点的数据组装/storage_service/snapshots端点由 set_snapshot 注册其处理器调用snap_ctl.local().get_snapshot_details()获得结果后流式输出 JSON 数组数组中每个元素的结构为{key: snapshot_name, value: [{ks: keyspace, cf: table, live: 0, total: 45056}]}测试用例 test/nodetool/test_snapshot.py 中的 mock 响应与此结构完全一致可作为字段含义的参考。3. snapshot_ctl 的细节处理db/snapshot-ctl.cc 中的get_snapshot_details()在返回前还会做一步处理如果表是一个索引secondary index底层以物化视图形式存储则把cf名称从物化视图的内部表名转换回用户可见的索引名。因此listsnapshots输出中对索引快照显示的是索引名称而非底层物化视图表名。汇总值true_snapshots_size()则对所有快照条目的live字段求和见 db/snapshot-ctl.cc即所有快照独占磁盘空间的总和对应输出中的Total TrueDiskSpaceUsed。4. 与无快照分支的一致性当 REST API 返回空数组时客户端直接打印There are no snapshots并返回见 tools/scylla-nodetool.cc不会请求/snapshots/size/true端点因此无快照场景下不会出现Total TrueDiskSpaceUsed行。快照生命周期与 listsnapshots 的配合使用listsnapshots通常是快照管理工作流中的读环节它应与以下命令配合理解相关文档均位于 nodetool-commands 目录命令作用snapshot创建快照支持按 Keyspace / 表 / 表列表可用--tag命名、--ttl设置过期时间listsnapshots本文查看已存在的快照及空间占用clearsnapshot删除快照默认删除全部可用-t snapshot_name指定删除某一个快照如何被创建与存储listsnapshots列出的快照主要有两类来源详见 kb/snapshots 文档手动创建执行nodetool snapshot或cluster snapshot创建的计划备份快照自动创建当auto_snapshot配置项/etc/scylla/scylla.yaml默认true开启时执行DROP TABLE、TRUNCATE TABLE、DROP KEYSPACE会自动为被删除/清空的表生成快照作为误删数据的兜底保护。每个快照都位于表 SSTable 数据目录下的snapshots/子目录中例如/var/lib/scylla/data/keyspace/table-uuid/snapshots/snapshot_name/目录内的文件如la-1-big-Data.db、la-1-big-Index.db、manifest.json等是 SSTable 文件的硬链接参见 snapshot.rst 中的目录示例。理解这一点是读懂 True Size / Size on Disk 差异的前提。使用建议与注意事项用 True Size 评估清理收益执行clearsnapshot释放空间前先运行listsnapshots重点关注 True Size 非 0 的快照条目它们才是真正占用额外磁盘空间的部分警惕 dropped 表的自动快照由于 dropped 表不会出现在listsnapshots中其自动快照可能被忽视。若auto_snapshot开启且长期未清理这些隐藏快照会持续占用磁盘。可在/etc/scylla/scylla.yaml中配置auto_snapshot_ttl默认864000秒即 10 天让过期快照自动回收大小单位差异表格内使用十进制单位KB/MB/GB按 1024 计算但沿用传统命名汇总行使用二进制单位KiB/MiB/GiB对比数值时注意区分快照是节点本地的listsnapshots默认只展示目标节点的快照。如需查看整个集群需在各节点上分别执行或使用cluster级别的运维流程如 备份/恢复相关文档 所述快照需复制到次级存储才能构成完整备份。小结nodetool listsnapshots是 ScyllaDB 运维中核对快照状态、评估磁盘占用的第一入口。掌握其输出中True Size与Size on Disk的语义差异即快照独占、移除后真正释放的空间与快照目录整体占用的空间是正确评估备份成本与清理收益的关键。结合 tools/scylla-nodetool.cc 的实现与 test/nodetool/test_snapshot.py 的测试断言可以确认该命令的所有输出细节包括空快照提示与Total TrueDiskSpaceUsed汇总行从而在自动化脚本中可靠地解析其结果。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考