如何通过 SSH 隧道安全连接远程 MariaDB（Java 实现）-java教程-PHP中文网

如何通过 SSH 隧道安全连接远程 MariaDB（Java 实现）

本文详解 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！

✅ 正确做法如下：

明确三元组角色：
- sshServer：跳板机地址（如 jump.example.com），SSH 连接目标；
- databaseHost：MariaDB 实际所在服务器内网地址（如 10.10.5.20 或 db.internal），必须能被跳板机访问；
- databasePort：MariaDB 监听端口（默认 3306）。
建立本地端口转发（Local Port Forwarding）：

Java 接口排错助手
在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。

下载
```
// ✅ 正确：将本地 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() 安全传参。