DBX 项目 etcd 3.5 初始化指南:用 etcdctl v3 API 自动创建 root 用户并启用认证

DBX 项目 etcd 3.5 初始化指南:用 etcdctl v3 API 自动创建 root 用户并启用认证 数据库开发者工具桌面应用CLIMCP 服务AI 应用【免费下载链接】dbx15MB轻量级跨平台数据库客户端、数据库管理工具。支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、DuckDB、ClickHouse、SQL Server 等。15MB, lightweight, cross-platform database client. Supports MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, ClickHouse, SQL Server and more.项目地址https://gitcode.com/t8y2/dbx点击查看免费下载导读本文围绕 DBX 开源仓库中 etcd 3.5 初始化说明 展开讲解 DBX 的数据库测试环境体系如何在 etcd 3.5 服务健康后自动完成root用户创建、root角色授予与 etcd 认证开启的全过程。读完本文你将掌握 etcd 配方recipe的初始化与验证机制、recipe.json中每一步命令的参数含义以及如何用make命令一键启动、校验、清理一套带认证的 etcd 3.5 环境。一、初始化说明文档讲了什么deploy/database/etcd/3.5/init/README.md 全文虽短但精确概括了 etcd 3.5 配方的核心初始化契约服务健康后配方运行器recipe runner创建root用户密码123456可通过DB_PASSWORD覆盖为其授予root角色并通过 etcdctl v3 API 启用 etcd 认证命名卷named volume持久化已初始化的认证状态。这短短几句话背后对应着一整套可复现的 Docker Compose 环境。该目录归属于 DBX 的deploy/database测试环境体系其整体约定在 deploy/database/README.md 中有详细说明每个版本化配方使用固定镜像pinned image、命名卷、仅回环地址的端口绑定、健康检查以及验证过程中创建的初始化数据或冒烟smoke数据。二、配方文件结构recipe.json、compose.yaml 与 init/2.1 目录布局deploy/database/etcd/3.5/ ├── recipe.json # 连接字段、初始化步骤与冒烟命令 ├── compose.yaml # Docker Compose 环境定义 └── init/ # 随环境初始化的说明文档这一布局遵循 deploy/database/RECIPE_TEMPLATE.md 中规定的通用模板。同一仓库还提供 etcd 3.7 版本deploy/database/etcd/3.7/两版共用同一套初始化逻辑仅镜像与端口号不同。2.2 核心配置recipe.jsondeploy/database/etcd/3.5/recipe.json 是初始化流程的“剧本”关键字段如下字段值说明imagequay.io/coreos/etcd:v3.5.21固定镜像保证环境可复现defaultPort2379etcd 原生客户端端口connectionhost127.0.0.1, port10710, usernameroot, password123456, databasedbx, peerPort10711初始化完成后 DBX 使用的连接信息hostPortsDB_PORT10710, ETCD_PEER_PORT10711主机端口映射DB_PORT用于客户端端口ETCD_PEER_PORT用于 peer 端口shelletcdctl --endpointshttp://127.0.0.1:2379 --user root:${DB_PASSWORD}交互式 shell 入口已带认证参数2.3 容器环境compose.yamldeploy/database/etcd/3.5/compose.yaml 定义了单节点 etcd 3.5 环境services: database: image: quay.io/coreos/etcd:v3.5.21 container_name: dbx-etcd-3.5 restart: always command: - /usr/local/bin/etcd - --names1 - --data-dir/etcd-data - --listen-client-urlshttp://0.0.0.0:2379 - --advertise-client-urlshttp://0.0.0.0:2379 - --listen-peer-urlshttp://0.0.0.0:2380 - --initial-advertise-peer-urlshttp://0.0.0.0:2380 - --initial-clusters1http://0.0.0.0:2380 - --initial-cluster-tokentkn - --initial-cluster-statenew - --log-levelinfo - --loggerzap - --log-outputsstderr ports: - ${DB_BIND_ADDRESS:-127.0.0.1}:${DB_PORT:-10710}:2379 - ${DB_BIND_ADDRESS:-127.0.0.1}:${ETCD_PEER_PORT:-10711}:2380 volumes: - data:/etcd-data healthcheck: test: [CMD, /usr/local/bin/etcdctl, --endpointshttp://127.0.0.1:2379, endpoint, health] interval: 5s timeout: 5s retries: 30 start_period: 10s volumes: data:值得注意的细节固定镜像与容器名镜像固定在v3.5.21容器名统一为dbx-etcd-3.5遵循dbx-product-version命名规范由 scripts/database-env.mjs 中的expectedContainerName校验。端口绑定默认仅回环${DB_BIND_ADDRESS:-127.0.0.1}保证默认只监听本机如需远程访问须显式设置DB_BIND_ADDRESS0.0.0.0并配合强密码与防火墙。健康检查用 etcdctl 的endpoint health探测 2379 端口start_period: 10s给足启动时间。命名卷持久化data:/etcd-data将数据目录挂载到命名卷。这正是初始化说明文档中“命名卷保持已初始化的认证状态”的实现基础——即使容器重建认证配置也不会丢失而make db-reset会删除该命名卷以彻底重置。三、初始化流程逐行解析认证如何在健康检查之后开启3.1 时机为何在“服务健康之后”scripts/database-env.mjs 中的ensureBootstrap函数约 L444-L457规定了执行顺序先等待 Docker Compose 健康检查通过再同步执行一次性初始化步骤。源码注释点明了原因——保证--wait不会在凭据就绪之前返回// Keep one-shot setup synchronous after Compose health checks so --wait cannot return before credentials exist. const checkCommand expandSmokeCommand(recipe.bootstrap.check.command, recipe); const check tryRunCompose(recipe, [exec, -T, recipe.service, ...checkCommand]); if (check.ok check.output.includes(recipe.bootstrap.check.expect)) return;3.2 幂等校验先查认证状态recipe.json中的bootstrap.check会先执行{ check: { command: [/usr/local/bin/etcdctl, --endpointshttp://127.0.0.1:2379, --user, root:${DB_PASSWORD}, auth, status], expect: Authentication Status: true } }若auth status已返回Authentication Status: true说明认证此前已初始化完成例如命名卷中已保存过认证状态则直接跳过后续步骤。这一设计使初始化具备幂等性容器重启、配方重复执行都不会重复建用户或重复开启认证。3.3 四步初始化etcdctl v3 API 的完整调用链当认证尚未开启时配方运行器依次执行bootstrap.steps中的四个步骤对应初始化说明文档中“创建 root、授予 root 角色、启用认证”的完整过程步骤命令期望输出1. 创建 root 用户etcdctl --endpointshttp://127.0.0.1:2379 user add root:${DB_PASSWORD}User root created2. 创建 root 角色etcdctl --endpointshttp://127.0.0.1:2379 role add rootRole root created3. 授予角色etcdctl --endpointshttp://127.0.0.1:2379 user grant-role root rootRole root is granted to user root4. 启用认证etcdctl --endpointshttp://127.0.0.1:2379 auth enableAuthentication Enabled每一步执行后都会将命令输出与expect字段比对任何一步输出不匹配都会抛出错误Bootstrap check did not contain expected text: ...从而保证初始化失败能被及时发现。要点解读密码注入${DB_PASSWORD}为占位符默认123456可由环境变量DB_PASSWORD覆盖——这也是 README 中“(orDB_PASSWORD)”的含义。该变量在 Makefile 中通过export DB_PASSWORD暴露给配方运行器。v3 API 认证模型etcd 的认证体系由 user用户、role角色、权限授予三层构成。先建用户再建同名角色然后user grant-role把角色授予用户最后auth enable全局开启认证。启用认证后所有后续访问包括 shell 与冒烟测试都必须携带--user root:${DB_PASSWORD}。3.4 初始化后的连接信息初始化完成后scripts/database-env.mjs 的printConnection会打印标准化的连接字段root / 123456或DB_PASSWORD覆盖后的密码、主机端口10710、数据库名dbx并生成dbx://connection/new深链接可直接在 DBX Desktop 中打开新建连接对话框。注意该链接可能包含密码不应保存在共享终端历史、日志或工单中。四、冒烟验证认证开启后的读写自检recipe.json中的smoke字段定义了认证开启后的功能验证{ smoke: { steps: [ { name: write authenticated smoke key, command: [/usr/local/bin/etcdctl, --endpointshttp://127.0.0.1:2379, --user, root:${DB_PASSWORD}, put, dbx:smoke, DBX smoke], expect: OK }, { name: read authenticated smoke key, command: [/usr/local/bin/etcdctl, --endpointshttp://127.0.0.1:2379, --user, root:${DB_PASSWORD}, get, dbx:smoke], expect: DBX smoke } ] } }它携带认证凭据执行一次put dbx:smoke写入和一次get dbx:smoke读取验证两件事一是 etcd 认证确已生效无凭据无法通过二是带认证的读写链路完全可用。源码层面由 scripts/database-env.mjs 中的 smoke 执行逻辑约 L577-L580逐条比对expect输出不匹配即抛错。五、一键操作从启动到重置的 Make 命令初始化说明文档描述的自动化流程最终通过仓库根目录的 Make 目标对外暴露定义见 Makefile 的db-*系列目标其内部均转发到pnpm db:envmake db-list # 列出全部可用数据库版本及端口映射 make db DBetcd3.5 # 启动 etcd 3.5 环境并执行初始化 make db-verify DBetcd3.5 # 启动并运行冒烟检查验证认证读写 make db-down DBetcd3.5 # 停止容器 make db-reset DBetcd3.5 CONFIRM1 # 删除容器并清空命名卷彻底重置认证状态 make db-check # 校验所有配方的结构与 Compose 文件合法性make db-verify对应 README 中“验证过程中创建冒烟数据”的环节每次运行都会重新 put/getdbx:smoke键。make db-reset会删除命名卷data因此必须显式带CONFIRM1才会执行——这与初始化说明文档中“命名卷保持已初始化的认证状态”互为补充要回到未认证的初始状态只能删除卷。底层诊断可使用更细粒度的pnpm db:env -- info|status|logs|shell etcd 3.5其中shell会以--user root:${DB_PASSWORD}打开带认证的 etcdctl 交互入口。六、与 etcd 3.7 配方的对照仓库同时维护 deploy/database/etcd/3.7/ 版本两者初始化逻辑完全一致差异集中在两点差异点3.53.7镜像quay.io/coreos/etcd:v3.5.21docker.cnb.cool/znb/images/etcd:v3.7.0客户端主机端口1071010700peer 主机端口1071110701两版的bootstrap与smoke步骤完全相同这印证了初始化说明文档描述的是 etcd 家族通用的认证初始化模式而非某个版本的专属行为。七、小结一条完整的“健康检查 → 初始化 → 冒烟 → 持久化”链路回到 etcd 3.5 初始化说明其描述的三句话背后是完整的工程化链路服务健康后compose.yaml 的健康检查用etcdctl endpoint health探测就绪配方运行器等待健康通过后才继续创建凭据并启用认证bootstrap.check先做幂等校验随后四步 etcdctl 命令依次完成建用户、建角色、授角色、开认证命名卷持久化data:/etcd-data卷保存认证状态保证重启不丢、重复执行不重复初始化而make db-reset通过删卷提供彻底重置的出口。对开发者而言这套机制的价值在于任何一次make db DBetcd3.5都能得到一份密码已知、认证已开启、读写已验证的可复现 etcd 环境配合 recipe.json 中的连接信息与深链接即可立刻接入 DBX 客户端进行验证或开发调试。赞分享数据库开发者工具桌面应用CLIMCP 服务AI 应用【免费下载链接】dbx15MB轻量级跨平台数据库客户端、数据库管理工具。支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、DuckDB、ClickHouse、SQL Server 等。15MB, lightweight, cross-platform database client. Supports MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, ClickHouse, SQL Server and more.项目地址https://gitcode.com/t8y2/dbx点击查看免费下载相关推荐DBX 仓库中 etcd 3.5 数据库测试环境初始化指南root 用户创建、认证启用与状态持久化DBX 仓库中 etcd 3.5 数据库测试环境初始化指南root 用户创建、认证启用与状态持久化 deploy/database/etcd/3.5/init数据库客户端数据库桌面应用CLI后端MCP 服务AI 应用DBX 中 etcd 3.7 数据库测试环境的初始化指南从健康检查到认证启用的完整流程DBX 中 etcd 3.7 数据库测试环境的初始化指南从健康检查到认证启用的完整流程 etcd 默认不开启任何身份认证任何人只要网络可达即可读写键值这显数据库开发者工具桌面应用CLIMCP 服务AI 应用One API 如何用 INITIAL_ROOT_TOKEN 在首次启动时自动创建 root 用户令牌One API 如何用 INITIAL_ROOT_TOKEN 在首次启动时自动创建 root 用户令牌 One API 部署完成后默认只提供一个网页账号用户后端API网关LLM 网关大模型创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考