企业官网建设流程全解析

• 数据库
• 开发者工具
• 桌面应用
• CLI
• MCP 服务
• AI 应用

导读

本文围绕 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.json

deploy/database/etcd/3.5/recipe.json 是初始化流程的“剧本”，关键字段如下：

2.3 容器环境：compose.yaml

deploy/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 - --name=s1 - --data-dir=/etcd-data - --listen-client-urls=http://0.0.0.0:2379 - --advertise-client-urls=http://0.0.0.0:2379 - --listen-peer-urls=http://0.0.0.0:2380 - --initial-advertise-peer-urls=http://0.0.0.0:2380 - --initial-cluster=s1=http://0.0.0.0:2380 - --initial-cluster-token=tkn - --initial-cluster-state=new - --log-level=info - --logger=zap - --log-outputs=stderr 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", "--endpoints=http://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_ADDRESS=0.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", "--endpoints=http://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 角色、启用认证”的完整过程）：

每一步执行后都会将命令输出与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", "--endpoints=http://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", "--endpoints=http://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:env）：

make db-list # 列出全部可用数据库版本及端口映射 make db DB=etcd@3.5 # 启动 etcd 3.5 环境并执行初始化 make db-verify DB=etcd@3.5 # 启动并运行冒烟检查（验证认证读写） make db-down DB=etcd@3.5 # 停止容器 make db-reset DB=etcd@3.5 CONFIRM=1 # 删除容器并清空命名卷（彻底重置认证状态） make db-check # 校验所有配方的结构与 Compose 文件合法性

• make db-verify对应 README 中“验证过程中创建冒烟数据”的环节，每次运行都会重新 put/getdbx:smoke键。
• make db-reset会删除命名卷（data），因此必须显式带CONFIRM=1才会执行——这与初始化说明文档中“命名卷保持已初始化的认证状态”互为补充：要回到未认证的初始状态，只能删除卷。
• 底层诊断可使用更细粒度的pnpm db:env -- info|status|logs|shell etcd 3.5，其中shell会以--user root:${DB_PASSWORD}打开带认证的 etcdctl 交互入口。

六、与 etcd 3.7 配方的对照

仓库同时维护 deploy/database/etcd/3.7/ 版本，两者初始化逻辑完全一致，差异集中在两点：

两版的bootstrap与smoke步骤完全相同，这印证了初始化说明文档描述的是 etcd 家族通用的认证初始化模式，而非某个版本的专属行为。

七、小结：一条完整的“健康检查 → 初始化 → 冒烟 → 持久化”链路

回到 etcd 3.5 初始化说明，其描述的三句话背后是完整的工程化链路：

1. 服务健康后：compose.yaml 的健康检查用etcdctl endpoint health探测就绪，配方运行器等待健康通过后才继续；
2. 创建凭据并启用认证：bootstrap.check先做幂等校验，随后四步 etcdctl 命令依次完成建用户、建角色、授角色、开认证；
3. 命名卷持久化：data:/etcd-data卷保存认证状态，保证重启不丢、重复执行不重复初始化，而make db-reset通过删卷提供彻底重置的出口。

对开发者而言，这套机制的价值在于：任何一次make db DB=etcd@3.5都能得到一份密码已知、认证已开启、读写已验证的可复现 etcd 环境，配合 recipe.json 中的连接信息与深链接，即可立刻接入 DBX 客户端进行验证或开发调试。

• 数据库
• 开发者工具
• 桌面应用
• CLI
• MCP 服务
• AI 应用