DBX 中的 Consul 2.0.2 本地测试环境：无 ACL 开发 Agent、KV 冒烟数据与一键校验流程-迪斯科星球

DBX 中的 Consul 2.0.2 本地测试环境：无 ACL 开发 Agent、KV 冒烟数据与一键校验流程

【免费下载链接】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

DBX 仓库在deploy/database/下为每种数据库维护可复现的 Docker Compose 测试环境，Consul 2.0.2 是其中一套典型配方。本篇以 deploy/database/consul/2.0.2/init/README.md 为核心，完整讲清这套环境的无 ACL 开发 Agent 配置、dbx/smoke冒烟 KV 数据、三组端口映射，以及make db-verify DB=consul@2.0.2背后的执行链路，读完即可在本地一键拉起、验证并清理该 Consul 环境。

init/README.md 说明了什么

init/README.md 原文只有两句，但每一句都对应一个可验证的事实：

Consul 开发 Agent 以无 ACL 鉴权的方式启动——容器内运行的是consul agent -dev单节点模式，没有启用acl子系统的 bootstrap 令牌，因此所有 HTTP/gRPC/DNS 接口对容器网络内开放；
make db-verify DB=consul@2.0.2会写入并读回dbx/smoke这个 KV 值——这正是 deploy/database/README.md 中提到的“初始化/冒烟数据在验证期间创建”的约定：Consul 不支持镜像级的初始化目录约定，init/目录里的文件仅用于说明该环境验证时创建的冒烟数据（与 Redis 等 KV 类服务的处理方式一致）。

这两句话分别指向配方目录下的两个文件：无 ACL 的启动参数定义在 compose.yaml，冒烟数据的读写命令定义在 recipe.json。下面逐一展开。

配方目录结构：recipe.json、compose.yaml 与 init/

按照 deploy/database/README.md 的配方布局约定，每个版本目录包含三件套：

consul/2.0.2/ ├── recipe.json # 连接字段与冒烟命令 ├── compose.yaml # Docker Compose 环境 └── init/ # 环境初始化/冒烟数据说明 └── README.md

Consul 2.0.2 配方完全符合这一结构。init/目录必须包含至少一个文件，这一点由make db-check的静态校验强制执行（见 scripts/database-env.mjs 中init directory must contain a file的断言）——所以 init/README.md 的存在既是对冒烟数据的说明，也是配方合法性的一部分。

compose.yaml：无 ACL 的单节点开发 Agent

deploy/database/consul/2.0.2/compose.yaml 的关键配置如下：

services: database: image: docker.cnb.cool/znb/images/consul:2.0.2 container_name: dbx-consul-2.0.2 restart: unless-stopped command: - agent - -dev - -client=0.0.0.0 - -ui - -data-dir=/consul/data ports: - "${DB_BIND_ADDRESS:-127.0.0.1}:${DB_PORT:-10900}:8500" - "${DB_BIND_ADDRESS:-127.0.0.1}:${CONSUL_GRPC_PORT:-10901}:8502" - "${DB_BIND_ADDRESS:-127.0.0.1}:${CONSUL_DNS_PORT:-10902}:8600/tcp" - "${DB_BIND_ADDRESS:-127.0.0.1}:${CONSUL_DNS_PORT:-10902}:8600/udp" volumes: - data:/consul/data healthcheck: test: ["CMD", "consul", "members", "-http-addr=http://127.0.0.1:8500"] interval: 5s timeout: 5s retries: 30 start_period: 10s volumes: data:

各部分的设计意图：

启动参数：agent -dev即 init/README.md 所说的开发模式（无 ACL、内存/单节点可用）；-client=0.0.0.0让 HTTP API 与 UI 在容器内所有网卡可达，配合宿主机端口映射对外提供；-ui启用 Consul 自带的 Web UI；-data-dir=/consul/data指向命名卷data，使 KV 数据在容器重建后保留。
端口映射：Consul 三个服务端口全部映射到宿主机 Consul 专属的109xx端口段：
容器端口协议宿主机默认端口环境变量用途
8500 TCP 10900 DB_PORT HTTP API / UI
8502 TCP 10901 CONSUL_GRPC_PORT gRPC API
8600 TCP + UDP 10902 CONSUL_DNS_PORT DNS 接口
四条映射都以${DB_BIND_ADDRESS:-127.0.0.1}开头，默认只绑定回环地址。从源码结构看，scripts/database-env.mjs 中 Consul 被分配了10900–10999的默认端口区间，validateHostPorts会校验配方声明的端口必须落在该区间且不重复，这保证多套配方可以并行运行而互不冲突。
健康检查：以consul members -http-addr=http://127.0.0.1:8500作为就绪判据，5 秒间隔、最多 30 次重试。make db-verify启动容器时使用的--wait参数会阻塞到该健康检查通过，这解释了为什么冒烟步骤可以在up返回之后立即执行而不需要额外 sleep。
镜像与容器名：镜像版本固定（pinned）为consul:2.0.2，容器名遵循dbx-<product>-<version>规范；这两项同样是make db-check的强制检查项（scripts/database-env.mjs）。

