读懂 etcd 官方 Roadmap：v3.6 / v3.7 / v3.8 演进计划与源码中的落地证据

etcd 通过 roadmap.md 记录每个大版本中最重要任务的排期与优先级，是维护者容量与项目方向的公开承诺。本文以该文档为骨架，完整梳理 v3.6.0、v3.7.0、v3.8.0 三个版本及 Backlog 的关键任务，并结合当前仓库源码（etcdctl 命令、健康检查端点、RangeStream 实现等）逐条印证这些"路线图条目"是如何在代码中落地的，帮助读者既看清 etcd 的演进路线，又能快速定位每项特性的实现与验证位置。

Roadmap 的维护机制：Milestone 为主，文档只记要事

roadmap 文档开篇明确了三件事：

1. GitHub Milestone 才是任务的完整清单。etcd 用 GitHub milestones 跟踪每个 major/minor 版本的所有任务，roadmap.md 只记录每个版本中最重要的任务（原文："The roadmap.md file only records the most important tasks for each release"）。
2. 路线图受维护者容量约束。条目列表基于当前维护者的人力，可能随时间变化；"Proposed milestones are what we think we can deliver with the people we have"。如果关键方向获得更多社区支持，backlog 中的条目才有可能被拾取。
3. 技术债是近几个版本的主基调。文档明确写道：etcd 将在接下来几个 major/minor 版本中继续以技术债偿还为主线（"continue to mainly focus on technical debt"）。

这一机制决定了读 roadmap 的正确姿势：不要把表格里的条目当成"必定在指定版本交付"的硬性契约，而应把它理解为"维护者当前认为可以承诺的最高优先级集合"。完整任务清单需要去对应版本的 milestone（v3.6 对应 milestone etcd-v3.6，v3.7 对应 etcd-v3.7）查看。

优先级标签的定义

roadmap 中每个条目都带有优先级标签，其定义位于 triage_issues.md 的 "Step 5 - Prioritise the issue" 小节，完整语义如下表：

优先级标签	含义	典型场景
priority/critical-urgent	维护者必须确保该问题被主动推进——"放下手头一切"，应在下个版本前修复	核心功能的用户可见严重 bug、tier1 平台构建失败、严重安全问题
priority/important-soon	当前或近期必须有人接手推进——理想情况下赶在下个版本完成	—
priority/important-longterm	长期重要，但可能暂无人力，需要跨多个版本完成	—
priority/backlog	普遍认为有价值但无人近期投入，欢迎社区贡献（评审可能在发版前后排队）	—
priority/awaiting-more-evidence	可能有用，但证据/支持尚不足以立项	多为好点子的占位符，避免反复重提

另外注意 v3.7.0 表格中的 P0/P1 写法是同一体系的简写（P0 对应 important-soon 级别、P1 对应 important-longterm 级别），阅读时应做等价理解。

v3.6.0 关键任务全解

支持降级（Downgrade）——已完成

roadmap 记录："etcd will support downgrade starting from 3.6.0. But it will also support offline downgrade from 3.5 to 3.4."。即从 3.6.0 起 etcd 原生支持集群降级流程，同时 3.5 到 3.4 仍走离线降级方式。

当前仓库中这一能力已经落地为 etcdctl 的 downgrade 命令组，见 downgrade_command.go：

dc := &cobra.Command{
    Use:     "downgrade <TARGET_VERSION>",
    Short:   "Downgrade related commands. Use `etcdctl downgrade --help` to see subcommands",
    ...
}
dc.AddCommand(NewDowngradeValidateCommand())  // validate <TARGET_VERSION>
dc.AddCommand(NewDowngradeEnableCommand())    // enable <TARGET_VERSION>
dc.AddCommand(NewDowngradeCancelCommand())    // cancel

三个子命令构成完整的降级操作生命周期：downgrade validate <TARGET_VERSION> 在降级前校验集群是否允许降到目标版本；downgrade enable <TARGET_VERSION> 正式启动降级动作；downgrade cancel 取消进行中的降级。配套的降级请求处理链可见 maintenance.go 与 maintenance.go 中的 Downgrade 相关 RPC。这解释了 roadmap 中"Completed"状态的含义：它不是"将来做"，而是"当前代码已具备、可按此命令序列操作"。

支持 /livez 与 /readyz 端点——已完成

roadmap 备注："It provides clearer APIs, and can also work around the stalled writes issue"（提供清晰的 API，同时可以绕过 stalled writes 问题）。

源码层面该功能位于 health.go，文件头注释即写明 "The endpoints include /livez, /readyz and /health"，并定义了两类检查类型与新的响应结构：

const (
    PathHealth   = "/health"
    ...
    checkTypeLivez  = "livez"
    checkTypeReadyz = "readyz"
    checkTypeHealth = "health"
)

// HealthStatus is used in new /readyz or /livez health checks instead of the Health struct.
type HealthStatus struct {
    Reason string `json:"reason"`
    Status string `json:"status"`
}

