企业官网建设流程全解析

• 数据库客户端
• 数据库
• 桌面应用
• CLI
• 后端
• MCP 服务
• AI 应用

DBX 是一款用 Rust 构建的开源（Apache-2.0）跨平台数据库管理工具，以单个约 25 MB 的二进制文件支撑 90+ 种数据库的连接与管理，无需 Java、Python 或内嵌 Chromium 等运行时依赖。本指南以仓库根目录 README.zh-CN.md 为主线，系统讲解 DBX 的功能特性、MCP AI 集成、多平台安装、Docker 自托管与源码开发流程，并辅以仓库内源码与配置作为实现依据；读完你将掌握从零接入 DBX、为 AI 编程助手配置 MCP Server、以及用 Docker 部署团队共享 Web 版的完整方案。

DBX 是什么：25 MB 驾驭 90+ 种数据库

DBX 的核心定位是"轻量 + 全能"：单个小巧的二进制文件即可下载、安装、连接，全平台可用且无需额外运行时。与依赖 Java 的 DBeaver、Freemium 模式的 TablePlus 等工具不同，DBX 采用 Rust 编写后端，前端基于 Vue 3 与 CodeMirror 6，官方在 README.zh-CN.md 中明确其四个核心卖点：

从常见问题（FAQ）一节还可以确认：DBX 完全免费、基于 Apache-2.0 协议开源、不收集任何遥测数据，且桌面端完全支持离线使用——内网环境可通过「设置 > 驱动管理」导入离线驱动包。

支持的数据库矩阵：原生直连与 Agent 扩展

DBX 的数据库覆盖分为两层，README 的"功能特性"与"常见问题"两处给出了完整清单：

• 原生直连：MySQL、PostgreSQL、SQLite、Cloudflare D1、Redis、MongoDB、DuckDB、ClickHouse、SQL Server、Oracle、Elasticsearch、Easysearch、Meilisearch、MariaDB、TiDB、OceanBase、openGauss、GaussDB、KWDB、KingbaseES、Vastbase、GoldenDB、Doris、SelectDB、StarRocks、Manticore Search、Redshift、达梦 DM、TDengine、虚谷 XuguDB、CockroachDB、Access、HighGo、UXDB、Dolt 等。
• Agent/JDBC 扩展：H2、Snowflake、Trino、PrestoSQL、Hive、DB2、Informix、Neo4j、Cassandra、BigQuery、Cloud Spanner、Kylin、SunDB、JDBCX、Databricks、SAP HANA、Teradata、Vertica、Firebird、Exasol、崖山 YashanDB、GBase 8a/8s、Databend、RQLite、Turso、InfluxDB、QuestDB、IoTDB、etcd、ZooKeeper、Nacos、Consul KV、IRIS 及自定义 JDBC 连接，并支持 Pulsar、Kafka、RocketMQ 消息队列管理。

仓库中 plugins/connection-types/ 目录以 YAML 声明式定义了每种连接类型的元数据，例如 mysql.yaml 中可见dbType: mysql、rustVariant: Mysql、defaultPort: 3306、runtimeMode: native、mcpMode: direct等字段，以及queryExecution、metadataBrowse、diagram、tableDataEdit等能力开关——这正是"一个工具搞定所有数据库"的底层驱动模型。同一目录下还包含mq.yaml、mqtt.yaml、etcd.yaml、zookeeper.yaml、nacos.yaml等非关系型数据源定义，印证了"数据库 + 消息队列 + 键值存储"的统一管理能力。

功能特性全景

查询编辑器

基于 CodeMirror 6 构建，提供语法高亮、元数据感知自动补全、Cmd+Enter执行、选中 SQL 执行、SQL 格式化与诊断提示，内置 9 种编辑器主题；查询历史、常用 SQL 片段、标签页恢复和 SQL 文件执行让重复性工作更顺手。

AI SQL 助手

用自然语言描述需求即可生成 SQL，还能解释查询、优化 SQL、修复错误。支持 Claude、OpenAI、本地模型（Ollama）或任何 OpenAI 兼容端点。关键的安全设计是：内置安全检查会在执行前审查 AI 生成的 SQL，避免把未经确认的语句直接发往数据库。

数据表格

