# 快速开始

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

Source: https://dbxio.com/cn/docs/getting-started

Language: zh-CN

Relative links resolve against https://dbxio.com/cn/docs/getting-started.



本页帮助你完成三件事：

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

## 选择安装方式

### macOS

使用 Homebrew 安装：

```bash
brew install --cask dbx
```

之后可用以下命令更新：

```bash
brew upgrade --cask dbx
```

也可以从 [GitHub Releases](https://github.com/t8y2/dbx/releases) 下载 `.dmg` 安装包。

### Windows

使用 Scoop 安装：

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

之后可用以下命令更新：

```bash
scoop update dbx
```

也可以从 [GitHub Releases](https://github.com/t8y2/dbx/releases) 下载 `.msi` 安装包。

### Linux

使用 Flatpak 从 [FlatPark](https://flatpark.org/apps/com.dbxio.dbx/) 安装（适用于任意发行版）：

```bash
flatpak remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo
flatpak install flatpark com.dbxio.dbx
```

之后可用以下命令更新：

```bash
flatpak update com.dbxio.dbx
```

银河麒麟 V10、统信 UOS 等系统推荐通过[星火应用商店](https://spk-resolv.spark-app.store/?spk=spk://store/development/dbx)安装，并选择 **APM 版本**。AmberPM 提供兼容运行环境，可减少发行版依赖差异导致的安装或启动问题，后续也可直接在星火应用商店客户端中获取更新。

APM 版本在兼容环境中运行 DBX。如果为 Agent/JDBC 驱动选择宿主机 Java，需要在路径前添加 `/host`，例如将 `/usr/bin/java` 填写为 `/host/usr/bin/java`。

也可以从 [GitHub Releases](https://github.com/t8y2/dbx/releases) 下载对应安装包：

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

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

```bash
chmod +x DBX*.AppImage
```

### Docker

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

```bash
docker run -d \
  --pull=always \
  --name dbx \
  -p 4224:4224 \
  -v dbx-data:/app/data \
  t8y2/dbx:latest
```

`latest` 标签会拉取当前发布版本。这里使用跨平台的 `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`：

```bash
docker compose -f deploy/docker-compose.release.yml up -d
```

```yaml
services:
  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 中通常还需要把目录挂载进容器。

通过 MCP 打开表或展示查询结果等桌面 UI 工具，需要 DBX 桌面版正在运行。只使用查询类 MCP 工具时，可以直接读取本机 DBX 数据目录，或连接 DBX Web/Docker 后端。

## 创建第一个连接

### 打开新建连接

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

### 选择数据库类型

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

### 填写连接信息

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

### 有 URL 时直接粘贴

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

### 配置网络选项

如果数据库在内网、跳板机后面、只能通过 Web 网关访问，或网络要求 SOCKS5/HTTP 代理，可以配置 [隧道/代理](/cn/docs/ssh-tunnel)。

### 测试并保存

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

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

[配置导出/导入](/cn/docs/config-export)

。

## 降低生产误操作

* 给生产连接起明确名称，例如 `prod-orders`，并使用颜色、分组和备注说明用途。
* 查询专用连接同时启用数据库只读账号和 DBX **只读连接**。
* 启用**生产环境保护**，按连接或指定数据库标记生产范围；写入时 DBX 会逐次要求明确确认。
* 一个服务器上数据库或 Schema 很多时，只显示当前需要的对象，减少误选目标。
* 对编辑、导入、传输、SQL 文件执行或 Schema 同步生成的 SQL，先审查再执行。
* 提供给 MCP 的连接使用 allowlist，并优先选择“只读”或“数据读写”，不要默认开放“完全访问”。

完整行为和推荐配置见 [生产环境与写入安全](/cn/docs/production-safety)。

## 下一步可以做什么

### [写 SQL](/cn/docs/query-editor)

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

### [看数据](/cn/docs/data-grid)

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

### [看结构](/cn/docs/schema-browser)

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

## 常见连接问题

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

## 从源码运行

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

第一次参与开发请阅读[从源码编译与参与贡献](/cn/docs/contributing)。教程包含各系统环境安装、Fork、Issue 认领、测试和提交 PR 的完整步骤。

### 环境要求

* [Node.js](https://nodejs.org/) >= 22.13.0
* [pnpm](https://pnpm.io/) 10.27.0
* Make（macOS 和 Linux 需要；Windows 可选）
* [Rust](https://www.rust-lang.org/tools/install) >= 1.88

### 系统依赖

### macOS

`bash brew install unixodbc `

### Linux

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

### Windows

安装 [Strawberry Perl](https://github.com/StrawberryPerl/Perl-Dist-Strawberry/releases)（编译内置 OpenSSL 所需）：

```powershell
winget install StrawberryPerl.StrawberryPerl
```

DBX 默认启用 `sqlite-sqlcipher` 特性，需要从源码编译 SQLCipher 和 OpenSSL，而 Windows 上编译 OpenSSL 必须使用 Perl 执行 `Configure` 脚本。安装后请重新打开终端，使 `perl` 进入 `PATH`。

### 启动开发环境

```bash
git clone https://github.com/t8y2/dbx.git
cd dbx
make
```

`make` 会在需要时安装根目录依赖，并启动本地 Tauri 桌面端开发环境。

Web 版本：

```bash
make dev-web
make dev-backend
```

### 构建桌面安装包

```bash
make package
```

桌面安装包会输出到 `target/release/bundle/`。