MagicDB Studio 标志 MagicDB Studio 内测版
文档/ 连接管理/ 高级连接配置
Connection Management

高级连接配置

从网络入口、加密边界到 JDBC 驱动与超时策略，逐项验证复杂数据源连接。

适用场景

当数据库不在本机、不能直接暴露端口，或需要使用厂商驱动时，应在保存连接前完成高级配置。典型场景包括：

  • 数据库位于内网，需要先通过跳板机建立 SSH 隧道。
  • 数据库服务端要求 SSL 加密，或要求客户端证书参与双向校验。
  • 内置驱动不适配目标版本，需要从驱动模板下载，或加载管理员提供的本地 .jar。
  • 同一实例包含多个数据库、服务名或 Schema，需要按目标数据库类型填写对应标识。
  • 开发、测试与生产连接并存，需要用环境标签降低误操作概率，并为不稳定链路调整连接超时。
边界说明：不同数据库的 JDBC 参数并不一致。MySQL 的数据库名、Oracle 的服务标识、SQL Server 的数据库选择等不能机械套用；端口默认值也可能被服务端修改。请以实例管理员提供的信息和对应驱动文档为准。

入口路径

打开 MagicDB Studio 的「连接中心」，选择「新建连接」并先确定数据库类型；编辑已有连接时，从连接中心对目标连接执行编辑操作。基础区域用于名称、主机、端口、数据库与凭据，高级区域用于 SSH、SSL 及其他可用选项。

新建连接 · MySQL
MagicDB Studio 新建 MySQL 连接表单，包含主机、端口、数据库和高级配置入口
连接配置入口：先选择数据库类型，再填写该类型对应的主机、端口、数据库与认证信息；高级页签用于 SSH 和 SSL 等连接边界。

连接驱动需要补充或替换时，进入「驱动中心」浏览对应 JDBC 模板，或按实际需要上传本地驱动文件。不要在尚未确认数据库类型和版本时随意替换驱动。

前置条件

  • 从数据库管理员处确认真实主机名或 IP、监听端口、目标数据库标识、账号及认证方式。
  • 从客户端所在机器确认 DNS、VPN、防火墙与网络路由可达；使用 SSH 时，另行确认跳板机地址、端口、用户名以及密码或私钥。
  • 使用 SSL 时，确认服务端是否只要求加密传输，还是还要求校验 CA、服务端名称或客户端证书；按要求准备证书文件。
  • 使用本地 JAR 时，确认文件来源、数据库与驱动版本兼容性，并保留原驱动配置以便回退。
  • 准备一条低风险验证路径，例如只读账号、测试数据库或简单查询；生产连接先核对环境标签，避免把试验操作落到生产实例。
先确认再配置：SSH 只解决客户端到数据库网络入口的问题，SSL 保护的是数据库协议链路；二者用途不同，启用其中一个不代表自动满足另一个边界。

编号步骤

  1. 选择数据库类型并核对目标。在新建或编辑连接页面确认数据库类型，填写易识别的连接名称，并用环境标签标记开发、测试或生产。保存前再次核对标签与真实实例是否一致。
  2. 填写网络与数据库参数。输入数据库主机、监听端口和目标数据库标识。不要只接受界面默认值：向管理员确认端口是否改动，并按当前数据库类型判断该字段表示数据库名、服务名或其他标识。
  3. 按网络边界配置 SSH。仅当数据库需要经跳板机访问时启用 SSH，填写跳板机主机、端口、用户名及认证方式。使用私钥时确认选中正确文件；数据库主机应按隧道建立后的访问关系填写，不要把跳板机地址误填为数据库地址。
  4. 按服务端策略配置 SSL。确认是仅加密、校验服务端证书，还是双向证书认证，再填写 CA、客户端证书与私钥等对应材料。不要为绕过证书错误而盲目降低校验要求，应先排查证书链、主机名与有效期。
  5. 确认驱动来源。优先检查驱动中心是否已有匹配模板；模板不满足目标版本或厂商要求时，再选择经过确认的本地 .jar。上传后核对驱动类与 URL 模板，不要假定不同数据库可共用同一组参数。
  6. 设置超时并预览配置。连接超时应覆盖正常网络握手与隧道建立时间，但不宜无限放大。高延迟链路可逐步增加；若一直超时，先检查 DNS、路由、防火墙、SSH 与服务监听，而不是持续提高数值。
  7. 执行测试连接。点击「测试连接」，确认驱动加载、网络、认证和目标数据库均通过。失败时记录原始错误阶段，逐层修正后重试；测试成功后再保存。
  8. 保存后做低风险验证。从连接中心打开该连接，确认对象树指向预期实例与数据库。对生产环境先执行只读检查，再开始实际工作；如果看到的对象或环境不符，立即断开并返回配置页复核。