虚拟滚动可轻松应对大型结果集；支持行内编辑、保存前 SQL 预览、WHERE / ORDER BY 控件、DataGrip 风格过滤器、LIKE / NOT LIKE 右键过滤、排序、全文搜索、分页、列宽调整、自动列宽、行号、斑马纹和完整单元格详情。数据可导出或复制为 CSV、JSON、Markdown、XLSX、INSERT 语句。

Schema 工具

• 结构浏览— 数据库、Schema、表、字段、索引、外键、触发器，支持侧边栏搜索和置顶
• 对象浏览— 按类型分组查看过程、函数、视图，并可在支持的数据库中编辑源码
• 表结构编辑器— 对支持的数据库执行可审查的字段和索引变更
• ER 关系图— 可视化表间关联
• Schema 对比— 跨连接对比表结构差异
• 执行计划— 可视化查询执行计划
• 字段血缘— 字段级血缘分析
• 数据库搜索— 在大型 Schema 中快速查找对象

数据操作

• 数据导入— CSV、Excel
• 数据迁移— 在数据库之间迁移数据
• 数据库导出— 完整数据库导出
• 数据对比— 对比表数据并审查同步结果
• SQL 文件执行— 直接执行.sql文件
• 文件预览— 拖入 Parquet、CSV、JSON 即时预览（基于 DuckDB）
• 连接导入— 从 DBeaver 或 Navicat 导入连接配置

专项浏览器

• Redis— 模式匹配搜索、批量键操作、命令执行器、TTL 编辑，全数据类型支持（String、Hash、List、Set、ZSet、Stream）
• MongoDB— 文档增删改查、分页浏览，支持 Atlas 和副本集 URL 直连

安全与连接

SSH 隧道（密钥和密码认证）、数据库与 AI 代理设置、断线自动重连、危险操作确认对话框、加密导出/导入连接配置、连接颜色标记、驱动商店与可选 JDBC 插件。结合 FAQ 可确认：DBX 不收集任何遥测数据，更新通知仅在用户点击"重启并更新"后才安装，且可在设置中关闭自动检查。

精致 UI

深色模式原生标题栏同步、9 种编辑器主题、界面语言支持 English / 简体中文 / Español、布局偏好设置、内置自动更新。

AI 编程助手集成（MCP Server）实战

DBX 原生提供 MCP Server，让 Claude Code、Cursor、Windsurf 等 MCP 兼容的 AI 编程助手直接通过 DBX 中已配置的数据库连接查询数据。完整实现位于 crates/dbx-mcp/，其 lib.rs 对外导出DbxMcpServer、LocalBackend、WebBackend等核心模块；MCP 协议、连接读取、SQL 安全检查、Schema、Redis、MongoDB shell 解析、Web 后端与数据库执行均由 Rust 实现，Node.js 仅作为 npm 启动器以兼容现有工具链。

架构

@dbx-app/mcp-server └── 轻量 Node.js 启动器 └── 当前平台的 Rust dbx-mcp 二进制 └── dbx-core 数据库和 Agent 基础设施

安装与配置

方式一：npx（无需全局安装，推荐），在.mcp.json中添加：

{ "mcpServers": { "dbx": { "command": "npx", "args": ["-y", "@dbx-app/mcp-server"] } } }

方式二：npm 全局安装：

npm install -g @dbx-app/mcp-server

{ "mcpServers": { "dbx": { "command": "dbx-mcp-server" } } }

方式三：原生二进制 / 离线安装。每个 packages 版本会在 Releases 发布各平台归档与SHA256SUMS：macOS Apple Silicon（dbx-mcp-darwin-arm64.tar.gz）、macOS Intel（dbx-mcp-darwin-x64.tar.gz）、Linux glibc ARM64 / x64（dbx-mcp-linux-arm64-gnu.tar.gz/dbx-mcp-linux-x64-gnu.tar.gz）、Windows ARM64 / x64（dbx-mcp-win32-arm64.zip/dbx-mcp-win32-x64.zip）。解压前先校验：

sha256sum --check SHA256SUMS tar -xzf dbx-mcp-linux-x64-gnu.tar.gz chmod +x dbx-mcp

macOS 用shasum -a 256，Windows 用certutil -hashfile <archive> SHA256。随后直接配置二进制路径：

