clickhouse issues

❓❓❓ clickhouse 常见问题

这篇文章汇总了我在使用 ClickHouse 过程中遇到的一些常见问题与解决方案，持续更新中 🚀

🛠️ 问题：ClickHouse 报错 Cannot execute replicated DDL query, maximum retries exceeded

❓ 问题说明

当一个 复制表的 DDL 操作（如 ALTER TABLE、DROP TABLE）无法在所有副本间成功同步，并且超过重试次数时，就会出现这个报错：

Cannot execute replicated DDL query, maximum retries exceeded

---

🔍 原因

ClickHouse 使用 ZooKeeper 来协调多个副本间的 DDL 执行。

一旦有任何副本：

• 宕机、
• 状态异常（只读、失联）、
• 或处理队列阻塞、出错，

就可能导致该 DDL 操作迟迟无法完成同步，最终达到重试上限并失败。

✅ 解决

1. 查看副本状态

SELECT * FROM system.replicas WHERE table = 'your_table';

重点关注字段：

• is_session_expired 是否会话过期
• is_readonly 是否处于只读状态
• errors_count, last_error 是否有错误
• future_parts, queue_size 是否堆积任务

2. 查看副本同步队列

SELECT * FROM system.replication_queue WHERE table = 'your_table';

该表显示每个副本上的同步任务，包括 DDL、分片、数据合并等是否卡住、重试、失败等信息。

3. 重启异常副本

进入异常副本所在服务器执行：

sudo systemctl restart clickhouse-server

或在任意节点执行 SQL：

SYSTEM RESTART REPLICA your_database.your_table;

4.（可选）跳过等待，强制执行 DDL

⚠️ 谨慎使用！ 若明确当前副本异常并可后续处理同步，可强制不等待所有副本：

SET distributed_ddl_task_timeout = 0;
-- 然后执行你的 DDL 操作

这样可避免 DDL 阻塞，但副本间可能暂时不一致，后续需修复同步。

🧠 建议

• 执行 DDL 前，务必先检查 system.replicas 状态是否健康
• 避免在任意副本只读、卡顿、异常时操作 DDL
• 保持 ZooKeeper 正常、响应及时
• 建议建立监控面板，对副本延迟、队列堆积进行实时监测

---

🛠️ 问题：ClickHouse 打开的文件数过多，超过默认限制

❓ 问题说明

ClickHouse 在处理大量并发查询或大表合并时，可能会同时打开非常多的文件。一旦超过其默认的 open file limit（默认是 500000），就会导致查询失败或服务异常。

✅ 解决

提升文件打开数限制
通过修改 systemd 启动配置，增加限制。

1. 编辑 override 配置文件

sudo mkdir -p /etc/systemd/system/clickhouse-server.service.d
sudo vim /etc/systemd/system/clickhouse-server.service.d/override.conf

在文件中添加以下内容：

[Service]
TimeoutStartSec=900
TimeoutStopSec=900
TimeoutSec=900
LimitNOFILE=4194304    # ← ★ 新增：提升最大文件打开数限制

2. 重新加载配置并重启 ClickHouse

sudo systemctl daemon-reexec
sudo systemctl restart clickhouse-server

3. 验证配置是否生效

systemctl show clickhouse-server | grep NOFILE

输出：

LimitNOFILE=4194304
LimitNOFILESoft=4194304

说明文件描述符限制已被成功提升 ✅

🧠 建议

• 建议将 LimitNOFILE 设置为 高于默认值（如 1000000+），防止大规模查询或写入时出现 “too many open files” 报错
• 可配合 lsof -p $(pidof clickhouse-server) 查看实际打开文件数
• 也可以监控 /proc/<pid>/limits 中的 Max open files

---