Kafka Connect集群加载自定义连接器插件后未出现在插件列表问题咨询

常见原因 #

• 插件扫描路径配置错误：Kafka Connect通过plugin.path配置项指定扫描连接器的目录，Confluent官方镜像默认值通常为/usr/share/java,/usr/share/confluent-hub-components，如果自定义jar包挂载的目录不在该配置范围内，服务不会扫描加载。
• Jar包未配置SPI发现规则：Kafka Connect基于SPI机制识别连接器，要求jar包中必须包含META-INF/services/org.apache.kafka.connect.connector.Connector文件，且文件内写入自定义连接器的全限定类名，缺少该配置则无法被识别。
• Jar包缺少依赖或结构异常：你构建的jar包不是包含所有依赖的fat jar（uber jar），或者打包时遗漏了连接器核心类文件，都会导致加载失败。
• 文件权限不足：Docker容器中运行Kafka Connect的用户（默认通常为UID 1000的confluent用户）没有挂载的jar包的读取权限，扫描时会直接跳过该文件。
• 版本不兼容或依赖冲突：从你返回的插件列表可知当前集群版本为5.5.0，对应Kafka版本为2.5.x，如果自定义连接器依赖的kafka-connect-api版本和集群版本不一致，会出现类加载异常，导致连接器被过滤。
• 挂载路径不符合规范：部分Kafka Connect镜像要求每个连接器单独存放在plugin.path下的独立子目录中，直接将jar包放在plugin.path根目录可能不会被识别。

排查步骤 #

1. 进入运行中的Kafka Connect容器，执行echo $CONNECT_PLUGIN_PATH查看实际生效的扫描路径，确认jar包所在目录在该路径范围内，同时执行ls -l <jar包路径>检查文件权限，确认容器运行用户有读取权限。
2. 执行jar tf <你的jar包名称>检查jar包结构，确认两个点：一是存在自定义连接器全限定类名对应的class文件，二是存在SPI配置文件META-INF/services/org.apache.kafka.connect.connector.Connector，且文件内容和连接器全类名一致。
3. 查看Kafka Connect启动日志，搜索自定义连接器类名或ERROR/WARN级别的日志，确认是否存在类加载失败、依赖缺失等报错信息。
4. 检查连接器pom.xml中kafka-connect-api的依赖版本，调整为和集群匹配的2.5.x版本，同时确认打包配置已引入maven-shade-plugin或maven-assembly-plugin，重新打fat jar后重启服务验证。

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