{ "mcpServers": { "dbx": { "command": "/绝对路径/dbx-mcp" } } }

直接运行原生文件不需要 Node.js。注意：npm 安装时不要使用--no-optional，因为平台二进制通过 npmoptionalDependencies自动安装；Linux 当前仅支持 glibc，暂不支持 Alpine/musl。

连接 DBX Web 或 Docker 部署时，让 MCP Server 指向 Web 后端 API；若 Web 登录页需要密码，DBX_WEB_PASSWORD填写同一登录密码：

{ "mcpServers": { "dbx": { "command": "npx", "args": ["-y", "@dbx-app/mcp-server"], "env": { "DBX_WEB_URL": "http://localhost:4224", "DBX_WEB_PASSWORD": "你的 Web 登录密码" } } } }

18 个 MCP 工具

dbx_execute_query的可选参数max_rows取值为 1–1000、默认 100，越界值会被夹取到范围内而非报错；它只对 SQL 连接生效——MongoDB shell 命令始终最多返回 100 行，多语句脚本每条语句最多返回 100 行。这些参数约束在 server.rs 的ExecuteQueryRequest定义中有对应的 schema 注释（如字符串单元格默认截断 200 字符、最大 4000 字符等）。

dbx_peek_messages在启用mq-admin后可用于本地与 Web 模式，参数包括connection_id/connection_name、topic、可选count（1–100，默认 20）、start_position（默认latest，也支持earliest、offset）以及可选的非负partition；仅 offset 模式需要非负offset，未指定分区时位点应用于所有分区。响应保留 base64 消息体与元数据，用incomplete标记底层不完整读取、用outputTruncated标记因 256 KiB 输出预算省略整条消息的情况。工具遵守连接与工具范围，允许只读和生产连接读取且不提交消费位点。

启用连接作用域后，连接增删类工具与桌面 UI 工具会被隐藏。

四种执行模式

• 本地原生模式（默认）：直接读取 DBX 连接存储并在 Rust 进程内执行。支持 PostgreSQL、MySQL、SQLite 等常见 SQL 数据库、Redis standalone 与 MongoDB；DuckDB 需先在 DBX Driver Manager 中安装独立 DuckDB 驱动。连接存储默认位置：macOS~/Library/Application Support/com.dbx.app/dbx.db、Linux~/.local/share/com.dbx.app/dbx.db、Windows%APPDATA%\com.dbx.app\dbx.db，可用DBX_DATA_DIR覆盖。
• Agent/JDBC 模式：达梦、金仓 KingbaseES、Oracle、DB2、Hive、Trino、Snowflake、SAP HANA 等通过 DBX Java Agent 基础设施运行；需先通过 DBX Driver Manager 安装对应 Agent、JDBC Driver 和 JRE（npm/GitHub 原生包不捆绑厂商专有驱动）。
• DBX Web / Docker 模式：设置DBX_WEB_URL指向部署的 Web 后端即可；Web 模式不读取本机桌面存储，也不暴露桌面 UI 工具。Web 请求遵循HTTP_PROXY/HTTPS_PROXY/ALL_PROXY（空值表示不走代理）、NO_PROXY绕过列表；认证代理使用http://user:pass@host:port形式；DBX_WEB_HEADERS可附加 JSON 对象形式的自定义请求头（如{"Authorization":"Bearer <token>"}）；自签名 HTTPS 后端可用DBX_WEB_INSECURE_SKIP_VERIFY=1跳过校验，或DBX_WEB_CA_CERT信任私有 CA。
• 原生 Streamable HTTP：默认 stdio 传输，如需本机 HTTP 服务则携带 Bearer Token 启动：

DBX_MCP_HTTP_TOKEN=replace-with-a-long-random-secret dbx-mcp-server --http

默认监听http://127.0.0.1:5225/mcp，客户端配置：

{ "type": "http", "url": "http://127.0.0.1:5225/mcp", "headers": { "Authorization": "Bearer replace-with-a-long-random-secret" } }

