
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/dbxDBX 仓库在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 DBconsul2.0.2背后的执行链路读完即可在本地一键拉起、验证并清理该 Consul 环境。init/README.md 说明了什么init/README.md 原文只有两句但每一句都对应一个可验证的事实Consul 开发 Agent 以无 ACL 鉴权的方式启动——容器内运行的是consul agent -dev单节点模式没有启用acl子系统的 bootstrap 令牌因此所有 HTTP/gRPC/DNS 接口对容器网络内开放make db-verify DBconsul2.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.mdConsul 2.0.2 配方完全符合这一结构。init/目录必须包含至少一个文件这一点由make db-check的静态校验强制执行见 scripts/database-env.mjs 中init directory must contain a file的断言——所以 init/README.md 的存在既是对冒烟数据的说明也是配方合法性的一部分。compose.yaml无 ACL 的单节点开发 Agentdeploy/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 - -client0.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-addrhttp://127.0.0.1:8500] interval: 5s timeout: 5s retries: 30 start_period: 10s volumes: data:各部分的设计意图启动参数agent -dev即 init/README.md 所说的开发模式无 ACL、内存/单节点可用-client0.0.0.0让 HTTP API 与 UI 在容器内所有网卡可达配合宿主机端口映射对外提供-ui启用 Consul 自带的 Web UI-data-dir/consul/data指向命名卷data使 KV 数据在容器重建后保留。端口映射Consul 三个服务端口全部映射到宿主机 Consul 专属的109xx端口段容器端口协议宿主机默认端口环境变量用途8500TCP10900DB_PORTHTTP API / UI8502TCP10901CONSUL_GRPC_PORTgRPC API8600TCP UDP10902CONSUL_DNS_PORTDNS 接口四条映射都以${DB_BIND_ADDRESS:-127.0.0.1}开头默认只绑定回环地址。从源码结构看scripts/database-env.mjs 中 Consul 被分配了10900–10999的默认端口区间validateHostPorts会校验配方声明的端口必须落在该区间且不重复这保证多套配方可以并行运行而互不冲突。健康检查以consul members -http-addrhttp://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。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-addrhttp://127.0.0.1:8500], smoke: { steps: [ { name: write a Consul KV smoke value, command: [consul, kv, put, -http-addrhttp://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-addrhttp://127.0.0.1:8500, dbx/smoke], expect: DBX smoke } ] } }对应 init/README.md 的两句话authentication: none与-dev无 ACL 启动方式互相印证。源码校验规则明确认证为none的配方不允许声明connection.passwordscripts/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-addrhttp://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-addrhttp://127.0.0.1:8500等价于容器健康检查命令。make db-verify DBconsul2.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把consul2.0.2解析为 productconsul、version2.0.2若同一产品存在多个版本而未指定版本号会明确报错要求DBproductversion格式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-addrhttp://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-addrhttp://127.0.0.1:8500 dbx/smoke # 期望输出包含: DBX smoke冒烟命令在展开时支持${DB_PORT}与${DB_PASSWORD}两个占位符替换expandSmokeCommand本配方固定使用 8500 且无密码故不受影响。与 DBX 客户端的连接对接配方启动后DBX 客户端如何连接这个 Consul两个来源给出了答案深度链接make db DBconsul2.0.2启动成功后会打印预填的连接链接。从 dbxConnectionDeepLink 的实现看Consul 属于DBX_DEEP_LINK_TYPES中支持的consul类型L30-L43生成的链接形如dbx://connection/new?typeconsulnameConsul 2.0.2 (local)host127.0.0.1port10900databasedbx由于认证方式为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镜像必须固定版本禁止latestcontainer_name必须等于dbx-consul-2.0.2必须定义 healthcheck 与命名卷所有端口映射必须默认回环绑定allPortMappingsDefaultToLoopback逐行检查 compose 端口行L342-L369hostPorts声明与 compose 端口默认值必须一一对应且落在 Consul 的10900–10999区间connection.host必须为127.0.0.1init/目录非空。常用操作均在仓库根目录执行make db-list # 列出全部配方及端口映射 make db DBconsul2.0.2 # 启动并打印连接字段/深度链接 make db-verify DBconsul2.0.2 # 启动 KV 冒烟验证 make db-down DBconsul2.0.2 # 停止环境 make db-reset DBconsul2.0.2 CONFIRM1 # 停止并删除命名卷数据清空 make db-check # 校验所有配方与 Compose 文件 pnpm db:env -- logs consul 2.0.2 # 查看日志FOLLOW1 可跟踪 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 DBconsul2.0.2落实为“等待健康检查 → 容器内 exec 冒烟命令 → 断言输出”的确定性流程。理解这套机制后可以照 deploy/database/RECIPE_TEMPLATE.md 的模板为其它产品扩展同样结构的可复现测试环境。【免费下载链接】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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考