MySQL报错 远程修复 MySQL Error number:MY-011303 ER_XPLUGIN_CLIENT_SSL_HANDSHAKE_FAILED SQLSTATE:HY000 故障处理

MySQL报错：远程修复ER_XPLUGIN_CLIENT_SSL_HANDSHAKE_FAILED故障实录

场景引入

"老王，咱们新上线的数据分析平台连不上MySQL了！"早上刚到公司，我就被开发同事小李一把拉住，系统监控大屏上赫然显示着鲜红的错误提示："MySQL Error number: MY-011303 ER_XPLUGIN_CLIENT_SSL_HANDSHAKE_FAILED SQLSTATE: HY000"，这个突如其来的SSL握手失败错误，让整个团队都紧张起来——毕竟数据库连接问题直接影响着业务系统的正常运行。

错误解析

首先我们需要理解这个错误的具体含义，ER_XPLUGIN_CLIENT_SSL_HANDSHAKE_FAILED（错误代码MY-011303）是MySQL X Plugin在建立SSL加密连接时出现的典型故障，当客户端尝试通过X Protocol（MySQL 8.0默认使用的协议）连接服务器时，如果SSL/TLS握手过程失败,就会抛出这个错误。

常见触发场景包括：

• SSL证书配置错误或过期
• 客户端与服务器支持的SSL协议版本不匹配
• 加密套件配置不一致
• 系统时间不同步导致证书验证失败
• 防火墙拦截了SSL握手流量

逐步排查与修复

第一步：验证基础连接

在深入SSL问题前,先确认基础网络连接是否正常：

telnet mysql_server_ip 33060

如果33060端口（X Plugin默认端口）不通，可能是防火墙问题，如果连接正常,我们继续排查SSL配置。

第二步：检查MySQL服务器SSL配置

登录MySQL服务器,查看当前SSL状态：

SHOW VARIABLES LIKE '%ssl%';

重点关注：

• have_ssl：是否支持SSL（应为YES）
• xplugin_ssl_mode：X Plugin的SSL模式
• ssl_ca, ssl_cert, ssl_key：证书文件路径

第三步：验证证书有效性

确保所有证书文件存在且权限正确：

ls -l /var/lib/mysql/server-cert.pem
ls -l /var/lib/mysql/server-key.pem
ls -l /var/lib/mysql/ca.pem

证书权限通常应设置为mysql用户可读：

chown mysql:mysql /var/lib/mysql/*.pem
chmod 600 /var/lib/mysql/*.pem

第四步：检查SSL协议兼容性

有时问题出在协议版本不匹配,查看服务器支持的协议：

SHOW SESSION STATUS LIKE 'Ssl_version';

在客户端连接时，可以指定允许的协议版本,例如在连接字符串中添加：

?ssl-mode=REQUIRED&tls-versions=[TLSv1.2,TLSv1.3]

第五步：调试SSL握手过程

对于更复杂的情况,可以启用详细日志记录：

1. 在MySQL服务器配置文件中添加：

   [mysqld]
   ssl=1
   xplugin_ssl_mode=REQUIRED
   log_error_verbosity=3

2. 在客户端启用SSL调试（Linux/Mac）：

   export SSLKEYLOGFILE=~/ssl_key.log
   mysqlsh --ssl-mode=REQUIRED -u root -h mysql_server_ip -p

第六步：临时解决方案（非生产环境）

如果急需恢复服务且环境允许,可以临时降级安全要求：

SET GLOBAL xplugin_ssl_mode=PREFERRED;

或者在客户端连接时使用：

mysqlsh --ssl-mode=DISABLED -u root -h mysql_server_ip -p

注意：这会使通信变为明文传输,仅限紧急情况使用。

预防措施

为避免未来再次出现类似问题,建议：

1. 证书管理自动化：使用Let's Encrypt等工具自动续期证书
2. 配置标准化：在所有环境使用相同的SSL配置模板
3. 监控告警：对证书到期时间设置监控
4. 文档记录：详细记录SSL配置变更过程

这次ER_XPLUGIN_CLIENT_SSL_HANDSHAKE_FAILED故障的根本原因是证书链不完整，由于运维团队最近更新了CA证书，但忘记将中间证书包含在服务器证书中，导致部分客户端无法验证证书链，通过重新生成包含完整链的证书并重启MySQL服务,问题最终得到解决。

处理SSL相关问题时，保持耐心和系统性排查非常重要，从网络基础连通性开始，逐步验证证书、协议和配置,往往比直接修改配置更能有效解决问题。