DBX 中的 Pulsar 4.2 测试环境：standalone 部署与 DBX smoke 冒烟验证指南-平芜编程栈

数据库客户端
数据库
桌面应用
CLI
后端
MCP 服务
AI 应用

【免费下载链接】dbx

20 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

点击查看免费下载

DBX 仓库在deploy/database/下为 Apache Pulsar 4.2 维护了一套可直接复现的 Docker Compose 测试环境，其中init/README.md说明了这套环境的冒烟数据约定：Pulsar standalone 会自动创建public/default命名空间，make db-verify会向persistent://public/default/dbx-smoke发布一条DBX smoke消息来验证端到端可用性。本文以该说明为骨架，结合 compose.yaml、recipe.json 与底层脚本 database-env.mjs，完整讲解该测试环境的结构、冒烟验证原理与实操命令，帮助你快速拉起一个本机 Pulsar 实例并接入 DBX 进行消息队列功能验证。

Pulsar 4.2 测试配方在仓库中的位置

DBX 将每种数据库的测试环境组织为"配方（recipe）"目录，统一遵循deploy/database/README.md中描述的布局：

<product>/<version>/ ├── recipe.json # 连接字段和冒烟命令 ├── compose.yaml # Docker Compose 环境 └── init/ # 环境初始化数据

Pulsar 4.2 配方位于 deploy/database/pulsar/4.2/，由三个部分组成：

compose.yaml：基于固定镜像docker.cnb.cool/znb/images/pulsar:4.2.3的 standalone 部署定义；
recipe.json：声明连接字段、宿主端口映射与冒烟验证步骤；
init/README.md：说明环境初始化数据的语义，即本文所围绕的冒烟数据说明。

文档站点 database-lab.mdx 的配方清单表中也登记了该环境：版本pulsar/4.2、镜像docker.cnb.cool/znb/images/pulsar:4.2.3、宿主端口11400、容器名dbx-pulsar-4.2，与配方文件完全一致。

standalone 模式与 public/default 命名空间的自动创建

init/README.md首先强调了一个关键事实：Pulsar standalone 会自动创建public/default命名空间，因此测试环境无需任何额外的初始化脚本。

这一点在 compose.yaml 中有直接印证：

services: database: image: docker.cnb.cool/znb/images/pulsar:4.2.3 container_name: dbx-pulsar-4.2 restart: always command: ["bin/pulsar", "standalone", "--advertised-address", "localhost"] ports: - "${DB_BIND_ADDRESS:-127.0.0.1}:${DB_PORT:-11400}:6650" - "${DB_BIND_ADDRESS:-127.0.0.1}:${PULSAR_WEB_PORT:-11401}:8080" volumes: - data:/pulsar/data - conf:/pulsar/conf healthcheck: test: ["CMD-SHELL", "bin/pulsar-admin brokers healthcheck"] interval: 10s timeout: 10s retries: 60 start_period: 30s volumes: data: conf:

逐项解读这份配置：

启动命令：以bin/pulsar standalone单机模式启动，并通过--advertised-address localhost声明对外通告地址为localhost。standalone 模式内置了 broker、bookie、zookeeper 等组件，启动后即自动创建public/default租户/命名空间，这正是冒烟消息可以直接发布到persistent://public/default/dbx-smoke的前提。
端口映射：Pulsar 客户端二进制协议端口6650与 Web/HTTP 管理端口8080分别映射到宿主机的11400与11401（均可用环境变量覆盖，详见下文）。DB_BIND_ADDRESS默认127.0.0.1，保证测试环境只对回环地址开放。
数据持久化：命名卷data挂载到/pulsar/data、conf挂载到/pulsar/conf，消息数据与配置在容器重建后仍然保留。
健康检查：以bin/pulsar-admin brokers healthcheck作为探针，interval: 10s、timeout: 10s、最多重试 60 次、启动宽限期start_period: 30s。健康检查通过后，上层编排才会认为环境就绪，这是后续冒烟验证能够稳定执行的基础。

recipe.json 中的connection字段则从 DBX 客户端视角再次确认了该命名空间约定：

"connection": { "host": "127.0.0.1", "port": 11400, "authentication": "none", "database": "dbx", "namespace": "public/default", "webPort": 11401 }

namespace字段直接指向public/default，说明 DBX 在建立 Pulsar 连接时会使用这个 standalone 自动创建的命名空间。

DBX smoke 冒烟数据与 verify 验证流程

init/README.md的第二句话定义了冒烟验证的核心动作：verify命令会向persistent://public/default/dbx-smoke发布DBX smoke消息。注意init/目录本身并没有存放实际的数据文件——这里的"初始化数据"是一种约定说明，真正的数据在验证阶段由命令动态产生。

冒烟步骤定义在 recipe.json 的smoke字段中：

"smoke": { "steps": [ { "name": "produce a smoke message", "command": [ "bin/pulsar-client", "produce", "persistent://public/default/dbx-smoke", "--messages", "DBX smoke" ], "expect": "1 messages successfully produced" } ] }

这段配置的含义是：在容器内执行bin/pulsar-client produce persistent://public/default/dbx-smoke --messages "DBX smoke"，向persistent://public/default/dbx-smoke主题生产一条内容为DBX smoke的消息，并断言命令输出包含1 messages successfully produced。

verify命令的底层实现位于 scripts/database-env.mjs。其执行逻辑（verify分支）依次为：

