defrag必须在compact之后执行才能真正释放物理磁盘空间；仅compact无法缩小etcd.db文件体积，defrag通过重写数据回收被标记删除的空闲块，并需用节点实际证书验证、逐节点操作、超时保护及alarm disarm验证。
当 etcd 数据库因 MVCC 历史版本堆积导致物理磁盘空间持续增长、甚至触发 database space exceeded 告警时，必须执行 defrag 才能真正回收被标记为“删除”的空闲块——仅靠 compact 不会缩小 etcd.db 文件体积。
确认当前 etcd 状态与权限准备
先检查集群健康状态和证书路径，避免因 endpoint 不可达或证书错误导致 defrag 中断：
运行 ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/server.crt --key=/etc/kubernetes/pki/etcd/server.key endpoint health，输出应含 healthy；若报 x509: certificate signed by unknown authority，说明证书路径错误或 ca.crt 不匹配，【必须用该节点实际使用的 etcd peer 或 server 证书，不可混用 client 证书】。
这一步操作起来很简单，直接把命令复制进终端回车就行。
执行 defrag 回收物理空间
defrag 是在线操作，不影响读写服务，但会短暂升高 I/O 和 CPU 使用率；建议在业务低峰期执行，且单节点逐个操作，避免多节点并发引发集群响应抖动。
方法一：基础命令（适用于单节点、证书路径明确）
ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/server.crt --key=/etc/kubernetes/pki/etcd/server.key defrag
方法二：带超时保护（适用于数据量大、磁盘响应慢的环境）
添加 --command-timeout=300s 防止因长时间 I/O 等待被意外中断：ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/server.crt --key=/etc/kubernetes/pki/etcd/server.key --command-timeout=300s defrag
注意：defrag 必须在 compact 之后执行，否则无实际空间释放效果——compact 只是逻辑清理，defrag 才是物理重写。
验证 defrag 是否生效
第一步：查看 etcd.db 文件大小变化
执行 ls -lh /var/lib/etcd/member/snap/db（Kubernetes 默认路径）或根据 ETCD_DATA_DIR 实际值定位，对比 defrag 前后文件大小。典型场景下，5GB 的 db 文件经 defrag 后可回落至 1.8GB 左右。
第二步：检查磁盘占用是否下降
运行 df -h | grep etcd，确认挂载点可用空间增加；若未变化，说明 defrag 未成功执行或目标文件非主存储文件。
第三步：确认告警已解除（关键验证）
执行 ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/server.crt --key=/etc/kubernetes/pki/etcd/server.key alarm list，输出应为空；若仍有 NOSPACE，需立即执行 alarm disarm，否则 etcd 拒绝所有写入请求。
