远程数据库连接故障排查经验总结
一、故障背景
|----------|---------------------------------------------------|
| 项目 | 内容 |
| 环境 | 腾讯云 CVM（Ubuntu 24.04），宝塔面板（BT Panel）已卸载 MySQL |
| 客户端 | DBeaver（本地 Windows） |
| 报错 | Communications link failure ... Connect timed out |
| 关键转折 | 安全组始终开放 3306 端口，服务恢复后仍需刷新客户端状态才最终连通 |
二、排查逻辑链
服务进程是否运行？
↓ 是
MySQL 监听地址是否为 0.0.0.0:3306？
↓ 是
root 用户是否允许远程登录（host = %）？
↓ 是
操作系统防火墙（UFW/iptables）是否放行 3306？
↓ 是
云平台安全组是否放行 3306？
↓ 是
客户端连接状态/网络缓存是否正常？
↓ 是
✅ 连接成功三、各环节排查与判断
第一层：服务进程状态
# 注意：Ubuntu APT 安装的服务名为 mysql，宝塔安装的为 mysqld
sudo systemctl status mysql
# 或
sudo systemctl status mysqld|--------------------------|---------|-------------------------------------|
| 结果 | 含义 | 处理 |
| active (running) | 服务正常 | 进入下一层 |
| inactive (dead) / failed | 服务未运行 | sudo systemctl start mysql |
| not found | 服务单元不存在 | 改用 service mysql status ，或检查是否误用服务名 |
第二层：MySQL 监听地址
sudo netstat -tulnp | grep 3306
|----------------|-----------|----------------------------------------------------------------------------------------|
| 结果 | 含义 | 处理 |
| 0.0.0.0:3306 | 监听所有 IP ✅ | 进入下一层 |
| 127.0.0.1:3306 | 仅监听本地 | 修改 /etc/mysql/mysql.conf.d/mysqld.cnf ，将 bind-address = 127.0.0.1 改为 0.0.0.0 ，重启 MySQL |
第三层：root 用户远程权限
sudo mysql -uroot -p -e "SELECT host, user FROM mysql.user WHERE user='root';"
|------------------|----------------|----------------------------------------------------------------------------|
| 结果 | 含义 | 处理 |
| host = % | 允许任意 IP 远程登录 ✅ | 进入下一层 |
| host = localhost | 仅允许本地登录 | 执行 UPDATE mysql.user SET host = '%' WHERE user = 'root'; FLUSH PRIVILEGES; |
第四层：操作系统防火墙
# 检查 UFW
sudo ufw status
# 检查 iptables
sudo iptables -L -n | grep 3306|-------------|--------------------------------------------------------------------------------|
| 结果 | 处理 |
| 无 3306 放行规则 | sudo ufw allow 3306/tcp 或 sudo iptables -I INPUT -p tcp --dport 3306 -j ACCEPT |
第五层：云平台安全组
|---------|-----------------------------------------------------------------|
| 平台 | 操作路径 |
| 腾讯云 | 控制台 → 云服务器 → 实例 → 安全组 → 入站规则 → 添加 TCP:3306 ，来源 0.0.0.0/0 或指定 IP |
| 阿里云 | 控制台 → ECS → 实例 → 安全组 → 入站规则 → 添加 TCP:3306 |
特别注意 ：安全组规则修改后立即生效 ，无需重启服务器。
第六层：客户端连接状态/网络缓存
适用场景 ：数据库服务中断后重新上线，安全组始终开放，但 DBeaver 仍报超时。
|------------------------|-------------------------|
| 操作 | 命令/步骤 |
| 刷新本地 DNS （Windows） | ipconfig /flushdns |
| 重启 DBeaver | 完全退出后重新打开 |
| 新建连接 | 在 DBeaver 中新建连接（非复制旧连接） |
| 切换网络 | 切换 Wi-Fi / 连接手机热点，再切回 |
| 清空 DBeaver 驱动缓存 | 数据库 → 驱动管理器 → 重置为默认 |
| 重启本地路由器 （可选） | 清除 NAT 缓存 |
四、宝塔处理
环境特征识别
- 日志路径：/www/server/data/
- 配置文件路径：/etc/my.cnf（宝塔） vs /etc/mysql/mysql.conf.d/（APT）
- 服务名：mysqld（宝塔） vs mysql（APT）
宝塔卸载残留常见问题
|-------------------------------------|------------------------------|----------------------------------------------------------------------|
| 现象 | 原因 | 解决方案 |
| systemctl status mysqld → not found | 宝塔删除了 systemd 单元文件 | 改用 sudo service mysql status |
| sudo mysql → command not found | 客户端未加入系统 PATH | sudo apt install mysql-client -y 或使用绝对路径 /www/server/mysql/bin/mysql |
| 多个配置文件冲突 | /etc/my.cnf 与 /etc/mysql/ 共存 | 用 sudo find / -name my.cnf 2>/dev/null 查找并清理多余配置 |
宝塔环境推荐操作方式
- 登录宝塔面板 → 软件商店 → 已安装 → MySQL → 设置
- 通过面板的"命令行"选项卡执行 SQL
- 通过面板的"重启"按钮启动服务（错误信息更直观）
五、工具链速查
|-----------------------------|------------------------------------------------------------------|
| 场景 | 命令/工具 |
| 测试端口连通性 （Linux/Mac） | telnet IP 3306 或 nc -zv IP 3306 |
| 测试端口连通性 （Windows） | Test-NetConnection -ComputerName IP -Port 3306 |
| 安装 Telnet 客户端 （Windows） | dism /online /Enable-Feature /FeatureName:TelnetClient （管理员 CMD） |
| 安装 MySQL 客户端 （Ubuntu） | sudo apt install mysql-client -y |
| 查看 MySQL 日志 | sudo tail -n 50 /var/log/mysql/error.log |
| 查看宝塔 MySQL 日志 | sudo tail -n 50 /www/server/data/*.err |
| 查看服务端口监听 | sudo netstat -tulnp | grep 3306 |
| 查看防火墙状态 （UFW） | sudo ufw status |
| 查看防火墙规则 （iptables） | sudo iptables -L -n |
六、复盘
|-----------|--------------------|-----------------------------------|------------------------------------|
| 阶段 | 问题 | 发现方式 | 解决方式 |
| 第 1 层 | MySQL 服务崩溃（宝塔卸载残留） | systemctl status mysqld 显示 failed | 用 sudo apt install mysql-server 重装 |
| 第 2 层 | mysql 客户端命令缺失 | sudo mysql → command not found | sudo apt install mysql-client -y |
| 第 3 层 | root 免密登录失败（有密码） | sudo mysql → ERROR 1045 | 改用 sudo mysql -uroot -p |
| 第 4 层 | 监听地址正常 | netstat 显示 0.0.0.0:3306 | ✅ 通过 |
| 第 5 层 | root 用户权限正常 | SELECT host,user 显示 % | ✅ 通过 |
| 第 6 层 | 云安全组始终开放 | 控制台确认 | ✅ 通过 |
| 第 7 层 | 客户端连接状态残留 | Test-NetConnection 端口不通，但安全组已开放 | 重启 DBeaver + 新建连接 + 刷新 DNS |
结论 ：服务中断期间，本地 DBeaver / 操作系统 / 路由器缓存了"该 IP:端口 不可达"的状态，服务恢复后未自动刷新。因此虽然后 4 层全部正常，客户端仍报超时。
七、核心认知
"服务活着 ≠ 端口开着，端口开着 ≠ 防火墙放过，防火墙放过 ≠ 云网关放行，云网关放行 ≠ 客户端能连。"