docker compose up -d --wait启动环境并等待健康检查通过；
ensureBootstrap(recipe)执行必要的引导；
遍历recipe.smoke.steps，对每一步通过docker compose exec -T <service>在容器内执行命令并捕获输出；
若输出不包含step.expect指定的文本，则抛出错误并打印实际输出；包含则打印OK <step name>。

对应代码（节选）：

case 'verify': runCompose(recipe, ['up', '-d', '--wait']); ensureBootstrap(recipe); for (const step of recipe.smoke.steps) { const command = expandSmokeCommand(step.command, recipe); const output = runCompose(recipe, ['exec', '-T', recipe.service, ...command], { capture: true }); if (step.expect && !output.includes(step.expect)) throw new Error(`Smoke check did not contain expected text: ${step.expect}\n${output}`); console.log(`OK ${step.name}`); } break;

此外，database-env.mjs 在配方校验阶段（check分支）会强制smoke.steps非空，且每一步必须包含name、非空的command数组与字符串类型的expect——这保证了每个已提交的配方都带有一组可自动验证的冒烟步骤。

实操：启动 Pulsar 4.2 并执行冒烟验证

所有操作在仓库根目录通过make目标或底层pnpm db:env命令完成。Make 目标定义在 Makefile 中，均委托给pnpm db:env -- <command>：

# 查看所有可用数据库配方 make db-list # 启动 Pulsar 4.2（等价于 pnpm db:env -- start，DB=pulsar@4.2 通过环境变量传递） make db DB=pulsar@4.2 # 启动并执行冒烟验证（发布 DBX smoke 消息） make db-verify DB=pulsar@4.2 # 停止容器 make db-down DB=pulsar@4.2 # 停止并删除命名卷（会清除消息数据，必须显式确认） make db-reset DB=pulsar@4.2 CONFIRM=1

make db-verify是最能体现init/README.md语义的命令：它完成启动、健康检查等待，然后执行produce a smoke message步骤，最终在控制台打印OK produce a smoke message。

诊断与排障时可使用更底层的命令：

pnpm db:env -- info pulsar 4.2 # 打印连接信息 pnpm db:env -- status pulsar 4.2 # 容器状态 pnpm db:env -- logs pulsar 4.2 # 容器日志（FOLLOW=1 时持续跟踪） pnpm db:env -- shell pulsar 4.2 # 进入容器 shell

端口覆盖与常见端口还原

配方默认使用11400/11401以避免与常见服务端口冲突。若需要还原为 Pulsar 的标准端口，database-lab.mdx 给出了明确用法：

DB_PORT=6650 PULSAR_WEB_PORT=8080 make db DB=pulsar@4.2

其中DB_PORT覆盖主连接端口（映射容器6650），PULSAR_WEB_PORT覆盖 Web 管理端口（映射容器8080），与recipe.json中hostPorts字段（DB_PORT: 11400、PULSAR_WEB_PORT: 11401）的覆盖规则一一对应。

通过 DBX 客户端连接 Pulsar

Pulsar 配方完成后即可接入 DBX 客户端。在 catalog.yaml 的连接类型清单中，Apache Pulsar 以mq（消息队列）类别登记：

- id: mq dbType: mq label: Apache Pulsar icon: pulsar pickerIcon: mq port: 8080 user: "" host: 127.0.0.1 category: mq

结合配方connection字段可知，连接参数为：主机127.0.0.1、二进制端口11400、Web 端口11401、无认证（authentication: none）、命名空间public/default、数据库名dbx。

按照 deploy/database/README.md 的说明，对于 DBX 支持的连接类型，make db启动完成后会输出一条预填好的dbx://connection/new深链，在已安装 DBX 桌面端的 macOS 上可直接执行open '<链接>'打开新建连接对话框。由于该链接可能包含密码，文档明确提醒不要将其写入共享终端历史、日志或工单。

安全边界与配方校验

Pulsar 配方是刻意保持无认证的单节点开发环境。database-lab.mdx 明确指出：Kafka 与 Pulsar 均为无认证的单节点开发配方，Pulsar 使用 standalone 模式，切勿将这类服务暴露到远程。

配方对此提供了三层保护：

回环地址绑定：DB_BIND_ADDRESS默认127.0.0.1，端口只对本机开放；
显式放开：如确需远程访问，必须显式设置DB_BIND_ADDRESS=0.0.0.0，同时使用强DB_PASSWORD与防火墙规则限制访问；
配方校验：make db-check（对应pnpm db:env -- check）会校验每个配方的结构、标准容器名（dbx-<product>-<version>），并要求 Docker Compose 校验 Compose 文件本身，防止提交损坏的配方。

小结

围绕 init/README.md 的两条核心约定，可以还原出 DBX 的 Pulsar 4.2 测试环境的完整运行链路：standalone 模式自动创建public/default命名空间（compose.yaml）→ 配方声明冒烟步骤与期望输出（recipe.json）→make db-verify在容器内执行pulsar-client produce并向persistent://public/default/dbx-smoke发布DBX smoke消息、断言输出（database-env.mjs）→ 通过dbx://connection/new深链接入 DBX 客户端完成消息队列功能验证。这套"配方 + 冒烟数据说明 + 自动验证"的组合，让任何开发者都能在数分钟内获得一个可重复、可验证的本机 Pulsar 环境。