通过Spark Connect运行Notebook连接Kafka失败求助

核心原因 #

这个错误本质是Spark集群的所有节点（Master、Worker、Spark Connect服务端）缺少Spark Kafka连接器依赖包。基础Spark操作正常说明核心运行环境没问题，但Kafka作为外部数据源，需要额外的专属连接器JAR才能被Spark识别。

具体解决步骤 #

1. 匹配Spark与Kafka连接器版本 #

必须使用与你的Spark主版本完全匹配的Kafka连接器，同时注意Scala版本对应（比如Spark基于Scala 2.12编译，连接器也要选对应Scala版本的包）。例如：

• Spark 3.5.x → org.apache.spark:spark-sql-kafka-0-10_2.12:3.5.0
• Spark 3.4.x → org.apache.spark:spark-sql-kafka-0-10_2.12:3.4.1
  下载完整的连接器JAR包，以及其依赖的kafka-clients、spark-token-provider-kafka-0-10等相关JAR。

2. 在Docker Compose中给所有Spark服务添加依赖 #

因为你用Docker Compose部署集群，需要确保每个Spark容器（Master、Worker、Spark Connect）都能访问到连接器JAR，有两种方式：

方式一：自定义Spark镜像（推荐，避免挂载路径问题）

创建Dockerfile基于你当前使用的Spark镜像（比如bitnami/spark），将连接器JAR复制到容器的$SPARK_HOME/jars目录：

FROM bitnami/spark:3.5.0
COPY spark-sql-kafka-0-10_2.12-3.5.0.jar /opt/bitnami/spark/jars/
COPY kafka-clients-3.4.0.jar /opt/bitnami/spark/jars/
COPY spark-token-provider-kafka-0-10_2.12-3.5.0.jar /opt/bitnami/spark/jars/

然后在docker-compose.yml中使用自定义镜像替代原Spark镜像。

方式二：本地挂载JAR到容器

在docker-compose.yml中，给spark-master、spark-worker、spark-connect服务添加卷挂载配置，将本地下载的JAR挂载到容器的$SPARK_HOME/jars目录：

services:
  spark-master:
    image: bitnami/spark:3.5.0
    volumes:
      - ./spark-defaults.conf:/opt/bitnami/spark/conf/spark-defaults.conf
      - ./spark-sql-kafka-0-10_2.12-3.5.0.jar:/opt/bitnami/spark/jars/spark-sql-kafka-0-10_2.12-3.5.0.jar
      - ./kafka-clients-3.4.0.jar:/opt/bitnami/spark/jars/kafka-clients-3.4.0.jar
      - ./spark-token-provider-kafka-0-10_2.12-3.5.0.jar:/opt/bitnami/spark/jars/spark-token-provider-kafka-0-10_2.12-3.5.0.jar
    # 其他配置...
  spark-worker:
    image: bitnami/spark:3.5.0
    volumes:
      - ./spark-defaults.conf:/opt/bitnami/spark/conf/spark-defaults.conf
      - ./spark-sql-kafka-0-10_2.12-3.5.0.jar:/opt/bitnami/spark/jars/spark-sql-kafka-0-10_2.12-3.5.0.jar
      - ./kafka-clients-3.4.0.jar:/opt/bitnami/spark/jars/kafka-clients-3.4.0.jar
      - ./spark-token-provider-kafka-0-10_2.12-3.5.0.jar:/opt/bitnami/spark/jars/spark-token-provider-kafka-0-10_2.12-3.5.0.jar
    # 其他配置...
  spark-connect:
    image: bitnami/spark:3.5.0
    volumes:
      - ./spark-defaults.conf:/opt/bitnami/spark/conf/spark-defaults.conf
      - ./spark-sql-kafka-0-10_2.12-3.5.0.jar:/opt/bitnami/spark/jars/spark-sql-kafka-0-10_2.12-3.5.0.jar
      - ./kafka-clients-3.4.0.jar:/opt/bitnami/spark/jars/kafka-clients-3.4.0.jar
      - ./spark-token-provider-kafka-0-10_2.12-3.5.0.jar:/opt/bitnami/spark/jars/spark-token-provider-kafka-0-10_2.12-3.5.0.jar
    # 其他配置...

3. 检查spark-defaults.conf配置 #

确保配置文件中没有错误覆盖依赖加载路径：

• 如果已经将JAR挂载到$SPARK_HOME/jars，无需额外配置spark.jars或spark.executor.extraClassPath，Spark会自动扫描该目录。
• 如果手动指定依赖路径，要确保路径在所有节点都可访问（比如使用共享存储卷）。

4. 重启所有Spark服务 #

修改配置或镜像后，执行以下命令重启集群：

docker-compose down
docker-compose up -d

5. 验证修复效果 #

在Jupyter Notebook中运行简单的Kafka读取测试代码：

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .appName("KafkaTest") \
    .getOrCreate()

# 读取Kafka主题测试
df = spark.readStream \
    .format("kafka") \
    .option("kafka.bootstrap.servers", "kafka:9092") \
    .option("subscribe", "test-topic") \
    .load()

df.printSchema()

如果能正常打印Schema，说明问题已解决。

常见避坑点 #

• 不要只给Spark Master添加依赖：Spark任务实际在Worker节点执行，Worker必须有连接器JAR。
• 不要忽略Spark Connect服务端：Spark Connect客户端的请求由服务端执行，服务端同样需要依赖包。
• 严格匹配版本：Spark与连接器版本不匹配会导致兼容性错误，甚至同样触发数据源找不到的异常。

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