Skip to main content
损坏或异常的 ClickHouse Keeper 快照可能导致严重的系统不稳定，例如元数据不一致、表进入只读状态、资源耗尽或备份失败。本文涵盖：

​
Keeper 快照概述

​
什么是快照？

快照是 Keeper 在某一特定时间点内部数据的序列化状态 (例如有关集群、表协调路径和配置的元数据) 。快照对于重新同步集群中的 Keeper 节点、在发生故障时恢复元数据，以及依赖已知正常 Keeper 状态的启动或重启过程都至关重要。

​
在哪里可以找到快照？

快照以文件形式存储在 Keeper 节点的本地文件系统中。默认情况下，它们位于 /var/lib/clickhouse/coordination/snapshots/；如果你在 keeper_server.xml 文件中通过 snapshot_storage_path 指定了自定义路径，则会存储在那里。快照名称按递增编号命名 (例如 snapshot.23) ，编号越大表示快照越新。 对于多节点集群，每个 Keeper 节点都有各自的快照目录。
各节点上的快照保持一致性对于恢复至关重要。

​
Keeper 损坏快照的关键症状和表现

下表列出了一些 Keeper 快照损坏的常见症状和表现： 日志指示： 在诊断快照损坏之前，请检查 Keeper 日志 中是否存在特定错误模式：

​
从损坏的 Keeper 快照中恢复

在操作任何文件之前，务必始终：
  1. 停止所有 Keeper 节点，防止进一步损坏
  2. 将整个协调目录复制到安全位置，备份所有内容
  3. 验证集群的 quorum，确保至少有一个节点保存了完好的数据

​
1. 从现有备份中恢复

如果出现以下情况，应按此流程操作：
  • Keeper 元数据或快照损坏，导致当前数据无法恢复。
  • 存在一个 Keeper 状态已知正常的备份。
按照以下步骤从现有备份中恢复：
  1. 找到最新的备份，并验证其元数据一致性。
  2. 关闭 ClickHouse 和 Keeper 服务。
  3. 用备份目录中的快照和日志替换损坏的快照和日志。
  4. 重启 Keeper 集群，并验证元数据同步是否正常。
定期备份如果备份已过期，你可能会丢失最近的元数据变更。因此，我们建议定期备份。

​
2. 回滚到较早的快照

在以下情况下，应按此流程操作：
  • 最近的快照已损坏，但较早的快照仍可使用。
  • 增量日志完好，可用于一致性恢复。
按以下步骤回滚到较早的快照：
  1. 从 Keeper 目录中找到并选择一个有效的较早快照 (例如 snapshot.19) 。
  2. 删除较新的快照和日志。
  3. 重启 Keeper，使其重放日志以重建元数据状态。
元数据不同步风险如果快照和日志缺失或不完整，可能会导致元数据不同步。

​
3. 使用 SYSTEM RESTORE REPLICA 恢复元数据

在以下情况下，应遵循此流程：
  • Keeper 元数据丢失或损坏，但表数据仍存在于磁盘上
  • 由于缺少 ZooKeeper/Keeper 元数据，表已切换为只读模式
  • 你需要根据本地可用的数据分区片段在 Keeper 中重建元数据
按照以下步骤恢复元数据：
  1. 验证表数据是否存在于本地的 clickHouse-server 数据路径中，该路径由 config 中的 <path> 配置项指定。 (默认为 /var/lib/clickhouse/data/)
  2. 对于每个受影响的表，执行：
  1. 进行数据库级恢复时 (如果使用 Replicated 数据库引擎) ：
  1. 等待同步完成：
  1. 通过检查 system.replicas 中的 is_readonly = 0 并监控 system.detached_parts，验证恢复是否成功
工作原理SYSTEM RESTORE REPLICA 会先分离所有现有 parts，在 Keeper 中重建元数据 (就像这是一个新的空表一样) ，然后再重新附加所有 parts。这样可以避免通过网络重新下载数据。
前置条件只有在本地数据分区片段完好的情况下，此方法才有效。如果数据也已损坏，请改用策略 #5 (重建集群) 。

​
4. 在 Keeper 中删除并重建副本元数据

在以下情况下，建议按此流程处理：
  • 错误仅发生在集群中的某一个副本上，且该副本在 Keeper 中的元数据已损坏或不一致
  • 你遇到类似 “Part XXXXX intersects previous part YYYYY” 的错误
  • 你需要在保留本地数据的同时，彻底重置某个副本在 Keeper 中的元数据
按照以下步骤删除并重建元数据：
  1. 在受影响的副本上，对该表执行 detach：
  1. 从 Keeper 中删除该副本的元数据 (可在任意副本上执行) ：
要找到正确的 ZooKeeper 路径：
  1. 重新附加该表 (将以只读模式附加) ：
  1. 恢复副本元数据：
  1. 与其他副本同步：
  1. 恢复后检查所有副本上的 system.detached_parts
在所有受影响的副本上执行如果损坏影响了多个副本，请在每个副本上依次重复这些步骤。
适用于整个数据库如果使用的是 Replicated 数据库，也可以改用 SYSTEM DROP REPLICA ... FROM DATABASE db_name。
替代方案：使用 force_restore_data 标志 如需在服务器启动时自动恢复所有复制表：
  1. 停止 ClickHouse server
  2. 创建恢复标志：
  1. 启动 ClickHouse server
  2. 服务器会自动删除该标志，并恢复所有复制表
  3. 监控日志，查看恢复进度
当多个表需要同时恢复时，这种方法很有用。

​
5. 重建 Keeper 集群

在以下情况下，应按此流程操作：
  • 没有可用于恢复的有效快照、日志或备份。
  • 需要重建整个 Keeper 集群及其元数据。
按照以下步骤重建 Keeper 集群：
  1. 完全停止 ClickHouse 和 Keeper 集群。
  2. 清理快照和日志目录，以重置每个 Keeper 节点。
  3. 将一个 Keeper 节点初始化为 leader，然后逐步添加其他节点。
  4. 如果外部记录中有可用信息，请重新导入元数据。
耗时较长的流程此流程非常耗时，并且存在长时间中断的风险。需要重建全部数据。
最后修改于 2026年7月23日