本文详解 Java 应用通过 JSch 建立本地端口转发（SSH Tunnel），再使用 MariaDB JDBC 驱动连接远程数据库的完整流程，涵盖常见 SQLNonTransientConnectionException: Socket fail to connect to host 错误的根因分析与实战解决方案。
本文详解 java 应用通过 jsch 建立本地端口转发（ssh tunnel），再使用 mariadb jdbc 驱动连接远程数据库的完整流程，涵盖常见 `sqlnontransientconnectionexception: socket fail to connect to host` 错误的根因分析与实战解决方案。
在企业级 Java 应用中，出于安全策略限制，生产环境的 MariaDB 数据库通常不直接暴露公网，而是要求通过跳板机（Bastion Host）或 SSH 隧道访问。此时若仅依赖 JSch 建立 SSH 会话却未正确配置端口转发逻辑，极易触发 SQLNonTransientConnectionException: Socket fail to connect to host —— 这并非驱动或认证问题，而是本地应用根本未成功将流量路由至目标数据库端口。
✅ 正确的 SSH 隧道 + JDBC 连接流程
关键在于：session.setPortForwardingL() 的参数必须严格匹配数据库服务真实监听地址与端口，而不能复用 SSH 连接的主机/端口。
常见错误示例（即提问中的问题）：
// ❌ 错误：将 remoteSSHPort（如 22）误传为数据库端口 int assignedPort = session.setPortForwardingL(localPort, serverHost, remoteSSHPort); // remoteSSHPort=22 → 转发到本机 localPort，但目标是 SSH 端口，不是 MySQL！ String url = "jdbc:mariadb://" + serverHost + ":" + assignedPort + "/" + database; // serverHost 是跳板机 IP，非数据库 IP！
✅ 正确做法如下：
立即学习“Java免费学习笔记（深入）”；
-
明确三元组角色：
Java 接口排错助手下载在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。
-
sshServer：跳板机地址（如jump.example.com），SSH 连接目标； -
databaseHost：MariaDB 实际所在服务器内网地址（如10.10.5.20或db.internal），必须能被跳板机访问； -
databasePort：MariaDB 监听端口（默认3306）。
-
-
建立本地端口转发（Local Port Forwarding）：
// ✅ 正确：将本地 localPort 映射到跳板机可访问的 databaseHost:databasePort int tunnelPort = 3307; // 本地任意空闲端口（避免与本地 MySQL 冲突） session.setPortForwardingL(tunnelPort, databaseHost, 3306); // ← 关键：databaseHost 是 DB 内网地址，3306 是 DB 真实端口
-
JDBC URL 指向
localhost+ 隧道端口：String jdbcUrl = "jdbc:mariadb://localhost:" + tunnelPort + "/" + database + "?user=" + userSQL + "&password=" + passwordSql + "&allowPublicKeyRetrieval=true&useSSL=false"; // 根据环境调整 SSL 策略 Connection conn = DriverManager.getConnection(jdbcUrl);
⚠️ 注意：JDBC 中的
host必须是localhost（或127.0.0.1），因为隧道已将localhost:tunnelPort流量经 SSH 加密转发至databaseHost:3306。若仍写serverHost或databaseHost，则绕过隧道直连，必然失败。
? 排查与验证步骤
| 步骤 | 操作 | 预期结果 |
|---|---|---|
| ① 验证 SSH 隧道是否生效 |
telnet localhost 3307（Linux/macOS）或 Test-NetConnection localhost -Port 3307（PowerShell） |
显示 Connected to localhost 或 TcpTestSucceeded: True
|
| ② 验证跳板机可达 DB | 在跳板机上执行 nc -zv 10.10.5.20 3306
|
返回 succeeded!
|
| ③ 检查 MariaDB 绑定与权限 | 登录数据库服务器，确认： – bind-address 在 my.cnf 中未设为 127.0.0.1（应为 0.0.0.0 或具体内网 IP）– 用户授权包含 'user'@'jump-host-ip' 或 'user'@'%'
|
SELECT host FROM mysql.user WHERE User='your_user'; 应含跳板机来源 IP |
? 常见陷阱与修复
DBeaver 可连但 Java 不行？
DBeaver 默认启用 SSH 隧道配置（图形化设置SSH Configuration），而 Java 代码中常混淆sshServer与databaseHost，或未关闭防火墙/SELinux 对本地端口的拦截。-
SQLNonTransientConnectionException伴随Connection refused
90% 源于隧道未建立成功（session.isConnected()为true≠ 隧道就绪），务必在setPortForwardingL()后加日志：System.out.println("SSH tunnel active on localhost:" + tunnelPort); -
容器化 MariaDB 场景（如 Docker）
若数据库运行在容器中，需确保启动时映射端口：docker run -d --name mariadb -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=pass -d mariadb:10.11
并确认容器网络允许跳板机访问（如使用
host网络模式或自定义 bridge 并开放端口）。
✅ 完整可运行示例（含异常处理）
public Connection createTunneledConnection() throws Exception {
JSch jsch = new JSch();
jsch.setKnownHosts(System.getProperty("user.home") + "/.ssh/known_hosts");
jsch.addIdentity("/path/to/private_key");
Session session = jsch.getSession("ssh-user", "jump.example.com", 22);
session.setConfig("StrictHostKeyChecking", "yes");
session.connect(30_000); // 30秒超时
// ✅ 关键：隧道目标 = DB 内网地址 + 真实端口
int localTunnelPort = 3307;
session.setPortForwardingL(localTunnelPort, "10.10.5.20", 3306);
String url = "jdbc:mariadb://localhost:" + localTunnelPort + "/myapp"
+ "?user=dbuser&password=dbpass&allowPublicKeyRetrieval=true&useSSL=false";
return DriverManager.getConnection(url);
}? 最佳实践提示：
- 将
session.disconnect()和session.setPortForwardingL(...)的生命周期统一管理（建议使用try-with-resources包装Connection）；- 生产环境禁用
useSSL=false，应配置受信任证书链；- 使用 HikariCP 等连接池时，确保
jdbcUrl中不包含用户名密码，改用HikariConfig.setDataSourceProperties()安全传参。
通过精准区分 SSH 连接点与数据库服务点、严格绑定隧道参数、并辅以分层验证，即可彻底规避 Socket fail to connect to host 类错误，实现安全、稳定、可运维的远程数据库访问。
