--- title: 将 etcd 从 v3.5 升级到 v3.6 weight: 6600 description: 升级 etcd 3.5 至 3.6 的流程、检查清单与注意事项 categories: [任务] upstream_link: "https://github.com/etcd-io/website/blob/824597935df6e95992ef61c07e3222f4f796ca6c/content/en/docs/v3.7/upgrades/upgrade_3_6.md" aliases: [/etcd/upgrades/upgrade_3_6/] --- 在一般情况下，从 etcd v3.5 升级到 v3.6 可以实现零停机时间的滚动升级： - 逐一停止 etcd v3.5 进程，并替换为 etcd v3.6 进程 - 所有 v3.6 进程运行后，集群即可使用 v3.6 中的新特性 在 [开始升级](#upgrade-procedure) 之前，请通读本指南其余部分以做好准备。 ### 升级检查列表 {#upgrade-checklists} #### 更新 3.5 {#update-35} > [!IMPORTANT] > 升级至 3.6 之前，请确保 [所有 3.5 版本的成员均已更新至 3.5.32 或更高版本](https://etcd.io/blog/2026/july-patch-release/)。补丁版本 3.5.24 至 3.5.26 修复了多个潜在的升级障碍；[3.5.32](https://etcd.io/blog/2026/july-patch-release/) 增加了 `--v2-deprecation=write-only-skip-check` 功能，并将 `etcdutl check v2store` 扩展至可检查 WAL 记录以及 v2 快照。 #### V2 存储系统 {#v2-store} > [!NOTE] > 如果未配置 `--enable-v2` 标志或将其设置为 false，则无需采取进一步操作。 如果配置了 `--enable-v2`，请运行命令 `etcdutl check v2store`，以验证 v2store 中是否存在非成员关系（自定义）数据。若不存在自定义数据，可安全移除该标志。否则，请参阅 [v2 迁移指南](https://etcd.io/docs/v3.4/op-guide/v2-migration/) 获取更多详情。 ### 新增标志 {#flags-added} ```diff +etcd --discovery-token '' +etcd --discovery-endpoints '' +etcd --discovery-dial-timeout '2s' +etcd --discovery-request-timeout '5s' +etcd --discovery-keepalive-time '2s' +etcd --discovery-keepalive-timeout '6s' +etcd --discovery-insecure-transport 'true' +etcd --discovery-insecure-skip-tls-verify 'false' +etcd --discovery-cert '' +etcd --discovery-key '' +etcd --discovery-cacert '' +etcd --discovery-user '' +etcd --discovery-password '' +etcd --feature-gates +etcd --log-format ``` ### 已移除标志 {#flags-removed} ```diff -etcd --enable-v2 -etcd --experimental-enable-v2v3 -etcd --proxy -etcd --proxy-failure-wait -etcd --proxy-refresh-interval -etcd --proxy-dial-timeout -etcd --proxy-write-timeout -etcd --proxy-read-timeout ``` ### 标志已弃用 {#flags-deprecated} **`etcd --experimental-bootstrap-defrag-threshold-megabytes` 标志已被弃用.** ```diff -etcd --experimental-bootstrap-defrag-threshold-megabytes +etcd --bootstrap-defrag-threshold-megabytes ``` **`etcd --experimental-compaction-batch-limit` 标志已被弃用.** ```diff -etcd --experimental-compaction-batch-limit +etcd --compaction-batch-limit ``` **`etcd --experimental-compact-hash-check-time` 标志已被弃用.** ```diff -etcd --experimental-compact-hash-check-time +etcd --compact-hash-check-time ``` **`etcd --experimental-compaction-sleep-interval` 标志已被弃用.** ```diff -etcd --experimental-compaction-sleep-interval +etcd --compaction-sleep-interval ``` **`etcd --experimental-corrupt-check-time` 标志已被弃用.** ```diff -etcd --experimental-corrupt-check-time +etcd --corrupt-check-time ``` **`etcd --experimental-enable-distributed-tracing` 标志已弃用.** ```diff -etcd --experimental-enable-distributed-tracing +etcd --enable-distributed-tracing ``` **`etcd --experimental-distributed-tracing-address` 标志已被弃用.** ```diff -etcd --experimental-distributed-tracing-address +etcd --distributed-tracing-address ``` **`etcd --experimental-distributed-tracing-instance-id` 标志已弃用.** ```diff -etcd --experimental-distributed-tracing-instance-id +etcd --distributed-tracing-instance-id ``` **`etcd --experimental-distributed-tracing-sampling-rate` 标志已被弃用.** ```diff -etcd --experimental-distributed-tracing-sampling-rate +etcd --distributed-tracing-sampling-rate ``` **`etcd --experimental-distributed-tracing-service-name` 标志已弃用.** ```diff -etcd --experimental-distributed-tracing-service-name +etcd --distributed-tracing-service-name ``` **`etcd --experimental-downgrade-check-time` 标志已被弃用.** ```diff -etcd --experimental-downgrade-check-time +etcd --downgrade-check-time ``` **`etcd --experimental-max-learners` 标志已被弃用.** ```diff -etcd --experimental-max-learners +etcd --max-learners ``` **`etcd --experimental-memory-mlock` 标志已被弃用.** ```diff -etcd --experimental-memory-mlock +etcd --memory-mlock ``` **`etcd --experimental-peer-skip-client-san-verification` 标志已被弃用.** ```diff -etcd --experimental-peer-skip-client-san-verification +etcd --peer-skip-client-san-verification ``` **`etcd --experimental-snapshot-catchup-entries` 标志已被弃用.** ```diff -etcd --experimental-snapshot-catchup-entries +etcd --snapshot-catchup-entries ``` **`etcd --experimental-warning-apply-duration` 标志已弃用.** ```diff -etcd --experimental-warning-apply-duration +etcd --warning-apply-duration ``` **`etcd --experimental-warning-unary-request-duration` 标志已被弃用.** ```diff -etcd --experimental-warning-unary-request-duration +etcd --warning-unary-request-duration ``` **`etcd --experimental-watch-progress-notify-interval` 标志已被弃用.** ```diff -etcd --experimental-watch-progress-notify-interval +etcd --watch-progress-notify-interval ``` ### v3.5 功能门控的等效标志 {#equivalent-flags-of-v35-feature-gates} **对应的功能门控标志 `etcd --experimental-compact-hash-check-enabled=true`** ```diff -etcd --experimental-compact-hash-check-enabled=true +etcd --feature-gates=CompactHashCheck=true ``` **对应的功能门控标志 `etcd --experimental-initial-corrupt-check=true`** ```diff -etcd --experimental-initial-corrupt-check=true +etcd --feature-gates=InitialCorruptCheck=true ``` **对应的功能门控标志 `etcd --experimental-enable-lease-checkpoint=true`** ```diff -etcd --experimental-enable-lease-checkpoint=true +etcd --feature-gates=LeaseCheckpoint=true ``` **对应的功能门控标志 `etcd --experimental-enable-lease-checkpoint-persist=true`** ```diff -etcd --experimental-enable-lease-checkpoint-persist=true +etcd --feature-gates=LeaseCheckpointPersist=true ``` **对应的功能门控标志 `etcd --experimental-stop-grpc-service-on-defrag=true`** ```diff -etcd --experimental-stop-grpc-service-on-defrag=true +etcd --feature-gates=StopGRPCServiceOnDefrag=true ``` **对应的功能门控标志 `etcd --experimental-txn-mode-write-with-shared-buffer=false`** ```diff -etcd --experimental-txn-mode-write-with-shared-buffer=false +etcd --feature-gates=TxnModeWriteWithSharedBuffer=false ``` ### 带有新默认值的标志 {#flags-with-new-defaults} **原始默认标志 `etcd --snapshot-count=100000`** ```diff -etcd --snapshot-count=100000 +etcd --snapshot-count=10000 ``` **原始默认标志 `etcd --v2-deprecation='not-yet'`** ```diff -etcd --v2-deprecation='not-yet' +etcd --v2-deprecation='write-only' ``` **原始默认标志 `etcd --discovery-fallback='proxy'`** ```diff -etcd --discovery-fallback='proxy' +etcd --discovery-fallback='exit' ``` ### Prometheus 指标差异 {#difference-in-prometheus-metrics} ```diff # metrics added in v3.6 +etcd_network_known_peers +etcd_server_feature_enabled ``` ### 服务器升级检查清单 {#server-upgrade-checklists} #### 升级要求 {#upgrade-requirements} 要将现有的 etcd 部署升级至 v3.6，运行中的集群版本必须为 v3.5 或更高。若版本低于 v3.5，请先 [升级至 v3.5](/zh/docs/etcd/upgrades/upgrade_3_4/)，再升级至 v3.6。 此外，为确保滚动升级顺利进行，运行中的集群必须处于健康状态。在继续操作前，请使用 `etcdctl endpoint health` 命令检查集群健康状况。 #### 准备 {#preparation} 在升级 etcd 之前，请务必在预发环境中测试依赖 etcd 的服务，再将升级部署到生产环境。 开始前，请先 [下载快照备份](/zh/docs/etcd/op-guide/maintenance/#snapshot-backup)。如果升级出现问题，可以使用此备份 [回滚](#rollback)到现有 etcd 版本。请注意，`snapshot` 命令只备份 v3 数据。 #### 混合版本 {#mixed-versions} 升级期间，etcd 集群支持不同版本的 etcd 成员共存，并以最低公共版本的协议运行。只有当集群中所有成员均升级至 v3.6 版本后，才认为集群已完成升级。内部机制上，etcd 成员之间会相互协商以确定集群的整体版本，该版本控制报告的版本及支持的功能。 #### 回滚 {#rollback} 升级 etcd 集群前，请创建并 [下载快照备份](/zh/docs/etcd/op-guide/maintenance/#snapshot-backup)。该快照可用于在需要时将集群恢复至升级前的状态。若用户在升级过程中遇到问题，应首先识别并解决根本原因。若集群仍处于混合版本状态——即至少有一个成员仍运行在 v3.5 版本——则可选择将二进制文件或镜像替换为旧版 v3.5，或直接使用快照恢复集群。在此混合状态下，集群仍以 v3.5 集群模式运行，支持回滚而无需执行正式的降级流程。 然而，一旦所有成员均升级至 v3.6 版本，集群即被视为已完全升级，此时使用二进制文件回滚将不再可行。在此情况下，唯一的恢复方式是恢复升级前创建的快照。若用户希望在完成完整升级后返回原始版本，应遵循官方降级指南，以确保一致性并避免数据损坏。 ### 升级流程 {#upgrade-procedure} 本示例演示如何升级在本地计算机上运行的 3 个成员的 v3.5 etcd 集群。 #### 步骤 1: 检查升级要求 {#step-1-check-upgrade-requirements} 集群是否健康且运行 v3.5.x 版本？ ```bash etcdctl --endpoints=localhost:2379,localhost:22379,localhost:32379 endpoint health < `{"level":"info","ts":"2025-03-01T04:40:36.828+0530","caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.5"}` > > `{"level":"info","ts":"2025-03-01T04:40:36.889+0530","caller":"membership/cluster.go:539","msg":"updated cluster version","cluster-id":"59a05384c9b79ee","local-member-id":"bf9071f4639c75cc","from":"3.0","to":"3.5"}` > > `{"level":"info","ts":"2025-03-01T04:40:36.828+0530","caller":"api/capability.go:76","msg":"enabled capabilities for version","cluster-version":"3.5"}` > > `{"level":"info","ts":"2025-03-01T04:40:36.894+0530","caller":"etcdserver/server.go:1686","msg":"published local member to cluster through raft","local-member-id":"bf9071f4639c75cc","local-member-attributes":"{Name:node1 ClientURLs:[http://127.0.0.1:2379]}","cluster-id":"59a05384c9b79ee","publish-timeout":"7s"}` 验证每个成员以及整个集群在使用新的 v3.6 etcd 二进制文件后是否恢复正常健康状态： ```bash etcdctl endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379 < `{"level":"info","ts":"2025-03-01T04:58:32.375+0530","caller":"etcdserver/server.go:2149","msg":"updating cluster version using v3 API","from":"3.5","to":"3.6"}` > `{"level":"info","ts":"2025-03-01T04:58:32.377+0530","caller":"etcdserver/server.go:2164","msg":"cluster version is updated","cluster-version":"3.6"}` 成员 2： > `{"level":"info","ts":"2025-03-01T04:58:32.377+0530","caller":"membership/cluster.go:539","msg":"updated cluster version","cluster-id":"59a05384c9b79ee","local-member-id":"91bc3c398fb3c146","from":"3.5","to":"3.6"}` 成员 3： > `{"level":"info","ts":"2025-03-01T04:58:32.377+0530","caller":"membership/cluster.go:539","msg":"updated cluster version","cluster-id":"59a05384c9b79ee","local-member-id":"fd422379fda50e48","from":"3.5","to":"3.6"}` ```bash endpoint health --endpoints=localhost:2379,localhost:22379,localhost:32379 <