DBeaver SSH 隧道配置不生效怎么办：SSH 页、localhost 与端口转发核对

不少场景下远程数据库只会开放跳板机的访问权限，你在DBeaver里开了SSH隧道选项，不代表后续数据库连接就默认走这条隧道。最常见的两个配置坑是：SSH标签页信息全填对了，结果Main主页面还留着远端数据库的公网地址；或是你用自定义JDBC URL连的时候，忘了手动配置端口转发规则。碰到“隧道测试显示成功，但死活连不上数据库”的情况，照着下面的界面项逐项核对，比你反复试密码换密钥效率高得多。

排查核心逻辑：先验证SSH隧道本身连通正常，再改主页面数据库地址为localhost走转发，手动JDBC连接额外核对端口映射。

DBeaver 报错时先区分是哪一段连接失败

SSH隧道本身是一条独立的中间通道，数据库连接是跑在这条通道里的第二段连接，两段故障的表现完全不一样：SSH主机、端口或者密钥填错，通常在建立隧道的阶段就会直接报错；隧道能正常建立，但数据库驱动返回连接拒绝，大概率是Main页的Host、端口、数据库监听地址或者驱动参数配错了。

你可以先把问题拆成三个独立的检查点逐个确认：

SSH 页的设置入口和关键开关怎么填

打开 DBeaver 的新建连接窗口，点击连接配置区域的加号，选择 SSH。顶部出现 SSH 标签后，先勾选 Use SSH Tunnel，再填写 SSH 服务器的 Host/IP、Port 和 User name。默认 SSH 端口是 22，但生产环境经常会改成自定义端口，不能只凭习惯填写。

认证方式通常有 Password、Public Key 和 Agent。选择 Public Key 时，私钥路径和口令要指向 SSH 账户实际使用的密钥；选择 Agent 时，先确认本机的 ssh-agent 或对应代理已经启动。这里要注意，填的是SSH登录的凭据，不是数据库用户的密码，两个填反了的报错表现很像数据库连接失败，很容易误导排查方向。

SSH 页填写完成后点击 Test tunnel configuration。只有隧道测试通过，才值得继续排查数据库驱动和SQL层的问题；如果这里已经失败，应先处理主机可达性、密钥权限、跳板机或SSH服务端配置的问题。

Main 页为什么通常要改成 localhost

隧道建立完成后，DBeaver 会把远端数据库端口转发到本机的某个临时端口，数据库连接请求需要从本机的这个端口进入已经建立好的通道。因此官方的标准配置步骤要求在 Main 页把 Host 设置为 localhost。如果这里仍然写着只能在服务器内网访问的远端地址，DBeaver 会直接绕开隧道发起请求，结果自然还是连接超时或者被防火墙拦截。

数据库 Port 要看连接类型：普通连接可以让 DBeaver 自动选择本地转发端口；如果是 PostgreSQL、MySQL 等常规连接，重点是确认远端服务实际监听的端口，测试连接的时候留意有没有出现本机端口占用的提示，绝对不要把 SSH 服务端口 22 误填成数据库端口。

有个很容易踩的坑：SSH隧道测试成功，只能证明你本机可以正常登录SSH服务器，不代表远端的数据库进程正在正常运行监听，也不代表当前数据库账号有对应访问权限。数据库服务未启动、监听在仅限内网访问的网卡、账号被限制登录来源地址，都会在第二层数据库连接的时候报错。

JDBC URL 连接下，端口转发要手动对齐

手动填写 Host 和 Port 时，DBeaver 通常可以自动把远端端口映射到随机本地端口。但使用自定义复杂JDBC URL时，软件没办法安全替换URL内部写死的端口号，这时候你要打开 Advanced settings 面板，手动显式填写 Local Port 和 Remote Port 两个参数。

例如远端 PostgreSQL 监听 5432，你可以让 Local Port 也使用 5432；如果本机本地已经有PostgreSQL服务占用了这个端口，就换一个没人用的空闲本地端口，例如 15432，Remote Port 还是保持远端数据库实际监听的 5432。两者不是必须相同，只要分别对应“本机侧的入口端口”和“远端服务的实际端口”就行。

本机 DBeaver: localhost:15432
SSH 隧道:     localhost:15432  ->  db.internal:5432
远端数据库:   db.internal:5432

如果端口转发填写后还是连不上，先拿本机的端口扫描工具或者netstat检查 15432 有没有被其他进程占用，再去跳板机上核对远端数据库是不是真的在监听 5432。不要为了临时连通就随便勾选绕过SSH主机身份验证的选项，这会直接削弱SSH隧道的安全性，不能当作常规的修复手段。

Jump server 和共享隧道该怎么判断

本机没办法直接访问目标SSH主机，但可以先访问一台网关机的场景下，展开 Jump servers 配置项，先配置好网关信息，再配置目标主机信息。整条链路应该是“本机 → Jump server → 目标 SSH 主机 → 数据库”，少了任何一段都会在对应节点上报错。

同一SSH配置下要连多个数据库的时候，DBeaver 支持共享已经建好的隧道。共享隧道的判定条件包含SSH主机名、SSH端口、用户名以及所选认证方式；只要其中一项不一样，DBeaver 就会尝试新建一条独立的隧道。碰到一个连接正常、另一个连接失败的情况，不要光数开了多少条隧道，要逐行比对两条连接的SSH配置项是不是完全一致。

保存后用一条可重复的验收路径收尾

1. 在 SSH 页再次点击 Test tunnel configuration，确认认证和整条链路都正常。
2. 回到 Main 页确认 Host 是 localhost，数据库端口对应远端服务，而不是 SSH 的 22 端口。
3. 点击 Test Connection，区分是驱动报错、数据库账号密码错误还是远端端口拒绝连接。
4. 执行一条简单的只读查询，比如读取当前数据库版本，确认连接确实落到了你要访问的目标实例上。
5. 记录下你配置的本地端口；如果后续碰到端口冲突的问题，直接换个空闲本地端口，保持 Remote Port 不变就行。

如果只是临时排查故障，可以先关掉共享隧道、用明确的固定本地端口完成验证，之后再考虑要不要恢复共享配置。回退配置的时候不要直接删掉整个SSH配置页，先取消 Use SSH Tunnel 选项保存一份旧的连接设置，方便后面对比前后配置的差异。

常见问题

Test tunnel configuration 成功，Test Connection 仍然失败怎么办？

先检查 Main 页 Host 是不是已经改成 localhost，再检查数据库服务是不是正常监听远端端口。隧道成功只代表 SSH 链路是通的，不代表数据库服务本身和数据库账号权限没有问题。

为什么 SSH 端口是 22，数据库端口却不能填 22？

22 是 SSH 服务自己的端口，数据库通常监听 3306、5432 这类独立端口。SSH 负责搭建加密通道，数据库端口是通道里最终要访问的目标服务端口，两者职责完全不同。

Local Port 和 Remote Port 必须设置成一样吗？

不必须。本机已有服务占用远端数据库的常用端口时，可以随便换一个空闲的 Local Port，Remote Port 还是填写远端数据库实际监听的端口就可以。

结语

DBeaver SSH 隧道排错的关键不是反复试密码改配置，而是把 SSH 通道、数据库目标和端口转发三个环节拆开逐个验证。先把 SSH 页的隧道测试跑通，再把主页面地址改成 localhost 访问远端数据库；只有用自定义JDBC URL或者碰到本地端口冲突的场景时，再重点调整 Advanced settings 里的端口映射配置。这样每一步都有明确的状态反馈，出了问题也很容易回退定位原因。