驱动中心 · MySQL JDBC 模板
MagicDB Studio 驱动中心中的 MySQL JDBC 驱动模板与驱动管理界面
驱动中心：查找和下载 JDBC 驱动模板，或根据目标数据库要求管理本地 .jar；选择前应核对数据库类型与版本。

参数说明

参数组填写与检查重点边界与风险
主机填写数据库服务可解析的主机名或 IP；经 SSH 时按隧道后的访问关系确认。不要混淆数据库主机与跳板机；容器、VPN 和内网 DNS 下的地址可能只在特定网络可达。
端口使用实例实际监听端口，并与防火墙放行规则核对。默认端口只是常见值，不代表服务端没有修改，也不代表网络已放行。
数据库 / 服务标识按所选数据库类型填写数据库名、服务名或界面要求的目标标识。各数据库语义不同；不要复制另一种数据库的填写方式。
用户名与密码使用具备所需最小权限的账号；测试后确认实际登录身份。认证通过不等于拥有目标对象权限；导入配置后通常仍需补充凭据。
SSH 隧道配置跳板机地址、SSH 端口、用户，以及密码或私钥认证。SSH 负责网络转发，不替代数据库账号认证，也不自动开启数据库 SSL。
SSL按服务端策略选择加密和证书材料，校验证书链及主机名要求。不同驱动支持项与参数名可能不同；证书错误应定位原因，不应默认忽略校验。
驱动模板在驱动中心选择与数据库类型及版本相符的 JDBC 模板，并核对 URL 结构。模板提供常用起点，不保证适配每个厂商版本或部署形态。
本地 JAR仅加载来源明确、兼容性已确认的 .jar，保留版本记录与回退路径。错误版本可能导致驱动类找不到、握手失败或参数不兼容。
连接超时根据局域网、VPN、SSH 和跨地域延迟设置合理等待时间，并通过测试连接验证。过短会误判失败，过长会掩盖网络或地址错误并延迟反馈。
环境标签明确标记开发、测试、生产，并让名称与实例用途相互印证。标签是操作提示，不是权限隔离；生产保护仍依赖账号权限和操作确认。

预期结果

配置完成后，应同时满足以下检查，而不只是看到一次“测试成功”：

  • 「测试连接」在预期耗时内成功，且没有驱动加载、隧道、证书或认证错误。
  • 连接中心显示正确名称、数据库类型与环境标签，生产连接不会与测试连接混淆。
  • 打开连接后，对象树中的实例、数据库或 Schema 与目标一致，而不是同一主机上的其他环境。
  • 只读验证可正常执行，权限范围符合账号用途；需要写入时，再按团队流程确认目标环境和备份策略。
  • 重启应用或重新连接后仍能建立会话，避免把一次性的网络状态误认为长期配置正确。
验收建议：记录数据库类型、驱动来源、网络路径、SSL 要求、超时值和环境标签。后续连接异常时，可先比较这些基线，而不是直接重建连接。

常见问题

1. 测试连接超时，应该直接把超时设得很大吗？

不建议。先确认主机与端口、DNS、VPN、防火墙和数据库监听；启用 SSH 时，再确认跳板机本身可达、认证有效且转发目标正确。只有链路确实高延迟时，才逐步增加超时并记录可接受范围。

2. SSH 登录成功，为什么数据库仍连接失败？

SSH 成功只代表到跳板机的隧道入口可用。继续检查从跳板机视角可达的数据库主机与端口、数据库账号认证、目标数据库标识，以及数据库服务是否限制来源地址。

3. 启用 SSL 后提示证书或主机名错误，如何处理？

核对 CA 与客户端证书是否对应当前实例、证书是否在有效期内、连接主机名是否符合证书声明，并确认服务端要求的是单向还是双向认证。不要把关闭校验当作默认解决方案。

4. 已上传本地 JAR，仍提示找不到驱动类或 URL 不兼容怎么办？

核对 JAR 是否为目标数据库对应的 JDBC 驱动、版本是否支持当前服务端，并检查驱动类名和 URL 模板。必要时回到驱动中心对照已有模板；保留原配置，避免在未验证时覆盖可用驱动。

5. 测试成功，但展开对象树后数据库不对怎么办？

立即断开连接，复核数据库或服务标识、账号默认数据库以及连接 URL 中的目标参数。随后重新测试，并用对象树和只读查询双重确认实例身份；生产环境不要在目标不明时继续操作。