DBX

安装 DBX、创建第一个连接，并了解桌面版、Docker 版和源码运行方式。

本页帮助你完成三件事：

安装 DBX 或启动 Docker 版本
创建并测试第一个数据库连接
在需要参与开发或本地调试时从源码运行 DBX

选择安装方式

使用 Homebrew 安装：

brew install --cask t8y2/tap/dbx

之后可用以下命令更新：

brew upgrade --cask t8y2/tap/dbx

也可以从 GitHub Releases 下载 .dmg 安装包。

使用 Scoop 安装：

scoop bucket add dbx https://github.com/t8y2/scoop-bucket
scoop install dbx

之后可用以下命令更新：

scoop update dbx

也可以从 GitHub Releases 下载 .msi 安装包。

从 GitHub Releases 下载对应安装包：

格式	适用场景
`.deb`	Debian、Ubuntu 及兼容发行版
`.AppImage`	通用 Linux 桌面环境

如果使用 .AppImage，首次运行前可能需要添加执行权限：

chmod +x DBX*.AppImage

Docker 版本适合部署在服务器上，并通过浏览器访问：

docker run -d \
  --name dbx \
  -p 4224:4224 \
  -v dbx-data:/app/data \
  t8y2/dbx

启动后访问 http://localhost:4224。

Docker Compose：

services:
  dbx:
    image: t8y2/dbx
    ports:
      - "4224:4224"
    volumes:
      - dbx-data:/app/data
    restart: unless-stopped

volumes:
  dbx-data:

桌面版还是 Docker

模式	适合场景	后端路径	存储位置
桌面版	本机日常工作、本地文件、原生窗口、从 MCP 打开 DBX 界面	Tauri 命令调用 Rust core	本机应用数据目录
Docker / Web	服务器自托管、浏览器访问	HTTP 路由调用同一套 Rust core	Docker volume 或服务器数据目录

核心数据库能力保持一致，但通过 MCP 打开桌面窗口等集成需要 DBX 桌面版正在运行。

创建第一个连接

打开新建连接

在侧边栏或工具栏中点击 新建连接。

选择数据库类型

选择 MySQL、PostgreSQL、SQLite、Redis、MongoDB、DuckDB、ClickHouse、SQL Server、Oracle，或数据库支持中列出的兼容类型、Agent/JDBC 类型。

填写连接信息

网络数据库需要填写主机、端口、用户名、密码和必要的默认数据库。SQLite、DuckDB、Access 这类文件型数据库需要选择本地数据库文件，不填写主机和端口。

有 URL 时直接粘贴

DBX 可以解析常见连接 URL，例如 MySQL、PostgreSQL、Redis、MongoDB、ClickHouse、SQL Server、Oracle、Elasticsearch、DM、GaussDB、openGauss、TDengine 和 Access。保存前请检查解析出的字段。

配置网络选项

如果数据库在内网或跳板机后面，可以启用 SSH 隧道。如果网络环境要求 SOCKS5 或 HTTP 代理，可以在代理页签中配置。

测试并保存

点击测试验证账号、网络和权限。测试通过后保存连接，并从侧边栏打开。

连接密码、SSH 密码、SSH 密钥密码和连接字符串会与普通连接 JSON 分开存储在 DBX 本地数据中。需要迁移加密连接配置时，使用配置导出/导入。

降低生产误操作

给生产连接起明确名称，例如 prod-orders。
用连接颜色区分生产、预发、测试和本地环境。
一个服务器上数据库很多时，只显示当前需要的数据库。
对编辑、导入、传输、SQL 文件执行或 Schema 同步生成的 SQL，先审查再执行。

下一步可以做什么

写 SQL

使用补全、格式化、选中执行、取消执行和查询历史。

看数据

查看结果、在安全时编辑行、预览 SQL 并导出数据。

看结构

浏览数据库、Schema、表、字段、Redis 键和 MongoDB 集合。

常见连接问题

现象	检查项
连接超时	主机、端口、防火墙、安全组、VPN、Docker 主机网络或内网访问权限
认证失败	用户名、密码、认证方式、SSL 要求、账号是否允许远程登录
能连接但看不到表	默认数据库、Schema、权限、元数据读取权限、可见数据库过滤
文件数据库打不开	文件路径、文件权限、Docker volume 挂载、文件扩展名是否支持
内网数据库无法访问	配置 SSH 隧道、代理、VPN，或让 Docker 部署机器能访问目标数据库

从源码运行

当你想参与开发或本地调试 DBX 时，可以从源码运行。

环境要求

Node.js >= 18
pnpm
Rust >= 1.77

系统依赖

brew install unixodbc

sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev librsvg2-dev patchelf libssl-dev unixodbc-dev

Windows 通常不需要额外安装系统依赖。

启动开发环境

git clone https://github.com/t8y2/dbx.git
cd dbx
pnpm install
pnpm dev:tauri

Web 版本：

pnpm dev:web
pnpm dev:backend

构建桌面安装包

pnpm tauri build

桌面安装包会输出到 src-tauri/target/release/bundle/。

快速开始