Java 通过 SSH 隧道安全连接远程 MariaDB 数据库的完整实践指南-java教程-PHP中文网

Java 通过 SSH 隧道安全连接远程 MariaDB 数据库的完整实践指南

本文详解如何在 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 接口排错助手

在调试 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 实例。