监听非回环地址必须同时满足：DBX_MCP_HTTP_ALLOW_REMOTE=1、--http-allow-remote参数、非空的DBX_MCP_HTTP_ALLOWED_HOSTS与DBX_MCP_HTTP_ALLOWED_ORIGINS白名单（使用精确的公网值）。DBX Web 也可通过现有监听器直接提供原生 Streamable HTTP（设置DBX_WEB_MCP_TOKEN或DBX_WEB_MCP_TOKEN_FILE并配置 Host 白名单），容器映射4225:4224时端点为http://localhost:4225/mcp；反向代理加路径前缀时设置DBX_PUBLIC_BASE_PATH，端点为<base-path>/mcp。

Windows 便携版需要在 MCP 配置中设置DBX_DATA_DIR，指向DBX.exe同级的data目录（即包含dbx.db的文件夹）。

DBX 管理的 MCP 权限策略

连接 allowlist 与"只读 / 数据读写 / 完全访问"三档执行权限统一在 DBX 的设置 → MCP中管理（机器可读值为read_only、safe_write、high_risk_write），客户端配置无需声明权限或连接范围环境变量。策略在每次请求时重新加载：

允许访问的连接控制 MCP 可列出/解析的稳定连接 ID；连接自身只读、生产库保护、数据库账号权限与 allowlist 在任何模式下都是权限上限。WHERE TRUE、WHERE 1 = 1、_id: {$exists: true}、互补条件或不透明 MongoDB 过滤器仍按高风险处理，未知 Redis 命令失败关闭；MongoDB 更新/删除必须提供可验证有效的 filter（除非完全访问），$out、$merge聚合阶段按高风险写操作处理。

为兼容升级，旧配置中的DBX_MCP_ALLOW_WRITES=0（或false）仅在中央 MCP 策略首次保存前继续作为只读限制；它不能开启写入，也不能覆盖已保存的中央策略。旧连接 scope 变量可进一步收窄 allowlist：

{ "mcpServers": { "dbx-production-scope": { "command": "dbx-mcp-server", "env": { "DBX_MCP_SCOPE_CONNECTION_NAME": "production-postgres", "DBX_MCP_SCOPE_DATABASE": "analytics" } } } }

可使用DBX_MCP_SCOPE_CONNECTION_ID、逗号分隔的DBX_MCP_SCOPE_CONNECTION_IDS或DBX_MCP_SCOPE_CONNECTION_NAME，ID scope 优先于名称 scope。

环境变量速查

常见问题排查

• 提示平台 optional package 未安装：npm uninstall -g @dbx-app/mcp-server后重新npm install -g @dbx-app/mcp-server@latest，切勿加--no-optional。
• 提示找不到dbx.db：DBX_DATA_DIR应指向包含dbx.db的目录，而不是数据库文件本身。
• 提示 DBX 未运行：普通查询可在桌面端关闭时本地执行；仅dbx_open_table、dbx_execute_and_show等桌面 UI 工具需要桌面端运行。
• Agent 数据库无法启动：通过 DBX Driver Manager 安装/更新对应 Agent、JDBC Driver 和 JRE。
• 出现better-sqlite3或 Node ABI 错误：Rust MCP 运行时不依赖better-sqlite3，通常表示 MCP 版本过旧，升级即可。

DBX CLI：终端与脚本工作流

DBX 提供独立的 CLI 包，适合终端、脚本和 Codex 工作流：

npm install -g @dbx-app/cli # 或通过 Homebrew brew tap t8y2/tap && brew install dbx-cli dbx connections list --json dbx query local "select 1" --json

常用命令一览（详见 CLI README）：

dbx doctor dbx capabilities dbx connections list --json dbx schema list local --json dbx schema describe local users --json dbx query local "select count(*) as total from users" --json dbx query local --file ./query.sql --json dbx context local --tables users,orders dbx open local users

dbx query默认只读；--limit <n>控制返回行数，--timeout <duration>（支持500ms、10s、1m格式）控制超时；非危险写语句需--allow-writes，DROP、TRUNCATE、ALTER等危险 SQL 还需同时加--allow-dangerous-sql。可用DBX_CONNECTION环境变量省略连接名参数，JSON 错误使用稳定错误码（如SQL_BLOCKED、CONNECTION_NOT_FOUND、DBX_NOT_RUNNING）。Codex 等工具可直接调用 CLI：

dbx context local --tables users,orders | codex exec "Write a retention query"

