Rainbond 内置 etcd 集群升级实战：从 2.3 到 3.0 的零停机滚动升级指南-平芜编程栈

云原生
后端
微服务
DevOps
AI 应用

【免费下载链接】rainbond

无需学习 Kubernetes 的容器平台，在 Kubernetes 上构建、部署、组装和管理应用，无需 K8s 专业知识，全流程图形化管理

项目地址：https://gitcode.com/goodrain/rainbond

etcd 是 Rainbond 平台底层依赖的关键分布式键值存储组件，本指南以仓库内置的 etcd 2.3 升级到 3.0 官方文档（third_party/coreos-etcd/Documentation/upgrades/upgrade_3_0.md）为核心，系统讲解升级前置检查、备份策略、混合版本行为、滚动升级五步操作法以及回退限制，并结合仓库源码剖析版本协商与集群版本判定的底层原理，帮助读者在 Rainbond 环境中安全、可回退地完成 etcd 主版本升级。

一、升级总览：一次零停机滚动升级

在一般情况下，etcd 从 2.3 升级到 3.0 可以做到零停机滚动升级，其核心思想非常简单：

逐个停止 etcd v2.3 进程，并替换为 etcd v3.0 进程；
当集群中所有成员都运行 v3.0 之后，v3.0 新增特性才对整个集群开放。

这种"逐个替换"的方式之所以可行，是因为 etcd 集群在设计上允许成员以混合版本运行一段时间（详见下文"混合版本"一节）。在动手执行升级之前，务必通读本指南的检查清单并逐项准备，尤其是健康检查、数据备份与回退路径，不要跳过。

从仓库结构看，third_party/coreos-etcd 目录完整内置了 etcd 源码与官方 Documentation，本文所讲的升级流程即对应其中Documentation/upgrades/系列升级指南的第一篇；Rainbond 自身的代码则全部基于etcd v3 client（clientv3）与 etcd v3 数据模型进行开发（见 util/etcd/client.go 中NewClient的注释："new etcd client v3 for all rainbond module, attention: do not support v2"），因此在 Rainbond 语境下，完成 2.3 → 3.0 的迁移意味着平台各模块能够真正接入 v3 数据面与 v3 API。

二、升级检查清单（Upgrade checklists）

2.1 版本前提（Upgrade requirements）

升级到 3.0 的前提是：当前正在运行的集群版本必须是 2.3 或更高。

如果集群版本低于 2.3，请先升级到 etcd 2.3 版本，再执行本指南的 3.0 升级流程；
此外，为了确保滚动升级平滑进行，运行中的集群必须是健康的（healthy）。在动手之前，务必使用etcdctl cluster-health命令确认集群健康状态。

2.2 升级前准备（Preparation）

先在预发/测试环境验证：升级 etcd 之前，务必先在预发环境测试所有依赖 etcd 的服务，确认无误后再部署到生产环境；
备份数据目录：升级开始前，按照官方 v2 管理指南中 "Backing up the datastore" 一节的方法备份 etcd 数据目录（仓库中对应文档位于 third_party/coreos-etcd/Documentation/v2/admin_guide.md，目录内亦提供基于 systemd 的备份脚本 third_party/coreos-etcd/contrib/systemd/etcd2-backup-coreos）。如果升级过程中出现问题，可以借助这份备份回退（downgrade）到原有 etcd 版本；
另外，升级过程中还应当为所有 etcd 成员都保存一份数据目录备份，这样即使在集群整体升级完成之后，也保留了将集群回退到 v2.3 状态的可能性（详见下文"回退"一节）。

2.3 混合版本行为（Mixed versions）

升级过程中，etcd 集群支持成员以混合版本运行，并统一按照"最低公共版本（the lowest common version）"的协议工作：

只有所有成员都升级到 v3.0 之后，集群才被认定为完成升级；
在内部，etcd 各成员之间会相互协商以确定整个集群的版本（cluster version），该版本决定了对外上报的版本号以及可用的功能特性（capabilities）。

仓库源码印证了这一机制：third_party/coreos-etcd/etcdserver/cluster_util.go 中的decideClusterVersion函数会遍历所有成员上报的Server版本，取最小版本作为集群版本；同时isCompatibleWithCluster/isCompatibleWithVers（third_party/coreos-etcd/etcdserver/cluster_util.go）会校验各成员的集群版本是否落在[MinClusterVersion, Version]范围内，超出范围的成员会被判定为不兼容。当集群版本最终变化时，third_party/coreos-etcd/etcdserver/membership/cluster.go 会记录 "updated the cluster version from ... to ..." 并将新版本持久化到 store——这正是升级日志中那条关键消息的来源。

2.4 升级限制（Limitations）

