数据库测试实验室

数据库测试实验室提供轻量、固定版本的 Docker Compose 环境，方便使用真实数据库版本验证 DBX。每个配方都使用命名数据卷、健康检查、初始化数据或验证阶段创建的冒烟数据，并且默认监听 127.0.0.1。

可用配方

每个产品使用专属的 101xx 至 115xx 宿主端口段，校验器会验证全部声明的默认映射位于正确范围且全局唯一。默认密码统一为 123456，默认数据库名为 dbx。Redis 不支持命名数据库，因此使用 DB 0，并以 dbx: 作为冒烟键前缀。Compose 默认使用 CNB 镜像列；官方上游镜像列保留原始镜像地址，便于核对来源或直接拉取。Redis 3.0.7 仅支持 amd64；在 arm64 主机上启动时会单独提醒，Docker 将使用模拟运行。其余配方均支持 amd64 和 arm64。

Nacos 使用管理员用户名 nacos、密码 123456 和默认 public 命名空间。V2 的 HTTP、gRPC 和 Raft 宿主端口为 11000、11001、11002；V3 的 HTTP、Web 控制台、gRPC 和 Raft 宿主端口为 11003、11004、11005、11006。两个版本默认即可并行运行。

DB_PORT=11030 NACOS_CONSOLE_PORT=11031 NACOS_GRPC_PORT=11032 NACOS_RAFT_PORT=11033 make db DB=nacos@3.2

r-nacos 使用管理员账号 admin 和密码 123456。DBX 配方的 HTTP、gRPC 和 Web 控制台宿主端口默认分别为 11100、11101、11102；上游单机 Compose 使用 8848:8848、9848:9848、10848:10848。

DB_PORT=11130 RNACOS_GRPC_PORT=11131 RNACOS_CONSOLE_PORT=11132 make db DB=rnacos@0.8

etcd 会创建密码为 123456 的 root 用户、授予 root 角色并开启认证。默认客户端和 peer 主机端口为 10700、10701。如需使用上游 Docker 命令中的端口，可执行：

DB_PORT=2379 ETCD_PEER_PORT=2380 make db DB=etcd@3.7

Qdrant 将 123456 作为管理员 API Key。在 DBX 中请将用户名留空，并把 API Key 填入密码字段，驱动会通过 HTTP 请求头 api-key 发送。HTTP 和 gRPC 默认主机端口分别为 11200、11201。如需使用上游 Docker 命令中的端口，可执行：

DB_PORT=6333 QDRANT_GRPC_PORT=6334 make db DB=qdrant@1.8

ZooKeeper 使用 Digest 凭据 root / 123456 保护 /dbx 节点。默认主机端口为 10800；设置 DB_PORT=2181 即可匹配上游 Docker 命令。ZooKeeper 的 Digest ACL 模型保护单个节点，并不提供全局登录开关。

Kafka 和 Pulsar 均为刻意保持未认证的单节点开发配方：Kafka 使用 PLAINTEXT，Pulsar 使用 standalone，因此不要将它们暴露到远程网络。Kafka 如需使用常用端口，可执行 DB_PORT=9092 make db DB=kafka@4.3；Pulsar 使用常用端口可执行 DB_PORT=6650 PULSAR_WEB_PORT=8080 make db DB=pulsar@4.2。

Redis 3.0.7 和 Redis 7.4.9 用于覆盖兼容性的两个端点。Redis 3 早于 ACL、RESP3、Streams 及许多现代命令，Redis 7 则覆盖当前协议与命令集。对这个实验室而言，同时保留 6.2 和 7.4 所提供的兼容性覆盖更小。

Consul 为单节点开发模式，使用 agent -dev -client=0.0.0.0 -ui 启动，不启用 ACL。HTTP API 与 UI、gRPC 和 DNS 的默认宿主端口分别为 10900、10901 和 10902；DNS 同时开放 TCP 和 UDP。以下命令可使用本地常用端口 8500、8502 和 8600：

