# 驱动管理

> 管理内置驱动、原生 Agent 和 JDBC Agent，配置 JRE 版本并处理驱动更新。

Source: https://dbxio.com/cn/docs/driver-management

Language: zh-CN

Relative links resolve against https://dbxio.com/cn/docs/driver-management.



DBX 使用混合驱动架构：内置 Rust 驱动、独立原生 Agent，以及 Java/JDBC Agent。

## 驱动架构

| 驱动类型            | 工作方式                          | 适用场景                                                                                                                          |
| --------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 原生（内置）          | Rust 驱动编译进 DBX                | MySQL、PostgreSQL、SQLite、SQL Server、Redis、MongoDB、ClickHouse 等                                                                 |
| 原生 Agent / 外部驱动 | DBX 管理的 Go/Rust 独立进程或 sidecar | Oracle、KingbaseES、虚谷 XuguDB、DuckDB，以及 RabbitMQ 等需要独立运行时的连接                                                                    |
| JDBC Agent      | DBX 管理的 Java 子进程              | 需要 JDBC 的数据库：GaussDB、openGauss、DM、HighGo、Vastbase、UXDB、Trino、Hive、DB2、Informix、Neo4j、TDengine、YashanDB、GoldenDB、Kylin、SunDB 等 |

内置驱动可直接使用；原生 Agent/sidecar 需要对应平台文件，JDBC Agent 还需要 JRE。连接对话框会提示缺少的组件，但安装是否自动完成取决于网络、平台、驱动许可和当前设置。

## 内置驱动

驱动管理的**内置驱动**标签页列出所有可用的 Agent 驱动及其状态：

* **已安装驱动**：版本号、大小和更新可用性
* **可用驱动**：可一键安装的驱动
* **更新角标**：注册中心有新版本时显示

从顶部工具栏打开**驱动管理**（可在 设置 → 工具栏 中控制该按钮显隐），或点击创建需要 Agent 驱动的连接时出现的驱动提示。

## 安装驱动

### 打开驱动管理

从顶部工具栏打开**驱动管理**，或点击连接对话框中的驱动安装提示。

### 选择驱动

找到所需的数据库驱动。每个条目显示支持的数据库和驱动版本。

### 点击安装

DBX 会下载原生 Agent 可执行文件或 JDBC Agent JAR，以及所需运行时。下载过程中显示进度。

### 创建连接

返回连接对话框。驱动此时即可使用。

## JRE 管理

JDBC Agent 驱动需要 Java 运行环境。DBX 内置 JRE 管理：

* **系统 JRE**：DBX 可使用系统上已有的 Java 安装
* **托管 JRE**：DBX 可下载并管理自己的 JRE，与系统 Java 隔离
* **多 JRE 支持**：不同驱动可按需使用不同 JRE 版本
* **重新安装**：如托管 JRE 损坏，可在**内置驱动**标签页顶部的 Java 运行时区域重新安装

## 驱动更新

DBX 会定期检查驱动更新：

* 有新版本时，**内置驱动**标签页中会显示更新角标
* 点击**升级全部驱动**一次性更新所有已安装的驱动
* 单个驱动可从商店中对应条目升级

## 运行时监控

驱动管理会汇总正在运行的外部驱动和 Agent，包括协议模式、活动 Session、PID、内存、CPU、运行时长和最后错误。支持控制的运行时可以在这里停止或重启；共享运行时可能服务多个连接，操作前应检查活动 Session。

RabbitMQ 等消息队列 Agent 还可能同时使用业务协议和管理 API。自定义 AMQP/管理端口、SSH 隧道和 TLS 目标必须分别配置，不能从一个端口推断另一个端口。

## 离线驱动导入

对于无法访问互联网的环境，DBX 支持离线驱动安装：

1. 从另一台机器下载与目标操作系统和 CPU 架构匹配的 DBX 离线驱动 ZIP 包
2. 将其传输到离线机器
3. 在驱动管理中使用**导入离线包**安装驱动包

这适用于气隙网络、严格防火墙环境或企业中预先批准的驱动版本。

所有 Agent 都提供单驱动 ZIP，可直接使用**导入离线包**安装。Java Agent 的单驱动包跨平台，但不重复携带 JRE；KingbaseES、Oracle、Xugu 等原生 Agent 的单驱动包按操作系统和 CPU 架构区分。

如果目标机器尚未安装 Java Agent 所需的托管 JRE，可在**导入离线包**中选择对应平台的 `dbx-jre-<jre-key>-<platform>.tar.zst`（例如 `dbx-jre-21-macos-aarch64.tar.zst`），或者直接使用包含全部驱动和 JRE 的完整离线 ZIP 包。独立 JRE 包仅包含 Java 运行时，不包含数据库驱动，也不需要 `agent-registry.json`。DBX 会验证 Java 的操作系统和 CPU 架构后安装到托管 JRE 目录。

### Windows 导入 KingbaseES

Windows x64 下载 `dbx-agent-kingbase-<version>-windows-x64.zip`，Windows ARM64 下载 `dbx-agent-kingbase-<version>-windows-aarch64.zip`，然后在驱动管理中选择**导入离线包**。请勿导入 Linux 或 macOS 包。

ZIP 内包含版本信息和对应平台的原生 Agent。DBX 会将其安装为 `%USERPROFILE%\.dbx\agents\drivers\kingbase\agent.exe`，不需要手动解除浏览器下载文件的阻止状态或复制文件。

### 离线导入 JDBC 插件

通用 JDBC 连接（自定义 JDBC URL + 导入的驱动 JAR）通过独立的 **DBX JDBC 插件** 运行，发布为单独的 `dbx-jdbc-plugin-*.zip` 资源，**不会**打进各数据库的 Agent ZIP。请在 **JDBC 驱动** 页签使用 **本地安装** 安装它（不要用内置驱动里的**导入离线包**，那是给 Agent ZIP 用的）。

导入真正的驱动 JAR（例如 Oracle 的 `ojdbc*.jar`）始终是本地操作，不需要这个插件包，也不需要网络——在同一页签使用 **导入 JAR**，无论 JDBC 插件本身是否已安装。

## 插件更新

对于由 [JDBC 插件](/cn/docs/plugins)支持的数据库，当有新插件版本可用时，DBX 会显示更新通知。插件更新遵循与内置 Agent 驱动相同的安装流程。

## 故障排除

| 问题          | 解决方案                                  |
| ----------- | ------------------------------------- |
| 驱动下载失败      | 检查网络连接和防火墙规则。尝试离线导入方法。                |
| Agent 无法启动  | 在驱动管理中验证 JRE 安装。如需要，重新安装托管 JRE。       |
| 驱动安装后连接测试失败 | 确认 JDBC URL 格式与驱动的预期格式匹配。检查 SSH/代理设置。 |
| 驱动版本错误      | 卸载当前驱动并从商店安装正确版本。                     |