Docker部署Confluent平台SSLHandshakeException truststore问题排查

核心异常原因 #

• 环境变量命名不符合Confluent Docker镜像的解析规则
  当前使用的KAFKA_SSL_KEYSTORE_FILENAME、KAFKA_SSL_*_CREDENTIALS缩写命名，并非官方镜像支持的标准映射规则：

  Kafka原生对应truststore路径的配置为ssl.truststore.location，对应的标准环境变量为KAFKA_SSL_TRUSTSTORE_LOCATION；密码类配置若要通过文件传入，需要在完整配置对应的环境变量后追加_CREDENTIALS后缀，例如ssl.truststore.password对应的合法变量为KAFKA_SSL_TRUSTSTORE_PASSWORD_CREDENTIALS。
  缩写命名未被entrypoint识别，最终导致ssl.truststore.location、ssl.truststore.password两个配置项为null。

• 启动报错的直接诱因
  未加载truststore的SSL引擎没有可信证书根，启动时内置的SSLEngine双向可用性自检直接抛出SSL握手异常，触发Broker启动失败流程。
• 额外排查点
  需确认本地挂载目录中确实存在kafka.broker.truststore.jks文件，避免文件缺失导致后续配置修正后仍然无法加载。

排查与解决步骤 #

• 第一步：修正所有SSL相关环境变量为标准命名
  将原配置块：

  KAFKA_SSL_KEYSTORE_FILENAME: kafka.broker.keystore.jks
  KAFKA_SSL_KEYSTORE_CREDENTIALS: password.txt
  KAFKA_SSL_KEY_CREDENTIALS: password.txt
  KAFKA_SSL_TRUSTSTORE_FILENAME: kafka.broker.truststore.jks
  KAFKA_SSL_TRUSTSTORE_CREDENTIALS: password.txt
  

  替换为：

  # 直接指定证书文件的完整挂载路径
  KAFKA_SSL_KEYSTORE_LOCATION: /etc/kafka/secrets/kafka.broker.keystore.jks
  KAFKA_SSL_TRUSTSTORE_LOCATION: /etc/kafka/secrets/kafka.broker.truststore.jks
  # 用标准规则指定密码文件
  KAFKA_SSL_KEYSTORE_PASSWORD_CREDENTIALS: password.txt
  KAFKA_SSL_KEY_PASSWORD_CREDENTIALS: password.txt
  KAFKA_SSL_TRUSTSTORE_PASSWORD_CREDENTIALS: password.txt
  

• 第二步：验证容器内文件可读性
  执行命令确认所有证书文件已正确挂载且有权限读取：

  docker exec -it kafka1 ls -l /etc/kafka/secrets
  

  确保kafka.broker.keystore.jks、kafka.broker.truststore.jks、password.txt三个文件均存在，且运行用户有读取权限。
• 第三步：校验密码文件格式
  打开本地password.txt确认仅包含纯密码内容，无多余换行、空格或注释，避免entrypoint读取到无效密码。
• 第四步：清理缓存后重启服务
  执行以下命令清理旧容器残留配置后重新启动：

  docker-compose down -v
  docker-compose up -d
  

• 第五步：验证配置加载结果
  查看启动日志，确认出现以下输出即代表truststore配置已正确加载：

  ssl.truststore.location = /etc/kafka/secrets/kafka.broker.truststore.jks
  ssl.truststore.password = [hidden]
  

  随后观察启动流程，确认SSL自检通过、服务正常启动即可。

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