etcd 3.7：RangeStream、v3store 启动与升级时真正要检查的事

预计阅读时间：10 分钟

etcd v3.7.0 是一个不小的 minor release。它解决了大范围查询一次性缓冲带来的延迟和内存问题，引入 RangeStream；继续压低 Kubernetes 控制平面的 CPU 开销；同时把启动链路从遗留 v2store 中抽离出来，并完成 protobuf 依赖的大规模更新。对只运行官方镜像的团队来说，这更像一次需要认真读升级说明的常规升级；对依赖 etcd Go module、旧 v2 API 或实验性参数的团队来说，它可能会直接碰到编译和配置变化。

RangeStream：大结果集不再必须一次性吞下

在 v3.6 及更早版本里，Range 请求如果返回大量 key-value，服务端会先把完整结果集缓冲好再发送。这个模型在小查询里很简单，但在 Kubernetes 或自建控制面这类场景中，大范围扫描会把延迟和内存占用变得难预测。

v3.7 的 RangeStream RPC 改变了这个交付方式：调用方可以分块接收结果集。它的价值不是让查询语义变复杂，而是把峰值内存和首批数据到达时间控制得更可预期。对需要列出大量资源、做离线巡检、同步缓存的应用来说，这是最值得优先评估的新能力。

Kubernetes 也计划在后续 v1.37 中通过 EtcdRangeStream feature gate 暴露这项能力。这一点很关键：etcd 和 Kubernetes 的协同发布节奏正在变得更紧，控制面性能优化不再只是 etcd 自己的内部变化。

性能改进不只是一句“更快”

v3.7 里有几处性能改动非常具体。

keys_only Range 请求现在可以只读内存索引，直接返回匹配到的 key，而不是像过去那样把 bbolt 中的序列化 value 也加载出来。唯一例外是按 value 排序的 keys-only 查询，因为排序本身需要读取 value。对于只做 key 枚举的巡检脚本、控制器缓存预热、目录式 key 结构扫描，这会减少不必要的后端读取和内存压力。

Lease 路径也变了。LeaseRevoke 在过载时会被优先处理，避免租约过期被拖延；新的 FastLeaseKeepAlive 可以通过跳过等待 applied index 来加快续约。对依赖 lease 做 leader election、会话保活、临时节点的系统来说，这类改动直接影响故障恢复时的尾延迟。

Watch 方向则通过更快的 find() 操作改善并发 watch 场景。v3.7 还新增了 watch send-loop 相关指标，以及新的 etcd_server_request_duration_seconds，方便把 watch 路径上的慢点拆开看。

v2store 退场：升级前别只看镜像标签

v3.7 现在完全从 v3store 启动，移除了启动流程中对遗留 v2 store 的依赖。这是从 v3.4 到 v3.7 跨多个版本推进的技术债清理。短期看，它简化了启动路径；长期看，它给后续继续清理和优化 etcd 内部状态管理留出空间。

但兼容性仍然要认真处理。v3.7 还会生成 v2 snapshot，--snapshot-count 也仍然保留；不过公告明确说 v2 snapshot generation 和 --snapshot-count 会在 v3.8 移除。也就是说，如果你的运维脚本、备份流程或监控规则仍然把这些行为当成长期稳定接口，现在就应该开始迁移。

同时，v2 discovery、v2 request support、v2 client support 已经被移除。还在使用 v2 API 包、client/internal/v2，或者从老版本直接跳升级的团队，要先做依赖扫描，而不是在生产集群里靠滚动升级试运气。

可以这样实践：升级前做一次配置和行为巡检

下面的命令不是替代官方升级指南，而是一个可以放进变更单里的预检查骨架。你需要把 ETCDCTL_ENDPOINTS、证书路径、命名空间和镜像名改成自己的环境。

#!/usr/bin/env bash
set -euo pipefail

export ETCDCTL_API=3
export ETCDCTL_ENDPOINTS="https://127.0.0.1:2379"
export ETCDCTL_CACERT="/etc/etcd/pki/ca.crt"
export ETCDCTL_CERT="/etc/etcd/pki/client.crt"
export ETCDCTL_KEY="/etc/etcd/pki/client.key"

echo "== cluster health =="
etcdctl endpoint health --cluster

