PyCharm 连接 MySQL 出现 Connection refused 或超时错误排查

在 PyCharm 专业版的 Database 工具窗口中配置 MySQL 数据源时，点击“Test Connection”最常见的失败提示就是 Connection refused 或连接超时（Connection timed out）。这两种报错都表明 TCP 三次握手未能顺利完成，但背后的网络链路状态存在根本区别。解决这一问题的关键在于理清网络层状态：先确认服务端是否在指定地址监听端口，再排查沿途防火墙与安全组策略，最后检查 MySQL 用户访问来源与客户端配置。

一、区分核心错误：Connection refused 与 Connection timed out

当网络通信在握手阶段受阻时，客户端收到的反馈直接揭示了故障发生的具体层级：

• Connection refused（连接被拒绝）：PyCharm 向目标 IP 和端口发送 TCP SYN 请求包后，目标主机操作系统明确返回了 RST 确认包。这说明目标 IP 顺利可达，但目标主机的操作系统协议栈判定目标端口上没有程序在监听，或者本地进程绑定限制拒绝了该来源。排查重点是服务是否启动、监听网卡是否正确（如仅绑定了本地环回）。
• Connection timed out（连接超时）：PyCharm 发送 TCP SYN 包后，在设定的超时时间（通常为十几秒到数十秒）内没有收到任何响应报文，重传多次后彻底放弃。这通常是因为通信报文在网络传输路径中被静默丢弃（DROP）。排查重点是云服务器安全组策略、机房硬件防火墙或网络路由不可达。

二、排查步骤一：检查 MySQL 服务状态与端口绑定

如果报错为 Connection refused，首先需要登录 MySQL 所在的服务器或容器内部，确认数据库进程是否存活，以及它的网络绑定地址。

1. 查看服务运行状态

在 Linux 服务器终端执行系统服务命令，确认 mysqld 服务处于 active (running) 状态：

# 针对 systemd 管理的 Linux 系统
sudo systemctl status mysql
# 或在 CentOS/RHEL 系列中
sudo systemctl status mysqld

如果是通过 Docker 启动的 MySQL 容器，使用以下命令检查容器状态：

docker ps -f name=mysql

2. 检查端口监听与绑定地址（bind-address）

即便服务正常启动，默认的安全配置通常会将 MySQL 绑定在 127.0.0.1。这意味着它只接收来自本机内部的连接，来自局域网或公网 IP 的请求在抵达操作系统协议栈时会被立即拒绝。

# 查看 3306 端口在哪个 IP 地址上监听
sudo ss -tulpn | grep 3306
# 或者使用 netstat
sudo netstat -tlpn | grep 3306

根据输出结果判断绑定状态：

• 若显示 127.0.0.1:3306：说明仅允许本地回环访问，PyCharm 从外部连接必然抛出 Connection refused。
• 若显示 0.0.0.0:3306 或 :::3306：说明已监听所有网卡接口，配置正确。

3. 修改配置文件并重启

编辑 MySQL 主配置文件（Ubuntu/Debian 位于 /etc/mysql/mysql.conf.d/mysqld.cnf，CentOS 位于 /etc/my.cnf）：

[mysqld]
# 将原有 bind-address = 127.0.0.1 修改为 0.0.0.0，或直接注释该行
bind-address = 0.0.0.0

保存后重启服务使配置生效：

sudo systemctl restart mysql

三、排查步骤二：排查网络链路、防火墙与安全组（解决超时）

当 PyCharm 提示连接超时（Connection timed out）时，说明数据包在到达 MySQL 服务之前被中间的网络屏障丢弃。

1. 本地网络探测

在安装了 PyCharm 的本地开发机终端（macOS、Linux 或 Windows PowerShell）中，逐步测试网络与端口通畅度：

# 1. 验证基础网络层是否可达
ping 192.168.1.10

# 2. 验证 3306 端口传输层连通性 (Linux / macOS)
nc -zv -w 5 192.168.1.10 3306
# 或使用 telnet
telnet 192.168.1.10 3306

