ClickHouse 排查不能只看一条 SQL。需要同时看集群状态、表结构、写入链路和查询结果。
先确认集群状态
排查前先看：
- 实例是否正常。
- 磁盘是否充足。
- CPU 和内存是否异常。
- 副本是否同步。
- 查询是否堆积。
- 是否有写入失败。
如果基础状态异常，先处理资源和集群问题。
表结构要核对
ClickHouse 表结构影响很大。
要检查：
- 引擎类型。
- 分区字段。
- 排序键。
- 字段类型。
- 是否有本地表和分布式表。
- 是否存在物化视图。
字段类型不一致、分区设计不合理，都可能导致写入或查询问题。
写入错误要看上下游
写入失败可能来自：
- 字段缺失。
- 类型不匹配。
- 批量过大。
- 超时。
- 网络异常。
- MQ 重试。
- 数据重复。
排查时要把应用日志、MQ 状态和 ClickHouse 错误一起看。
查询验证要可复现
验证数据时不要只看页面。
最好保留：
- 查询 SQL。
- 查询时间范围。
- 过滤条件。
- 样本数据。
- 预期结果。
- 实际结果。
这样后续复盘才能知道当时验证了什么。
维护建议
ClickHouse 排查文档可以固定包含：集群状态、表结构、写入链路、查询 SQL 和最终结论。
这套结构能避免排查过程散落在聊天记录里。
正文完
