3. 单节点 etcd 部署：环境准备与实例启动

单节点 etcd 是压测沙盘的基础单元。本节将完成从操作系统配置、Go 语言环境准备、etcd 二进制下载安装，到单节点实例启动与健康验证的全流程。所有操作均面向后续压测场景，强调可复现性与最小化干扰。

3.1 环境准备：操作系统与 Go 版本

etcd 官方对 Linux 平台支持最佳，推荐使用 Ubuntu 22.04 LTS 或 CentOS 7.9+。以下为已验证的基准环境配置：

环境项 推荐值 最低要求 说明
操作系统 Ubuntu 22.04 LTS Linux kernel 4.15+ 内核需支持 epoll 与 TCP 快速重传
Go 版本 1.21.x 1.19+ 编译 etcd 源码或运行 Go 客户端压测工具
CPU 4 核 2 核 压测场景建议 4 核以上
内存 8 GB 4 GB etcd 默认使用 2 GB 内存缓存
磁盘 SSD, 100 GB HDD, 20 GB 强烈建议 SSD，避免 IO 成为瓶颈
Go 版本检查： 执行 go version 确认版本。若未安装，可通过以下命令快速安装 Go 1.21： 
wget https://go.dev/dl/go1.21.13.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.13.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

3.2 下载与安装 etcd

etcd 提供预编译二进制包，推荐直接从 GitHub Releases 获取。以下为 v3.5.15 版本的安装步骤（当前稳定版）：

  1. 下载压缩包 
    ETCD_VER=v3.5.15
wget https://github.com/etcd-io/etcd/releases/download/${ETCD_VER}/etcd-${ETCD_VER}-linux-amd64.tar.gz
  2. 解压并移动二进制文件 
    tar -xzf etcd-${ETCD_VER}-linux-amd64.tar.gz
sudo mv etcd-${ETCD_VER}-linux-amd64/etcd* /usr/local/bin/
  3. 验证安装 
    etcd --version
etcdctl version
    输出应显示版本号 3.5.15 及 API 版本 3.5。
注意： 不要使用系统包管理器（如 apt、yum）安装 etcd，其版本通常滞后且缺少压测所需的最新特性。始终从官方 Release 下载。

3.3 启动单节点实例

单节点模式无需配置集群参数，只需指定数据目录与监听地址。以下为最小化启动命令：

etcd --name etcd-single \
  --data-dir /var/lib/etcd \
  --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-single- \
  --initial-cluster-state new

参数说明：

参数 值 作用
--name etcd-single 节点名称，用于集群内标识
--data-dir /var/lib/etcd 数据持久化目录
--listen-client-urls http://0.0.0.0:2379 客户端监听地址，压测工具连接此端口
--advertise-client-urls http://127.0.0.1:2379 对外公布的客户端地址
--initial-cluster-state new 新建集群，非加入已有集群

启动后，etcd 会在前台打印日志。建议使用 nohup 或 systemd 将其转为后台服务：

nohup etcd --name etcd-single \
  --data-dir /var/lib/etcd \
  --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-single- \
  --initial-cluster-state new \
  &> /var/log/etcd.log &

3.4 验证服务状态

启动后，通过以下三种方式验证 etcd 是否正常运行：

  1. 检查进程与端口 
    ss -tlnp | grep -E '2379|2380'
ps aux | grep etcd
    应看到 etcd 进程监听 2379（客户端）和 2380（节点间通信）端口。
  2. 使用 etcdctl 检查集群健康 
    etcdctl --endpoints=http://127.0.0.1:2379 endpoint health
    返回 http://127.0.0.1:2379 is healthy: successfully committed proposal: took = 2.345ms 表示健康。
  3. 写入与读取键值对 
    etcdctl put /test-key "hello-etcd"
etcdctl get /test-key
    应输出 /test-key 及值 hello-etcd。
压测前置检查： 在开始压测前，务必执行 etcdctl endpoint status --write-out=table 确认节点版本、DB 大小与 leader 信息。单节点模式下，leader 即为自身。

3.5 单节点部署架构示意

下图展示了单节点 etcd 实例的内部组件与外部交互关系，为后续压测中的客户端连接模型提供参考：

单节点 etcd 部署架构 单节点 etcd 部署架构 压测客户端 benchmark / etcdctl gRPC 连接池 PUT/GET/WATCH etcd 实例 Raft 状态机 KV 存储引擎 WAL / 快照 gRPC Server Raft 层 数据目录 /var/lib/etcd member/ /wal/ /snap/ 持久化 说明： • 客户端通过 gRPC 协议与 etcd 交互，默认端口 2379。 • 单节点模式下，Raft 层仅有一个成员，所有提案立即提交。 • 数据目录包含 WAL 日志与快照文件，压测前建议清理旧数据。

3.6 常见问题与排查

现象 可能原因 解决方式
端口 2379 被占用 已有 etcd 或其他服务运行 sudo lsof -i:2379 查找进程并停止，或更换端口
数据目录权限不足 etcd 以非 root 用户运行 sudo chown -R $(whoami) /var/lib/etcd
etcdctl 连接超时 防火墙或监听地址未绑定 0.0.0.0 检查 --listen-client-urls 是否包含 0.0.0.0
启动日志报 "rafthttp: request cluster ID mismatch" 数据目录残留旧集群数据 清空 /var/lib/etcd/member 后重新启动
压测前重置环境： 每次压测前建议执行 etcdctl del "" --prefix 清空所有键值，或直接删除 --data-dir 目录并重启，确保测试基线一致。
← 上一章 📖 返回目录 下一章 →