升级过程有两个重要的时间预期，请据此安排节奏：

数据量大于 50MB 时，新升级的成员追上集群进度可能需要最多 2 分钟。可以查看最近一次快照的大小来估算总数据量。换句话说，最稳妥的做法是每升级完一个成员后等待 2 分钟再升级下一个；
数据总量达到 100MB 或更大时，这次一次性追赶过程耗时会更长。管理超大规模 etcd 集群的运维人员可以在升级前联系 etcd 团队咨询操作建议。

2.5 回退（Downgrade）

关于回退，需要明确两条规则：

一旦所有成员都升级到 v3.0，集群整体版本即升级为 v3.0，此时无法再回退（从已完成升级的终态回退是不可能的）；
只要还有任何一个成员仍停留在 v2.3，整个集群及其操作就仍处于 "v2.3" 语义之下，此时可以从这种混合集群状态恢复为全部成员运行 v2.3 二进制。

因此，务必在升级前为所有 etcd 成员备份数据目录，为集群在完全升级后仍保留可回退能力。

三、升级操作五步法（Upgrade procedure）

下面以运行在本机的三节点 v2.3 etcd 集群为例，给出完整的升级步骤。三个成员的客户端端口分别为12379、22379、32379（对应 peer 端口12380、22380、32380）。

第 1 步：检查升级前提

确认集群健康且运行在 v2.3.x：

$ etcdctl cluster-health member 6e3bd23ae5f1eae0 is healthy: got healthy result from http://localhost:22379 member 924e2e83e93f2560 is healthy: got healthy result from http://localhost:32379 member 8211f1d0f64f3269 is healthy: got healthy result from http://localhost:12379 cluster is healthy $ curl http://localhost:2379/version {"etcdserver":"2.3.x","etcdcluster":"2.3.8"}

etcdctl cluster-health输出中每个成员都返回 "healthy"、最后一行输出cluster is healthy，说明集群健康；
/version接口返回etcdserver与etcdcluster两个字段，前者是服务版本，后者是集群版本，2.3.x / 2.3.8满足升级前提。

第 2 步：停止现有 etcd 进程

逐个停止 v2.3 etcd 进程。停止某个成员时，其他成员会输出预期中的错误日志——这是因为集群成员连接被（暂时）断开了，属于正常现象：

2016-06-27 15:21:48.624124 E | rafthttp: failed to dial 8211f1d0f64f3269 on stream Message (dial tcp 127.0.0.1:12380: getsockopt: connection refused) 2016-06-27 15:21:48.624175 I | rafthttp: the connection with 8211f1d0f64f3269 became inactive

此时是一个理想的备份时机，建议立即备份 etcd 数据目录，为可能出现的任何问题保留回退路径：

$ etcdctl backup \ --data-dir /var/lib/etcd \ --backup-dir /tmp/etcd_backup

第 3 步：放入 v3.0 二进制并启动新进程

将二进制替换为 etcd v3.0 并启动。新的 v3.0 成员会向集群发布自身信息：