与旧版 /health 只返回 success/error 不同，/livez 与 /readyz 返回带 status 和 reason 的结构化结果——这正是"clearer API"的含义：调用方不仅能判断"挂没挂"，还能拿到具体的失败原因。端到端验证用例见 http_health_check_test.go，其中覆盖了 livez/readyz 的行为断言。

StoreV2 弃用——进行中

条目指向 "StoreV2 deprecation"（issue #12913），备注"该任务将横跨 3.6 和 3.7 两个版本"。状态为 In progress，是 roadmap 全表中唯一未完成的 v3.6 条目。etcd 早期（v2 时代）的 StoreV2 存储接口在 v3 架构下属于历史包袱，该任务的目标是逐步移除/禁用这条旧链路。仓库内 tests/integration/v2store 等目录仍保留了 v2 相关的测试资产，可以从中观察该弃用过程的边界。

依赖底座升级：raft 3.6.0 与 bbolt 1.4.0——均已完成

任务	说明
Release raft 3.6.0	etcd 3.6.0 依赖 etcd-io/raft 3.6.0
Release bbolt 1.4.0	etcd 3.6.0 依赖 etcd-io/bbolt 1.4.0

raft 是 etcd 的一致性核心，bbolt（原 bolt）是其存储引擎，二者独立发版并随 etcd 版本联动升级，这是理解 etcd 依赖管理节奏的关键：roadmap.md 中"依赖 X.Y.0 发版"类条目本质上是版本锁——etcd 3.6 的存储层与共识层行为，取决于这两个上游版本的发布内容。

gRPC 升级与 grpc-gateway 处置

• Bump gRPC（#16290，Completed）：备注坦言"不保证在 3.6 内解决，可能推迟到 3.7 取决于工作量与风险"，最终标记完成。
• Deprecate grpc-gateway or bump it（#14499，Completed）：同样备注"可能推迟"，最终完成。

etcd 的 gRPC-gateway 是 HTTP/JSON 网关，升级 gRPC 版本会连带影响 rpc_grpc.pb.go 等生成代码与 gw/rpc.pb.gw.go 网关实现；仓库提供了 check-grpc-experimental 工具与 verify_grpc_experimental.sh 脚本，用于约束 gRPC 实验性 API 的使用边界，这两项任务的"风险"正体现在此。

bbolt 可观测性与修复工具

• bbolt: Add logger into bbolt（bbolt #509，Completed）——"对诊断 bbolt 问题很重要"。bbolt 是纯嵌入式引擎，内部错误日志是排障的第一手线索。
• bbolt: Add surgery commands（bbolt #370，Completed）——"surgery 命令对修复损坏的 db 文件至关重要"。etcd 的 member.db 一旦损坏，surgery 命令提供了在线修复路径而非只能快照恢复。

Lease 重构：防止旧 Leader 误回收租约

条目 "Refactor lease: Lease might be revoked by mistake by old leader"（#15247，Completed）指向一个经典的分布式系统问题：脑裂窗口内，任期过期的旧 leader 可能仍在运行租约回收逻辑，导致被新 leader 认可的有效租约被误删。租约核心实现位于 lessor.go 与 lease.go，该重构保证了租约回收只由当前有效 leader 驱动。

实验特性评估——尚未启动

"Evaluate and (Graduate or deprecate/remove) experimental features"（#16292，priority/backlog，Not started）：对处于 experimental 阶段的特性做毕业/弃用/移除的裁决，横跨 3.6 与 3.7。仓库中 features.go 定义了 etcd 的特性门（feature gate），这是该任务未来落地的直接抓手。

v3.7.0 关键任务全解

v3.7 表格中四个条目全部标记 Completed，当前仓库（版本 3.8.0-alpha.0，见 version.go 中 Version = "3.8.0-alpha.0"）即包含了这些成果。

Bootstrap etcdserver from v3store（P0）

指 etcdserver 的引导流程从依赖旧 v2 store 迁移到 v3 store，与 v3.6 的 "StoreV2 deprecation" 是一体两面：3.6 开始弃用旧接口，3.7 完成启动路径的彻底切换。AllVersions 版本常量表同样集中在 version.go 中维护，用于升级/降级的版本比较逻辑。

支持 Range Stream（P0）——仓库中可直接溯源

"Support range stream"（#12342）允许 Range 请求以流式方式返回大量键值，避免一次性在内存中堆积全部结果。源码证据链完整：

• API 层：rpc.proto 定义了 RangeStream 方法与 RangeStreamResponse 消息，由 rpc_grpc.pb.go 生成客户端桩。
• 客户端：kv.go 提供 RangeStreamResponse 类型与 GetStreamToGetResponse 辅助函数，流式结果可逐块消费，也可收敛回普通 GetResponse；retry.go 中同样处理了 RangeStream 的重试路径。
• 服务端：key.go 中 kvServer.RangeStream 在 checkRangeStreamRequest 中明确了两条约束：

