从源码编译与参与贡献

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

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

1. 选择并认领任务

打开 DBX Issues，选择一个尚未分配、评论中也没有人正在处理的 Issue。第一次贡献优先考虑：

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

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

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

/claim

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

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

2. 安装开发环境

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

安装 Node.js 和 pnpm

先从 Node.js 官网安装 Node.js 22 或更新的 LTS 版本，然后启用仓库指定的 pnpm：

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

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

npm install --global pnpm@10.27.0

安装 Rust

按照 Rust 官方安装说明安装 rustup。安装后重新打开终端并检查：

rustc --version
cargo --version

安装系统依赖

Tauri 的完整系统要求可以参考 Tauri 官方前置依赖文档。DBX 还需要 ODBC 开发库。

xcode-select --install
brew install unixodbc

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

3. Fork 和克隆仓库

先在 GitHub 打开 t8y2/dbx，点击右上角 Fork 创建自己的仓库副本。

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

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

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

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

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

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

4. 第一次运行 DBX

macOS 和 Linux

在仓库根目录执行：

make

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

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

make dev-fast

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

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

Windows

在 PowerShell 中执行：

pnpm install --frozen-lockfile
pnpm dev:tauri

使用相同的轻量构建：

pnpm tauri dev -- --no-default-features --features duckdb-sidecar

判断是否启动成功

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

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

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

本地数据库测试环境

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

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 并配置防火墙。所有支持的配方、覆盖变量和重置安全要求请参阅数据库测试实验室。

5. 认识项目结构

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

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

6. 完成第一次修改

路线 A：修改官网文档

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

docs/content/docs/example.mdx
docs/content/docs/example.cn.mdx

启动文档站：

make docs

Windows 使用：

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

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

docs/content/docs/meta.json
docs/content/docs/meta.cn.json

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

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

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

路线 B：修改桌面前端

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

make dev-web

完成修改后至少运行：

pnpm typecheck
pnpm lint
pnpm test

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

路线 C：修改 Rust 后端

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

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
• agents/docs/agent-authoring.zh-CN.md

修改现有 Java/JDBC Agent

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

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

Shadow JAR 输出在：

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

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

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

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/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 替换本地运行时可执行文件：

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

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

Agent 提交前完整验证

在 agents/ 目录执行：

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. 提交前检查

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

git status
git diff

按修改范围执行检查：

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

8. 提交并推送

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

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 更新代码

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

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

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

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

常见问题

第一次 Rust 编译很慢

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

pnpm 提示版本不正确

重新启用仓库指定版本：

corepack prepare pnpm@10.27.0 --activate

改了代码但界面没有变化

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

不知道需要跑哪些测试

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

获取帮助

• 在原 Issue 中描述卡点，并附完整错误信息和操作系统版本
• 加入 Discord
• 查看仓库根目录的 CONTRIBUTING.zh-CN.md

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