PyCharm通过SSH隧道连接远程内网MySQL数据库的方法

竹里

发布时间：2026-10-21 | 4人浏览过

原创

在现代云端架构中，为保障核心数据安全，生产与测试环境的 MySQL 数据库通常部署在隔离的私有网络（VPC）中，仅分配内网私有 IP 且不直接对外开放公网访问端口。若要在本地开发机使用 PyCharm 专业版自带的 Database 工具直接连通该数据库，最标准且安全的解决路径是配置 SSH 隧道（SSH Tunneling）：以一台同时具备公网 IP 和内网访问权限的 Linux 服务器作为跳板机（Bastion / Jump Host），由 PyCharm 在本地与跳板机间建立加密通道，并将数据库访问请求透明转发至内网 MySQL 服务端。

一、SSH 隧道转发原理与网络拓扑

理解连接流程的关键在于区分“连接的发起方”与“流量的转发视角”。直接从本地开发机向内网 IP（如 10.0.0.25）发起请求会被公网路由直接丢弃或被云厂商防火墙拦截。SSH 隧道本质上是在本地客户端与远端跳板机之间建立一条加密隧道，由跳板机充当代理客户端，代表本地 PyCharm 向内网数据库发起 TCP 会话。

在此模式下，数据传输分为两个阶段：前半段是本地计算机到跳板机公网 IP 的 SSH 流量（默认走 22 端口，具有高强度非对称或对称加密保护）；后半段则是跳板机在内网网卡上发起的 MySQL 协议会话（走 3306 端口，处于内网私有子网内）。本地 PyCharm 在底层分配一个瞬态随机端口，并在 UI 层面完成协议封装与解包，使开发者能够像操作本地数据库一样执行查询与管理。

图 1：SSH 隧道穿透内网访问远程 MySQL 数据库的网络拓扑与流量转发流程

二、前置准备与连接要素清单

在进入 PyCharm 配置界面之前，必须事先确认跳板机与内网 MySQL 的网络互通性，并收集齐备两组独立的凭据信息。将这两组信息清晰划分，能够避免后续配置中频繁出现的混淆。

分类	配置项	典型示例	说明与要求
跳板机配置 (SSH层)	跳板机公网 IP	`123.57.45.67`	必须可从本地网络 ping 通或建立 TCP 握手
	SSH 服务端口	`22`	云平台安全组必须放行本地公网 IP 或对应网段
	SSH 登录用户名	`ubuntu` / `root`	具备跳板机登录权限的系统用户
	认证凭据	私钥文件 (`id_rsa` / `.pem`) 或密码	推荐使用标准 OpenSSH 格式的密钥对
目标数据库配置 (MySQL层)	内网主机地址	`10.0.0.25` 或 `127.0.0.1`	必须为“跳板机能够直接访问”的目标 IP 或域名
	MySQL 服务端口	`3306`	内网防火墙必须对跳板机的内网 IP 放行 3306 端口
	数据库账号与密码	`app_dev` / `P@ssw0rd!`	MySQL 中被授权访问相应库的用户
	数据库名称	`business_db`	需操作的实际库名（可选，不填默认展示全部有权限的库）

特别说明：关于跳板机与 MySQL 是否部署在同一台机器

若你的 MySQL 直接安装在跳板机本机，只是配置了 bind-address = 127.0.0.1 因而无法外网直连，那么后文中数据库主机的 Host 直接填写 127.0.0.1 或 localhost 即可；若 MySQL 运行在另一台纯内网服务器上，则此处必须填写该服务器在内网中的真实私有 IP（如 10.0.0.25）。

三、PyCharm 详细配置步骤

注意：本功能需使用 PyCharm Professional（专业版）。PyCharm 社区版默认不内置 Database 驱动与数据源管理套件。

1. 打开数据源管理器

在 PyCharm 右侧边缘栏找到 Database 工具窗口。如果右侧没有显示，可在顶部菜单栏点击 View > Tool Windows > Database。在打开的 Database 工具窗中，点击左上角的加号 +，依次选择 Data Source > MySQL。

2. 配置 SSH 隧道参数 (SSH/SSL 标签页)

在新建数据源弹窗中，不要急于在第一页填写数据库信息，首先点击切换到 SSH/SSL 标签页：

勾选 Use SSH tunnel（使用 SSH 隧道）复选框。
点击 SSH configuration 下拉框右侧的省略号 ...（或者选择已有的 SSH 配置新建一个）。
在弹出的 SSH Configurations 窗口中配置跳板机信息：
- Host：填写跳板机的公网 IP（例如 123.57.45.67）。
- Port：填写 22（若服务器修改了 SSH 端口，如 2222，需填写真实端口）。
- User name：填写跳板机系统用户（如 ubuntu 或 ecs-user）。
- Authentication type：若为密钥登录选择 Key pair 并浏览选中本地私钥路径；若为密码登录选择 Password 并输入密码。
点击 SSH 配置弹窗中的 Test Connection 按钮。若提示 Successfully connected，表明本地至跳板机的通道正常，点击 OK 保存并返回数据源弹窗。

3. 配置 MySQL 数据库常规参数 (General 标签页)

返回数据源弹窗后，点击切换回 General 标签页。此处是配置失误率最高的地方，请严格按以下逻辑填写：

Host：此处填写的地址是站在跳板机的角度看 MySQL 所在的主机地址。
- 若 MySQL 就在跳板机上：填 127.0.0.1 或 localhost。
- 若 MySQL 在内网另一台服务器：填内网私网 IP（如 10.0.0.25），绝对不能填写跳板机的公网 IP。
Port：保持默认的 3306（或内网 MySQL 实际监听的端口）。
Authentication：一般选择 User & Password。
User：输入 MySQL 数据库用户名（例如 app_dev）。
Password：输入对应的 MySQL 用户密码。
Database：输入需要连接的具体数据库库名。

