本文详解如何在Java应用中借助JSch建立SSH本地端口转发，并正确连接远程MariaDB数据库，涵盖常见SQLNonTransientConnectionException: Socket fail to connect to host错误的根因分析、标准实现步骤、关键配置要点及调试验证方法。
本文详解如何在java应用中借助jsch建立ssh本地端口转发，并正确连接远程mariadb数据库，涵盖常见`sqlnontransientconnectionexception: socket fail to connect to host`错误的根因分析、标准实现步骤、关键配置要点及调试验证方法。
在企业级Java应用开发中，出于安全合规要求，生产环境的MariaDB（或MySQL）通常禁止公网直连，必须通过跳板机（Bastion Host）或SSH隧道访问。开发者常误以为“SSH连接成功 = 数据库连接就绪”，却忽略端口转发与JDBC连接目标之间的逻辑映射关系——这正是SQLNonTransientConnectionException: Socket fail to connect to host异常的典型成因。
? 核心问题定位：混淆了SSH目标与数据库目标
您当前代码中的关键错误在于：
int assignedPort = session.setPortForwardingL(localPort, serverHost, remoteSSHPort); String url = "jdbc:mariadb://" + serverHost + ":" + assignedPort + "/" + database;
此处 serverHost 是数据库服务器的内网地址（如 10.10.5.20），而 remoteSSHPort 是该数据库服务器上 MariaDB 监听的端口（默认 3306）。但 setPortForwardingL() 的语义是：
将本机
localPort的入站请求，经已建立的SSH会话，转发到 SSH服务器能访问的远端地址+端口。
因此，serverHost 必须是 SSH服务器（sshServer）网络可达的地址 —— 通常是数据库服务器在内网中的IP，而非 localhost 或 127.0.0.1（后者仅对数据库本机有效）。若 sshServer 无法直接 ping 通 serverHost，端口转发即失败，后续JDBC自然无法建立Socket连接。
在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。
✅ 正确做法：确保 serverHost 是数据库服务器在SSH跳板机视角下的可路由内网IP，且数据库服务已绑定该IP（非仅 127.0.0.1）。
✅ 完整可运行示例（含健壮性增强）
import com.jcraft.jsch.*;
import java.sql.*;
public class MariaDBOverSSH {
private static Session sshSession;
private static final int LOCAL_PORT = 3307; // 避免与本机3306冲突
public static void setupSSHAndConnect() throws Exception {
JSch jsch = new JSch();
jsch.setKnownHosts(System.getProperty("user.home") + "/.ssh/known_hosts");
jsch.addIdentity("/path/to/private/key"); // 推荐使用私钥，非publicKey字符串
sshSession = jsch.getSession("ssh_user", "ssh.jump-server.com", 22);
sshSession.setConfig("StrictHostKeyChecking", "yes");
sshSession.connect(10000); // 10秒超时
// ✅ 关键：forward to DB server's internal IP & port (e.g., 10.10.5.20:3306)
// 注意：此处 serverHost 必须是 SSH服务器能访问的数据库内网地址！
String dbInternalHost = "10.10.5.20"; // 替换为真实数据库内网IP
int dbPort = 3306;
int forwardedPort = sshSession.setPortForwardingL(LOCAL_PORT, dbInternalHost, dbPort);
System.out.println("SSH port forwarding established on local port: " + forwardedPort);
// ✅ JDBC URL 指向 localhost（本机），因为端口转发已在本机监听
String jdbcUrl = "jdbc:mariadb://localhost:" + LOCAL_PORT + "/mydb?useSSL=false&allowPublicKeyRetrieval=true";
Properties props = new Properties();
props.setProperty("user", "db_user");
props.setProperty("password", "db_pass");
try (Connection conn = DriverManager.getConnection(jdbcUrl, props)) {
System.out.println("✅ Successfully connected to MariaDB via SSH tunnel!");
try (Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT VERSION()")) {
if (rs.next()) {
System.out.println("MariaDB Version: " + rs.getString(1));
}
}
}
}
public static void main(String[] args) {
try {
setupSSHAndConnect();
} catch (Exception e) {
e.printStackTrace();
// 建议：捕获并打印 JSch 异常（如 Proxy error）、SQL 异常（如 Connection refused）
} finally {
if (sshSession != null && sshSession.isConnected()) {
sshSession.disconnect();
System.out.println("SSH session closed.");
}
}
}
}
⚠️ 关键注意事项与排错清单
| 项目 | 说明 | 验证方式 |
|---|---|---|
| ① 数据库绑定地址 | MariaDB 配置中 bind-address 不能为 127.0.0.1，需设为 0.0.0.0 或具体内网IP（如 10.10.5.20） |
sudo grep bind-address /etc/mysql/mariadb.conf.d/50-server.cnf |
| ② 防火墙放行 | SSH跳板机 → 数据库服务器的 3306 端口必须开放 |
ssh user@jump-server 'telnet 10.10.5.20 3306' |
| ③ JDBC URL主机名 |
必须用 localhost 或 127.0.0.1，而非数据库内网IP —— 因为端口转发发生在本机环回接口 |
❌ jdbc:mariadb://10.10.5.20:3307/... → ✅ jdbc:mariadb://localhost:3307/...
|
| ④ 本地端口可用性 |
LOCAL_PORT（如3307）不能被本机其他进程占用 |
lsof -i :3307 或 netstat -ano \| findstr :3307
|
| ⑤ 用户权限与host匹配 | 数据库用户需授权从 ssh_server_ip 或 % 连接（如 GRANT ALL ON mydb.* TO 'db_user'@'%' IDENTIFIED BY 'pwd';） |
登录数据库执行 SELECT User, Host FROM mysql.user;
|
? 为什么DBeaver能连而Java不能？
DBeaver 内置了图形化SSH隧道配置，它自动将 localhost 映射到SSH隧道的本地端口，并严格遵循 localhost → 转发端口 → SSH → DB内网IP:3306 的链路。而您的Java代码中错误地将JDBC URL指向了数据库内网IP（绕过隧道），导致连接直接尝试走公网或局域网直连，自然失败。
✅ 总结
解决此类问题的核心逻辑链是：
SSH会话建立 → 端口转发规则生效（本机端口 ↔ SSH服务器 ↔ DB内网地址:端口）→ JDBC连接本机转发端口（localhost:xxx）→ 流量经SSH加密抵达数据库
只要确保 serverHost 是SSH服务器可达的数据库内网地址、JDBC URL使用 localhost、数据库服务正确监听并授权，即可稳定实现安全连接。建议在生产环境中将端口转发封装为独立初始化模块，并加入连接池健康检查（如HikariCP的connection-test-query），以提升系统鲁棒性。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