09:58:25.938673 I | etcdserver: published {Name:infra1 ClientURLs:[http://localhost:12379]} to cluster 524400597fb1d5f6

随后验证该成员乃至整个集群在新二进制下恢复健康：

$ etcdctl cluster-health member 6e3bd23ae5f1eae0 is healthy: got healthy result from http://localhost:22379 member 924e2e83e93f2560 is healthy: got healthy result from http://localhost:32379 member 8211f1d0f64f3269 is healthy: got healthy result from http://localhost:12379 cluster is healthy

在整个集群全部升级完成之前，已升级的成员会持续输出如下告警日志，这是混合版本阶段的预期现象，待所有成员都升级到 v3.0 后即会消失：

2016-06-27 15:22:05.679644 W | etcdserver: the local etcd version 2.3.7 is not up-to-date 2016-06-27 15:22:05.679660 W | etcdserver: member 8211f1d0f64f3269 has a higher version 3.0.0

这两条告警的源码出处正是前面提到的decideClusterVersion：当发现本机版本低于某个成员时，会依次打出 "the local etcd version ... is not up-to-date" 与 "member ... has a higher version ..."（见 third_party/coreos-etcd/etcdserver/cluster_util.go）。

第 4 步：对其余成员重复第 2、3 步

对所有剩余成员依次执行"停止 → 备份 → 启动 v3.0"，并且如前文所述，在数据量较大时每升级一个成员后等待约 2 分钟，给新成员留出追赶进度的时间。

第 5 步：完成

当所有成员都升级完成后，集群会报告升级到 3.0 成功：

2016-06-27 15:22:19.873751 N | membership: updated the cluster version from 2.3 to 3.0 2016-06-27 15:22:19.914574 I | api: enabled capabilities for version 3.0.0

第一条日志即由 third_party/coreos-etcd/etcdserver/membership/cluster.go 中的集群版本更新逻辑输出；第二条则来自 third_party/coreos-etcd/etcdserver/api/capability.go 的UpdateCapability——集群版本提升后，对应版本的新增能力（capabilities）才会被启用。

使用 v3 API 再次确认所有端点健康：

$ ETCDCTL_API=3 etcdctl endpoint health 127.0.0.1:12379 is healthy: successfully committed proposal: took = 18.440155ms 127.0.0.1:32379 is healthy: successfully committed proposal: took = 13.651368ms 127.0.0.1:22379 is healthy: successfully committed proposal: took = 18.513301ms

注意这里已切换为ETCDCTL_API=3环境变量与endpoint health子命令，这是 v3 API 对应的健康检查方式。

四、进一步注意事项（Further considerations）

升级到 v3 之后，etcdctl 的环境变量体系发生了变化：

如果ETCDCTL_API=2 etcdctl cluster-health工作正常，但ETCDCTL_API=3 etcdctl endpoint health报错Error: grpc: timed out when dialing，请务必使用 etcdctl 文档中定义的新变量名（v3 采用 gRPC 通信，需要正确的端点与连接参数）；
v3 相关的运维命令与 v2 差异明显，例如 v3 中查询端点状态使用ETCDCTL_API=3 etcdctl --endpoints=127.0.0.1:2379 endpoint status（参见 third_party/coreos-etcd/Documentation/op-guide/versioning.md），而 v3 的快照备份使用etcdctl snapshot save backup.db（参见 third_party/coreos-etcd/Documentation/op-guide/maintenance.md）。

五、已知问题（Known Issues）

官方文档明确记录的 v2.3 → v3.0 升级相关已知问题如下，升级前请对照排查：

Go 版本与 etcd 版本兼容性：使用 Go 高于 v1.7 构建的 etcd v3.1 以下版本无法正常工作（对应官方 Issue 6951）；
gRPC/HTTP2 传输错误：如果 etcd 服务端日志出现transport: http2Client.notifyError got notified that the client transport was broken unexpected EOF.，请确认 etcd 使用的是官方预编译发布版，或者满足(etcd v3.1+ 且 go v1.7+)或(etcd <v3.1 且 go v1.6.x)的构建组合；
升级期间禁止变更成员：向 v2.3 集群添加 v3 节点是不被支持的，可能触发 panic（对应官方 Issue 7429）。混合版本只允许在 v3 迁移过程中存在，请务必在所有成员升级完成后再进行任何成员变更（增删成员等）。

六、Rainbond 环境中的 etcd v3 落地参考

完成 2.3 → 3.0 升级的最终目的，是让上层服务真正使用 v3 数据面。仓库源码显示 Rainbond 各模块对 etcd 的接入已经全面基于 v3：

统一客户端：util/etcd/client.go 定义ClientArgs（含Endpoints、DialTimeout、AutoSyncInterval及CaFile/CertFile/KeyFile三个 TLS 参数），并通过NewClient创建clientv3.Client；默认DialTimeout为 5 秒、AutoSyncInterval为 10 秒，TLS 三项证书同时配置时才会启用加密连接；
分布式锁/选主：util/etcd/etcdlock/master.go 基于clientv3/concurrency的Election与Session实现主节点选举，CreateMasterLock支持自定义选举名称、竞选者标识与 lease TTL；
第三方服务发现：worker/appm/thirdparty/discovery/etcd.go 展示了 Rainbond 作为 etcd v3客户端消费数据的真实场景——通过cli.Get(ctx, key, c.WithPrefix())拉取端点列表，并使用cli.Watch监听键变更，实现第三方服务的动态发现与在线状态同步。

这些实现全部依赖 etcd v3 API 与 v3 存储模型，因此对运行 etcd 的版本有硬性要求——这也是本文档所指导的 2.3 → 3.0 升级在 Rainbond 技术栈中具有实际意义的原因。若 Rainbond 环境内的 etcd 仍运行在 2.x 版本，请按照上述五步法完成升级，使平台各模块能够稳定接入 v3 数据面。

七、总结

etcd 2.3 → 3.0 的升级是一条"逐节点滚动替换"的路径：升级前确认版本与健康状态、为每个成员备份数据目录；升级中容忍混合版本与阶段性的告警日志，利用"最低公共版本"协商机制保证集群协议一致；升级完成后以ETCDCTL_API=3的 v3 命令验证端点健康。牢记两条红线——完全升级后不可回退、升级期间不得变更成员——即可在 Rainbond 环境中以最小风险完成这次关键的存储层主版本迁移。