ClickHouse报错schema文件中找不到指定proto消息如何解决

问题根因 #

• ClickHouse对Protobuf格式schema的缓存分为两类，且均为节点本地存储，和Kafka引擎表的删除、重建操作没有绑定关系：
  • 进程内存级缓存：首次加载proto文件后，会把解析出的descriptor存在进程内存中，不会因为同名表删除重建自动失效
  • 磁盘临时缓存：首次解析proto时生成的编译后临时文件，会落盘存储在临时目录，后续加载同路径/同标识的schema时会优先读取缓存
• 你遇到的两类异常对应触发逻辑：
  1. 重建同名Kafka表无法识别新proto路径：内存中仍持有旧表绑定的旧proto路径缓存，不会主动扫描新目录
  2. 新命名Kafka表报Not found a message named 'MyMessage'：要么是新proto文件本身配置/权限/依赖有问题，要么是旧缓存优先级高于新文件读取，没有加载到新proto的实际内容

具体解决步骤 #

该问题需要清理对应缓存，按节点滚动操作即可，不需要全量重启集群

1. 前置校验新proto文件合法性
   • 确认新目录下的test/my_message.proto中确实存在名为MyMessage的顶层message定义，注意Protobuf的message名大小写敏感，必须和建表语句中protobuf_message_name参数声明的值完全一致
   • 确认ClickHouse进程运行用户对新proto存放目录有可读+可执行权限，对目录下所有proto文件有可读权限
   • 如果proto文件使用import语句引入了其他proto定义，确认所有依赖文件都按相对路径存放在新目录的对应位置，依赖缺失会导致proto解析失败，抛出找不到目标message的报错
2. 清理Protobuf缓存
   • 清理内存缓存：在对应节点执行如下SQL，直接清空Protobuf格式的内存缓存，不需要重启服务：

     SYSTEM DROP FORMAT SCHEMA CACHE FOR Protobuf;
     

   • 清理磁盘缓存：默认缓存路径为/var/lib/clickhouse/tmp/format_schemas/，如果自定义过config.xml中的tmp_path配置，就到对应配置的临时目录下找format_schemas子目录，删除目录下所有和目标proto文件名相关的缓存文件即可。操作前先暂停目标Kafka表的消费线程，避免操作过程中读写冲突：

     -- 卸载目标Kafka表，停止后台消费线程
     DETACH TABLE <你的Kafka引擎表完整表名>;
     -- 手动删除磁盘缓存文件后，重新挂表恢复消费
     ATTACH TABLE <你的Kafka引擎表完整表名>;
     

3. 双节点集群操作注意
   • 上述校验、清缓存、挂表操作需要在两个节点分别执行，Protobuf缓存是节点本地独立维护的，单节点操作不会同步到其他节点
   • 确保两个节点上存放的新版proto文件内容、路径完全一致，避免节点间schema不统一导致消费数据异常

后续维护避坑 #

• 后续更新Kafka表使用的proto schema时，不需要删表重建，直接替换原路径下的proto文件、清空Protobuf格式缓存、重启对应表消费即可生效
• 不要用不同目录存放不同版本的同名proto文件绑定同名表，只要proto路径、message定义有变更，先清空格式缓存再做表配置调整，避免旧缓存干扰加载逻辑

内容的提问来源于stack exchange，提问作者ArefehTam