func checkRangeStreamRequest(r *pb.RangeRequest) error {
    if err := checkRangeRequest(r); err != nil {
        return err
    }
    if !txn.IsDefaultOrdering(r.SortTarget, r.SortOrder) {
        return status.Errorf(codes.Unimplemented, "RangeStream does not support custom sort orders")
    }
    if txn.HasRevisionFilters(r) {
        return status.Errorf(codes.Unimplemented, "RangeStream does not support revision filters")
    }
    return nil
}

即 RangeStream 暂不支持自定义排序与 revision 过滤器——这是使用该 API 时必须知道的能力边界。集成测试见 kv_test.go 与 v3_grpc_test.go，benchmark 工具 range.go 也接入了该接口。

Protobuf 栈清理（P0）

"cleanup both golang/protobuf and gogo/protobuf"（#14533）：etcd 历史上同时使用 gogo/protobuf（性能优化的旧代码生成器）与 golang/protobuf，长期并存导致 API 双轨。该任务统一了 protobuf 运行时。当前 api/ 下的生成代码即为清理后的产物。

bbolt 命令 cobra 化（P1）

"Migrate all commands to cobra style commands"（bbolt #472）：bbolt 的独立工具命令迁移到 cobra 框架，与 etcdctl 的 cobrautl 风格统一，改善子命令、帮助与错误处理的一致性。

v3.8.0 计划中任务

当前仓库版本即 3.8.0-alpha.0，以下条目处于"规划中/调研中"状态，roadmap 未标注完成状态：

任务	优先级	说明
Stop generating v2 snapshots and cleanup up existing ones（#20187）	P0	停止生成 v2 快照并清理存量——StoreV2 弃用的最终收尾：v3 快照不再夹带 v2 数据，降低快照体积与兼容负担
Define an official performance validation suite for etcd（#16467）	P1	定义官方性能验证套件，为每个版本提供可复现的性能基线
Integrate raft's new feature (async write) into etcd（#16291）	P1	备注"still tentative, and to be investigated"：raft 异步写特性集成仍是候选项，尚未立项调研结论
Evaluate and potentially replace cmux（#18032）	P1	评估是否替换 cmux（多路复用库），属于依赖健康度治理

从源码结构看，"停止生成 v2 快照"与 v3.7 的 v3store bootstrap 衔接紧密：既然引导路径已不再依赖 v2 store，快照中的 v2 数据就失去了消费方，可以在 3.8 中安全移除。

Backlog：更远期的方向

roadmap 末尾的 Backlog 表列出了未排期、但方向明确的候选项：

任务	含义
Proposals should include a merkle root（#13839）	提案消息携带 merkle root，为日志内容的可校验性（如未来的一致性证明）打基础
Add Distributed Tracing using OpenTelemetry（#12460）	引入 OpenTelemetry 分布式追踪，补齐跨 gRPC/raft/存储层的可观测性
Support CA rotation（#11555）	支持证书颁发机构轮换，缓解 TLS 部署中的 CA 替换痛点
raft: enhance the configuration change validation（raft #80）	增强 raft 成员变更的校验逻辑

注意 Backlog 表不标注优先级列值（表格中 Priority 列为空），这与 triage 体系中"backlog = 有共识但未排期"的定义一致——这些条目是方向性备忘，而非承诺。

实践建议：如何跟随这份 Roadmap

1. 以 milestone 为权威：roadmap.md 是精选视图，完整任务（含所有状态流转）在对应 GitHub milestone（etcd-v3.6 / etcd-v3.7）中，两者互补。
2. 用优先级标签判断可信度：important-soon 条目大概率随版本交付（如 3.6 的降级支持、3.7 的 Range Stream）；backlog 与"tentative"备注（raft async write）应视为调研方向。
3. 交叉验证完成状态：本文已示范的方法——在仓库中搜索对应实现（downgrade 命令、checkTypeLivez、RangeStream）与测试（http_health_check_test.go、kv_test.go），比任何状态标记都可靠。
4. 关注版本文件：version.go 中的 Version、MinClusterVersion（当前为 3.0.0）与 AllVersions 常量表，是判断当前开发线所处版本、以及升级/降级兼容边界的唯一事实来源。
5. 技术债主线：3.6–3.8 的条目大量集中在依赖升级（raft/bbolt/gRPC/gateway）、旧接口移除（StoreV2、v2 快照）与可观测性（livez/readyz、bbolt logger），规划 etcd 运维窗口（升级、降级、快照恢复演练）时，这些条目比新功能更具实际影响。

需要强调的是：roadmap 文档本身声明其内容"based on the current maintainer capacity that may shift over time"——本文所有条目状态均以当前仓库快照（3.8.0-alpha.0 开发线）为准，版本正式发布前个别条目的完成状态仍可能调整。