# 数据库测试实验室 > 为 DBX 开发与验证启动可重复创建的本地数据库实例。 Source: https://dbxio.com/cn/docs/database-lab Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/database-lab. 数据库测试实验室提供轻量、固定版本的 Docker Compose 环境，方便使用真实数据库版本验证 DBX。每个配方都使用命名数据卷、健康检查、初始化数据或验证阶段创建的冒烟数据，并且默认监听 `127.0.0.1`。 默认密码为 `123456` ，但端口默认只能从本机访问。如需远程访问，请显式设置 `DB_BIND_ADDRESS=0.0.0.0` 、修改 `DB_PASSWORD` ，并配置常规防火墙规则。这些环境用于开发，不是生产部署模板。 ## 可用配方 | 数据库 | 版本目录 | 官方上游镜像 | Compose 使用的 CNB 镜像 | 默认宿主端口 | 容器名 | | ------------- | ------------------- | --------------------------------------------------- | --------------------------------------------------------- | ------: | ----------------------- | | ClickHouse | `clickhouse/24.8` | `clickhouse/clickhouse-server:24.8.14.39` | `docker.cnb.cool/znb/images/clickhouse-server:24.8.14.39` | `10600` | `dbx-clickhouse-24.8` | | Consul | `consul/2.0.2` | `hashicorp/consul:2.0.2` | `docker.cnb.cool/znb/images/consul:2.0.2` | `10900` | `dbx-consul-2.0.2` | | Elasticsearch | `elasticsearch/6.8` | `docker.elastic.co/elasticsearch/elasticsearch:6.8` | `docker.cnb.cool/znb/images/elasticsearch:6.8` | `11500` | `dbx-elasticsearch-6.8` | | etcd | `etcd/3.5` | `quay.io/coreos/etcd:v3.5.21` | `quay.io/coreos/etcd:v3.5.21` | `10710` | `dbx-etcd-3.5` | | etcd | `etcd/3.7` | `gcr.io/etcd-development/etcd:v3.7.0` | `docker.cnb.cool/znb/images/etcd:v3.7.0` | `10700` | `dbx-etcd-3.7` | | Kafka | `kafka/4.3` | `apache/kafka:4.3.1` | `docker.cnb.cool/znb/images/kafka:4.3.1` | `11300` | `dbx-kafka-4.3` | | MariaDB | `mariadb/10.11` | `mariadb:10.11.11` | `docker.cnb.cool/znb/images/mariadb:10.11.11` | `10200` | `dbx-mariadb-10.11` | | MongoDB | `mongodb/5.0` | `mongo:5.0.5` | `docker.cnb.cool/znb/images/mongo:5.0.5` | `10400` | `dbx-mongodb-5.0` | | MongoDB | `mongodb/8.2` | `mongo:8.2.3-noble` | `docker.cnb.cool/znb/images/mongo:8.2.3-noble` | `10401` | `dbx-mongodb-8.2` | | MySQL | `mysql/5.7` | `mysql:5.7.44` | `docker.cnb.cool/znb/images/mysql:5.7.44` | `10100` | `dbx-mysql-5.7` | | MySQL | `mysql/8.4` | `mysql:8.4.6` | `docker.cnb.cool/znb/images/mysql:8.4.6` | `10101` | `dbx-mysql-8.4` | | Nacos | `nacos/2.5` | `nacos/nacos-server:v2.5.2` | `docker.cnb.cool/znb/images/nacos-server:v2.5.2` | `11000` | `dbx-nacos-2.5` | | Nacos | `nacos/3.2` | `nacos/nacos-server:v3.2.3` | `docker.cnb.cool/znb/images/nacos-server:v3.2.3` | `11003` | `dbx-nacos-3.2` | | PostgreSQL | `postgresql/14.23` | `postgres:14.23` | `docker.cnb.cool/znb/images/postgres:14.23` | `10300` | `dbx-postgresql-14.23` | | PostgreSQL | `postgresql/17.4` | `postgres:17.4` | `docker.cnb.cool/znb/images/postgres:17.4` | `10301` | `dbx-postgresql-17.4` | | Pulsar | `pulsar/4.2` | `apachepulsar/pulsar:4.2.3` | `docker.cnb.cool/znb/images/pulsar:4.2.3` | `11400` | `dbx-pulsar-4.2` | | Qdrant | `qdrant/1.8` | `qdrant/qdrant:v1.8.3` | `docker.cnb.cool/znb/images/qdrant:v1.8.3` | `11200` | `dbx-qdrant-1.8` | | Redis | `redis/3.0.7` | `redis:3.0.7-alpine` | `docker.cnb.cool/znb/images/redis:3.0.7-alpine` | `10500` | `dbx-redis-3.0.7` | | Redis | `redis/7.4` | `redis:7.4.9-alpine` | `docker.cnb.cool/znb/images/redis:7.4.9-alpine` | `10501` | `dbx-redis-7.4` | | r-nacos | `rnacos/0.8` | `qingpan/rnacos:v0.8.5` | `docker.cnb.cool/znb/images/rnacos:v0.8.5` | `11100` | `dbx-rnacos-0.8` | | ZooKeeper | `zookeeper/3.9` | `zookeeper:3.9.5` | `docker.cnb.cool/znb/images/zookeeper:3.9.5` | `10800` | `dbx-zookeeper-3.9` | 每个产品使用专属的 `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`。两个版本默认即可并行运行。 ```bash 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`。 ```bash 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 命令中的端口，可执行： ```bash 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 命令中的端口，可执行： ```bash 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`： ```bash 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`： ```bash DB_PORT=9200 ELASTICSEARCH_TRANSPORT_PORT=9300 make db DB=elasticsearch@6.8 ``` 所有已提交配方都有唯一的默认宿主端口分配，因此版本和产品可默认并行运行。仅在本地规范需要不同端口时使用 `DB_PORT`： ```bash DB_PORT=10150 make db DB=mysql@5.7 make db DB=mysql@8.4 ``` ## 启动并验证环境 在仓库根目录执行。先列出可用配方，再选择数据库和版本： ```bash 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` 还会在数据库容器中执行配方中的冒烟命令，并校验预期输出；提交数据库相关修复前推荐执行此命令。 ## 命令和变量 | Make 目标 | 用途 | | -------------------------------------------- | --------------------------- | | `make db-list` | 列出数据库版本、容器到宿主机端口映射、镜像和支持的平台 | | `make db DB=product@version` | 创建、等待环境就绪并输出连接字段 | | `make db-verify DB=product@version` | 启动并运行冒烟检查 | | `make db-down DB=product@version` | 停止环境但保留数据卷 | | `make db-reset DB=product@version CONFIRM=1` | 删除环境及数据卷 | | `make db-check` | 校验全部配方和 Compose 文件 | `DB_BIND_ADDRESS` 修改主机侧绑定地址，`DB_PORT` 修改主机侧端口，`DB_PASSWORD` 修改默认密码。例如： ```bash DB_PORT=13306 DB_PASSWORD=local-secret make db-verify DB=mysql@8.4 ``` 远程访问必须显式启用： ```bash 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 `。 ## Tab 补全 仓库提供 Make 目标和 `DB=product@version` 值的动态补全。它会读取当前配方目录，因此新增版本后无需修改补全脚本。 ```bash # 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///` 下添加目录，并提供： ```text recipe.json compose.yaml init/ ``` `recipe.json` 提供 DBX 连接字段和冒烟命令数组。不要使用 shell 字符串，命令必须作为参数数组执行。Compose 文件必须固定镜像版本、使用命名卷和健康检查、将端口默认绑定至 `${DB_BIND_ADDRESS:-127.0.0.1}`，并把 `container_name` 设置为 `dbx--`。 完成后运行： ```bash pnpm test:db-env make db-check ```