快速开始
本页帮助你完成三件事：
- 安装 DBX 或启动 Docker 版本
- 创建并测试第一个数据库连接
- 在需要参与开发或本地调试时从源码运行 DBX
选择安装方式
使用 Homebrew 安装：
brew install --cask dbx之后可用以下命令更新：
brew upgrade --cask dbx也可以从 GitHub Releases 下载 .dmg 安装包。
使用 Scoop 安装：
scoop bucket add dbx https://github.com/t8y2/scoop-bucket
scoop install dbx之后可用以下命令更新：
scoop update dbx也可以从 GitHub Releases 下载 .msi 安装包。
使用 Flatpak 从 FlatPark 安装（适用于任意发行版）：
flatpak remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo
flatpak install flatpark com.dbxio.dbx之后可用以下命令更新：
flatpak update com.dbxio.dbx银河麒麟 V10、统信 UOS 等系统推荐通过星火应用商店安装，并选择 APM 版本。AmberPM 提供兼容运行环境，可减少发行版依赖差异导致的安装或启动问题，后续也可直接在星火应用商店客户端中获取更新。
APM 版本在兼容环境中运行 DBX。如果为 Agent/JDBC 驱动选择宿主机 Java，需要在路径前添加 /host，例如将 /usr/bin/java 填写为 /host/usr/bin/java。
也可以从 GitHub Releases 下载对应安装包：
| 格式 | 适用场景 |
|---|---|
.deb | Debian、Ubuntu 及兼容发行版 |
.rpm | Fedora、 CentOS、 SUSE 及兼容发行版 |
.AppImage | 通用 Linux 桌面环境 |
如果使用 .AppImage，首次运行前可能需要添加执行权限：
chmod +x DBX*.AppImageDocker 版本适合部署在服务器上，并通过浏览器访问：
docker run -d \
--pull=always \
--name dbx \
-p 4224:4224 \
-v dbx-data:/app/data \
t8y2/dbx:latestlatest 标签会拉取当前发布版本。这里使用跨平台的 dbx-data 命名卷；中国大陆用户可改用 docker.cnb.cool/dbxio.com/dbx:latest，以获得更快的拉取速度。
环境变量
Docker 镜像支持以下启动参数。使用 -e 变量名=值 指定，例如生产环境可添加 -e DBX_PASSWORD=your-password：
| 参数 | 默认值 | 用途 |
|---|---|---|
DBX_PASSWORD | 未设置 | Web 登录密码，生产环境建议设置 |
DBX_DISABLE_PASSWORD | false | 设为 true 或 1 可关闭登录保护 |
DBX_DATA_DIR | /app/data | 持久化数据目录 |
DBX_PORT | 4224 | 容器内监听端口 |
DBX_PUBLIC_BASE_PATH | / | 子路径部署，例如 /dbx |
启动后访问 http://localhost:4224。
deploy/docker-compose.yml 用于构建当前源码。若要部署已发布镜像，请使用 deploy/docker-compose.release.yml：
docker compose -f deploy/docker-compose.release.yml up -dservices:
dbx:
image: t8y2/dbx:latest
# 中国大陆用户可改用 CNB 镜像，以加快拉取速度：
# image: docker.cnb.cool/dbxio.com/dbx:latest
pull_policy: always
ports:
- "4224:4224"
volumes:
- dbx-data:/app/data
restart: unless-stopped
volumes:
dbx-data:桌面版还是 Docker
| 模式 | 适合场景 | 存储位置 | 需要注意 |
|---|---|---|---|
| 桌面版 | 本机日常工作、本地数据库文件、完整工作台 | 本机应用数据目录 | 支持本地 SQL 文件树/SQL 库、桌面 Deep Link 和操作系统文件集成 |
| Docker / Web | 服务器自托管、远程浏览器访问 | Docker 卷或服务器数据目录 | 文件路径属于服务器；部分本地文件和桌面集成功能不可用 |
桌面版和 Web 版共享大部分数据库工作流和 Rust 核心能力，但并非所有本地集成完全一致。需要 SQLite、DuckDB、Access、外部 SQL 文件或本机目录时，先确认文件实际位于哪台机器；Docker 中通常还需要把目录挂载进容器。
创建第一个连接
打开新建连接
在侧边栏或工具栏中点击 新建连接。
选择数据库类型
选择 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、Easysearch、Meilisearch、DM、GaussDB、openGauss、TDengine 和 Access。保存前请检查解析出的字段。
测试并保存
点击 测试 验证账号、网络和权限。测试通过后保存连接，并从侧边栏打开。
降低生产误操作
- 给生产连接起明确名称，例如
prod-orders，并使用颜色、分组和备注说明用途。 - 查询专用连接同时启用数据库只读账号和 DBX 只读连接。
- 启用生产环境保护，按连接或指定数据库标记生产范围；写入时 DBX 会逐次要求明确确认。
- 一个服务器上数据库或 Schema 很多时，只显示当前需要的对象，减少误选目标。
- 对编辑、导入、传输、SQL 文件执行或 Schema 同步生成的 SQL，先审查再执行。
- 提供给 MCP 的连接使用 allowlist，并优先选择“只读”或“数据读写”，不要默认开放“完全访问”。
完整行为和推荐配置见 生产环境与写入安全。
下一步可以做什么
常见连接问题
| 现象 | 检查项 |
|---|---|
| 连接超时 | 主机、端口、防火墙、安全组、VPN、Docker 主机网络或内网访问权限 |
| 认证失败 | 用户名、密码、认证方式、SSL 要求、账号是否允许远程登录 |
| 能连接但看不到表 | 默认数据库、Schema、权限、元数据读取权限、可见数据库过滤 |
| 文件数据库打不开 | 文件路径、文件权限、Docker volume 挂载、文件扩展名是否支持 |
| 内网数据库无法访问 | 配置隧道/代理、VPN，或让 Docker 部署机器能访问目标数据库 |
从源码运行
当你想参与开发或本地调试 DBX 时，可以从源码运行。
第一次参与开发请阅读从源码编译与参与贡献。教程包含各系统环境安装、Fork、Issue 认领、测试和提交 PR 的完整步骤。
环境要求
系统依赖
bash brew install unixodbc bash sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev librsvg2-dev patchelf libssl-dev unixodbc-dev 安装 Strawberry Perl（编译内置 OpenSSL 所需）：
winget install StrawberryPerl.StrawberryPerlDBX 默认启用 sqlite-sqlcipher 特性，需要从源码编译 SQLCipher 和 OpenSSL，而 Windows 上编译 OpenSSL 必须使用 Perl 执行 Configure 脚本。安装后请重新打开终端，使 perl 进入 PATH。
启动开发环境
git clone https://github.com/t8y2/dbx.git
cd dbx
makemake 会在需要时安装根目录依赖，并启动本地 Tauri 桌面端开发环境。
Web 版本：
make dev-web
make dev-backend构建桌面安装包
make package桌面安装包会输出到 target/release/bundle/。