企业官网建设流程全解析

JumpServer DBeaver 数据库应用 Applet 使用指南：驱动安装与密码代填限制解析

【免费下载链接】jumpserverJumpServer is an open-source Privileged Access Management (PAM) platform that provides DevOps and IT teams with on-demand and secure access to SSH, RDP, Kubernetes, Database and RemoteApp endpoints through a web browser.项目地址: https://gitcode.com/GitHub_Trending/ju/jumpserver

本篇技术指南围绕 JumpServer 内置的DBeaver Community 数据库应用 Applet展开，重点讲解通过 Web 浏览器连接 MySQL、PostgreSQL、SQL Server、Oracle 等数据库时，JDBC 驱动应如何下载/离线预装，以及"代填（autofill）"机制下数据库密码不允许包含|字符的底层原因。读完本文，你将掌握 DBeaver Applet 的安装部署方式、驱动配置方法，并理解密码字符限制的实现原理，从而避免在实际运维中踩坑。

一、DBeaver Applet 在 JumpServer 中的定位

JumpServer 作为开源特权访问管理（PAM）平台，支持通过 Web 浏览器对 SSH、RDP、Kubernetes、数据库与 RemoteApp 端点进行安全访问。其中**数据库应用（Database App）**场景由dbeaverApplet 承载：它在用户本机启动 DBeaver 社区版，并以"代填"方式自动注入数据库账号密码，用户无需接触真实凭据即可完成连接。

Applet 的元信息定义在 manifest.yml 中，关键字段如下：

也就是说，该 Applet 覆盖了当前主流的关系型数据库协议；针对每一种协议，JumpServer 都内置了对应的 JDBC 驱动定义（详见下文第四节）。

二、客户端安装与补丁：setup.yml 与 patch.yml

DBeaver Applet 需要在**用户本机（Windows）**安装 DBeaver 客户端。安装与补丁描述分别位于：

• setup.yml：主程序静默安装
• patch.yml：官方补丁静默安装

主安装脚本内容如下：

type: exe # exe, zip, manual source: jms:///download/applets/dbeaver-ce-22.3.4-x86_64-setup.exe arguments: - /S - /allusers destination: C:\Program Files\DBeaver program: C:\Program Files\DBeaver\dbeaver-cli.exe md5: EDA4440D4E32312DD25C9CE5289A228E

• type: exe：通过可执行文件安装（另有zip、manual、msi等类型）；
• source：安装包来源于 JumpServer 服务器自身的jms:///download/applets/下载通道，对应版本为DBeaver CE 22.3.4（x86_64）；
• arguments：/S静默安装、/allusers为所有用户安装，安装过程无需人工点击；
• destination/program：安装目录与最终启动的可执行文件路径为C:\Program Files\DBeaver\dbeaver-cli.exe，Applet 运行时会直接调用该 CLI 程序（见 app.py 中的_default_path常量）；
• md5：安装包完整性校验值，防止下载被篡改。

补丁脚本 patch.yml 则通过msi类型安装dbeaver-patch-22.3.4-x86_64-setup.msi，参数为/quiet（静默模式），用于对已安装的 DBeaver 进行修复/升级。

实操提示：在 JumpServer 管理后台部署 DBeaver 应用时，这些安装脚本会引导用户完成客户端部署；由于安装与补丁包都托管在 JumpServer 的jms://下载通道，要求服务器端已上传对应安装包。

三、驱动下载：离线预装 or 连接时按提示安装

关联文档明确指出：

连接数据库应用时，需要下载驱动，可提前离线安装或者连接时按提示安装相应驱动。

DBeaver 连接数据库的第一步是加载对应 JDBC 驱动（Driver）。驱动获取有两条路径：

1. 连接时在线下载：DBeaver 在首次连接时根据drivers.xml中声明的 Maven 依赖，从 Maven Central 下载对应的 JDBC JAR 包；
2. 提前离线安装：运维人员预先将驱动 JAR 放入 DBeaver 的drivers目录（如C:\Program Files\DBeaver\drivers），或在 JumpServer 侧准备好内置驱动包，避免用户连接时因网络不可达导致失败。

在源码层面，Applet 启动时会做两类驱动相关初始化（见 app.py）：

• init_driver_config()：将 Applet 自带的 config/drivers.xml合并进用户工作区的workspace6/.metadata/.config/drivers.xml。合并采用"去重追加"策略——_merge_driver_xml会遍历内置 XML 中的每个<driver>，若目标文件不存在相同tag且相同属性的条目，才将其追加进去；若目标文件尚不存在（首次运行），则直接复制内置drivers.xml。该文件位于用户目录下的C:\Users\<用户名>\AppData\Roaming\DBeaverData（由get_app_work_path()计算）。
• init_other_config()：写入org.jkiss.dbeaver.core.prefs，关闭自动更新检查（ui.auto.update.check=false）、取消示例数据库提示（sample.database.canceled=true）与每日提示弹窗（ui.show.tip.of.the.day.on.startup=false），保证代填连接过程不被弹窗干扰。

