altinity-expert-clickhouse-replication

复制与 Keeper 健康状况

通过 system.zookeeper_connection、system.replicas、system.replication_queue、system.replicated_fetches、system.events 和 system.text_log 回答“副本是否已连接、保持同步，并正在清空队列？” 如果尚未确定连接模式、集群和时间范围，请先运行 altinity-expert-clickhouse-connection。

查询包

• triage.sql — 2 项检查：每台主机的 Keeper/ZooKeeper 会话状态（replication-triage-01，@requires keeper），以及来自 system.replicas 的分级复制概览（replication-triage-02）。从这里开始。
• queue.sql — 2 项检查：按表和主机分级的队列大小（replication-queue-01），以及带有异常或延后原因的各个队列任务（replication-queue-02）。
• fetches.sql — 2 项检查：正在进行的抓取及其已耗时长和进度（replication-fetches-01），以及近期的 DownloadPart 活动（replication-fetches-02，需要 system.part_log）。
• keeper.sql — 2 项检查：根据 ZooKeeperWaitMicroseconds 与 ZooKeeperTransactions 计算的每台主机平均 Keeper 往返延迟（replication-keeper-01），以及过去 24 小时内的 Keeper 错误和警告（replication-keeper-02，需要 system.text_log）。

如何运行查询包

1. 从此技能的目录中读取每个查询包文件（技能加载器会打印目录路径）。
2. 每次运行一条语句，切勿运行整个文件。语句以 ; 结尾，并以 -- @check <id> <title> 标头开头；将 id 与结果一并保留。
3. 遵循 -- @requires：如果指定的表不存在、要求 keeper 但服务器没有 Keeper/ZooKeeper，或不满足版本条件，则跳过该语句。列出已跳过的 id 及原因。
4. 如果存在集群宏，按原样保留 {cluster}；否则应用连接技能中的重写规则。任何其他 {placeholder} 都是模板变量：请先替换为实际值，否则跳过该语句。
5. 出错时，记录检查 id 和错误的第一行，然后继续。仅当错误为 UNKNOWN_IDENTIFIER 时，运行 DESCRIBE TABLE system.<table> 并删除缺失的列。
6. severity 列是该行的判定结果。照原样复制，不要重新评级。

解释规则

• 如果连接技能报告 has_keeper = 0，则整个技能不适用。说明这一点并停止：没有 Keeper，就没有要诊断的复制表。
• is_readonly = 1 或 is_session_expired = 1 属于严重问题。副本已丢失 Keeper 会话，无法接受写入。先检查 Keeper 连通性，然后检查磁盘空间，最后查看服务器日志。
• active_replicas < total_replicas 表示有副本已在 Keeper 中注册，但当前未运行。指出缺失的主机，并检查是否发生重启、网络分区或服务器已停止。
• 延迟等级根据 SQL 结果判定：absolute_delay 超过 300 秒或 queue_size 超过 200 为中等；超过 3600 秒或超过 1000 个条目为严重。并列引用这两个数值，因为队列很大但没有延迟，表示副本正在追赶进度；延迟很大但队列为空，则表示副本没有收到任务。
• last_exception 或 postpone_reason 非空的队列条目可指出卡住的表和任务类型。根据 type 确定处理方向：GET_PART 表示抓取，MERGE_PARTS 表示合并，MUTATE_PART 表示变更。
• 如果 num_tries 或 num_postponed 较高，且 last_exception_time 较近，说明任务仍在重试。如果这些数值相同，但异常时间较早，则表示问题已经恢复。
• 大量长时间运行的抓取任务，或部件日志中反复出现的 DownloadPart 错误，本身就是延迟的原因，而非症状。调整复制设置前，先检查网络吞吐量和源副本。
• replication-keeper-01 中的 avg_latency_us 升高与延迟和只读副本相关。如果所有主机的延迟同时升高，应将 Keeper 变慢视为根本原因；如果只有一台主机变慢，则应视为本地问题。
• Keeper 延迟根据服务器启动以来的累计计数器计算，因此应比较各主机之间的数值，而不是与绝对阈值比较。

报告格式

1. 标题：连接模式、集群或“单节点”、ClickHouse 版本、时间范围。
2. 发现：包含 check、severity、object、evidence、recommendation 列的表格；每项发现占一行，严重问题排在最前。Evidence 引用结果行中的数值。
3. 正常检查：用一行列出未返回问题行的检查 ID。
4. 跳过和失败的检查：列出 ID 和原因或第一行错误。此部分不得省略。
5. 后续步骤：列出接下来要加载的技能和立即采取的措施。

后续技能

• part_mutations_in_queue 较高，或队列任务因 MUTATE_PART 错误失败 → 加载技能 altinity-expert-clickhouse-mutations
• merges_in_queue 较高，或队列任务因 MERGE_PARTS 错误失败 → 加载技能 altinity-expert-clickhouse-merges
• 大量 DownloadPart 反复执行，或抓取任务反复失败，需要查看各部件的历史记录 → 加载技能 altinity-expert-clickhouse-part-log
• Keeper 错误需要完整的服务器日志上下文，或缺少 system.text_log → 加载技能 altinity-expert-clickhouse-logs
• 磁盘已满导致副本转为只读 → 加载技能 altinity-expert-clickhouse-storage
• 复制表上的插入失败或停滞 → 加载技能 altinity-expert-clickhouse-ingestion