etcd安装与配置完全指南

etcd 是一个基于 Raft 协议的分布式键值存储系统，主要用于服务发现、配置共享和分布式锁管理。

项目信息

• 项目仓库: https://github.com/etcd-io/etcd
• 当前版本: 3.6.5
• 下载链接: etcd-v3.6.5-linux-amd64.tar.gz

安装步骤

1. 解压安装包

# 下载并解压到指定目录
tar -xzf etcd-v3.6.5-linux-amd64.tar.gz
sudo mv etcd-v3.6.5-linux-amd64 /usr/local/etcd-v3.6.5/# 设置文件权限
sudo chown -R $(whoami):$(whoami) /usr/local/etcd-v3.6.5/
chmod +x /usr/local/etcd-v3.6.5/etcd
chmod +x /usr/local/etcd-v3.6.5/etcdctl

2. 创建 systemd 服务实现持久化运行

创建 /etc/systemd/system/etcd.service 文件：

[Unit]
Description=etcd key-value store
After=network.target[Service]
Type=notify
ExecStart=/usr/local/etcd-v3.6.5/etcd \--data-dir=/data/etcd \--logger=zap \--log-outputs=/data/etcd/etcd.log \--log-level=info \--listen-client-urls http://0.0.0.0:2379 \--advertise-client-urls http://0.0.0.0:2379
Restart=always
RestartSec=10[Install]
WantedBy=multi-user.target

配置项说明

[Unit] 部分

• Description=etcd key-value store: 服务描述信息
• After=network.target: 网络服务启动后再启动此服务

[Service] 部分

• Type=notify: 服务类型为 notify，服务启动完成后会通知 systemd
• ExecStart: 服务启动命令及参数配置：
  • --data-dir=/data/etcd: 指定 etcd 数据存储目录
  • --logger=zap: 使用 zap 作为日志记录器
  • --log-outputs=/data/etcd/etcd.log: 日志输出文件路径
  • --log-level=info: 设置日志级别
  • --listen-client-urls http://0.0.0.0:2379: 监听客户端连接端口
  • --advertise-client-urls http://0.0.0.0:2379: 对外通告的客户端访问地址
• Restart=always: 服务异常退出时总是自动重启
• RestartSec=10: 重启间隔时间（秒）

[Install] 部分

• WantedBy=multi-user.target: 服务归属于 multi-user.target

3. 启动服务

# 重新加载 systemd 配置
systemctl daemon-reload# 设置开机自启
systemctl enable etcd# 启动服务
systemctl start etcd# 检查服务状态
systemctl status etcd

验证安装

检查版本一致性

# 检查 etcdctl 和 etcd 版本是否匹配
etcdctl version
etcd --version

集群健康检查

# 检查集群健康状态
etcdctl endpoint health# 查看集群成员列表
etcdctl member list

输出字段解析

• 成员 ID: 如 8e9e05c52164694d
• 成员状态: started 表示正在运行
• 成员名称: 如 default
• peer URL: http://localhost:2380，集群内部通信地址
• client URL: http://0.0.0.0:2379，客户端连接地址
• learner 状态: false 表示不是 learner 节点

安全配置

默认安全状态

• 无默认密码: etcd 初始安装时没有默认用户名和密码
• 默认无认证: 新安装实例默认无需认证即可访问

启用认证

# 1. 创建 root 用户
etcdctl user add root
# 输入密码并确认# 2. 启用认证
etcdctl auth enable# 3. 授权角色权限
etcdctl user grant-role root root# 4. 查看用户列表
etcdctl user list

⚠️ 重要提醒: 必须先创建 root 用户再启用认证，否则会出现 root user does not exist 错误。

启用认证后，所有 etcdctl 命令都需要提供凭证：

etcdctl --user root:password command

常见问题解答

Q1: 为什么手动启动进程会消失且数据丢失？

/usr/local/etcd-v3.6.5/etcd --listen-client-urls http://0.0.0.0:2379 --advertise-client-urls http://0.0.0.0:2379 >/dev/null 2>&1 &

原因: 未指定 --data-dir 参数，etcd 使用临时目录存储数据，进程停止后数据丢失。

解决方案: 明确指定数据目录

/usr/local/etcd-v3.6.5/etcd \--data-dir=/data/etcd \--listen-client-urls http://0.0.0.0:2379 \--advertise-client-urls http://0.0.0.0:2379

Q2: systemd 配置修改后提示需要重新加载？

警告信息:

Warning: etcd.service changed on disk. Run 'systemctl daemon-reload' to reload units.

解决方法:

systemctl daemon-reload
systemctl restart etcd
systemctl status etcd

Q3: 如何查看更多配置选项？

/usr/local/etcd-v3.6.5/etcd --help