若 ping 正常但 nc 命令卡住并报告超时，表明网络通畅但端口被防火墙或安全组拦截。

2. Linux 本机防火墙放行

根据服务器使用的防火墙组件放行 3306 端口流量：

# 针对 UFW (Ubuntu / Debian)
sudo ufw allow 3306/tcp
sudo ufw reload

# 针对 firewalld (CentOS / RHEL / Fedora)
sudo firewall-cmd --zone=public --add-port=3306/tcp --permanent
sudo firewall-cmd --reload

# 针对原生 iptables (若使用默认 DROP 策略)
sudo iptables -A INPUT -p tcp --dport 3306 -j ACCEPT

3. 云服务商安全组入方向配置

若 MySQL 部署在阿里云、腾讯云、华为云或 AWS 等云服务器（ECS/CVM/EC2）上，系统内部防火墙即使全开放，云平台的虚拟防火墙（安全组）默认也会拦截未授权端口。必须进入云控制台：

1. 定位到目标实例绑定的安全组配置。
2. 在“入方向规则”（Inbound Rules）中添加一条新规则。
3. 协议类型选择 TCP，端口范围填写 3306。
4. 授权对象建议填写开发人员本地的公网出口 IP（如 203.0.113.15/32），避免对 0.0.0.0/0 全开放以防数据库遭受恶意暴力破解。

四、排查步骤三：核对 MySQL 用户的主机授权（Host %）

在网络与端口完全畅通后，若账号权限设置不当，连接可能会进一步演变为权限错误。虽然权限问题通常直接提示 Access denied for user，但在某些特定代理或高安全层级下也可能表现为异常断开。

登录服务器上的本地 MySQL 命令行，检查账号的来源主机限制：

SELECT user, host, plugin FROM mysql.user WHERE user = 'root';

若 host 列仅为 localhost，说明该账号只允许在服务器本地登录。从 PyCharm 远程登录必须配置允许外部 Host：

# 生产环境推荐：新建专用的远程开发账号，不直接开放 root 远程权限
CREATE USER 'dev_user'@'%' IDENTIFIED BY 'StrongPassword123!';
GRANT ALL PRIVILEGES ON my_database.* TO 'dev_user'@'%';
FLUSH PRIVILEGES;

五、PyCharm 数据源配置进阶技巧：SSH 隧道安全连接

在企业级开发或云服务器生产环境中，通常不建议直接将 3306 端口暴露给公网，否则容易遭受扫描与攻击。若不想调整安全组开放 3306 端口，最佳实践是利用 PyCharm 原生支持的 SSH 隧道（SSH Tunnel）。

由于服务器通常已经开放了安全的 22 端口供开发人员登录，PyCharm 可以通过 SSH 协议在本地开发机与远程服务器之间建立加密通道，将 MySQL 请求打包传输并在服务器内部直接转发给本地 127.0.0.1:3306：

1. 打开 PyCharm 数据源配置面板（Database 窗口 -> Data Sources -> MySQL）。
2. 在 General 标签页中，Host 保持填写 127.0.0.1，Port 填写 3306（此处代表服务器本地回环地址）。
3. 切换到 SSH/SSL 标签页，勾选 Use SSH tunnel。
4. 配置 SSH 代理参数：
   • Host：云服务器公网 IP 地址。
   • Port：22。
   • User Name：SSH 登录账号（如 ubuntu、root 等）。
   • Authentication type：选择 Key Pair（公私钥对）或 Password。
5. 返回 General 页面点击 Test Connection。

这种方案下，服务器端 MySQL 甚至不需要修改 bind-address = 0.0.0.0，依然保持最高安全级的 127.0.0.1 监听即可正常工作。

六、排查速查矩阵与解决闭环

根据排查过程中的各项表现与修复动作，整理速查表格如下：

排查 PyCharm 连接 MySQL 故障时，遵循“报错反馈判定 -> 服务与本地绑定检查 -> 网络与防火墙探测 -> 隧道或账号授权补全”的闭环链路，即可在数分钟内精确定位瓶颈并恢复顺畅连接。