数据库开发者工具桌面应用CLIMCP 服务AI 应用【免费下载链接】dbx15MB轻量级跨平台数据库客户端、数据库管理工具。支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、DuckDB、ClickHouse、SQL Server 等。15MB, lightweight, cross-platform database client. Supports MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, ClickHouse, SQL Server and more.项目地址https://gitcode.com/t8y2/dbx点击查看免费下载本指南面向 DBX 仓库的维护者与贡献者系统讲解 deploy/database 目录下的可复现数据库测试环境体系它如何以带版本配方recipe的形式为 MySQL、PostgreSQL、Redis、MongoDB、ClickHouse、Elasticsearch 等十余种数据库/中间件提供一键启停、冒烟验证与配方校验的 Docker Compose 工作流。读完本文你将掌握make db-list/make db/make db-verify等目标的使用方法、recipe.json与compose.yaml的编写规范、端口分配与安全绑定约定并能用make db-check与pnpm test:db-env验证自己新增的配方。一、目录定位为人工验证而生的可复现环境deploy/database/不是生产部署模板而是一套面向手动数据库功能验证的测试环境仓库。其核心承诺是可重复创建reproducible每个带版本的配方都同时满足以下约束见 README.md固定镜像版本pinned image杜绝今天启动和昨天启动镜像不同的漂移使用命名卷named volume数据与容器生命周期解耦支持db-reset精确清空仅绑定本机回环地址默认127.0.0.1不向局域网暴露服务定义健康检查healthcheck供 Compose 判定服务就绪携带初始化数据init/目录或在验证阶段创建冒烟数据smoke data。从目录结构看当前仓库已内置 18 个产品、25 个版本配方含多版本产品产品版本MySQL5.7、8.4PostgreSQL14.23、17.4MariaDB10.11Redis3.0.7、7.4MongoDB5.0、8.2ClickHouse24.8Elasticsearch6.8Kafka4.3Consul2.0.2Etcd3.5、3.7Nacos2.5、3.2Zookeeper3.9Pulsar4.2Qdrant1.8Rnacos0.8完整清单见 deploy/database 目录。二、快速上手六个核心 Make 目标所有命令均在仓库根目录执行。Make 目标只是对底层pnpm db:env命令的薄封装见 Makefile但提供了统一的配方选择器语法DBproductversion# 1. 列出所有可用配方按产品归并版本、端口映射、镜像、平台 make db-list # 2. 启动一个环境输出可直接复制的启动命令 make db DBmysql8.4 # 3. 启动并执行冒烟验证 make db-verify DBpostgresql17.4 # 4. 停止环境 make db-down DBpostgresql17.4 # 5. 清空数据会删除命名卷必须显式确认 make db-reset DBredis7.4 CONFIRM1 # 6. 校验全部配方与 Compose 文件 make db-check各目标职责如下目标说明见 Makefilemake db-list按产品归并展示各版本列出每项默认的容器→宿主机端口映射、镜像及支持平台make db为每个配方输出一条可复制的启动命令若该连接类型已被 DBX 支持启动完成后还会输出预填的dbx://connection/new深链make db-verify启动环境并执行recipe.json中定义的冒烟步骤smoke steps是验证配方可用性的主入口make db-down停止并清理容器但保留命名卷数据make db-reset删除容器与命名卷因此强制要求CONFIRM1防误删make db-check静态校验每个配方结构、标准容器名并要求 Docker Compose 校验每个 Compose 文件在新增/修改配方后必须运行make db-completion输出 Bash、Zsh、PowerShell 补全脚本的加载方式。值得强调的是db、db-verify、db-down、db-reset在 Makefile 中分别映射为pnpm db:env -- start|verify|down|reset因此你也可以跳过 Make 直接使用底层命令例如诊断时可执行pnpm db:env -- info|status|logs|shell product version其中pnpm db:env -- shell product version会以recipe.json中声明的交互式shell命令进入容器客户端。三、DBX 深链一键打开新建连接对话框对于 DBX 已支持连接类型的配方启动完成后会自动输出一条预填了连接参数的深链dbx://connection/new?host127.0.0.1port10101usernamerootpassword123456databasedbx在已安装 DBX Desktop 的 macOS 上直接执行open 链接即可打开新建连接对话框省去手工填写主机、端口、账号、密码与库名的步骤。没有对应 DBX 连接类型的配方如 Consul、Zookeeper 等中间件会明确报告深链不可用。安全提醒来自 README.md深链中包含密码明文因此不要将其写入共享终端历史共享 shell history不要写入日志logs或工单tickets使用后及时清理终端记录。四、配方结构recipe.json compose.yaml init/每个配方是deploy/database/product/version/下的一个目录见 README.md 与 RECIPE_TEMPLATE.mdproduct/version/ ├── recipe.json # 连接字段和冒烟命令 ├── compose.yaml # Docker Compose 环境 └── init/ # 环境初始化数据三层分工明确recipe.json机器可读的配方元数据——数据库类型、镜像、平台、默认端口、DBX 连接参数、交互式 shell 命令与非交互式冒烟步骤compose.yaml真正的 Docker Compose 环境——端口绑定、环境变量、命名卷、健康检查与 init 挂载init/随环境一起初始化的数据脚本SQL/JS 等由官方镜像的初始化目录约定自动执行。4.1 以 MySQL 8.4 为例解读 recipe.jsonmysql/8.4/recipe.json 完整字段{ database: mysql, name: MySQL, version: 8.4.6, displayVersion: 8.4, image: docker.cnb.cool/znb/images/mysql:8.4.6, platforms: [linux/amd64, linux/arm64], service: database, defaultPort: 3306, connection: { host: 127.0.0.1, port: 10101, username: root, password: 123456, database: dbx }, hostPorts: { DB_PORT: 10101 }, shell: [mysql, -uroot, -p${DB_PASSWORD}, -Ddbx], smoke: { steps: [{ name: query initialized row, command: [mysql, -uroot, -p${DB_PASSWORD}, -Ddbx, -Nse, SELECT note FROM dbx_smoke WHERE id1], expect: DBX smoke }] } }关键字段含义字段说明database/name/version内部标识、展示名称与精确镜像版本displayVersion配方选择器使用的短版本号如mysql8.4image固定镜像地址本仓库统一使用docker.cnb.cool/znb/images/...镜像源platforms支持的平台如linux/amd64、linux/arm64serviceCompose 服务名本仓库统一为databasedefaultPort服务原生端口MySQL 3306、PostgreSQL 5432、Redis 6379…connectionDBX 连接参数生成深链与连接配置的依据hostPorts默认宿主端口映射DB_PORT必须与connection.port及 Compose 回退值一致shell交互式客户端命令供pnpm db:env -- shell使用smoke.steps非交互冒烟步骤每个步骤含name、command、expect冒烟命令中可引用${DB_PASSWORD}环境变量expect字段用于断言命令输出例如 MySQL 的冒烟步骤查询dbx_smoke表并期望输出DBX smoke。4.2 对应 compose.yaml 的约束落实mysql/8.4/compose.yaml 展示了全部约定如何在 Compose 中落地services: database: image: docker.cnb.cool/znb/images/mysql:8.4.6 container_name: dbx-mysql-8.4 restart: always ports: - ${DB_BIND_ADDRESS:-127.0.0.1}:${DB_PORT:-10101}:3306 environment: MYSQL_ROOT_PASSWORD: ${DB_PASSWORD:-123456} MYSQL_DATABASE: dbx volumes: - data:/var/lib/mysql - ./init:/docker-entrypoint-initdb.d:ro healthcheck: test: [CMD-SHELL, mysqladmin ping -h 127.0.0.1 -uroot -p\$$MYSQL_ROOT_PASSWORD\ --silent] interval: 5s timeout: 5s retries: 30 start_period: 20s volumes: data:要点容器名统一为dbx-product-version如dbx-mysql-8.4make db-check会校验该命名规范端口绑定必须写作${DB_BIND_ADDRESS:-127.0.0.1}:${DB_PORT:-10101}:3306其中宿主机端口默认值必须与recipe.json的hostPorts.DB_PORT一致10101密码通过${DB_PASSWORD:-123456}注入命名卷data持久化数据目录实现db-reset的删卷清空init 挂载./init:/docker-entrypoint-initdb.d:ro只读挂载初始化脚本镜像首次启动时自动执行健康检查用官方客户端探测就绪状态统一 5s 间隔、5s 超时、30 次重试MySQL 额外带 20s 启动宽限期。PostgreSQL 17.4 的写法几乎同构见 postgresql/17.4/recipe.json 与 compose.yaml环境变量为POSTGRES_PASSWORD/POSTGRES_DB健康检查用pg_isready -U postgres -d dbx默认宿主端口为10301其冒烟步骤用env PGPASSWORD... psql -h 127.0.0.1 -p 5432 ... -Atc SELECT note FROM dbx_smoke WHERE id1通过 TCP 真实走一遍客户端连接。4.3 特殊产品Redis 与无命名数据库约定Redis 不遵循官方镜像的 init 目录约定因此其init/目录只有 README.md 说明文档真正的冒烟数据由verify在运行时创建并读取。看 redis/7.4/recipe.json 的 smoke 定义smoke: { steps: [ { name: seed smoke key, command: [redis-cli, -a, ${DB_PASSWORD}, SET, dbx:smoke, DBX smoke], expect: OK }, { name: read smoke key, command: [redis-cli, -a, ${DB_PASSWORD}, GET, dbx:smoke], expect: DBX smoke } ] }Redis 使用DB 0与dbx:键前缀dbx:smokeconnection中database: 0表示逻辑库编号。对应 compose.yaml 通过command直接传参启用 AOF 与密码command: [redis-server, --appendonly, yes, --requirepass, ${DB_PASSWORD:-123456}] environment: REDIS_PASSWORD: ${DB_PASSWORD:-123456}注意注释说明将密码保留在容器环境变量中是为了让CMD-SHELL健康检查能够安全地引用它redis-cli -a $$REDIS_PASSWORD ping | grep PONG避免在 Compose 文件中出现明文密码拼接。五、端口规划101xx–115xx 专属段位为保证所有已提交配方可以同时启动而不冲突、也不占用常见服务端口每个产品分配专属的101xx–115xx宿主端口段DB_PORT为每项配方的主端口。已确认的默认分配产品默认 DB_PORT服务原生端口MySQL101013306PostgreSQL103015432Redis105016379ClickHouse106008123Elasticsearch11500另 11501 为 transport9200其余产品的端口可在make db-list输出中查看。辅助端口使用各服务专属的环境变量覆盖例如 elasticsearch/6.8/compose.yaml 中 transport 端口为${ELASTICSEARCH_TRANSPORT_PORT:-11501}。六、变量覆盖与安全绑定6.1 可用环境变量变量作用默认值DB_PORT覆盖主连接宿主端口各配方专属端口DB_PASSWORD覆盖密码123456DB_BIND_ADDRESS绑定地址127.0.0.1各服务专属变量覆盖辅助端口如ELASTICSEARCH_TRANSPORT_PORT覆盖示例DB_PORT13306 DB_PASSWORDS3cret!x make db DBmysql8.46.2 远程访问的安全前提端口默认仅绑定回环地址127.0.0.1这保证了本地验证不会意外暴露服务。若确实需要远程访问必须同时满足三个条件见 README.md显式设置DB_BIND_ADDRESS0.0.0.0使用强密码而不是默认的123456覆盖DB_PASSWORD用防火墙规则限制来源访问。这三者缺一不可——只改绑定地址而保留弱密码等同于把无防护数据库直接暴露到网络。七、验证与维护db-check 与测试7.1 make db-check配方静态校验添加或修改任何配方后都必须运行make db-check它执行三类检查见 README.md校验配方结构recipe.json 字段完整性与一致性校验标准容器名dbx-product-version要求 Docker Compose 逐个校验 Compose 文件语法。7.2 新增配方的完整流程按 RECIPE_TEMPLATE.md 的指引在deploy/database/product/version/下创建三个组成部分后按顺序执行验证流水线pnpm test:db-env # 单元/集成测试验证 recipe 解析与端口一致性 make db-check # 校验配方结构与 Compose 文件 make db-verify DBproductversion # 启动并执行冒烟步骤 make db-reset DBproductversion CONFIRM1 # 清空数据验证可重置7.3 编写 recipe.json 的硬性规则defaultPort必须设置为服务的原生端口每一个默认宿主映射都必须显式声明在hostPorts中connection.port与 Compose 中DB_PORT的回退默认值必须一致都等于hostPorts.DB_PORT必须同时提供非交互的smoke.steps命令与交互式shell命令镜像必须固定版本宿主绑定必须默认${DB_BIND_ADDRESS:-127.0.0.1}端口取自本产品101xx–115xx段容器名为dbx-product-version密码123456、数据库dbxRedis 类无命名数据库服务则用 DB 0 与dbx:键前缀。7.4 shell 补全与跨平台make db-completion输出 Bash、Zsh、PowerShell 三种补全的加载方式对应脚本位于 deploy/database/completion/dbx-make.bash、_dbx-make.zsh、Dbx.Make.ps1可动态补全配方选择器如输入mysql后补全版本。由于 Make 目标避免了 POSIX Shell 条件语法这套流程在PowerShell、Git Bash、WSL中均可通过 GNU Make 正常工作。八、小结deploy/database/通过固定镜像 命名卷 回环绑定 健康检查 init/冒烟数据五要素把数据库人工验证变成了可复现、可校验、可并发的工程化流程make db一键起服务、make db-verify自动冒烟、dbx://connection/new深链直通新建连接对话框而make db-check与pnpm test:db-env保证了新增配方的正确性。对 DBX 贡献者而言掌握 recipe.json/compose.yaml 的编写约定与端口分配规则即可在几分钟内为任何新的数据库版本建立一套可复现的验证环境。延伸阅读配方编写规范见 RECIPE_TEMPLATE.mdMake 目标定义见 Makefile即仓库根目录 Makefile完整配方清单见 deploy/database。赞分享数据库开发者工具桌面应用CLIMCP 服务AI 应用【免费下载链接】dbx15MB轻量级跨平台数据库客户端、数据库管理工具。支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、DuckDB、ClickHouse、SQL Server 等。15MB, lightweight, cross-platform database client. Supports MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, ClickHouse, SQL Server and more.项目地址https://gitcode.com/t8y2/dbx点击查看免费下载相关推荐DBX 可复现数据库测试环境deploy/database 配方体系与 Make 工作流实战指南DBX 可复现数据库测试环境deploy/database 配方体系与 Make 工作流实战指南 DBX 在 deploy/database/ 目录维护了一套数据库客户端数据库桌面应用CLI后端MCP 服务AI 应用DBX Database Recipe 模板详解为 90 数据库构建可复现的 Docker 测试环境DBX Database Recipe 模板详解为 90 数据库构建可复现的 Docker 测试环境 DBX 内置一套 deploy/database 测试数据库客户端数据库桌面应用CLI后端MCP 服务AI 应用DBX 数据库测试环境实战基于 recipe 的 Docker Compose 配方系统与 Make 目标详解DBX 数据库测试环境实战基于 recipe 的 Docker Compose 配方系统与 Make 目标详解 本文围绕 DBX 仓库中的 deploy/da数据库客户端数据库桌面应用CLI后端MCP 服务AI 应用上一篇SWIG部署指南如何在生产环境中正确配置和使用下一篇parabeac_core 状态管理四重奏Bloc、Provider、Riverpod、Stateful 生成策略完整对比创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考