寫 ClickHouse 的人十有八九都躲不過 ON CLUSTER 刪表這個坎。平時一條DROP TABLE IF EXISTS xxx ON CLUSTER cluster_name敲下去幾秒鐘就返回感覺比本地刪表還省心。但一旦趕上 ZooKeeper 抖動、某個副本悄悄掛了這條命令就會變成一把懸在頭上的刀——要么卡住不動要么報一堆看不懂的錯誤更麻煩的是集群里有的節(jié)點表沒了、有的節(jié)點表還在整個元數(shù)據(jù)狀態(tài)變成一鍋粥。這篇文章就把這事徹底講明白。我會從分布式 DDL 的調(diào)度原理講起沿著一次真實故障的排查鏈路走一遍最后給出幾種不同場景下的恢復(fù)手段和日常預(yù)防參數(shù)。不管你是剛接觸 ClickHouse 的初學(xué)者還是已經(jīng)被 ON CLUSTER 折磨過的運維老手這篇都能幫你省下幾個熬夜排查的晚上。1. ON CLUSTER 刪表的調(diào)度流程與依賴1.1 分布式 DDL 的調(diào)度鏈路先明確一個容易被忽略的事實ClickHouse 里的ON CLUSTER并不是直接把一條 DDL 廣播給所有節(jié)點執(zhí)行而是把這條語句當(dāng)作一個任務(wù)先寫到 ZooKeeper或者 ClickHouse Keeper下面統(tǒng)一叫 ZK的某個隊列路徑下然后由集群內(nèi)每個節(jié)點上的DistributedDDLWorker后臺線程去拉取并執(zhí)行。這條隊列路徑一般是/clickhouse/task_queue/ddl。當(dāng)你在任意一個節(jié)點執(zhí)行DROP TABLE ON CLUSTER時該節(jié)點會生成一個帶唯一標(biāo)識的 DDL 任務(wù)節(jié)點寫入這個隊列這個節(jié)點本身扮演的就是“協(xié)調(diào)發(fā)起者”的角色。其他節(jié)點上的后臺線程會發(fā)現(xiàn)隊列里有新任務(wù)于是各自把它拉下來在本機執(zhí)行對應(yīng)的 SQL。這里有個關(guān)鍵點雖然語句是在一個節(jié)點上發(fā)起的但任務(wù)對所有節(jié)點是公平可見的。只要 ZK 正常、節(jié)點和 ZK 之間的會話沒斷理論上所有存活節(jié)點都會各自執(zhí)行一次刪表操作。這個機制的好處是天然并發(fā)壞處是——只要有一個節(jié)點和 ZK 會話出問題它就不會執(zhí)行這個任務(wù)于是整個環(huán)境就變得不一致。1.2 本地副本刪除時依賴哪些 ZK 路徑DROP TABLE在語義上分成兩步。第一步是從元數(shù)據(jù)里把表定義干掉第二步是刪掉本地數(shù)據(jù)目錄里的物理文件。如果是ReplicatedMergeTree系列的表引擎還會涉及和 ZK 的交互因為副本注冊信息是存在 ZK 里的。具體涉及的關(guān)鍵路徑大致有/clickhouse/tables/{shard}/{uuid}或舊版本里的/clickhouse/tables/{database}/{table}存放的是表級別的副本注冊信息包括每個副本的元數(shù)據(jù)版本、日志指針、活躍狀態(tài)等。/clickhouse/task_queue/ddl就是前面說的分布式 DDL 任務(wù)的隊列目錄。/clickhouse/session節(jié)點與 ZK 建立會話的臨時節(jié)點路徑會話過期的話這個路徑下會有殘留也會影響副本狀態(tài)判定。一個 ReplicatedMergeTree 表在刪表時會先從 ZK 里刪除自己這個副本對應(yīng)的注冊節(jié)點然后清理本地的 metadata 文件、WAL、數(shù)據(jù)目錄等。如果這些步驟中任何一環(huán)在 ZK 會話層面失敗那么本地文件可能刪了一半ZK 里的注冊信息也可能還在那一半的狀態(tài)就非常難受。1.3 DDL 任務(wù)超時與返回機制distributed_ddl_task_timeout這個參數(shù)控制的是發(fā)起點等待集群內(nèi)其他節(jié)點執(zhí)行 DDL 任務(wù)的超時時間。默認(rèn)值是 180 秒。這個參數(shù)不是“只要超時就失敗”而是超時后發(fā)起點會主動放棄等待只返回當(dāng)前已經(jīng)收到響應(yīng)的節(jié)點列表。新版本里還有一個distributed_ddl_output_mode參數(shù)用來控制返回結(jié)果的展示方式。比如none表示不等待響應(yīng)直接返回throw表示只要有一個節(jié)點報錯就拋出異常。實際使用中很多人會遇到“命令執(zhí)行了但是報錯說某節(jié)點沒響應(yīng)”這大概率就是這個超時機制在起作用——任務(wù)還在 ZK 隊列里沒被執(zhí)行但發(fā)起點已經(jīng)不想等了。理解了這條鏈路下面看故障現(xiàn)象就清楚多了。大概率不是 SQL 語法的問題而是這個分布式調(diào)度鏈路里某個環(huán)節(jié)斷了。2. 故障現(xiàn)象與根因庫2.1 常見的故障表現(xiàn)分類根據(jù)我遇到過的情況DROP TABLE ON CLUSTER的故障大致能分成三類。第一類是卡住不動。命令敲下去之后一直不返回既不報錯也不成功。這種一般有兩種可能要么發(fā)起點連不上 ZK要么 ZK 里的 DDL 隊列任務(wù)在等待某個不可用節(jié)點的響應(yīng)而那個節(jié)點已經(jīng)聯(lián)系不上了。第二類是直接報錯錯誤信息五花八門。最常見的有Code: 342. DB::Exception: The replica is not active、All replicas are lost、Cannot drop table because it is in readonly state等等。這些錯誤翻譯成人話就是這個表有副本但是副本的 ZK 會話已經(jīng)斷了或者副本自己都覺得自己已經(jīng)不健康了。第三類最隱蔽命令返回成功但集群狀態(tài)不對。有的節(jié)點表刪了有的節(jié)點表還在甚至有的節(jié)點上的表變成了只讀狀態(tài)。這種問題最坑的地方在于你以為刪完了實際上某個分片的數(shù)據(jù)還在磁盤上占著空間后續(xù)重新建表還可能因為元數(shù)據(jù)殘留而失敗。2.2 根因庫速查表結(jié)合實踐經(jīng)驗我把常見的根因整理成一個速查表排查的時候可以先對照一下。故障現(xiàn)象核心根因關(guān)鍵排查點命令卡住不返回ZK 會話異?；蛘吣硞€節(jié)點失聯(lián)system.replicas、ZK 節(jié)點狀態(tài)報 replica is not active某個副本的 ZK 會話過期system.replicas.is_active字段部分節(jié)點成功部分失敗失敗節(jié)點當(dāng)時和 ZK 斷連DDL 隊列殘留任務(wù)表變成 readonly元數(shù)據(jù)和 ZK 狀態(tài)不一致system.replicas的 readonly 字段重新建表失敗本地 metadata 殘留檢查 metadata 目錄一直顯示 deleted 狀態(tài)DDL 任務(wù)已標(biāo)記刪除但未清理ZK 任務(wù)隊列殘留2.3 為什么不同節(jié)點狀態(tài)會不一致ClickHouse 的集群一致性并不是“強同步”的它依賴 ZK 這個外部協(xié)調(diào)者來達(dá)成最終一致。每個節(jié)點都有自己的本地元數(shù)據(jù)ZK 里存的是集群維度的公共狀態(tài)。兩者之間靠會話和心跳維持同步。當(dāng)某個節(jié)點的 ZK 會話超時后這個節(jié)點上的副本會被標(biāo)記為readonly它不再接收寫入也不再參與副本同步。但它本地的元數(shù)據(jù)文件并不會自動消失。這個時候你發(fā)起一個DROP TABLE ON CLUSTER健康節(jié)點正常執(zhí)行刪除但這個斷連節(jié)點不響應(yīng) DDL 任務(wù)于是整個集群的元數(shù)據(jù)就不一致了。更麻煩的是如果這個會話長期沒有恢復(fù)ZK 里的副本注冊信息也會變成失聯(lián)狀態(tài)。此時即使你手動在這個節(jié)點上執(zhí)行本地DROP TABLE也會因為 ZK 狀態(tài)校驗不過而報錯。這就是為什么很多人最后只能選擇停掉節(jié)點手動清理元數(shù)據(jù)文件才能恢復(fù)。3. 完整排查實錄從故障到定位3.1 一次典型的 Drop On Cluster 卡住故障之前一個業(yè)務(wù)團隊遇到的情況非常有代表性。某天他們在例行清理過期分區(qū)時執(zhí)行了一條DROP TABLE IF EXISTS ods_order_temp ON CLUSTER cluster_01;命令敲下去之后終端直接卡住CtrlC 都救不回來。過了好幾分鐘才返回了一個類似這樣的報錯Received exception from server (Version 23.8.1): Code: 159. DB::Exception: Timeout exceeded while waiting for the DDL task to be executed on servers.這個報錯翻譯過來就是發(fā)起節(jié)點已經(jīng)把 DDL 任務(wù)寫進 ZK 了也等了一段時間但有一些服務(wù)器沒有在超時時間內(nèi)確認(rèn)執(zhí)行完成。當(dāng)時我第一反應(yīng)是去看system.replicas因為刪表卡住的本質(zhì)往往是副本狀態(tài)不健康而不是 SQL 本身的問題。SELECT database, table, is_readonly, is_session_expired, zookeeper_exception, replica_is_active FROM system.replicas WHERE database default;結(jié)果非常直觀其中某個分片的一塊副本is_session_expired 1replica_is_active 0。也就是說這個副本和 ZK 之間的會話已經(jīng)過期了它完全不知道自己應(yīng)該執(zhí)行什么任務(wù)。3.2 順著 DDL 隊列查無用功確認(rèn)副本不健康之后還需要確認(rèn) DDL 任務(wù)本身的狀態(tài)。ClickHouse 在較新版本里提供了一個內(nèi)部表system.distributed_ddl_queue可以直接查到 DDL 任務(wù)的執(zhí)行情況。SELECT query, host, status, create_time, cluster FROM system.distributed_ddl_queue ORDER BY create_time DESC LIMIT 10;從結(jié)果里能看到這條DROP TABLE任務(wù)的狀態(tài)是in_process也就是還在等待中。而正常執(zhí)行完的任務(wù)狀態(tài)應(yīng)該是finished。另外一步值得做的操作是去 ZK 里直接看 DDL 任務(wù)隊列目錄。ClickHouse 提供了system.zookeeper表可以像查普通表一樣查詢 ZK 節(jié)點內(nèi)容SELECT name, value, num_children FROM system.zookeeper WHERE path /clickhouse/task_queue/ddl LIMIT 20;這里能看到所有待執(zhí)行的 DDL 任務(wù)節(jié)點。正常來說這個目錄應(yīng)該是空的或者只有極少數(shù)正在執(zhí)行的任務(wù)。如果你發(fā)現(xiàn)里面堆積了大量歷史任務(wù)說明之前有多次刪表/建表操作失敗過殘留的任務(wù)一直沒被清理。3.3 定位到問題副本并驗證確認(rèn)問題副本后下一步要判斷這個副本還有沒有救。當(dāng)時我直接在一個健康的副本上執(zhí)行SYSTEM SYNC REPLICA ods_order_temp ON CLUSTER cluster_01;結(jié)果也是超時說明不只是當(dāng)前 DDL 卡住而是這個分片內(nèi)部的副本同步鏈路已經(jīng)斷了。再回頭看system.replicas里的zookeeper_exception字段里面會出現(xiàn)類似這樣的報錯All connection attempts to ZooKeeper failed這個字段是排查 ZK 會話類問題的金鑰匙。一旦出現(xiàn)這個值基本可以斷定該節(jié)點和 ZK 之間的網(wǎng)絡(luò)鏈路或者 ZK 自身的會話管理出了狀況。這個時候如果你不死心想直接在問題節(jié)點上執(zhí)行本地刪表DROP TABLE IF EXISTS default.ods_order_temp;大概率也會報錯。因為在 ZK 的副本注冊信息里當(dāng)前節(jié)點可能已經(jīng)不是 active 狀態(tài)了本地刪表操作過不了校驗。3.4 復(fù)盤當(dāng)時為什么沒更早發(fā)現(xiàn)這個案例到最后雖然救回來了但復(fù)盤時發(fā)現(xiàn)一個很明顯的問題這個不健康的副本其實已經(jīng)異常存在了一段時間如果平時有巡檢system.replicas的習(xí)慣早就應(yīng)該看到is_readonly 1或者zookeeper_exception不為空。但因為這個表平時讀取壓力不大業(yè)務(wù)側(cè)也沒發(fā)現(xiàn)異常直到刪表時才踩中。所以我現(xiàn)在做任何 ON CLUSTER 操作之前都會先看一眼集群整體副本健康度。與其等 DDL 卡住再去救不如在動手前就把不健康的副本排除掉。這個習(xí)慣幫我避了好幾次坑。4. 分場景恢復(fù)方案與強制清理4.1 場景一單副本會話過期表本身可以重建如果只是會話過期且表的數(shù)據(jù)已經(jīng)不是很重要最簡單的方式是先把不健康的副本清理掉。ClickHouse 提供了SYSTEM DROP REPLICA之類的命令可以刪除本地這副本在 ZK 里的注冊信息。SYSTEM DROP REPLICA replica_name FROM TABLE default.ods_order_temp;這個命令的作用是告訴 ZK這個副本我放棄了請移除它的注冊信息。之后再回到這個節(jié)點上執(zhí)行普通建表語句讓副本重新拉取元數(shù)據(jù)。注意一個細(xì)節(jié)replica_name不是隨便填的它是該節(jié)點配置的macros里的replica值。可以用這條 SQL 查到SELECT * FROM system.macros;確認(rèn)replica的取值后再執(zhí)行SYSTEM DROP REPLICA。4.2 場景二表數(shù)據(jù)不重要直接走強制清理如果表已經(jīng)沒有任何保留價值也沒必要費勁修復(fù)副本直接走強制清理流程。步驟一把所有節(jié)點的 ClickHouse 進程停掉。這一步是為了避免在清理過程中有后臺線程悄悄改 ZK 或本地元數(shù)據(jù)。步驟二找到 ClickHouse 的數(shù)據(jù)目錄默認(rèn)是/var/lib/clickhouse在metadata/目錄下找到對應(yīng)的數(shù)據(jù)庫文件。比如default庫的元數(shù)據(jù)路徑是/var/lib/clickhouse/metadata/default.sql。打開這個文件搜到ods_order_temp這張表對應(yīng)的CREATE TABLE語句手動刪掉。步驟三在metadata/{database}/目錄下可能會有該表的獨立元數(shù)據(jù)文件一并刪掉。同時檢查data/{database}/目錄下有沒有對應(yīng)的物理數(shù)據(jù)目錄有的話也一起刪除。步驟四再去看 ZK 里該表對應(yīng)的路徑是否還有殘留。用之前的system.zookeeper查詢方式先找SELECT * FROM system.zookeeper WHERE path /clickhouse/tables;找到對應(yīng)表路徑后確認(rèn)沒有其他副本還在使用的情況下可以直接刪掉這個 ZK 節(jié)點。不過這一步要非常謹(jǐn)慎最好在確認(rèn)所有節(jié)點都已經(jīng)停掉之后再操作否則容易引發(fā)其他副本的狀態(tài)混亂。4.3 場景三DDL 隊列殘留導(dǎo)致新 DDL 永遠(yuǎn)卡住還有一種情況某次 DDL 超時后那個任務(wù)節(jié)點一直殘留在 ZK 的 DDL 隊列里導(dǎo)致后續(xù)所有 ON CLUSTER 操作都要排隊甚至直接卡住。這種問題的解法相對簡單直接清掉這個殘留任務(wù)節(jié)點。查詢/clickhouse/task_queue/ddl找到那個查詢對應(yīng)的節(jié)點名稱在 ZK 客戶端里刪除它就行。用 clickhouse-client 操作的話需要借助system.zookeeper找到精確路徑然后調(diào)用zookeeper刪除接口。較新版本里 ClickHouse 提供了一個zk命令可以直接操作clickhouse-keeper-client --connection-stringlocalhost:9181進入客戶端后執(zhí)行rmdir /clickhouse/task_queue/ddl/ddl_query_id_xxx但說實話我一般不太推薦在生產(chǎn)環(huán)境直接對著 ZK 目錄刪東西。更穩(wěn)的方式是確認(rèn) DDL 任務(wù)確實已經(jīng)沒用了再重啟下出問題的節(jié)點。ClickHouse 啟動時如果發(fā)現(xiàn) DDL 隊列里有尚未完成的任務(wù)會嘗試重新執(zhí)行或標(biāo)記失敗并清理。多數(shù)情況下重啟節(jié)點就能把臟隊列帶出來。4.4 場景四表已經(jīng)只讀但還有歷史數(shù)據(jù)要保留如果表里還有需要保留的數(shù)據(jù)不能直接丟棄那就得先想辦法恢復(fù)副本的讀寫狀態(tài)。第一步先排查 ZK 鏈路看看zookeeper_exception是否已經(jīng)恢復(fù)。如果 ZK 連接恢復(fù)了直接在只讀副本上執(zhí)行SYSTEM RESTORE REPLICA;這個命令會嘗試用本地的元數(shù)據(jù)狀態(tài)去和 ZK 里的信息對齊重建會話狀態(tài)。執(zhí)行完后再看system.replicas如果is_readonly變成 0說明副本恢復(fù)了。如果執(zhí)行SYSTEM RESTORE REPLICA失敗或者報錯說 ZK 路徑不存在那說明 ZK 里的表注冊信息已經(jīng)被清理過了。這種情況想保留數(shù)據(jù)只能先停掉節(jié)點然后把本地的data目錄復(fù)制出來再重新建表導(dǎo)入數(shù)據(jù)。5. 參數(shù)調(diào)優(yōu)與日常預(yù)防建議5.1 調(diào)整 DDL 超時與輸出模式經(jīng)驗不足的時候很多人會直接把distributed_ddl_task_timeout調(diào)大覺得等久一點總能成功。實際上這個策略是錯的調(diào)大超時只是讓卡住的時間更長并不能解決問題本身。我的建議是把這個值調(diào)到一個“可接受的等待上限”比如 60 秒。同時把distributed_ddl_output_mode設(shè)置為throw這樣只要集群內(nèi)有節(jié)點反饋執(zhí)行異常發(fā)起點會第一時間把錯誤拋出來而不是默默等超時。profile distributed_ddl_task_timeout60/distributed_ddl_task_timeout distributed_ddl_output_modethrow/distributed_ddl_output_mode /profile這樣設(shè)置之后刪表操作如果遇到問題會很快暴露出來而不是卡到地老天荒。5.2 刪表前的副本健康檢查三件套在我自己的運維習(xí)慣里只要涉及 ON CLUSTER 的寫操作尤其是刪表這種破壞性操作動手前必須先過三關(guān)。第一關(guān)看system.replicas確認(rèn)所有相關(guān)表的副本都處于 active 狀態(tài)。SELECT database, table, count() AS total_replicas, sum(replica_is_active) AS active_replicas FROM system.replicas GROUP BY database, table HAVING total_replicas ! active_replicas;這條 SQL 會直接把有非活躍副本的表列出來。只要結(jié)果是空的說明副本層面是健康的。第二關(guān)看 ZK 的 DDL 隊列是否干凈。SELECT count() FROM system.zookeeper WHERE path /clickhouse/task_queue/ddl;這個數(shù)量最好常年為 0偶爾有 1 到 2 個正在執(zhí)行中的任務(wù)也正常。如果積壓了幾十個就先排查歷史故障原因。第三關(guān)確認(rèn) ZK 本身狀態(tài)正常。如果用的是 ZooKeeper 集群直接看監(jiān)控里的節(jié)點連接數(shù)、延遲、leader 狀態(tài)。如果用的是 ClickHouse Keeper可以用內(nèi)置的system.keeper相關(guān)表檢查。5.3 監(jiān)控與告警在故障之前接住它其實大部分 DROP TABLE ON CLUSTER 故障都是可以提前發(fā)現(xiàn)的。關(guān)鍵在于監(jiān)控里有沒有盯住下面幾個指標(biāo)監(jiān)控指標(biāo)推薦監(jiān)控內(nèi)容閾值建議副本活躍度replica_is_active為 0 的副本數(shù)持續(xù) 0ZK 連接狀態(tài)zookeeper_exception非空次數(shù)持續(xù) 0DDL 隊列積壓/clickhouse/task_queue/ddl子節(jié)點數(shù)超過 5 告警只讀表數(shù)量is_readonly為 1 的表數(shù)量持續(xù) 0這些指標(biāo)在 ClickHouse 的 prometheus 導(dǎo)出接口里基本都有暴露接入 Grafana 就能做成監(jiān)控大盤。比起事后救火提前盯住這幾個指標(biāo)能避免絕大多數(shù)麻煩。5.4 規(guī)避性的運維規(guī)范建議最后說幾條我在實際生產(chǎn)環(huán)境里總結(jié)出來的運維規(guī)范每條都踩過坑寫出來給大家避雷。第一個規(guī)范生產(chǎn)環(huán)境禁止直接對 ON CLUSTER 的 DROP 操作不加思考地執(zhí)行。尤其是大表先確認(rèn)這張表是否有下游依賴是否有備份是否真的不需要了?？梢杂肧HOW CREATE TABLE看一下表的引擎類型和集群定義心里先有個底。第二個規(guī)范執(zhí)行刪除前先備份元數(shù)據(jù)。最簡單的辦法是先執(zhí)行一次SHOW CREATE TABLE把結(jié)果保存到本地。萬一刪表過程中元數(shù)據(jù)殘留導(dǎo)致建表失敗有這條語句就能快速手工重建。第三個規(guī)范ZooKeeper 或 ClickHouse Keeper 的會話超時相關(guān)參數(shù)不要隨便改。調(diào)大了會導(dǎo)致副本故障發(fā)現(xiàn)變慢調(diào)小了又會造成誤判。默認(rèn)值通常是合理的除非你有充分的理由否則不要動它。第四個規(guī)范千萬不要在集群內(nèi)單個節(jié)點上直接執(zhí)行不帶 ON CLUSTER 的DROP TABLE。這在 ReplicatedMergeTree 表上往往不會成功就算僥幸成功也會立刻被其他副本把元數(shù)據(jù)同步回來造成狀態(tài)混亂。最后再分享一個實操小技巧如果你發(fā)現(xiàn)某個 ON CLUSTER 語句卡住了但又不確定到底卡在哪個節(jié)點上可以在執(zhí)行新語句之前先手動清理一下本地 DDL 隊列里的歷史任務(wù)。SYSTEM FLUSH DISTRIBUTED DDL;這命令會把本地已經(jīng)完成但還沒上報的 DDL 任務(wù)狀態(tài)刷新到 ZK能讓后續(xù)狀態(tài)查詢更準(zhǔn)確。雖然它不能直接解決卡住的問題但能讓你的排查視野更干凈。我個人的體感是ClickHouse 的 ON CLUSTER 機制本身設(shè)計得并不復(fù)雜真正復(fù)雜的是它依賴的外部協(xié)作者——ZK。大部分故障都不是 ClickHouse 自身壞了而是它和 ZK 之間的關(guān)系出了問題。所以下次再遇到 Drop Table On Cluster 的故障先別急著懷疑 SQL 寫錯了靜下心來查一查副本狀態(tài)和 ZK 隊列答案往往就在那里。