因此，即便用户本机没有预装驱动，只要能够访问 Maven 仓库（或 JumpServer 已代理相关下载），连接时也会按提示自动拉取；而离线环境下，则建议在客户端预先放好驱动 JAR。

四、内置驱动覆盖范围：drivers.xml 解析

config/drivers.xml 是 Applet 内置的驱动定义文件，共声明 5 个数据库驱动，与manifest.yml中的protocols一一对应：

每个<driver>节点同时声明了library依赖（Maven 坐标、版本与本地 JAR 路径）和license许可文件，DBeaver 启动时据此定位/下载 JAR。若需新增其他数据库类型，可在该 XML 中扩展对应的 provider/driver 节点。

五、密码代填机制与|字符限制

关联文档第二条限制是：

因代填的实现机制，连接的数据库密码不支持使用|字符。

为什么偏偏是|？答案在 Applet 的启动参数构造逻辑中。Applet 以python类型执行，入口 main.py 将 JumpServer 下发的 base64 参数解码为 JSON，随后AppletApplication.run()构造 DBeaver CLI 的-con连接参数串（见 app.py 中_get_exec_params()）：

params_string = f'name={self.name}|' \ f'driver={driver}|' \ f'host={self.host}|' \ f'port={self.port}|' \ f'database={self.db}|' \ f'user={self.username}|' \ f'password={self.password}|' \ f'save=false|' \ f'connect=true'

可以看到，|是各连接参数之间的分隔符：name、driver、host、port、database、user、password、save、connect依序以|拼接后，作为dbeaver-cli.exe -con <params>的参数传入。DBeaver CLI 解析时按|切分键值对——如果密码本身包含|，password=...的值会被提前截断，导致密码解析错误甚至参数错位。这正是"代填实现机制"对密码字符集的硬性约束。

实战建议：为通过 DBeaver Applet 访问的数据库账号设置密码时，请避免使用|字符；其余字符（如@、#、%等）在代填场景中均可正常传递。

六、不同协议下的代填参数差异

run()方法根据self.protocol动态选择参数构造函数，未命中时回退到通用的_get_exec_params()：

• MySQL / MariaDB：_get_mysql_exec_params()在通用参数后追加|prop.allowPublicKeyRetrieval=true，解决 MySQL 8 缓存 SHA-2 密码认证（caching_sha2_password）下Public Key Retrieval is not allowed的经典报错；
• Oracle：_get_oracle_exec_params()在连接选项use_sysdba为真时追加|authProp.oracle.logon-as=sysdba，支持以 SYSDBA 身份登录；
• SQL Server：_get_sqlserver_exec_params()将驱动固定切换为mssql_jdbc_ms_new（对应新版本 JDBC 驱动）后再生成参数。

主机与端口默认取自资产的address与协议端口（asset.get_protocol_port(self.protocol)）；若配置了隧道转发（tinker_forward），则改用隧道的 host/port。连接名称name形如主机地址-数据库名-时间戳，每次连接唯一。

连接建立后，wait()通过wait_pid（见 common.py）每 5 秒调用tasklist轮询 CLI 进程 PID，直到 DBeaver 退出才结束整个 Applet 生命周期；同时main.py在运行期间调用block_input()/unblock_input()临时锁定本机输入，防止代填过程中用户误操作干扰凭据注入。

七、部署与排障要点小结

1. 客户端准备：确保用户本机为 Windows 且已通过 setup.yml / patch.yml 安装 DBeaver CE 22.3.4 及补丁，安装路径保持默认的C:\Program Files\DBeaver。
2. 驱动准备：在线环境下首次连接按提示下载即可；离线/受限网络环境请提前将驱动 JAR 放置到 DBeaverdrivers目录，或通过内置drivers.xml统一管理（config/drivers.xml）。
3. 密码约束：数据库账号密码禁止包含|字符，原因见第五节参数拼接源码。
4. 常见报错对照：
   • MySQL 8 连接报Public Key Retrieval is not allowed：Applet 已自动追加allowPublicKeyRetrieval=true，一般无需手工处理；
   • 连接后弹窗/自动更新干扰：Applet 已通过init_other_config()关闭自动更新与每日提示；
   • 首次连接提示下载驱动失败：检查客户端到 Maven 仓库的网络，或改为离线预装驱动。

通过以上配置，即可在 JumpServer 中以"零接触凭据"的方式安全访问多种数据库。如需进一步阅读 Applet 完整实现，可参考 app.py、common.py 以及同目录下的 README_ZH.md（中文版说明）。

【免费下载链接】jumpserverJumpServer is an open-source Privileged Access Management (PAM) platform that provides DevOps and IT teams with on-demand and secure access to SSH, RDP, Kubernetes, Database and RemoteApp endpoints through a web browser.项目地址: https://gitcode.com/GitHub_Trending/ju/jumpserver