255 lines
8.6 KiB
Plaintext
255 lines
8.6 KiB
Plaintext
---
|
||
title: 快速开始
|
||
description: 安装 DBX、创建第一个连接，并了解桌面版、Docker 版和源码运行方式。
|
||
---
|
||
|
||
本页帮助你完成三件事：
|
||
|
||
1. 安装 DBX 或启动 Docker 版本
|
||
2. 创建并测试第一个数据库连接
|
||
3. 在需要参与开发或本地调试时从源码运行 DBX
|
||
|
||
## 选择安装方式
|
||
|
||
<Tabs groupId="platform" items={['macOS', 'Windows', 'Linux', 'Docker']}>
|
||
<Tab value="macOS">
|
||
使用 Homebrew 安装：
|
||
|
||
```bash
|
||
brew install --cask dbx
|
||
```
|
||
|
||
之后可用以下命令更新：
|
||
|
||
```bash
|
||
brew upgrade --cask dbx
|
||
```
|
||
|
||
也可以从 [GitHub Releases](https://github.com/t8y2/dbx/releases) 下载 `.dmg` 安装包。
|
||
|
||
</Tab>
|
||
<Tab value="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` 安装包。
|
||
|
||
</Tab>
|
||
<Tab value="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 提供兼容运行环境，可减少发行版依赖差异导致的安装或启动问题，后续也可直接在星火应用商店客户端中获取更新。
|
||
|
||
<Callout type="warn">
|
||
APM 版本在兼容环境中运行 DBX。如果为 Agent/JDBC 驱动选择宿主机 Java，需要在路径前添加 `/host`，例如将 `/usr/bin/java` 填写为 `/host/usr/bin/java`。
|
||
</Callout>
|
||
|
||
也可以从 [GitHub Releases](https://github.com/t8y2/dbx/releases) 下载对应安装包：
|
||
|
||
| 格式 | 适用场景 |
|
||
|---|---|
|
||
| `.deb` | Debian、Ubuntu 及兼容发行版 |
|
||
| `.rpm` | Fedora、 CentOS、 SUSE 及兼容发行版 |
|
||
| `.AppImage` | 通用 Linux 桌面环境 |
|
||
|
||
如果使用 `.AppImage`，首次运行前可能需要添加执行权限：
|
||
|
||
```bash
|
||
chmod +x DBX*.AppImage
|
||
```
|
||
|
||
</Tab>
|
||
<Tab value="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`，以获得更快的拉取速度。
|
||
|
||
启动后访问 `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:
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
## 桌面版还是 Docker
|
||
|
||
| 模式 | 适合场景 | 后端路径 | 存储位置 |
|
||
| ------------ | ------------------------------------------------------ | ----------------------------- | ------------------------------ |
|
||
| 桌面版 | 本机日常工作、本地文件、原生窗口、从 MCP 打开 DBX 界面 | Tauri 命令调用 Rust core | 本机应用数据目录 |
|
||
| Docker / Web | 服务器自托管、浏览器访问 | HTTP 路由调用同一套 Rust core | Docker 卷或服务器数据目录 |
|
||
|
||
<Callout type="info">核心数据库能力保持一致，但通过 MCP 打开桌面窗口等集成需要 DBX 桌面版正在运行。</Callout>
|
||
|
||
## 创建第一个连接
|
||
|
||
<Steps>
|
||
<Step>
|
||
### 打开新建连接
|
||
|
||
在侧边栏或工具栏中点击 **新建连接**。
|
||
|
||
</Step>
|
||
<Step>
|
||
### 选择数据库类型
|
||
|
||
选择 MySQL、PostgreSQL、SQLite、Redis、MongoDB、DuckDB、ClickHouse、SQL Server、Oracle，或 [数据库支持](/cn/docs/databases) 中列出的兼容类型、Agent/JDBC 类型。
|
||
|
||
</Step>
|
||
<Step>
|
||
### 填写连接信息
|
||
|
||
网络数据库需要填写主机、端口、用户名、密码和必要的默认数据库。SQLite、DuckDB、Access 这类文件型数据库需要选择本地数据库文件，不填写主机和端口。
|
||
|
||
</Step>
|
||
<Step>
|
||
### 有 URL 时直接粘贴
|
||
|
||
DBX 可以解析常见连接 URL，例如 MySQL、PostgreSQL、Redis、MongoDB、ClickHouse、SQL Server、Oracle、Elasticsearch、DM、GaussDB、openGauss、TDengine 和 Access。保存前请检查解析出的字段。
|
||
|
||
</Step>
|
||
<Step>
|
||
### 配置网络选项
|
||
|
||
如果数据库在内网、跳板机后面、只能通过 Web 网关访问，或网络要求 SOCKS5/HTTP 代理，可以配置 [隧道/代理](/cn/docs/ssh-tunnel)。
|
||
|
||
</Step>
|
||
<Step>
|
||
### 测试并保存
|
||
|
||
点击 **测试** 验证账号、网络和权限。测试通过后保存连接，并从侧边栏打开。
|
||
|
||
</Step>
|
||
</Steps>
|
||
|
||
<Callout type="info">连接密码、SSH 密码、SSH 密钥密码和连接字符串会与普通连接 JSON 分开存储在 DBX 本地数据中。需要迁移加密连接配置时，使用 [配置导出/导入](/cn/docs/config-export)。</Callout>
|
||
|
||
## 降低生产误操作
|
||
|
||
- 给生产连接起明确名称，例如 `prod-orders`。
|
||
- 用连接颜色区分生产、预发、测试和本地环境。
|
||
- 一个服务器上数据库很多时，只显示当前需要的数据库。
|
||
- 对编辑、导入、传输、SQL 文件执行或 Schema 同步生成的 SQL，先审查再执行。
|
||
|
||
## 下一步可以做什么
|
||
|
||
<Cards>
|
||
<Card title="写 SQL" href="/cn/docs/query-editor">
|
||
使用补全、格式化、选中执行、取消执行和查询历史。
|
||
</Card>
|
||
<Card title="看数据" href="/cn/docs/data-grid">
|
||
查看结果、在安全时编辑行、预览 SQL 并导出数据。
|
||
</Card>
|
||
<Card title="看结构" href="/cn/docs/schema-browser">
|
||
浏览数据库、Schema、表、字段、Redis 键和 MongoDB 集合。
|
||
</Card>
|
||
</Cards>
|
||
|
||
## 常见连接问题
|
||
|
||
| 现象 | 检查项 |
|
||
| ------------------ | -------------------------------------------------------------- |
|
||
| 连接超时 | 主机、端口、防火墙、安全组、VPN、Docker 主机网络或内网访问权限 |
|
||
| 认证失败 | 用户名、密码、认证方式、SSL 要求、账号是否允许远程登录 |
|
||
| 能连接但看不到表 | 默认数据库、Schema、权限、元数据读取权限、可见数据库过滤 |
|
||
| 文件数据库打不开 | 文件路径、文件权限、Docker volume 挂载、文件扩展名是否支持 |
|
||
| 内网数据库无法访问 | 配置隧道/代理、VPN，或让 Docker 部署机器能访问目标数据库 |
|
||
|
||
## 从源码运行
|
||
|
||
当你想参与开发或本地调试 DBX 时，可以从源码运行。
|
||
|
||
<Callout type="info">
|
||
第一次参与开发请阅读[从源码编译与参与贡献](/cn/docs/contributing)。教程包含各系统环境安装、Fork、Issue 认领、测试和提交 PR 的完整步骤。
|
||
</Callout>
|
||
|
||
### 环境要求
|
||
|
||
- [Node.js](https://nodejs.org/) >= 22.13.0
|
||
- [pnpm](https://pnpm.io/) 10.27.0
|
||
- Make
|
||
- [Rust](https://www.rust-lang.org/tools/install) >= 1.77
|
||
|
||
### 系统依赖
|
||
|
||
<Tabs groupId="dev-platform" items={["macOS", "Linux", "Windows"]}>
|
||
<Tab value="macOS">```bash brew install unixodbc ```</Tab>
|
||
<Tab value="Linux">```bash sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev librsvg2-dev patchelf libssl-dev unixodbc-dev ```</Tab>
|
||
<Tab value="Windows">Windows 通常不需要额外安装系统依赖。</Tab>
|
||
</Tabs>
|
||
|
||
### 启动开发环境
|
||
|
||
```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
|
||
```
|
||
|
||
桌面安装包会输出到 `src-tauri/target/release/bundle/`。
|