容器端口	协议	宿主机默认端口	环境变量	用途
8500	TCP	10900	`DB_PORT`	HTTP API / UI
8502	TCP	10901	`CONSUL_GRPC_PORT`	gRPC API
8600	TCP + UDP	10902	`CONSUL_DNS_PORT`	DNS 接口

recipe.json：连接字段、shell 命令与冒烟步骤

deploy/database/consul/2.0.2/recipe.json 是make db/make db-verify的实际数据源：

{ "database": "consul", "name": "Consul", "version": "2.0.2", "displayVersion": "2.0.2", "image": "docker.cnb.cool/znb/images/consul:2.0.2", "platforms": ["linux/amd64", "linux/arm64"], "service": "database", "defaultPort": 8500, "connection": { "host": "127.0.0.1", "port": 10900, "authentication": "none", "database": "dbx", "grpcPort": 10901, "dnsPort": 10902 }, "hostPorts": { "DB_PORT": 10900, "CONSUL_GRPC_PORT": 10901, "CONSUL_DNS_PORT": 10902 }, "shell": ["consul", "members", "-http-addr=http://127.0.0.1:8500"], "smoke": { "steps": [ { "name": "write a Consul KV smoke value", "command": ["consul", "kv", "put", "-http-addr=http://127.0.0.1:8500", "dbx/smoke", "DBX smoke"], "expect": "Success! Data written" }, { "name": "read the Consul KV smoke value", "command": ["consul", "kv", "get", "-http-addr=http://127.0.0.1:8500", "dbx/smoke"], "expect": "DBX smoke" } ] } }

对应 init/README.md 的两句话：

authentication: "none"与-dev无 ACL 启动方式互相印证。源码校验规则明确：认证为none的配方不允许声明connection.password（scripts/database-env.mjs），而带密码的配方必须使用统一默认密码123456——Consul 属于前者。
smoke.steps的两个步骤就是“写入并读回dbx/smoke”的具体实现：先consul kv put dbx/smoke "DBX smoke"并期望输出Success! Data written，再consul kv get dbx/smoke并期望输出DBX smoke。任何一步的输出不含expect文本，verify流程即抛出Smoke check did not contain expected text错误并带上实际输出（scripts/database-env.mjs）。

两个细节值得注意：

冒烟命令里的-http-addr=http://127.0.0.1:8500指向的是容器内部的 8500 端口，因为命令通过docker compose exec在容器内执行；宿主机侧的连接则使用 10900/10901/10902。
shell字段提供交互式诊断入口：pnpm db:env -- shell consul 2.0.2（或经 Makefile 封装）会exec进容器执行consul members -http-addr=http://127.0.0.1:8500，等价于容器健康检查命令。

`make db-verify DB=consul@2.0.2`的执行链路

Makefile 中的db-verify目标只做一件事：

db-verify: @$(PNPM) db:env -- verify

真正的逻辑在 scripts/database-env.mjs 的verify分支（L574-L583），完整链路为：

发现配方：discoverRecipes()扫描deploy/database/<product>/<version>/recipe.json，并按database/displayVersion排序（L45-L60）；
解析选择器：parseDatabaseSelection把consul@2.0.2解析为 product=consul、version=2.0.2；若同一产品存在多个版本而未指定版本号，会明确报错要求DB=<product>@<version>格式（L147-L159，并有 scripts/database-env.test.mjs 的测试覆盖）；
等待就绪：docker compose --project-name dbx-<repo>-consul-2.0.2 --file deploy/database/consul/2.0.2/compose.yaml up -d --wait，阻塞直至consul members健康检查通过；Consul 配方没有bootstrap字段，ensureBootstrap直接跳过；
执行冒烟：对smoke.steps逐项compose exec -T database <command>，捕获输出并断言包含expect文本，成功后打印OK <step name>。