DB_PORT=8500 CONSUL_GRPC_PORT=8502 CONSUL_DNS_PORT=8600 make db DB=consul@2.0.2

Elasticsearch 6.8 以未认证的单节点开发集群运行，并禁用机器学习功能。HTTP API 和 transport 默认宿主端口为 11500、11501；以下命令可使用上游端口 9200、9300：

DB_PORT=9200 ELASTICSEARCH_TRANSPORT_PORT=9300 make db DB=elasticsearch@6.8

所有已提交配方都有唯一的默认宿主端口分配，因此版本和产品可默认并行运行。仅在本地规范需要不同端口时使用 DB_PORT：

DB_PORT=10150 make db DB=mysql@5.7
make db DB=mysql@8.4

启动并验证环境

在仓库根目录执行。先列出可用配方，再选择数据库和版本：

make db
make db-list
make db DB=postgresql@17.4
make db-verify DB=postgresql@17.4
make db DB=rnacos@0.8
make db DB=consul@2.0.2
make db DB=elasticsearch@6.8

不带参数执行 make db 会输出当前全部支持的、可直接复制启动的命令，以及可选参数。传入 DB=product@version 后，db 会等待 Compose 健康检查通过并输出 DBX 连接字段；对于 DBX 已支持的连接类型，还会输出预填完成的 dbx://connection/new 深链。etcd、Consul、Nacos 2、Nacos 3 和 r-nacos 均已支持，其中 Nacos 配方会自动选择正确分流，Nacos 3 使用 API 端口而非独立控制台端口。复制该链接到浏览器或终端执行 open '<链接>'，即可打开桌面端的新建连接窗口。使用前请先安装并启动一次 DBX 桌面端以注册 dbx:// 协议。深链可能包含数据库密码或 Consul ACL token，因此不要将其写入共享终端历史、日志或工单。Kafka、Pulsar 等尚未具备 DBX 连接类型的配方会明确显示深链不可用。db-verify 还会在数据库容器中执行配方中的冒烟命令，并校验预期输出；提交数据库相关修复前推荐执行此命令。

命令和变量

DB_BIND_ADDRESS 修改主机侧绑定地址，DB_PORT 修改主机侧端口，DB_PASSWORD 修改默认密码。例如：

DB_PORT=13306 DB_PASSWORD=local-secret make db-verify DB=mysql@8.4

远程访问必须显式启用：

DB_BIND_ADDRESS=0.0.0.0 DB_PASSWORD=local-secret make db DB=mysql@8.4

db-reset 受安全保护：只有设置 CONFIRM=1 才会删除命名卷。Redis 不支持镜像初始化目录约定；其 init/README.md 说明了 verify 会创建并读取的冒烟键。需要诊断时，可直接运行 pnpm db:env -- info|status|logs|shell <product> <version>。

Tab 补全

仓库提供 Make 目标和 DB=product@version 值的动态补全。它会读取当前配方目录，因此新增版本后无需修改补全脚本。

# Bash
source deploy/database/completion/dbx-make.bash

# Zsh
autoload -Uz compinit && compinit
source deploy/database/completion/_dbx-make.zsh

# PowerShell
. .\deploy\database\completion\Dbx.Make.ps1

运行 make db-completion 可打印上述命令。加载对应脚本后，在 make db DB= 后按 Tab 即可选择配方。Make 目标本身已避免依赖 POSIX Shell 条件语法，因此在 PowerShell、Git Bash 或 WSL 中使用 GNU Make 均可运行；仍需安装 Docker Desktop 和 Node.js/pnpm。

添加配方

在 deploy/database/<product>/<version>/ 下添加目录，并提供：

recipe.json
compose.yaml
init/

recipe.json 提供 DBX 连接字段和冒烟命令数组。不要使用 shell 字符串，命令必须作为参数数组执行。Compose 文件必须固定镜像版本、使用命名卷和健康检查、将端口默认绑定至 ${DB_BIND_ADDRESS:-127.0.0.1}，并把 container_name 设置为 dbx-<product>-<version>。

完成后运行：

pnpm test:db-env
make db-check