升级

相关源文件

• CHANGELOG/CHANGELOG-2.3.md
• CHANGELOG/CHANGELOG-3.0.md
• CHANGELOG/CHANGELOG-3.1.md
• CHANGELOG/CHANGELOG-3.2.md
• CHANGELOG/CHANGELOG-3.3.md
• CHANGELOG/CHANGELOG-3.4.md
• CHANGELOG/CHANGELOG-3.5.md
• CHANGELOG/CHANGELOG-3.6.md
• CHANGELOG/CHANGELOG-3.7.md
• CHANGELOG/CHANGELOG-4.0.md
• CHANGELOG/README.md
• scripts/build.sh
• scripts/build_tools.sh

本文档提供了跨不同版本安全升级 etcd 实例和集群的指南。它解释了版本兼容性注意事项、推荐的升级路径、升级前后的程序以及您需要了解的版本特定详细信息。有关特定的部署配置，请参阅 部署与配置。

版本兼容性与支持

etcd 遵循语义版本控制 (主版本.次版本.补丁版本)，并提供以下兼容性保证：

• 补丁版本 (3.5.x → 3.5.y)：完全兼容，无破坏性更改
• 次版本 (3.x → 3.y)：对客户端向后兼容，可能需要仔细的升级步骤
• 主版本 (x → y)：可能包含破坏性更改，需要仔细迁移

最低推荐版本

生产环境最低推荐的 etcd 版本为：

版本	最低推荐
3.4.x	v3.4.22+
3.5.x	v3.5.6+

这些建议反映了已获得重要错误修复和稳定性改进的版本。

警告：为避免生产环境中因高负载导致数据损坏问题，请避免运行 etcd v3.5.0、v3.5.1 和 v3.5.2。

来源：CHANGELOG/README.md4-13

升级路径

支持的升级路径

• 建议在连续的次版本之间进行升级（3.4 → 3.5 → 3.6）
• 不建议跳过多个次版本，这可能会导致意外问题
• 降级路径更加受限，在较新版本中需要特殊步骤

来源：CHANGELOG/CHANGELOG-3.5.md424-439 CHANGELOG/CHANGELOG-3.6.md74-79

升级前检查清单

在升级 etcd 之前，请完成以下步骤：

1. 备份您的数据

   • 使用 etcdctl snapshot save 命令创建 etcd 数据快照
   • 将快照存储在 etcd 数据目录之外的安全位置

2. 查阅变更日志

   • 查看目标版本的变更日志，了解破坏性更改
   • 特别注意已弃用的功能或命令

3. 检查集群健康状况

   • 确保所有集群成员都健康：etcdctl endpoint health --cluster
   • 验证没有处于活动状态的告警：etcdctl alarm list

4. 计划停机时间

   • 对于单节点设置，升级需要停机
   • 对于集群，请计划滚动升级过程中潜在的性能影响

来源：CHANGELOG/CHANGELOG-3.5.md401-402 CHANGELOG/CHANGELOG-3.4.md652-654

升级策略

单节点升级

来源：CHANGELOG/CHANGELOG-3.5.md401-402 CHANGELOG/CHANGELOG-3.4.md385-388

集群滚动升级

对于 etcd 集群，请使用滚动升级策略以最大程度地减少停机时间。

对于成员数量多于三名的集群，请一次升级一个成员，始终先升级非 leader 成员，最后升级 leader。

来源：CHANGELOG/CHANGELOG-3.5.md590-597 CHANGELOG/CHANGELOG-3.4.md542-546

版本特定的升级注意事项

升级到 3.5.x

• Go 包已迁移以遵循 Go 模块约定
  • go.etcd.io/etcd → go.etcd.io/etcd/{api,pkg,raft,client,etcdctl,server,raft,tests}/v3
• clientv3/snapshot 包已移动到 clientv3/etcdctl
• go.etcd.io/client 包已迁移到 go.etcd.io/client/v2
• clientv3 API MemberList 的行为已更改
  • 现在它以可线性化保证提供服务
  • 如果服务器与仲裁断开连接，则会失败
• gRPC 网关仅支持 /v3 端点 (已弃用 /v3beta)
• etcd 3.5 是最后一个支持 V2 API 的版本
• --pre-vote 标志现在默认启用

来源：CHANGELOG/CHANGELOG-3.5.md438-493

升级到 3.6.x

破坏性变更

• etcd 将无法在由较新版本创建的数据目录上启动
  • 使用 etcdutl migrate 命令来降级/升级 etcd 数据目录
• etcd 不再在 peer 监听端点上提供客户端请求
• 依赖 etcd v3.6 包的应用程序必须使用 Go 1.18+ 构建
• 移除了多项功能
  • etcdctl defrag --data-dir
  • etcdctl snapshot status
  • etcdctl snapshot restore

Go 版本要求更新至 Go 1.23+。

来源：CHANGELOG/CHANGELOG-3.6.md74-169

降级注意事项

降级 etcd 比升级更复杂，应作为最后的手段。从 v3.6.0 开始，etcd 提供了用于降级的数据迁移工具。

从 3.6.x 降级到 3.5.x

1. 停止 etcd 服务器
2. 使用 etcdutl migrate 命令为旧版本准备数据目录
3. 安装旧版本的 etcd
4. 使用旧版本的 etcd 服务器启动

etcdutl migrate --data-dir=/var/lib/etcd --target-version="3.5"

对于 3.6.0 之前的版本，降级可能不受官方支持，您可能需要从备份进行恢复。

来源：CHANGELOG/CHANGELOG-3.6.md78-79 CHANGELOG/CHANGELOG-3.6.md106-107

升级后验证

升级后，验证升级是否成功

1. 检查版本

   etcdctl version
   

2. 验证服务器健康状况

   etcdctl endpoint health
   

3. 对于集群，请检查所有成员

   etcdctl endpoint health --cluster
   etcdctl endpoint status --cluster
   

4. 验证没有处于活动状态的告警

   etcdctl alarm list
   

5. 执行简单的读写测试

   etcdctl put test-key test-value
   etcdctl get test-key
   

来源：CHANGELOG/CHANGELOG-3.5.md598-605 CHANGELOG/CHANGELOG-3.4.md651-665

处理 v3.5.0-3.5.2 数据损坏问题

版本 3.5.0、3.5.1 和 3.5.2 在高负载下存在已知的版本数据损坏问题。如果 etcd 进程被终止，已提交的事务可能不会反映在所有成员上。

如果您正在运行这些版本

1. 立即升级到 v3.5.4 或更高版本
2. 监控不一致（日志中的数据损坏警告）
3. 如果检测到损坏，请遵循文档中的数据损坏恢复程序

来源：CHANGELOG/README.md7-13

监控升级

使用以下指标监控升级过程

指标	描述
etcd_server_version	当前服务器版本
etcd_cluster_version	当前集群版本
etcd_server_is_leader	指示该成员是否是 leader
etcd_server_health_failures	健康检查失败次数

这些指标可以帮助识别升级期间或升级后出现的问题。

来源：CHANGELOG/CHANGELOG-3.5.md512-522 CHANGELOG/CHANGELOG-3.4.md669-673

常见升级问题及解决方案

问题	解决方案
成员升级后无法重新加入集群	检查日志中的错误，确保版本兼容性，验证网络连接
成员之间版本不匹配	完成所有成员的滚动升级过程
升级后性能下降	检查是否有新的推荐配置选项，根据新版本调整参数
升级后认证失败	检查认证机制的变化，查看令牌 TTL 设置

来源：CHANGELOG/CHANGELOG-3.5.md590-604 CHANGELOG/CHANGELOG-3.4.md334-337