echo "== endpoint status =="
etcdctl endpoint status --cluster -w table

echo "== keys-only range smoke test =="
etcdctl get /registry/ --prefix --keys-only --limit=20

echo "== snapshot smoke test =="
etcdctl snapshot save /tmp/etcd-pre-upgrade.db
etcdutl snapshot status /tmp/etcd-pre-upgrade.db -w table

如果你用 Kubernetes 管理 etcd，v3.7 官方容器镜像只发布 multiarch 镜像，不再提供架构后缀镜像。可以把部署清单中的架构标签清掉，保留常规版本标签。下面是一个简化示例，按你的仓库地址和启动参数调整：

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: etcd
  namespace: kube-system
spec:
  serviceName: etcd
  replicas: 3
  selector:
    matchLabels:
      app: etcd
  template:
    metadata:
      labels:
        app: etcd
    spec:
      containers:
        - name: etcd
          image: registry.k8s.io/etcd:3.7.0
          command:
            - /usr/local/bin/etcd
          args:
            - --name=$(POD_NAME)
            - --data-dir=/var/lib/etcd
            - --listen-client-urls=https://0.0.0.0:2379
            - --advertise-client-urls=https://$(POD_IP):2379
          env:
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: POD_IP
              valueFrom:
                fieldRef:
                  fieldPath: status.podIP

滚动升级时仍然按 etcd minor release 的常规纪律来：一次只升级一个 member，升级后确认 health、leader、raft index 和业务侧错误率，再动下一个节点。

kubectl -n kube-system rollout status statefulset/etcd
kubectl -n kube-system exec -it etcd-0 -- etcdctl endpoint health --cluster
kubectl -n kube-system exec -it etcd-0 -- etcdctl endpoint status --cluster -w table

Go 依赖方要特别看 protobuf 和 client 行为

如果你只是运行官方二进制或官方容器，protobuf overhaul 多半不会直接改变你的使用方式。但如果你的项目 import 了 etcd client SDK，或者依赖 api/、pkg/ 下的包，v3.7 把 github.com/golang/protobuf、github.com/gogo/protobuf 迁到 google.golang.org/protobuf 这一类改动，可能让你的构建、类型断言、生成代码或间接依赖版本出现冲突。

另一个容易踩到的点是 client 创建。v3.7 不再遵守已废弃的 grpc.WithBlock dial option，client 创建会变成非阻塞语义。需要“启动时必须确认 etcd 可用”的服务，应显式做一次健康检查或带超时的请求，而不是依赖 dial 阶段阻塞。

可以这样实践：

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    clientv3 "go.etcd.io/etcd/client/v3"
)

func main() {
    cli, err := clientv3.New(clientv3.Config{
        Endpoints:   []string{"127.0.0.1:2379"},
        DialTimeout: 3 * time.Second,
    })
    if err != nil {
        log.Fatal(err)
    }
    defer cli.Close()

    ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
    defer cancel()

    resp, err := cli.Status(ctx, "127.0.0.1:2379")
    if err != nil {
        log.Fatalf("etcd is not ready: %v", err)
    }

    fmt.Printf("etcd version=%s dbSize=%d leader=%d\n", resp.Version, resp.DbSize, resp.Leader)
}

运行前把 endpoint 改成你的 etcd 地址；如果集群启用了 TLS，需要在 clientv3.Config 中补上 TLS 配置。

采用建议：把 v3.7 当成一次清债升级

v3.7 的收益很明确：大范围查询更稳，keys-only 查询更轻，lease 和 watch 路径更可靠，Kubernetes 控制面有望看到 CPU 下降，底层 bbolt 和 raft 也同步更新。但它不是“只换镜像”的版本。

升级前建议检查这几项：是否还存在 --experimental-* 参数；是否依赖 v2 discovery、v2 request 或 v2 client；是否把架构后缀容器镜像写死在部署系统里；Go 项目是否直接依赖 etcd 的 protobuf 相关包；启动逻辑是否依赖 grpc.WithBlock 的阻塞行为；备份和监控是否还假设 v2 snapshot 与 --snapshot-count 会长期存在。

如果这些检查都通过，v3.7 值得尽早在预生产环境验证。尤其是会产生大量 Range、keys-only scan、watch 和 lease keepalive 的系统，这个版本的改动正好打在高频路径上。