147 lines
9.0 KiB
Plaintext
147 lines
9.0 KiB
Plaintext
---
|
||
title: 数据库测试实验室
|
||
description: 为 DBX 开发与验证启动可重复创建的本地数据库实例。
|
||
---
|
||
|
||
数据库测试实验室提供轻量、固定版本的 Docker Compose 环境，方便使用真实数据库版本验证 DBX。每个配方都使用命名数据卷、健康检查、初始化数据或验证阶段创建的冒烟数据，并且默认监听 `127.0.0.1`。
|
||
|
||
<Callout type="warning">默认密码为 `123456`，但端口默认只能从本机访问。如需远程访问，请显式设置 `DB_BIND_ADDRESS=0.0.0.0`、修改 `DB_PASSWORD`，并配置常规防火墙规则。这些环境用于开发，不是生产部署模板。</Callout>
|
||
|
||
## 可用配方
|
||
|
||
| 数据库 | 版本目录 | Docker Hub 官方镜像 | Compose 使用的 CNB 镜像 | 默认宿主端口 | 容器名 |
|
||
| --- | --- | --- | --- | ---: | --- |
|
||
| ClickHouse | `clickhouse/24.8` | `clickhouse/clickhouse-server:24.8.14.39` | `docker.cnb.cool/znb/images/clickhouse-server:24.8.14.39` | `8124` | `dbx-clickhouse-24.8` |
|
||
| etcd | `etcd/3.7` | `gcr.io/etcd-development/etcd:v3.7.0` | `docker.cnb.cool/znb/images/etcd:v3.7.0` | `2380` | `dbx-etcd-3.7` |
|
||
| Kafka | `kafka/4.3` | `apache/kafka:4.3.1` | `docker.cnb.cool/znb/images/kafka:4.3.1` | `9093` | `dbx-kafka-4.3` |
|
||
| MariaDB | `mariadb/10.11` | `mariadb:10.11.11` | `docker.cnb.cool/znb/images/mariadb:10.11.11` | `3307` | `dbx-mariadb-10.11` |
|
||
| MongoDB | `mongodb/5.0` | `mongo:5.0.5` | `docker.cnb.cool/znb/images/mongo:5.0.5` | `27018` | `dbx-mongodb-5.0` |
|
||
| MongoDB | `mongodb/8.2` | `mongo:8.2.3-noble` | `docker.cnb.cool/znb/images/mongo:8.2.3-noble` | `27018` | `dbx-mongodb-8.2` |
|
||
| MySQL | `mysql/5.7` | `mysql:5.7.44` | `docker.cnb.cool/znb/images/mysql:5.7.44` | `3307` | `dbx-mysql-5.7` |
|
||
| MySQL | `mysql/8.4` | `mysql:8.4.6` | `docker.cnb.cool/znb/images/mysql:8.4.6` | `3307` | `dbx-mysql-8.4` |
|
||
| Nacos | `nacos/2.5` | `nacos/nacos-server:v2.5.2` | `docker.cnb.cool/znb/images/nacos-server:v2.5.2` | `8849` | `dbx-nacos-2.5` |
|
||
| Nacos | `nacos/3.2` | `nacos/nacos-server:v3.2.2` | `docker.cnb.cool/znb/images/nacos-server:v3.2.2` | `8849` | `dbx-nacos-3.2` |
|
||
| PostgreSQL | `postgresql/14.23` | `postgres:14.23` | `docker.cnb.cool/znb/images/postgres:14.23` | `5433` | `dbx-postgresql-14.23` |
|
||
| PostgreSQL | `postgresql/17.4` | `postgres:17.4` | `docker.cnb.cool/znb/images/postgres:17.4` | `5433` | `dbx-postgresql-17.4` |
|
||
| Pulsar | `pulsar/4.2` | `apachepulsar/pulsar:4.2.3` | `docker.cnb.cool/znb/images/pulsar:4.2.3` | `6651` | `dbx-pulsar-4.2` |
|
||
| Qdrant | `qdrant/1.8` | `qdrant/qdrant:v1.8.3` | `docker.cnb.cool/znb/images/qdrant:v1.8.3` | `6334` | `dbx-qdrant-1.8` |
|
||
| Redis | `redis/3.0.7` | `redis:3.0.7-alpine` | `docker.cnb.cool/znb/images/redis:3.0.7-alpine` | `6380` | `dbx-redis-3.0.7` |
|
||
| Redis | `redis/7.4` | `redis:7.4.9-alpine` | `docker.cnb.cool/znb/images/redis:7.4.9-alpine` | `6380` | `dbx-redis-7.4` |
|
||
| r-nacos | `rnacos/0.8` | `qingpan/rnacos:v0.8.5` | `docker.cnb.cool/znb/images/rnacos:v0.8.5` | `8849` | `dbx-rnacos-0.8` |
|
||
| ZooKeeper | `zookeeper/3.9` | `zookeeper:3.9.5` | `docker.cnb.cool/znb/images/zookeeper:3.9.5` | `2182` | `dbx-zookeeper-3.9` |
|
||
|
||
所有网络数据库的默认宿主端口都比标准端口大 `1`，并且该约定由配方校验器强制检查。默认密码统一为 `123456`，默认数据库名为 `dbx`。Redis 不支持命名数据库，因此使用 DB 0，并以 `dbx:` 作为冒烟键前缀。Compose 默认使用 CNB 镜像列；Docker Hub 列保留官方上游地址，便于核对来源或直接拉取。Redis 3.0.7 仅支持 amd64；在 arm64 主机上启动时会单独提醒，Docker 将使用模拟运行。其余配方均支持 amd64 和 arm64。
|
||
|
||
Nacos 使用管理员用户名 `nacos`、密码 `123456` 和默认 `public` 命名空间。V3 配方额外在 `http://127.0.0.1:8010` 暴露 Web 控制台；V2 控制台使用主端口 `8849`。如需并行运行两个 Nacos 版本，请为其中一个版本设置 `NACOS_CONSOLE_PORT`、`NACOS_GRPC_PORT` 和 `NACOS_RAFT_PORT`。
|
||
|
||
```bash
|
||
DB_PORT=8818 NACOS_CONSOLE_PORT=8010 NACOS_GRPC_PORT=9818 NACOS_RAFT_PORT=9819 make db DB=nacos@3.2
|
||
```
|
||
|
||
r-nacos 使用管理员账号 `admin` 和密码 `123456`。DBX 配方的 HTTP、gRPC 和 Web 控制台宿主端口默认分别为 `8849`、`9849`、`10849`；上游单机 Compose 使用 `8848:8848`、`9848:9848`、`10848:10848`。若需避开本机端口冲突，可使用以下自定义宿主端口映射（不是上游默认值）：
|
||
|
||
```bash
|
||
DB_PORT=3848 RNACOS_GRPC_PORT=3748 RNACOS_CONSOLE_PORT=3048 make db DB=rnacos@0.8
|
||
```
|
||
|
||
etcd 会创建密码为 `123456` 的 `root` 用户、授予 root 角色并开启认证。默认客户端和 peer 主机端口为 `2380`、`2381`。如需使用上游 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 默认主机端口分别为 `6334`、`6335`。如需使用上游 Docker 命令中的端口，可执行：
|
||
|
||
```bash
|
||
DB_PORT=6333 QDRANT_GRPC_PORT=6334 make db DB=qdrant@1.8
|
||
```
|
||
|
||
ZooKeeper 使用 Digest 凭据 `root` / `123456` 保护 `/dbx` 节点。默认主机端口为 `2182`；设置 `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 所提供的兼容性覆盖更小。
|
||
|
||
同一数据库的不同版本默认会共用宿主机端口。通常一次启动一个版本；需要并行对比时，为其中一个版本指定其他端口：
|
||
|
||
```bash
|
||
DB_PORT=13307 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=product@version` 后，`db` 会等待 Compose 健康检查通过并输出 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 <product> <version>`。
|
||
|
||
## 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/<product>/<version>/` 下添加目录，并提供：
|
||
|
||
```text
|
||
recipe.json
|
||
compose.yaml
|
||
init/
|
||
```
|
||
|
||
`recipe.json` 提供 DBX 连接字段和冒烟命令数组。不要使用 shell 字符串，命令必须作为参数数组执行。Compose 文件必须固定镜像版本、使用命名卷和健康检查、将端口默认绑定至 `${DB_BIND_ADDRESS:-127.0.0.1}`，并把 `container_name` 设置为 `dbx-<product>-<version>`。
|
||
|
||
完成后运行：
|
||
|
||
```bash
|
||
pnpm test:db-env
|
||
make db-check
|
||
```
|