# 从源码编译与参与贡献

> 从零搭建 DBX 开发环境，运行桌面版，完成第一次修改、测试并提交 Pull Request。

Source: https://dbxio.com/cn/docs/contributing

Language: zh-CN

Relative links resolve against https://dbxio.com/cn/docs/contributing.



这是一份面向第一次参与 DBX 开发者的完整教程。跟着本页操作，你将完成：

1. 准备 Node.js、pnpm、Rust 和系统编译依赖
2. Fork、克隆并运行 DBX 桌面版
3. 找到要修改的代码并完成一次小改动
4. 运行与改动范围匹配的检查和测试
5. 推送分支并提交 Pull Request

第一次贡献推荐从文档、翻译、小型 UI 问题或你熟悉的数据库问题开始。一个 PR 只解决一个明确问题，会更容易验证和合并。

本页的 PR 目标仓库是 `t8y2/dbx`，适用于 DBX 主应用、插件框架、SDK、CLI、文档和 Agent。普通插件源码保留在插件自己的仓库；插件上架 PR 应提交到 `t8y2/dbx-store`。完整流程见[开发和提交 DBX 插件](/cn/docs/plugin-development)。

## 1. 选择并认领任务

打开 [DBX Issues](https://github.com/t8y2/dbx/issues)，选择一个尚未分配、评论中也没有人正在处理的 Issue。第一次贡献优先考虑：

* 复现步骤和预期行为已经写清楚的问题
* 改动范围较小的文档、翻译或 UI 问题
* 你正在使用并且可以连接真实环境验证的数据库问题

不要只根据标签判断是否适合处理；先阅读完整正文、评论、截图和已有讨论，确认需求仍然有效并且没有重复实现。

确认 Issue 没有人处理后，在评论中单独发送：

```text
/claim
```

认领成功后，机器人会把 Issue 分配给你。如果你准备采用的方案可能影响现有行为，先在 Issue 中简要说明思路，等维护者确认后再开始大规模修改。

如果后续不准备继续或暂时无法完成，可以单独评论 `/unclaim`，也兼容 `/unclaimed`。工作流只会移除你自己的 assignee，之后其他贡献者可以重新认领。

## 2. 安装开发环境

DBX 桌面版基于 Tauri、Vue 和 Rust。仓库当前要求：

| 工具      | 版本                          |
| ------- | --------------------------- |
| Node.js | 22.13.0 或更高版本               |
| pnpm    | 10.27.0                     |
| Rust    | 1.88 或更高版本                  |
| Git     | 当前稳定版本                      |
| Make    | macOS 和 Linux 需要；Windows 可选 |

### 安装 Node.js 和 pnpm

先从 [Node.js 官网](https://nodejs.org/)安装 Node.js 22 或更新的 LTS 版本，然后启用仓库指定的 pnpm：

```bash
corepack enable
corepack prepare pnpm@10.27.0 --activate
node --version
pnpm --version
```

如果你的 Node.js 安装不包含 Corepack，也可以执行：

```bash
npm install --global pnpm@10.27.0
```

### 安装 Rust

按照 [Rust 官方安装说明](https://www.rust-lang.org/tools/install)安装 `rustup`。安装后重新打开终端并检查：

```bash
rustc --version
cargo --version
```

### 安装系统依赖

Tauri 的完整系统要求可以参考 [Tauri 官方前置依赖文档](https://v2.tauri.app/start/prerequisites/)。DBX 还需要 ODBC 开发库。

### macOS

安装 Xcode Command Line Tools 和 unixODBC：

```bash
xcode-select --install
brew install unixodbc
```

如果尚未安装 Homebrew，请先按照 [Homebrew 官网](https://brew.sh/)完成安装。

### Ubuntu / Debian

安装编译工具、Tauri WebKit/GTK 依赖和 unixODBC：

```bash
sudo apt update
sudo apt install -y \
  build-essential curl wget file pkg-config \
  libwebkit2gtk-4.1-dev libgtk-3-dev libxdo-dev \
  libayatana-appindicator3-dev librsvg2-dev patchelf \
  libssl-dev unixodbc-dev
```

### Windows

1. 安装 [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)。

2. 在安装器中选择 **Desktop development with C++**。

3. 确认已安装 Windows 10/11 SDK 和 WebView2。Windows 11 通常已自带 WebView2。

4. 安装 [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`。

5. 使用 PowerShell 执行本页的 Windows 命令。

Windows 不必安装 Make，本页会同时给出对应的 pnpm 命令。

## 3. Fork 和克隆仓库

先在 GitHub 打开 [t8y2/dbx](https://github.com/t8y2/dbx)，点击右上角 **Fork** 创建自己的仓库副本。

将下面的 `<你的 GitHub 用户名>` 替换为你的账号：

```bash
git clone https://github.com/<你的 GitHub 用户名>/dbx.git
cd dbx
git remote add upstream https://github.com/t8y2/dbx.git
git remote -v
```

推荐每个 Issue 使用一个独立分支：

```bash
git switch -c fix/issue-1234-short-description
```

开始新任务前，先同步主仓库：

```bash
git switch main
git fetch upstream
git rebase upstream/main
git push origin main
```

## 4. 第一次运行 DBX

### macOS 和 Linux

在仓库根目录执行：

```bash
make
```

`make` 会使用锁文件安装依赖，然后启动 Tauri 桌面开发环境。第一次编译 Rust 依赖需要较长时间，后续启动会明显更快。

如需轻量桌面开发构建，可以关闭默认 Rust feature，仅启用 DuckDB sidecar、DynamoDB 和 bundled SQLite：

```bash
make dev-fast
```

开发版可以与已安装的 DBX 同时运行。两者使用同一份本地 DBX 数据，因此连接和历史记录会同时可用；请避免在两个窗口中同时修改同一个连接、收藏 SQL 或全局设置。

测试 MCP bridge 时，后启动的实例会写入共享的 `mcp-bridge-port` 发现文件并接收 MCP 请求。Redis PubSub 优先使用端口 `4224`（设置 `DBX_PORT` 时优先使用该端口）；端口被占用时会自动回退到可用的本地端口，前端会使用实际监听端口。

### Windows

在 PowerShell 中执行：

```powershell
pnpm install --frozen-lockfile
pnpm dev:tauri
```

使用相同的轻量构建：

```powershell
pnpm tauri dev -- --no-default-features --features duckdb-sidecar,dynamodb,sqlite-bundled
```

### 判断是否启动成功

成功时会出现 DBX 桌面窗口，并且终端中没有编译错误。建议完成三个快速检查：

1. 打开设置页面
2. 创建或打开一个本地测试连接
3. 关闭窗口后再次启动，确认开发环境可重复运行

如果端口 `1420` 已被占用，先关闭旧的 DBX/Vite 开发进程再重新启动。

## 本地数据库测试环境

涉及数据库驱动、连接流程、元数据查询或数据库专用 UI 的改动，应尽可能通过真实实例验证。仓库为此提供了固定版本的本地 Docker Compose 配方：

```bash
make db-list
make db DB=mysql@8.4
make db-verify DB=mysql@8.4
make db-down DB=mysql@8.4
```

服务端口默认监听 `127.0.0.1`；在共享网络中暴露主机前，请设置 `DB_BIND_ADDRESS=0.0.0.0`、使用强 `DB_PASSWORD` 并配置防火墙。所有支持的配方、覆盖变量和重置安全要求请参阅[数据库测试实验室](/cn/docs/database-lab)。

## 5. 认识项目结构

| 路径                     | 适合修改的内容                  |
| ---------------------- | ------------------------ |
| `apps/desktop/src/`    | Vue 页面、组件、状态管理、交互和多语言文本  |
| `src-tauri/`           | Tauri 桌面命令、系统集成和应用打包     |
| `crates/dbx-core/`     | 数据库连接、查询、元数据和共享 Rust 逻辑  |
| `crates/dbx-web/`      | Docker/Web 后端            |
| `packages/app-tests/`  | 前端共享逻辑测试                 |
| `packages/cli/`        | DBX CLI                  |
| `packages/mcp-server/` | MCP Server               |
| `docs/content/docs/`   | 官网中英文文档                  |
| `agents/drivers/`      | Java/JDBC 和部分原生数据库 Agent |

不确定代码位置时，可以先用功能名称、界面文字或错误信息搜索：

```bash
rg "要查找的文字" apps/desktop/src crates src-tauri packages
```

## 6. 完成第一次修改

### 路线 A：修改官网文档

文档是最容易完成的第一次贡献。英文和中文页面使用相同文件名：

```text
docs/content/docs/example.mdx
docs/content/docs/example.cn.mdx
```

当前文档站语言以 `docs/lib/i18n.ts`、`docs/scripts/languages.mjs` 为准（现为 `en` / `cn`）。

启动文档站：

```bash
make docs
```

Windows 使用：

```powershell
cd docs
pnpm install --frozen-lockfile --ignore-workspace
pnpm dev
```

浏览器打开终端显示的本地地址。新增页面时，还要同时更新：

```text
docs/content/docs/meta.json
docs/content/docs/meta.cn.json
```

提交前先运行快速内容检查，再执行完整文档构建：

```bash
pnpm --dir docs content:check
make docs-build
```

`content:check` 会检查中英文页面配对、导航覆盖与顺序、frontmatter、重复标题和站内链接。`make docs-build` 会再次运行该检查并验证 Next.js 生产构建。

### 路线 B：修改桌面前端

前端代码位于 `apps/desktop/src/`。开发时可以运行完整桌面版，也可以只运行 Web 前端：

```bash
make dev-web
```

完成修改后至少运行：

```bash
pnpm typecheck
pnpm lint
pnpm test
```

涉及 UI 时，请同时检查亮色/暗色主题、窄窗口、空数据、加载中和失败状态，并在 PR 中附截图或录屏。

### 路线 C：修改 Rust 后端

Rust 共享逻辑主要位于 `crates/dbx-core/`，桌面命令位于 `src-tauri/`。不涉及 DuckDB 时先运行快速检查：

```bash
make cargo-check-fast
make cargo-test-fast
```

数据库相关修改应使用真实数据库实例验证，不要只依赖 mock。PR 中写清数据库类型、版本、复现 SQL、修改前行为和修改后行为。

### 路线 D：修改 Agent 驱动

Agent 是独立进程，通过 stdin/stdout JSON-RPC 与 DBX 通信。Java/JDBC Agent 通常使用 JDK 21；原生 Agent 使用 Go 或 Rust。开始前先阅读：

* [`agents/README.zh-CN.md`](https://github.com/t8y2/dbx/blob/main/agents/README.zh-CN.md)
* [`agents/docs/agent-authoring.zh-CN.md`](https://github.com/t8y2/dbx/blob/main/agents/docs/agent-authoring.zh-CN.md)

#### 修改现有 Java/JDBC Agent

从仓库根目录进入 `agents/`，只构建和测试目标模块：

```bash
cd agents
java --version
./gradlew :<驱动模块名>:test :<驱动模块名>:shadowJar
```

Shadow JAR 输出在：

```text
agents/drivers/<驱动模块名>/build/libs/
```

仅仅构建成功还不代表本地 DBX 使用了新代码。DBX 运行时读取用户目录下 `.dbx/agents/drivers/<db_type>/agent.jar`，因此必须备份并替换运行时 JAR：

### macOS / Linux

```bash
cp ~/.dbx/agents/drivers/<db_type>/agent.jar \
  ~/.dbx/agents/drivers/<db_type>/agent.jar.bak
cp drivers/<驱动模块名>/build/libs/*-all.jar \
  ~/.dbx/agents/drivers/<db_type>/agent.jar
```

### Windows PowerShell

```powershell
Copy-Item "$HOME\.dbx\agents\drivers\<db_type>\agent.jar" `
  "$HOME\.dbx\agents\drivers\<db_type>\agent.jar.bak"
$jar = Get-ChildItem "drivers\<驱动模块名>\build\libs\*-all.jar" | Select-Object -First 1
Copy-Item $jar.FullName "$HOME\.dbx\agents\drivers\<db_type>\agent.jar" -Force
```

替换后重启 DBX，或者断开并重新连接数据库，确保旧 Agent 进程退出并加载新 JAR。然后使用 Issue 对应的真实数据库版本重新执行复现步骤。

#### `agents/versions.json` 什么时候修改

修改已有驱动时，不要手动修改 `agents/versions.json`。Agent 发布工作流会以上一个 `agents-v*` 标签对比运行时代码，并使用该版本发布后的版本同步提交作为有效版本基线，自动为发生变化的模块增加 patch 版本；未变化模块会复用上一不可变 Release 中经过校验的产物。

* 修改 `agents/drivers/<module>/`：发布时自动 bump 该模块版本
* 修改 `agents/common/src/main/` 或 `agents/common/build.gradle`：发布时自动 bump 所有打包了 shared common runtime 的模块
* 新增驱动模块：必须在 `agents/versions.json` 增加初始版本，例如 `"rabbitmq": "0.1.0"`
* 新增 Java/JDBC 驱动时还必须同步 `agents/settings.gradle`、Agent README 支持列表、构建配置和测试
* 新增原生驱动时按照 Agent authoring/release checklist 登记对应构建和发布产物，不要假设 Gradle 会处理原生模块
* `versions.json` 中的键必须与实际发布模块一致；`common` 和 `test-support` 是基础设施模块，不登记版本

普通修复 PR 不需要为了“让更新生效”手动 bump 版本。版本 bump 和发布产物由 Agent release workflow 统一处理。

#### 原生 Agent

`oracle`、`kingbase`、`xugu` 等原生 Agent 使用 `agent` 可执行文件，而不是 `agent.jar`。在对应模块目录运行 Go 测试和构建，并按模块 README 替换本地运行时可执行文件：

```bash
cd agents/drivers/<原生模块>
go test ./...
go build -o agent .
```

新增数据库 Agent 时，如果存在成熟且许可证兼容的 Go/Rust 驱动，优先使用原生 Agent；只有缺少可靠原生驱动时再使用 Java/JDBC。

#### Agent 提交前完整验证

在 `agents/` 目录执行：

```bash
python3 -m unittest discover -s scripts -p '*_test.py'
python3 scripts/validate_agents.py
./gradlew test shadowJar --continue
python3 scripts/validate_agent_jars.py
```

`validate_agents.py` 会检查模块声明、`versions.json`、Gradle 配置、Main-Class、运行时分类和禁止残留文件；`validate_agent_jars.py` 会检查构建出的 JAR 是否包含正确入口类。

## 7. 提交前检查

先查看实际改动，确认没有提交构建产物、数据库文件、密钥或无关格式化：

```bash
git status
git diff
```

按修改范围执行检查：

| 修改范围              | 最低检查                                            |
| ----------------- | ----------------------------------------------- |
| 官网文档              | `make docs-build`                               |
| 前端/UI             | `pnpm typecheck && pnpm lint && pnpm test`      |
| Rust              | `make cargo-check-fast && make cargo-test-fast` |
| CLI/MCP/Node Core | `pnpm test:packages`                            |
| Agent             | Agent 脚本校验、对应 Gradle/Go 测试、构建产物校验和本地运行时真实验证     |

如果修改跨越多个区域，需要合并执行对应检查。修复 Bug 时，还应再次执行原始复现步骤，证明问题已消失，并检查相邻正常场景没有回归。

## 8. 提交并推送

提交信息使用简短的 conventional commit 格式：

```bash
git add <本次修改的文件>
git commit -m "fix(scope): describe the change"
git push -u origin HEAD
```

常用前缀：

* `fix(scope):` 修复问题
* `feat(scope):` 增加功能
* `docs:` 修改文档
* `test(scope):` 补充测试

不要把多个无关问题放在同一个提交或 PR 中。

## 9. 创建 Pull Request

在 GitHub 打开你的 Fork，点击 **Compare & pull request**，目标仓库选择 `t8y2/dbx`，目标分支选择 `main`。

PR 描述至少写清：

1. 关联的 Issue，例如 `Fixes #1234`
2. 修改了什么
3. 为什么这样修改
4. 运行了哪些测试
5. UI 改动的截图或录屏
6. 数据库改动的数据库名称、版本和验证步骤

提交 PR 后，如果 CI 失败，点击失败任务查看日志，在原分支继续提交修复即可，不需要重新创建 PR。

关联 PR 合并到默认分支后，如果 Issue 仍然处于打开状态，可以在 Issue 下单独评论 `/close`。工作流只会在评论者是当前 assignee，并且是已合并关联 PR 的作者时关闭 Issue。

## 10. 根据 Review 更新代码

维护者提出修改意见后，在同一分支继续修改、提交并推送：

```bash
git add <修改的文件>
git commit -m "fix(scope): address review feedback"
git push
```

如果主分支在 Review 期间有较多变化，可以同步后重新推送：

```bash
git fetch upstream
git rebase upstream/main
git push --force-with-lease
```

使用 `--force-with-lease`，不要使用裸 `--force`。它会在远程分支出现你未拉取的新提交时拒绝覆盖。

## 常见问题

### 第一次 Rust 编译很慢

这是正常现象。轻量桌面开发可以使用 `make dev-fast`，它关闭默认 Rust feature，仅启用 DuckDB sidecar 和 DynamoDB。`make cargo-check-fast` 和 `make cargo-test-fast` 会跳过全部可选默认 feature，因此不会验证 DuckDB 专用路径。

### pnpm 提示版本不正确

重新启用仓库指定版本：

```bash
corepack prepare pnpm@10.27.0 --activate
```

### 改了代码但界面没有变化

确认修改的是 `apps/desktop/src/`，终端中的 Vite/Tauri 进程仍在运行，并检查浏览器控制台或终端是否有编译错误。Rust 命令改动通常会触发重新编译。

### 不知道需要跑哪些测试

先运行与改动目录对应的最低检查，再针对 Issue 的复现路径做真实验证。仍不确定时，在 PR 中列出已完成的验证和未覆盖风险，维护者会补充建议。

## 获取帮助

* 在原 Issue 中描述卡点，并附完整错误信息和操作系统版本
* 加入 [Discord](https://discord.gg/W7NyVDRt6a)
* 查看仓库根目录的 [CONTRIBUTING.zh-CN.md](https://github.com/t8y2/dbx/blob/main/CONTRIBUTING.zh-CN.md)

请不要只发送“编译失败”。至少附上执行的命令、错误日志中最早出现的错误、操作系统、Node.js、pnpm 和 Rust 版本。