4、环境搭建：单节点etcd安装（二进制/docker）、启动参数详解、健康检查（etcdctl endpoint health）

在进入压测与性能观察之前，首先需要搭建一个可用的 etcd 运行环境。本章将演示单节点 etcd 的两种安装方式（二进制与 Docker），详细解析核心启动参数，并介绍使用 etcdctl 进行健康检查的标准方法。单节点环境是理解 etcd 基础行为、参数影响以及后续搭建集群的起点。

4.1 安装方式对比：二进制 vs Docker

根据实验环境与运维习惯，可以选择以下两种方式之一安装 etcd。下表从关键维度进行了对比：

维度	二进制安装	Docker 安装
依赖	仅需操作系统基础库	需预先安装 Docker 引擎
版本管理	手动下载替换二进制文件	通过镜像标签切换版本
启动速度	直接执行，毫秒级启动	需拉取镜像，首次较慢
资源隔离	共享宿主机进程空间	容器级隔离，便于清理
适用场景	生产环境、性能压测	快速实验、CI/CD 环境

4.1.1 二进制安装步骤

1. 下载：从 GitHub Releases 获取对应操作系统与架构的压缩包。例如 Linux amd64 版本：

wget https://github.com/etcd-io/etcd/releases/download/v3.5.15/etcd-v3.5.15-linux-amd64.tar.gz

2. 解压：

tar -xzf etcd-v3.5.15-linux-amd64.tar.gz
cd etcd-v3.5.15-linux-amd64

3. 安装：将二进制文件复制到系统 PATH 目录：

sudo cp etcd etcdctl /usr/local/bin/

4. 验证：

etcd --version
etcdctl version

4.1.2 Docker 安装步骤

1. 拉取镜像：

docker pull quay.io/coreos/etcd:v3.5.15

2. 启动容器（单节点快速模式）：

docker run -d --name etcd-single \
  -p 2379:2379 -p 2380:2380 \
  quay.io/coreos/etcd:v3.5.15 \
  etcd --advertise-client-urls http://0.0.0.0:2379 \
       --listen-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 default=http://0.0.0.0:2380 \
       --initial-cluster- etcd-cluster-1 \
       --initial-cluster-state new

3. 验证容器运行状态：

docker ps | grep etcd-single

4.2 核心启动参数详解

etcd 的启动参数决定了节点的身份、通信方式、存储行为与安全策略。以下按功能分组解析单节点模式下最关键的参数。

分组	参数名	默认值	说明
成员与通信	--name	default	节点名称，集群内唯一标识
	--data-dir	${name}.etcd	数据存储目录，包含 WAL 和快照
客户端监听	--listen-client-urls	http://localhost:2379	客户端请求监听地址，压测时需改为 http://0.0.0.0:2379
	--advertise-client-urls	http://localhost:2379	对外公布的客户端访问地址，用于客户端发现
集群通信	--listen-peer-urls	http://localhost:2380	集群节点间 Raft 消息监听地址
	--initial-advertise-peer-urls	http://localhost:2380	对外公布的集群通信地址
集群初始化	--initial-cluster	default=http://localhost:2380	初始集群成员列表，格式 name1=url1,name2=url2
	--initial-cluster-state	new	new 新建集群；existing 加入已有集群
	--initial-cluster-	随机生成	集群唯一令牌，防止跨集群节点误加入
性能与存储	--snapshot-count	100000	触发快照的累计事务数，影响启动恢复速度
	--max-wals	5	保留的最大 WAL 文件数，控制磁盘空间

单节点启动最小化命令示例：

etcd --name etcd-single \
     --data-dir /tmp/etcd-data \
     --listen-client-urls http://0.0.0.0:2379 \
     --advertise-client-urls http://127.0.0.1:2379 \
     --listen-peer-urls http://0.0.0.0:2380 \
     --initial-advertise-peer-urls http://127.0.0.1:2380 \
     --initial-cluster etcd-single=http://127.0.0.1:2380 \
     --initial-cluster- etcd-cluster-1 \
     --initial-cluster-state new

4.3 健康检查：etcdctl endpoint health

启动 etcd 后，第一步是确认节点是否正常提供服务。etcdctl 提供了 endpoint health 子命令用于快速检查。

4.3.1 基本用法

etcdctl --endpoints=http://127.0.0.1:2379 endpoint health

正常输出示例：

127.0.0.1:2379 is healthy: successfully committed proposal: took = 1.234ms

异常输出示例（节点未启动或网络不通）：

127.0.0.1:2379 is unhealthy: failed to connect: dial tcp 127.0.0.1:2379: connect: connection refused

4.3.2 健康检查的底层原理

endpoint health 命令会向目标节点发起一个 写入提案（proposal），并等待该提案被集群提交。如果提案在超时时间内成功提交，则判定为健康。这意味着该检查不仅验证网络连通性，还验证了节点的 Raft 状态机是否正常工作。

4.3.3 批量检查与格式化输出

当有多个端点时，可以一次性检查：

etcdctl --endpoints=http://127.0.0.1:2379,http://127.0.0.2:2379 endpoint health -w table

使用 -w table 参数可以输出表格格式，便于阅读：

+-------------------+--------+-------------+-------+
|     ENDPOINT      | HEALTH |    TOOK     | ERROR |
+-------------------+--------+-------------+-------+
| 127.0.0.1:2379   |   true |  1.234567ms |       |
| 127.0.0.2:2379   |   true |  2.345678ms |       |
+-------------------+--------+-------------+-------+

4.4 单节点架构与健康检查流程

下图展示了单节点 etcd 的内部组件关系以及 endpoint health 命令的请求路径：

4.5 常见问题与排查

现象	可能原因	解决措施
connection refused	etcd 进程未启动或端口被占用	检查进程 ps aux | grep etcd；更换端口或终止冲突进程
healthy 但 took > 100ms	磁盘 I/O 瓶颈或 CPU 资源争抢	使用 iostat 检查磁盘；压测时避免同机运行高 IO 任务
unhealthy: proposal dropped	Raft 循环阻塞或数据目录损坏	查看 etcd 日志；尝试 --force-new-cluster 恢复（仅单节点）
Docker 容器内健康检查失败	端口映射错误或容器网络模式限制	确认 -p 2379:2379；使用 --network host 模式