图 2：PyCharm 数据库连接面板中 SSH/SSL 与 General 标签页的参数对应关系

4. 驱动下载与连接验证

如果是首次在 PyCharm 中添加 MySQL 数据源，界面下方会提示缺少驱动文件（Download missing driver files）。直接点击蓝色的 Download 链接，PyCharm 会自动从官方仓库下载对应版本的 MySQL Connector/J 驱动包。

驱动就绪后，点击左下角的 Test Connection 按钮。PyCharm 会依次执行两步检验：先通过 SSH 登录跳板机建立端口代理，再通过该代理向内网 MySQL 发起认证握手。当看到绿色的对勾以及数据库版本号提示（例如 MySQL 8.0.32）时，说明配置完全成功。点击 OK 保存，右侧面板便会加载出数据库表结构树。

四、常见连接故障的分层排查决策

当点击 Test Connection 出现报错时，切勿盲目修改参数。通过观察具体的报错信息，可以将其精准定位到“SSH 连接层”、“内网路由层”或“MySQL 权限层”三个阶段中的某一个。

图 3：连接异常报错时的分层排查与处理路径

1. 故障表现：SSH tunnel: Connection refused 或 Auth fail

此类报错意味着问题完全卡在 SSH 阶段，请求尚未触及 MySQL 服务端。排查重点如下：

安全组或防火墙：确认跳板机所属的云安全组是否开放入站端口 22，且你的本地公网 IP 没有被防暴力破解策略（如 Fail2ban）暂时封禁。
私钥格式问题：PyCharm 偏好使用标准 OpenSSH 格式的私钥（文件首行通常为 -----BEGIN OPENSSH PRIVATE KEY----- 或 -----BEGIN RSA PRIVATE KEY-----）。如果是 PuTTY 生成的 .ppk 文件，需先在 PuTTYgen 中导出为 OpenSSH 格式。
SSH 转发权限被禁用：检查跳板机的 /etc/ssh/sshd_config 文件，确保存在配置项 AllowTcpForwarding yes。若为 no，sshd 会直接拒绝客户端创建端口转发隧道。

2. 故障表现：Communications link failure / Connect timed out

该报错通常说明 SSH 握手已经成功，但跳板机在尝试向 Host:Port 建立内网 TCP 握手时超时或连接重置。

首先登录跳板机终端，直接测试跳板机与 MySQL 主机之间的网络通畅性：

# 在跳板机执行，验证内网端口是否开放
nc -zv 10.0.0.25 3306
# 或者使用 telnet
telnet 10.0.0.25 3306

若显示 Connection refused，检查 MySQL 所在机器的 my.cnf 配置文件中，bind-address 是否被错误绑定到了 127.0.0.1。若要接受来自跳板机的内网连接，必须将其改为 0.0.0.0 或具体的内网私有 IP。
若显示连接超时，需排查 MySQL 服务器所属的安全组，确保其对跳板机的内网私有 IP（例如 10.0.0.8）放行了入站 3306 端口。

3. 故障表现：Access denied for user 'app_user'@'...'

此错误表明网络层已全部打通，但 MySQL 数据库的权限系统拒绝了本次认证。在 MySQL 中，用户身份是由 用户名 + 允许访问的主机名/IP 共同决定的。

若 MySQL 与跳板机在同一台主机，账号通常授权为 'app_user'@'localhost' 或 'app_user'@'127.0.0.1'。
若 MySQL 处于另一台内网主机，从跳板机转过来的流量在 MySQL 看来，客户端 IP 是跳板机的内网 IP（例如 10.0.0.8）。此时如果该用户在 MySQL 中仅被授权了 localhost，连接就会报 Access denied。解决办法是在 MySQL 管理端为该账号授权内网来源：
```
-- 允许来自特定跳板机内网IP的连接
CREATE USER 'app_user'@'10.0.0.8' IDENTIFIED BY 'YourStrongPassword!';
GRANT ALL PRIVILEGES ON business_db.* TO 'app_user'@'10.0.0.8';
FLUSH PRIVILEGES;
```

4. 故障表现：Server returns invalid timezone

在 MySQL 8.0 及部分特定时区配置的服务器上，JDBC 驱动连接时可能会报错提示无法识别服务器时区。解决办法是在数据源弹窗中切换到 Advanced 标签页，找到 serverTimezone 参数，将其值设置为 Asia/Shanghai、UTC 或与你的业务一致的时区名称，随后重新测试即可。

五、全链路配置核验与核心原则总结

通过 SSH 隧道连接内网数据库兼顾了开发便利性与生产级网络隔离。在日常开发与团队协作中，建议遵循以下标准规范以保障连接稳定与权限收敛：

图 4：PyCharm SSH 隧道连接内网数据库的核心配置原则与安全建议

会话心跳保活（Keep-Alive）：长时间在 IDE 中无查询操作时，运营商网关或云防火墙可能会静默切断处于空闲状态的 TCP 连接，导致下一次查询卡死或报错 Broken pipe。可以在跳板机的 /etc/ssh/sshd_config 中加入 ClientAliveInterval 60 和 ClientAliveCountMax 3，由服务端定期向客户端发送心跳探测包以维持连接活跃。
最小特权原则：严禁直接使用拥有全局超级权限的 root 账号配置日常开发连接。应按业务库或开发者角色划分独立的账号，并限制只授予 SELECT、INSERT、UPDATE 等必要权限。
跳板机公网暴露面收敛：跳板机的 SSH 端口（22 或自定义端口）不建议向全网 0.0.0.0/0 开放，应在云防火墙/安全组策略中限定仅允许公司固定办公网 IP 或个人出口 IP 访问。