DBX Database Recipe 模板详解为 90 数据库构建可复现的 Docker 测试环境【免费下载链接】dbx20 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbxDBX 内置一套deploy/database测试环境体系每个数据库产品以「版本化 Recipe」recipe.json compose.yaml init/的形式把镜像、端口、凭据、冒烟验证和交互式入口固化成可一键启动的环境。本文以 RECIPE_TEMPLATE.md 为核心逐条拆解 Recipe 的目录约定、字段规范与端口规划并结合 scripts/database-env.mjs 中的真实校验逻辑帮你从零写出一个能通过make db-check与make db-verify的标准 Recipe。一、Recipe 的目录结构与三件套模板要求每个环境放在deploy/database/product/version/下固定包含三个部分见 deploy/database/README.md 的 Recipe layout 一节product/version/ ├── recipe.json # 连接字段与冒烟命令 ├── compose.yaml # Docker Compose 环境定义 └── init/ # 随环境初始化的数据三者分工明确recipe.json声明「怎么连进来」——宿主端口、连接凭据、非交互冒烟命令和交互式 shell 入口是pnpm db:env工具链的唯一事实来源compose.yaml声明「怎么跑起来」——镜像、端口映射、卷、健康检查必须与recipe.json的端口声明严格一致init/初始化数据。以 MySQL 为例mysql/8.4/compose.yaml 将./init只读挂载到/docker-entrypoint-initdb.d容器首次启动时自动执行其中的 SQL。一个细节需要注意Redis 这类不支持镜像初始化目录约定的服务没有init/数据文件其 README如 redis/7.4 对应目录改为文档化verify阶段会创建并读回的冒烟键。二、硬性约定镜像、命名、端口与凭据模板第二段列出了所有 Recipe 必须满足的强制约束。下面结合仓库中真实 Recipe 逐条说明。2.1 固定版本镜像与容器命名每个 Recipe 必须使用pinned image精确到 patch 版本号。例如 mysql/8.4/recipe.json 声明image: docker.cnb.cool/znb/images/mysql:8.4.6而目录名用displayVersion8.4表示redis/7.4/recipe.json 则固定redis:7.4.9-alpine。compose.yaml的container_name必须为dbx-product-version如 mysql/8.4/compose.yaml 第 4 行的dbx-mysql-8.4。该校验是自动化的scripts/database-env.mjs 会检查 compose 文件中是否存在container_name: dbx-product-displayVersion缺失直接报错。2.2 端口规划defaultPort 与 hostPorts这是模板中最容易被忽视、却决定多环境能否并存的关键设计defaultPort填服务原生端口3306、5432、6379、9092…仅用于标识协议语义实际暴露给宿主机的端口放在hostPorts中每个产品独占101xx–115xx区间内的一组端口因此同一仓库的所有环境可以并行运行而互不冲突也不会撞上常见服务端口。仓库中已验证的分配示例产品原生端口 (defaultPort)hostPorts 声明区间MySQL 8.43306DB_PORT: 10101101xxPostgreSQL 17.45432DB_PORT: 10301103xxRedis 7.46379DB_PORT: 10501105xxetcd 3.72379DB_PORT: 10700,ETCD_PEER_PORT: 10701107xxNacos 2.58848DB_PORT: 11000,NACOS_GRPC_PORT: 11001,NACOS_RAFT_PORT: 11002110xxKafka 4.39092DB_PORT: 11300113xx对于Kafka、Nacos、etcd 这类多端口服务hostPorts会声明辅助端口辅助端口的宿主侧映射通过对应的专用环境变量覆盖README 说明service-specific variables override auxiliary ports但主端口统一走DB_PORT。2.3 一致性铁律三处端口必须相同模板明确规定connection.port与 Compose 中DB_PORT的默认回退值必须都等于hostPorts.DB_PORT。这条规则同样有自动化校验兜底scripts/database-env.mjsconnection.port must match hostPorts.DB_PORT同文件 L298-L300逐条比对compose.yaml中的端口默认值与recipe.json的hostPorts不一致即判失败。因此写 Recipe 时只需要选定hostPorts中的端口然后在recipe.json与compose.yaml中机械地复用同一数字即可。2.4 回环绑定、密码与默认库宿主绑定地址默认为回环模板要求 compose 端口写成${DB_BIND_ADDRESS:-127.0.0.1}:${DB_PORT:-10101}:3306形式见 mysql/8.4/compose.yaml。需要远程访问时显式设置DB_BIND_ADDRESS0.0.0.0同时必须更换强密码并配置防火墙——这属于运维侧决策模板默认姿态是「仅本机可连」。密码统一为123456默认库统一为dbx。校验逻辑scripts/database-env.mjs会强制connection.password必须是123456除非authentication: none此时禁止声明密码connection.database必须是dbx。Redis 例外没有命名数据库概念connection.database固定为0数字且键统一使用dbx:前缀例如冒烟键dbx:smoke见 redis/7.4/recipe.json。etcd 同样采用dbx:键前缀etcd/3.7/recipe.json。三、recipe.json 字段全解以 MySQL 8.4 为参照mysql/8.4/recipe.json 是一个最典型的单端口关系型 Recipe完整内容仅 14 行{ 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 }] } }字段说明取值约束来自 scripts/database-env.mjs 的必填与格式校验字段说明约束database/name产品标识小写目录名/ 展示名必填version/displayVersion精确镜像版本 / 目录级版本productdisplayVersion选择器用它必填image固定版本镜像必填须与 compose 一致platforms支持的平台列表db-list会展示如linux/amd64、linux/arm64servicecompose 中的 service 名必填通常为databasedefaultPort原生服务端口整数1–65534connection客户端连接参数host必须为127.0.0.1port等于hostPorts.DB_PORThostPorts环境变量 → 宿主端口映射非空对象键必须形如DB_PORT^[A-Z][A-Z0-9_]*$端口不可复用database-env.mjsshell交互式容器内 shell 入口非空命令数组database-env.mjssmoke非交互冒烟步骤steps非空每步必须有name、command数组与expect期望输出database-env.mjsconnection中还有若干按产品出现的可选字段authentication: noneKafka 等无认证服务使用kafka/4.3/recipe.json声明后不得再带password协议专属端口Kafka 的internalPort: 9095容器内 bootstrap 地址、etcd 的peerPort: 10701etcd/3.7/recipe.json、Nacos 的grpcPort/raftPortnacos/2.5/recipe.jsondeepLinkType如 Nacos 的nacos-v2用于生成 DBX 深度链接。smoke 与 shell 的设计差异模板要求两者缺一不可但定位不同smoke.steps是非交互的每步在容器内执行命令工具检查 stdout 是否包含expect子串。MySQL 的冒烟是查询init/初始化出的dbx_smoke表Redis 则是「先SET dbx:smoke、再GET dbx:smoke读回」两步redis/7.4/recipe.jsonKafka 一步之内完成建 topic、生产、消费并断言DBX smokekafka/4.3/recipe.json。shell是交互式的作为容器内 REPL 入口保留给人工排查。命令中的${DB_PASSWORD}会在运行时被工具链展开为实际密码database-env.mjs 构造DB_PASSWORD/DB_PORT环境。PostgreSQL 的 shell 还示范了通过env PGPASSWORD... psql注入密码的写法postgresql/17.4/recipe.json。可选的 bootstrap幂等初始化对于「镜像起来时凭据尚未初始化」的服务etcd 需要先建 root 用户再开启鉴权Nacos 需要先初始化管理员密码Recipe 可声明bootstrap块bootstrap.check一条幂等的检查命令 期望输出。etcd/3.7 用etcdctl auth status期望输出Authentication Status: truebootstrap.stepscheck 未通过时依次执行的初始化步骤建用户、建角色、授权、启用鉴权。执行逻辑见 scripts/database-env.mjs先跑 check若输出已包含期望值则跳过全部 steps否则逐步执行并断言每步输出。这让make db-verify在容器重建后也能安全重放初始化而不重复执行建号操作。四、compose.yaml 编写要点以 mysql/8.4/compose.yaml 为范本标准写法包含五个要素services: database: image: docker.cnb.cool/znb/images/mysql:8.4.6 # 1. 固定版本镜像与 recipe.json 一致 container_name: dbx-mysql-8.4 # 2. 规范容器名 restart: always ports: - ${DB_BIND_ADDRESS:-127.0.0.1}:${DB_PORT:-10101}:3306 # 3. 回环绑定 DB_PORT 回退值 environment: MYSQL_ROOT_PASSWORD: ${DB_PASSWORD:-123456} # 4. 密码回退值为 123456 MYSQL_DATABASE: dbx volumes: - data:/var/lib/mysql # 5. 命名卷供 db-reset 清理 - ./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:几个容易出错的点端口行三段式绑定地址:宿主端口:容器端口缺一不可且默认回退值${DB_PORT:-10101}必须等于hostPorts.DB_PORT见第三节 2.3健康检查是必备项README 将 health check 列为每个 Recipe 的标准配置之一。CMD-SHELL中引用环境变量需写成$$VARCompose 转义Redis 的写法见 redis/7.4/compose.yamlredis-cli -a $$REDIS_PASSWORD ping | grep PONG并特意把密码放容器环境以便安全引号化命名卷data:承载数据目录make db-reset会删除它——这也是db-reset强制要求CONFIRM1的原因deploy/database/README.md。五、验证与交付检查清单模板最后给出了新增/修改 Recipe 后的四条命令全部在仓库根目录执行pnpm test:db-env make db-check make db-verify DBproductversion make db-reset DBproductversion CONFIRM1各命令的职责目标定义见 Makefile底层均为pnpm db:env命令作用pnpm test:db-env运行工具链自身的单元测试确保验证逻辑本身可信make db-check静态校验全部 Recipe结构字段、端口一致性、容器名、compose 文件由 Docker Compose 实机校验make db-verify DBmysql8.4拉起环境、执行 bootstrap如需并逐步运行smoke.steps断言make db-reset DBmysql8.4 CONFIRM1删除容器与命名卷回到干净状态必须显式确认辅助目标还包括make db-list按产品分组列出各版本的容器端口映射、镜像与平台、make db打印可复制的启动命令、make db-down仅停止不删数据、make db-completionBash/Zsh/PowerShell 补全脚本在 deploy/database/completion/。另外两点实操提示深度链接对 DBX 支持的连接类型verify成功后会打印预填好参数的dbx://connection/new链接由 database-env.mjs 用connection字段拼装macOS 上可open link直接打开新建连接对话框链接含密码不要留存到共享日志。无兼容连接类型的 Recipe 会明确提示不提供深链。排查分层静态问题看db-check的报错信息错误文案即规范条款运行时问题用pnpm db:env -- info|status|logs|shell product version逐层诊断deploy/database/README.md。小结DBX 的 Recipe 模板本质上是一份「可机检的契约」product/version/三件套定义环境与连接defaultPort/hostPorts/connection.port三处端口一致性、dbx-*容器名、123456密码与dbx默认库构成统一约定smokeshell 可选bootstrap覆盖自动验证与人工排查。按模板约束写完三个文件后用make db-check过静态校验、make db-verify过运行时断言即完成一个新数据库测试环境的交付。更多现成范本可对照仓库中 MySQL、PostgreSQL、Redis、etcd、Nacos、Kafka 等 18 个产品的 20 余个版本化 Recipedeploy/database/。【免费下载链接】dbx20 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考