etcd分布式存储配置使用教程：从单机到集群完整步骤

什么是 etcd？为什么需要它？

etcd 是一个开源的分布式键值存储系统，常用于服务发现、配置共享和分布式锁。
你可以把它理解成一个高可靠的“配置中心”，多台服务器通过 etcd 协同工作，保证数据一致性。
很多容器编排工具（比如 Kubernetes）都依赖 etcd 来保存集群状态。
本文带大家从零开始完成 etcd 分布式存储配置使用，先跑通单节点，再搭建一个三节点集群。

准备工作：环境与依赖

开始操作前，你需要准备以下条件：

• Linux 服务器（CentOS 7/8 或 Ubuntu 20.04+）至少两台（搭建集群推荐三台）。
• root 权限或具有 sudo 权限的普通用户。
• 网络互通：各节点之间能互相访问 2379（客户端端口）和 2380（节点间通信端口）。
• 下载 etcd 二进制包，或使用包管理器安装。

示例（CentOS 使用 yum）：

# 如果系统无 epel 源，先安装
sudo yum install -y epel-release
sudo yum install -y etcd

示例（Ubuntu 使用 apt）：

sudo apt update
sudo apt install -y etcd

如果包管理器版本太旧，建议去 GitHub Releases 下载最新版二进制。

单节点快速配置与启动

安装完成后，我们先跑一个单节点实例，验证基础环境。

1. 修改配置文件

etcd 默认配置文件位于 /etc/etcd/etcd.conf。
编辑它：

sudo vi /etc/etcd/etcd.conf

核心参数如下（请根据实际 IP 替换）：

[member]
ETCD_NAME="node1"
ETCD_DATA_DIR="/var/lib/etcd/default.etcd"
ETCD_LISTEN_PEER_URLS="http://0.0.0.0:2380"
ETCD_LISTEN_CLIENT_URLS="http://0.0.0.0:2379,http://0.0.0.0:4001"

[cluster]
ETCD_INITIAL_ADVERTISE_PEER_URLS="http://192.168.1.10:2380"
ETCD_ADVERTISE_CLIENT_URLS="http://192.168.1.10:2379"
ETCD_INITIAL_CLUSTER="node1=http://192.168.1.10:2380"
ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster-1"
ETCD_INITIAL_CLUSTER_STATE="new"

说明：0.0.0.0:2379 表示监听所有网卡的客户端请求，192.168.1.10 改为本机真实 IP。

2. 启动服务并设置开机自启

sudo systemctl enable etcd --now
sudo systemctl status etcd

看到 active (running) 就代表成功。

3. 简单验证

electdctl put /test hello
electdctl get /test

如果输出 hello，单节点运行正常。

搭建三节点 etcd 集群

真正的生产环境需要多节点冗余。
以下假设你有三台服务器（IP 分别为 192.168.1.10、192.168.1.11、192.168.1.12）。

1. 每台节点配置集群参数

以 node1（192.168.1.10）为例，配置如下（其他节点按规则修改 IP 和名称）：

[member]
ETCD_NAME="node1"
ETCD_DATA_DIR="/var/lib/etcd/default.etcd"
ETCD_LISTEN_PEER_URLS="http://0.0.0.0:2380"
ETCD_LISTEN_CLIENT_URLS="http://0.0.0.0:2379,http://0.0.0.0:4001"

[cluster]
ETCD_INITIAL_ADVERTISE_PEER_URLS="http://192.168.1.10:2380"
ETCD_ADVERTISE_CLIENT_URLS="http://192.168.1.10:2379"
ETCD_INITIAL_CLUSTER="node1=http://192.168.1.10:2380,node2=http://192.168.1.11:2380,node3=http://192.168.1.12:2380"
ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster-1"
ETCD_INITIAL_CLUSTER_STATE="new"

关键点：ETCD_INITIAL_CLUSTER 必须包含所有三个节点的地址，且每个节点的 ETCD_NAME 必须唯一。

2. 依次启动所有节点

sudo systemctl start etcd
sudo systemctl enable etcd

注意：首次启动时，集群会自动选举 leader。
启动顺序无严格要求，但建议先启动所有节点再检查状态。

3. 验证集群成员

在任意节点执行：

electdctl member list

输出应显示三个节点，类似：

8212f9b5d9b2e37a, started, node1, http://192.168.1.10:2380, http://192.168.1.10:2379, false
c7a8e9f0d1b3c4d5, started, node2, http://192.168.1.11:2380, http://192.168.1.11:2379, false
...

还可以检查集群健康状态：

electdctl cluster-health

如果显示 cluster is healthy，大功告成。

避坑指南：常见问题与解决方法

坑1：端口被防火墙阻挡
确保 2379、2380 端口已放行：
`bash
sudo firewall-cmd --add-port=2379/tcp --add-port=2380/tcp --permanent
sudo firewall-cmd --reload
`

坑2：集群启动后新增节点报错
如果中途想加入新节点，必须将 ETCD_INITIAL_CLUSTER_STATE 改为 existing 并使用 etcdctl member add 添加，否则集群会拒绝。

坑3：数据目录权限问题
etcd 默认以 etcd 用户运行，确保 /var/lib/etcd 目录权限正确：sudo chown -R etcd:etcd /var/lib/etcd

坑4：时间不同步
集群节点之间时间必须同步（误差建议 < 1 秒）。使用 NTP 服务：
`bash
sudo yum install -y ntpdate
sudo ntpdate time.nist.gov
`

效果验证与日常操作

搭建完成后，可以模拟写入与读取，验证数据同步：

# 在 node1 上写入数据
electdctl put /config/db_host "192.168.1.100"

# 在 node2 上读取
electdctl get /config/db_host

如果得到相同值，说明集群正常工作。
你也可以尝试停止一台机器（systemctl stop etcd），然后继续读写，只要多数节点存活，服务就不会中断。

总结

通过本文，你完成了从单节点到三节点 etcd 分布式存储配置使用 的全流程。
记住几点：配置文件要一致、防火墙放行、时间同步、首次集群用 new 状态。
如果遇到异常，优先检查端口连通性和日志（journalctl -u etcd -n 50）。
etcd 是分布式系统的基石，掌握它的配置能让你在运维工作中更加得心应手。