因此一条完整的冒烟验证命令等价于：

docker compose --project-name dbx-<repo>-consul-2.0.2 \ --file deploy/database/consul/2.0.2/compose.yaml exec -T database \ consul kv put -http-addr=http://127.0.0.1:8500 dbx/smoke "DBX smoke" # 期望输出包含: Success! Data written docker compose --project-name dbx-<repo>-consul-2.0.2 \ --file deploy/database/consul/2.0.2/compose.yaml exec -T database \ consul kv get -http-addr=http://127.0.0.1:8500 dbx/smoke # 期望输出包含: DBX smoke

冒烟命令在展开时支持${DB_PORT}与${DB_PASSWORD}两个占位符替换（expandSmokeCommand），本配方固定使用 8500 且无密码，故不受影响。

与 DBX 客户端的连接对接

配方启动后，DBX 客户端如何连接这个 Consul？两个来源给出了答案：

深度链接：make db DB=consul@2.0.2启动成功后会打印预填的连接链接。从 dbxConnectionDeepLink 的实现看，Consul 属于DBX_DEEP_LINK_TYPES中支持的consul类型（L30-L43），生成的链接形如dbx://connection/new?type=consul&name=Consul 2.0.2 (local)&host=127.0.0.1&port=10900&database=dbx；由于认证方式为none，链接中不包含密码参数。README 同时提醒：含密码的链接不要存入共享的终端历史或工单——虽然 Consul 这条恰好无密码。
能力面：plugins/connection-types/consul.yaml 声明了dbType: consul、supportLevel: connect、specializedSurface: true，且queryExecution、metadataBrowse、tableDataEdit等能力全部为false——即 Consul 在 DBX 中是专门的 KV/服务发现连接面，不提供 SQL 执行或元数据浏览，这与冒烟验证只覆盖 KV 读写是一致的。

校验与运维操作速查

Consul 配方作为整套环境的一部分，受统一规则约束，修改后可用以下命令自检（规则实现见 validateRecipe）：

镜像必须固定版本，禁止latest；
container_name必须等于dbx-consul-2.0.2；
必须定义 healthcheck 与命名卷；
所有端口映射必须默认回环绑定（allPortMappingsDefaultToLoopback逐行检查 compose 端口行，L342-L369）；
hostPorts声明与 compose 端口默认值必须一一对应，且落在 Consul 的10900–10999区间；
connection.host必须为127.0.0.1；
init/目录非空。

常用操作（均在仓库根目录执行）：

make db-list # 列出全部配方及端口映射 make db DB=consul@2.0.2 # 启动并打印连接字段/深度链接 make db-verify DB=consul@2.0.2 # 启动 + KV 冒烟验证 make db-down DB=consul@2.0.2 # 停止环境 make db-reset DB=consul@2.0.2 CONFIRM=1 # 停止并删除命名卷（数据清空） make db-check # 校验所有配方与 Compose 文件 pnpm db:env -- logs consul 2.0.2 # 查看日志（FOLLOW=1 可跟踪） pnpm db:env -- shell consul 2.0.2 # 在容器内执行 consul members

覆盖端口与绑定地址的变量：DB_PORT、CONSUL_GRPC_PORT、CONSUL_DNS_PORT、DB_BIND_ADDRESS。由于-dev模式没有 ACL，若确需将DB_BIND_ADDRESS设为0.0.0.0做跨机访问，务必配合防火墙限制来源——这与 deploy/database/README.md 对整套环境的远程访问告诫一致。

小结

init/README.md 用两行文字锚定了 Consul 2.0.2 测试环境的全部关键事实：无 ACL 的开发 Agent 与dbx/smoke冒烟 KV。围绕它，compose.yaml 给出agent -dev启动参数、8500/8502/8600 到 10900/10901/10902 的三组回环端口映射与健康检查，recipe.json 声明连接字段与两步 KV 冒烟命令，而 scripts/database-env.mjs 把make db-verify DB=consul@2.0.2落实为“等待健康检查 → 容器内 exec 冒烟命令 → 断言输出”的确定性流程。理解这套机制后，可以照 deploy/database/RECIPE_TEMPLATE.md 的模板为其它产品扩展同样结构的可复现测试环境。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析