如何排查MySQL认证插件auth_token加载失败问题

问题背景 #

我正在开发一款MySQL认证插件，参考官方文档创建源文件后，在CMakeLists.txt中做了如下注册：

MYSQL_ADD_PLUGIN(
  auth_token
  auth_token.cc 
  MODULE_ONLY
  LINK_LIBRARIES jwt-cpp::jwt-cpp
)

按照指引将插件与MySQL源码一同编译并完成服务器安装，通过--plugin-load选项启动守护进程：

./bin/mysqld --user=mysql --plugin-load=auth_token.so &

创建认证用户：

CREATE USER 'token_user'@'%' IDENTIFIED WITH auth_token

但使用Workbench通过token_user连接服务器时，报错：

Your connection attempt failed for user 'token_user' to the MySQL server at XXX.XXX.XXX.XXX:3306:
Authentication plugin 'auth_token' cannot be loaded: The specified module could not be found.

已确认信息：

• 执行SHOW PLUGINS，结果显示auth_token插件状态为ACTIVE，类型为AUTHENTICATION，关联库文件为auth_token.so
• 插件文件存在于路径/usr/local/mysql/lib/plugin/auth_token.so
• mysqld的标准输出和syslog中无报错记录

排查步骤 #

1. 检查客户端侧插件可用性 #

Workbench作为MySQL客户端，需要能找到对应认证插件的库文件——你仅在服务器端部署了auth_token.so，客户端侧可能没有该文件：

• 找到Workbench的插件目录（通常为lib/mysql/plugin或系统对应库路径），将服务器端的auth_token.so复制到该目录
• 或通过客户端配置文件~/.my.cnf指定插件搜索路径：

[client]
plugin_dir=/usr/local/mysql/lib/plugin

2. 验证插件依赖库完整性 #

用ldd命令检查插件的依赖库是否能被客户端环境加载：

ldd /usr/local/mysql/lib/plugin/auth_token.so

如果存在缺失的依赖（如jwt-cpp相关库），需确保客户端环境安装了对应依赖，或修改CMake配置将依赖静态编译进插件。

3. 确认客户端与服务器版本兼容性 #

MySQL认证插件存在版本匹配要求，确保Workbench使用的MySQL客户端版本与服务器版本一致，版本差异过大可能导致插件加载失败。

4. 命令行客户端测试 #

避开Workbench的潜在问题，用MySQL命令行客户端直接测试连接：

mysql -u token_user -h XXX.XXX.XXX.XXX -P 3306 --plugin-dir=/usr/local/mysql/lib/plugin

如果命令行能成功连接，说明问题出在Workbench的配置或插件路径上；若命令行也报错，继续排查客户端侧插件加载逻辑。

5. 检查插件文件权限 #

确保客户端侧的auth_token.so文件权限正确，Workbench运行用户拥有读取权限：

chmod 755 /usr/local/mysql/lib/plugin/auth_token.so

6. 启用客户端调试日志 #

开启MySQL客户端调试日志，获取更详细的加载错误信息：

export MYSQL_DEBUG=d:t:i:O,/tmp/mysql_client.log
mysql -u token_user -h XXX.XXX.XXX.XXX -P 3306

查看生成的/tmp/mysql_client.log文件，定位具体加载失败原因。

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