必须二进制安装etcd；v3.5.x～v3.6.x为主流版本，apt源v3.4.15默认禁用v3 API致etcdctl put静默失败；排查需确认ETCDCTL_API=3、显式指定--endpoints、检查key空格、监听地址为*:2379、三节点集群需严格匹配name/url、peer URL用http://:2380、首次启动ETCD_INITIAL_CLUSTER_STATE设为new。
必须用二进制安装，不能用 apt/yum 包管理器装。2026 年主流 etcd 版本是 v3.5.x～v3.6.x，但 Ubuntu 22.04/24.04 的 apt 源仍卡在 v3.4.15，这个旧版本默认不启用 v3 API，etcdctl put 会静默失败——连错误都不报，排查成本极高。
为什么二进制安装后 etcdctl 还是没反应
不是 etcd 没起来，大概率是环境变量或 endpoint 错配。固定排查顺序：
-
echo $ETCDCTL_API必须输出3；没输出就补：写入/etc/profile或~/.bashrc，然后source生效 - 别依赖默认 endpoint，显式传参：
etcdctl --endpoints=http://localhost:2379 put test key123 - get 查不到？检查 key 是否带前导空格或不可见字符（比如粘贴时混入全角空格）
- 遇到
context deadline exceeded，先确认ss -tlnp | grep :2379看监听地址是不是*:2379，不是127.0.0.1:2379
单节点能跑，三节点集群起不来？重点看这三处
3 节点集群（满足 Raft 多数派）最容易卡在初始化阶段，核心是 peer 通信和初始状态对齐：
-
ETCD_INITIAL_CLUSTER必须包含所有节点的完整name=url对，且每个节点的name和ETCD_NAME严格一致（比如 node1、node2、node3），不能用 IP 替代 -
ETCD_LISTEN_PEER_URLS和ETCD_INITIAL_ADVERTISE_PEER_URLS都要写成http://:2380，不能写0.0.0.0或localhost -
ETCD_INITIAL_CLUSTER_STATE在首次启动时必须为new；已有数据目录再启，得改成existing，否则报member already exists - 所有节点时间偏差必须 chronyc tracking 确认，不要只靠
ntpdate一次同步
防火墙、SELinux、目录权限这些“隐形杀手”
etcd 启动不报错但连不上，90% 是被系统层拦截了：
- 云服务器（如阿里云、腾讯云）安全组必须放行
2379（client）和2380（peer）端口，不只是本地ufw或firewalld - SELinux 默认阻止网络绑定，临时关掉验证：
setenforce 0；长期方案是打策略：semanage port -a -t etcd_port_t -p tcp 2379 - 数据目录（如
/var/lib/etcd）必须属主为etcd用户，且权限不能是 777；推荐chown -R etcd:etcd /var/lib/etcd+chmod 700 /var/lib/etcd - 日志目录（如
/var/log/etcd）也要给etcd用户写权限，否则 systemd 启动时 silent fail
真正麻烦的从来不是配置项本身，而是 peer URL 写错一个字符、时间不同步几十毫秒、或者 ETCD_INITIAL_CLUSTER_TOKEN 在三个节点上不完全一致——这些细节不校验，集群就永远卡在 waiting for quorum。
