本文详解如何在 Java 应用中借助 JSch 建立 SSH 本地端口转发，并正确配置 MariaDB JDBC 连接，规避 SQLNonTransientConnectionException: Socket fail to connect to host 等典型连接异常。
本文详解如何在 java 应用中借助 jsch 建立 ssh 本地端口转发，并正确配置 mariadb jdbc 连接，规避 `sqlnontransientconnectionexception: socket fail to connect to host` 等典型连接异常。
在企业级 Java 应用开发中，出于安全策略限制，生产环境的 MariaDB（或 MySQL）数据库通常不直接暴露公网端口（如 3306），而是要求通过跳板机（Bastion Host）或 SSH 隧道访问。此时若仅简单复用 DBeaver 的图形化配置逻辑，极易因端口映射、连接参数或网络上下文理解偏差，触发 SQLNonTransientConnectionException: Socket fail to connect to host —— 这一错误表面是“无法连通主机”，实则多源于SSH 端口转发未生效、JDBC URL 指向错误、或数据库服务监听配置不匹配。
✅ 正确的 SSH + JDBC 连接流程
核心原则：SSH 端口转发后，JDBC 应连接 localhost（而非远程数据库主机名）。
你当前代码中的关键错误在于：
int assignedPort = session.setPortForwardingL(localPort, serverHost, remoteSSHPort); String url = "jdbc:mariadb://" + serverHost + ":" + assignedPort + "/" + database; // ❌ 错误！
此处 serverHost 是数据库服务器的真实内网地址（如 10.10.5.20），但 SSH 端口转发建立的是 本地回环隧道：localhost:localPort → serverHost:3306。因此 JDBC 必须连接 localhost，否则流量不会进入 SSH 隧道，而是直连 serverHost（该地址在客户端网络不可达）。
✅ 正确写法如下：
在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。
// 1. 建立 SSH 会话（你的原有逻辑已正确）
JSch jsch = new JSch();
jsch.setKnownHosts(System.getProperty("user.home") + "/.ssh/known_hosts");
jsch.addIdentity("/path/to/private_key");
Session session = jsch.getSession(sshUserName, sshServer, sshPort); // 注意：sshPort 是跳板机 SSH 端口（如 22），非数据库端口！
session.setConfig("StrictHostKeyChecking", "yes");
session.connect();
// 2. 设置本地端口转发：将本机 localPort 映射到远程数据库 serverHost:3306
// ⚠️ 关键：remoteSSHPort 应为数据库端口（3306），不是 SSH 端口！
int forwardedPort = session.setPortForwardingL(0, "127.0.0.1", 3306); // 使用 0 让系统自动分配可用端口
System.out.println("Local port forwarded to DB: " + forwardedPort);
// 3. JDBC 连接必须指向 localhost + 自动分配的端口
String jdbcUrl = "jdbc:mariadb://localhost:" + forwardedPort + "/" + database
+ "?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC";
Properties props = new Properties();
props.setProperty("user", userSQL);
props.setProperty("password", passwordSql);
props.setProperty("connectTimeout", "5000");
props.setProperty("socketTimeout", "30000");
Connection conn = DriverManager.getConnection(jdbcUrl, props);
System.out.println("✅ Successfully connected via SSH tunnel!");? 常见陷阱与排查要点
| 问题现象 | 根本原因 | 解决方案 |
|---|---|---|
Socket fail to connect to host |
JDBC URL 中 host 写成 serverHost 而非 localhost
|
强制使用 localhost 或 127.0.0.1
|
Connection refused |
数据库未监听 0.0.0.0:3306，仅监听 127.0.0.1:3306（本地回环） |
修改 MariaDB 配置 bind-address = 0.0.0.0 并重启；或确认 serverHost 是跳板机可访问的内网地址 |
Access denied for user |
数据库用户未授权从跳板机 IP 或 % 主机登录 |
执行 GRANT ALL ON *.* TO 'user'@'%' IDENTIFIED BY 'pwd'; FLUSH PRIVILEGES;
|
Unknown initial character set index |
JDBC 驱动版本与 MariaDB 不兼容 | 升级至 mariadb-java-client:3.1.4+，并显式指定 characterEncoding=utf8mb4
|
| SSH 连接成功但端口转发失败 |
setPortForwardingL() 返回 0 或抛异常 |
检查跳板机是否允许 TCP 转发（AllowTcpForwarding yes in /etc/ssh/sshd_config） |
? 补充建议：增强健壮性
-
资源管理：务必在使用完毕后关闭连接与 SSH 会话：
conn.close(); session.disconnect();
-
超时控制：在 JDBC URL 中添加
connectTimeout和socketTimeout，避免阻塞。 -
DBeaver 对比验证：DBeaver 的 SSH 隧道配置中，“Database Host” 填写的是
localhost（对应本地转发端口），而非远程数据库主机名——这正是你代码需对齐的关键点。
通过严格遵循“SSH 转发 → 本地回环连接 → 正确 JDBC 参数”三步范式，即可稳定实现 Java 应用安全访问隔离网络中的 MariaDB 实例。
立即学习“Java免费学习笔记（深入）”；