安装指南（桌面端）

从 Releases 页面下载最新版本，或使用各平台包管理器：

• Homebrew (macOS)：brew install --cask dbx
• Scoop (Windows)：scoop bucket add dbx ...后scoop install dbx
• WinGet (Windows)：winget install t8y2.dbx
• Flatpak (Linux)：flatpak remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo后flatpak install flatpark com.dbxio.dbx，之后通过flatpak update获取更新
• Spark Store 星火应用商店 (Linux)：一键安装，后续在商店客户端中更新
• 银河麒麟 V10、统信 UOS 等系统推荐选择APM（AmberPM）版本以减少发行版依赖差异；APM 在兼容环境中运行 DBX，若为 Agent/JDBC 驱动选择宿主机 Java，路径前需加/host（如将/usr/bin/java填为/host/usr/bin/java）

自托管：Docker 部署 Web 版

DBX 提供 Web 版本，可通过 Docker 部署（示例使用latest标签拉取当前发布版本）：

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

dbx-data为跨平台命名卷，中国大陆用户可改用 CNB 镜像docker.cnb.cool/dbxio.com/dbx:latest加速拉取。使用 Compose 时，deploy/docker-compose.release.yml 即为已发布镜像的部署配置（源码构建配置保留在deploy/docker-compose.yml）：

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

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:

如需通过 nginx 等反向代理发布到/dbx子路径，设置运行时上下文路径并将同一前缀代理到容器：

environment: - DBX_PUBLIC_BASE_PATH=/dbx

自行从源码构建前端并希望使用绝对资源路径时，可在pnpm build前设置VITE_DBX_BASE_PATH=/dbx/。浏览器访问http://localhost:4224，镜像支持 amd64 / arm64 双架构。

从源码快速开始（开发与构建）

环境要求

• Node.js >= 18
• pnpm
• Rust >= 1.88

系统依赖：macOS / Windows 无需额外安装；Ubuntu/Debian 需要：

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

NixOS 用户参考 README-NIX.md。

开发

make

make会在需要时安装根目录依赖并启动本地 Tauri 桌面端开发环境（对应 Makefile 中的dev目标）。开发版可与已安装的 DBX 同时运行并共享本地连接与历史数据，但应避免在两个窗口中同时修改同一连接或全局设置。DuckDB 从源码编译较慢，不涉及时可跳过以加速：

make cargo-check-fast # 快速检查（跳过 DuckDB） make cargo-test-fast # 快速测试 make dev-fast # Tauri 开发模式跳过 DuckDB

--no-default-features仅影响本地开发，发布构建（pnpm tauri build）始终包含 DuckDB。Web 版本与文档站：

make dev-web # 前端 make dev-backend # 后端 make docs # 文档站（docs/ 目录）

需要干净、可重复创建的本地数据库实例时，可使用 deploy/database/ 下的带版本 Docker Compose 配方：

make db-list make db-verify DB=mysql@8.4

JDBC Agent 驱动开发工程位于 agents/ 目录：

cd agents ./gradlew test

本地驱动安装流程会优先查找agents/drivers/<db-type>/build/libs/下的构建产物。

构建安装包

make package

安装包输出在src-tauri/target/release/bundle/目录。

技术栈一览

文档与继续深入

• 贡献指南 — 如何认领 Issue 并提交 PR
• Web API 参考 — Docker/Web 部署的 HTTP API
• 示例代码 — CLI、MCP、Docker 与 API 示例
• MCP Server 说明 与 CLI 说明 — 更完整的工具与命令参考

从整体看，DBX 的独特之处在于把"轻量二进制"、"90+ 数据源"、"AI 原生"与"MCP 开放协议"整合进同一套代码库：桌面端、Docker Web 版与 CLI 共享同一连接配置与安全策略，既适合个人日常查询，也适合通过 Docker 自托管为团队提供 AI 就绪的数据访问层。若你的下一步是让 Claude Code、Cursor 等助手直接操作数据库，建议从 README 的 MCP 章节出发，按本文的"npx 安装 → 设置 → MCP 配置权限 → 验证工具列表"路径逐步落地。

• 数据库客户端
• 数据库
• 桌面应用
• CLI
• 后端
• MCP 服务
• AI 应用