etcd v3.6 系列变更日志详解从 v3.6.0 破坏性变更、新特性到 v3.6.15 的安全修复全览【免费下载链接】etcdDistributed reliable key-value store for the most critical data of a distributed system项目地址: https://gitcode.com/GitHub_Trending/et/etcdetcd 官方变更日志 CHANGELOG-3.6.md 完整记录了 v3.6 版本线从 v3.6.0-rc.0 到 v3.6.15 的全部演进包括移除 v2 兼容层带来的破坏性变更、v2 弃用deprecation流程、一批新增服务端启动参数、存储层包结构重组以及十几个补丁版本中持续修复的 RBAC 越权、watch 权限泄漏等安全漏洞。读完本篇你将掌握 v3.6 相对 v3.5 的关键差异点、升级前必须核对的配置清单以及各补丁版本修复问题的分类索引用于制定安全的升级与回退策略。一、v3.6 版本线全景v3.6 是 etcd 版本演进中的重要节点官方变更日志按“发布版 补丁版”的方式组织v3.6.0-rc.0 ~ v3.6.0-rc.52025-02-13 至 2025-05-08候选发布版承载了绝大部分特性开发与破坏性变更v3.6.02025-05-15正式发布官方明确说明“自 v3.6.0-rc.5 之后没有任何生产代码变更”v3.6.1 ~ v3.6.15TBC从 2025-06-06 到 2026-07 之后的补丁版以缺陷修复、安全漏洞修复含多个 CVE 与 GHSA 公告和依赖升级为主其中 v3.6.13、v3.6.14 引入了少量功能性变更如--v2-deprecation的write-only-skip-check选项。从源码侧印证当前仓库的版本常量集中在 api/version/version.go 中定义了V3_5、V3_6、V3_7等 semver 版本对象与MinClusterVersion 3.0.0最小兼容集群版本v3.6 系列服务端在判断集群成员版本、执行降级检查时依赖这些常量。注意当前仓库主干已处于 3.8.0-alpha.0 开发阶段各go.mod要求 Go 1.26本文所有 v3.6 相关结论均以官方变更日志及仓库中可核对的实现为准适用于 v3.6.x 系列。二、v3.6.0 的破坏性变更升级前必读变更日志在 v3.6.0-rc.0 中用 “Breaking Changes” 一节集中声明了四类破坏性变更这是升级决策的核心依据2.1 数据目录不再向前兼容降级需用etcdutl migratev3.6 的etcd二进制无法直接运行在更高版本如 v3.7创建的数据目录上。如需将数据目录降级到 v3.6 可读取的格式官方指定路径是etcdutl migrate命令。这与 v3.6.0 中新增的etcdutl migrate命令用于降级/升级 etcd 数据目录文件相呼应——v3.6 正式确立了“新版本数据目录单向兼容”的原则。2.2 移除的启动参数以下 v2 时代与代理相关的 flag 被整体移除升级脚本中必须清理--enable-v2--experimental-enable-v2v3--proxy--proxy-failure-wait--proxy-refresh-interval--proxy-dial-timeout--proxy-write-timeout--proxy-read-timeout2.3 其他行为变更peer 端口不再服务客户端请求etcd不再支持在 peer 监听端口--listen-peer-urls上处理客户端请求。依赖“客户端复用 peer 端口”的部署需要显式配置 client 监听地址etcdctl 删除保护etcdctl执行不带--rangeflag 的 range delete 时会 sleep 2 秒为误操作提供缓冲窗口构建要求依赖 etcd v3.6 相关 Go 包的应用必须使用 Go 1.18 构建v3.6.0 发布线自身要求 Go 1.23 编译后续补丁版逐步升级到 Go 1.24、1.25 系列见 4.3 节。2.4 弃用与移除的既有能力变更日志的 Deprecations 一节列出弃用 V2 discoveryv2 发现协议弃用limitListenerConn中的SetKeepAlive与SetKeepAlivePeriod移除etcdctl defrag --data-dir选项移除etcdctl snapshot status与etcdctl snapshot restore命令snapshot 相关操作统一收敛到etcdutl snapshot移除server/embed包中的NewZapCoreLoggerBuilder导出 API。这些变更直接改变了运维工具链例如做快照备份/恢复的自动化脚本从 v3.5 的etcdctl snapshot切换为etcdutl snapshot。三、v3.6.0 的新特性与参数变化3.1 服务端新增启动参数v3.6.0 集中新增了一批服务端 flag以下结合变更日志说明其用途与默认值参数说明--log-format支持配置日志格式v3.6.5 中同时移除了--help输出里已删除的--experimental-snapshot-catch-up-entries残留--experimental-max-learners配置 learner 成员数量上限后在 rc.3 中被 Feature Gate 取代见 3.2 节--experimental-enable-lease-checkpoint-persist用于从开启了该特性的 v3.5.2 集群平滑升级该特性在 v3.6 中默认开启--max-concurrent-streams限制每个客户端可打开的最大并发 gRPC 流数量默认math.MaxUint32不限制--experimental-compact-hash-check-enabled/--experimental-compact-hash-check-time支持对已压缩compactedrevision 启用可靠的损坏检测--experimental-snapshot-catch-up-entries配置 raft 存储压缩后慢 follower 追赶所需的条目数默认 5000--tls-min-version/--tls-max-version启用对 TLS 1.3 的支持--warning-unary-request-duration由--experimental-warning-unary-request-duration毕业而来实验性 flag 已弃用并将在 v3.7 移除其中--max-concurrent-streams的默认值可以在当前仓库中得到印证server/etcdmain/config.go 中通过flags.Uint32FromFlag(cfg.cf.flagSet, max-concurrent-streams)读取该参数server/etcdmain/help.go 的帮助文本同样显示其默认值为math.MaxUint32。另一个影响运维直觉的默认值变更--snapshot-count的默认值从100,000 下调到 10,000即 raft 日志更频繁地触发快照降低磁盘上 WAL 的堆积。变更日志后续还记录了相关参数的反复调整v3.6.8 将--max-snapshots的移除时间从 v3.7 推迟到 v3.8并撤销了对--snapshot-count的弃用——这说明官方对快照相关参数的策略在 v3.6 系列中保持审慎。3.2 Feature Gate 机制与 v3.6 特性开关v3.6 引入了或扩展了Feature Gate 来管理实验性特性。当前仓库的 server/features/etcd_features.go 中定义了一套完整的 gate 注册表其中标注 “alpha: v3.6” 的条目与变更日志逐条对应StopGRPCServiceOnDefragdefragmentation 期间停止 gRPC 服务以处理客户端请求alpha默认 falseInitialCorruptCheck在服务任何 client/peer 流量前做数据损坏检查alpha默认 falseCompactHashCheckleader 周期性检查 follower 的 compaction 哈希即 3.1 节--experimental-compact-hash-check-*参数背后的 gatealpha默认 falseLeaseCheckpoint/LeaseCheckpointPersistleader 向其他成员发送租约检查点防止 leader 切换导致剩余 TTL 重置alpha默认 falseSetMemberLocalAddr允许使用initial-advertise-peer-urls中第一个非 loopback 本地地址作为与 peer 通信的本地地址alpha默认 falseTxnModeWriteWithSharedBuffer写事务在只读检查中使用共享缓冲区v3.5 起 beta默认 true。可以印证变更日志中的一段历史v3.6.0-rc.3 的 “Replace ExperimentalMaxLearners with a Feature Gate” 说明--experimental-max-learners参数最终被 Feature Gate 机制取代rc.2 还新增了“通过 Prometheus metric 查询服务端 feature gate”的能力便于运维在监控面观察 gate 状态。3.3 etcdctl 与 etcdutl 变化etcdctl v3的新增能力新增 shell completion 生成命令etcdutl 同样获得该能力endpoint status输出新增 db 使用大小字段并新增storageVersion字段v3.6.0-rc.1 进一步在endpoint status结果中加入DowngradeInfo降级信息与 v3.6 的降级/兼容性检查能力配套--max-txn-ops加入make-mirror命令make-mirror --rev支持增量镜像member list新增--consistencyflag成员列表 JSON 输出中raft_term恒定以十进制打印endpoint hash命令展示hash_revision字段新增全局 flag--max-request-bytes与--max-recv-bytes。etcdutl v3的新增能力新增migrate命令数据目录降级/升级见 2.1 节snapshot restore新增可选的--bump-revision与--mark-compacted参数。这一实现可在当前仓库 etcdutl/etcdutl/snapshot_command.go 中直接看到--bump-revision用于恢复后提升 revision--mark-compacted用于将恢复后的最新 revision 标记为计划压缩点当--bump-revision 0时--mark-compacted为必填否则禁止使用新增hashkv命令打印到指定 revision 为止的键值哈希用于跨集群数据一致性校验移除了 legacyetcdutl backup键数量统计改为“从用户视角”计数排除内部键使etcdutl报告的键数与用户可见数据一致。3.4 包结构重组与 raft 独立v3.6.0 对服务端 Go 包做了大规模搬移当前仓库目录结构正是其结果mvcc→storage/mvcc对应仓库 server/storage/mvccmvcc/backend→storage/backendmvcc/buckets→storage/schemawal→storage/waldatadir→storage/datadir。更深层的架构动作是raft 与 etcd 解耦raft 模块迁移到独立仓库并更名为go.etcd.io/raft/v3。此外 v3.6.0-rc.3 将client/internal/v2移入server/internal/clientv2v3.6.0-rc.4 则完成“v2 与 v3 同步后切换为校验 v3”的校验策略调整——这些都是 v2 数据平面逐步退役deprecation路线图的一部分。其他值得注意的基础设施变更镜像基础镜像切换为 Distroless降低攻击面并缩小镜像体积grpc-gateway 从 v1 升级到 v2Prometheus 集成从go-grpc-prometheus切换到grpc-ecosystem/go-grpc-middleware/providers/prometheus新增指标etcd_disk_defrag_inflight进行中的 defrag 数、etcd_debugging_server_alarms服务端告警、etcd_server_range_duration_secondsrange 请求耗时分布。3.5 v2 弃用deprecation流程v3.6 系列持续完善--v2-deprecation选项v3.6.13 新增write-only-skip-check选项以绕过 v2 内容检查为只需“只写不读”的场景提供过渡空间v3.6.12 修复了MemberUpdate意外提升 learner、以及 etcdutl 对数据文件路径 panic 而非校验的问题。e2e 测试 tests/e2e/v2store_deprecation_test.go 覆盖该流程下的快照恢复场景。四、v3.6.x 补丁版修复索引v3.6.1 ~ v3.6.15补丁版是运维选型的关键如果线上运行 v3.6.0/v3.6.1建议至少升级到包含下列安全修复的版本。4.1 安全修复按发布时间版本修复内容v3.6.92026-03-20CVE-2026-33413多个未鉴权端点的越权访问通过 auth 检查守护未认证端点CVE-2026-33343嵌套事务绕过 RBAC 授权检查对嵌套 txn 操作强制鉴权v3.6.112026-05-01RBAC 越权嵌套事务中 Put 请求通过 PrevKv 或 lease 挂接实现读越权PR #21681、#21685v3.6.132026-07-01配置--listen-client-http-urls时 gRPC listener 上 CRL 强制校验被绕过GHSA-3wh4-j44w-pg92v3.6.142026-07-23watch 权限漏洞仅对某个 key 有读权限的用户会收到从该 key 开始所有 key 的 watch 响应GHSA-xg4h-6gfc-h4m8peer 租约 HTTP handler 上无界io.ReadAll客户端http.Server缺少ReadHeaderTimeoutTLS 握手超时GHSA-6vch-q96h-7gc3依赖侧同步修复了多个 CVEgolang.org/x/netCVE-2026-25681 等 6 项、golang.org/x/cryptoCVE-2025-47914、CVE-2026-46598 等、google.golang.org/grpcGHSA-hrxh-6v49-42gf、CVE-2026-33186、OpenTelemetry SDKCVE-2026-29181 等、golang-jwtCVE-2025-30204。仓库安全公告的发布流程可参考 security/security-release-process.md。4.2 关键行为与数据正确性修复watchv3.6.1 修复“watch 未来 revision 返回旧事件/通知”v3.6.9 修复 read index 与 leader 切换的竞态、进程暂停导致的 stale readsv3.6.6 拒绝带 -1 revision 的 watch 请求防止在未压缩 etcd 上的非法 resync 行为leasev3.6.5 修复“租约已撤销时 leaseRenew 仍可能返回成功”v3.6.6 修复启用 auth 后无法从 follower 提升成员数据目录/快照v3.6.5 修复 applySnapshot 与 defragment 并发时的潜在数据损坏v3.6.4 修复回放 learner 提升操作导致 bootstrap 失败v3.6.6 修复--force-new-cluster在创建快照后无法清理 learner、以及 v3.6.1 在 corner case 下无法移除全部其他成员压缩compactionv3.6.0-rc.5 修复压缩暂停时长指标未按每批压缩输出的问题成员/集群v3.6.11 修复“一个成员宕机但 quorum 仍满足时无法添加新成员”v3.6.12 修复MemberUpdate意外提升 learner 的 bug、允许非 admin 获取 maintenance statusv3.6.10 允许非 admin 获取成员列表与告警gRPC/代理v3.6.9 修复 grpc-proxy 启动死锁v3.6.0-rc.3 修复 grpcproxy 陷入死循环导致高 CPUrc.2 升级 grpc-gateway 修复 REST watch 流请求导致 etcdserver 崩溃认证/可观测v3.6.7 日志中只打印 token 指纹而非原始 tokenv3.6.13 修复 bearer 前缀 auth token 的 websocket 认证v3.6.9 保证 metrics interceptor 先于其他 interceptor 执行以维持指标时效clientv3 客户端v3.6.14 修复leaseCache.entries的无同步 range 遍历v3.6.9 在 unary interceptor 中打印 gRPC 请求实际发送到的 endpointv3.6.8 移除对 grpc-go Metadata 字段的使用v3.6.0-rc.5 将resolver.State.Addresses替换为resolver.State.Endpoint.Addresses。4.3 Go 工具链与依赖追踪变更日志逐版本记录了编译工具链的演进可作为供应链核对依据v3.6.0 线Go 1.23.7 ~ 1.23.9v3.6.1Go 1.23.10v3.6.2Go 1.23.11 bbolt v1.4.2v3.6.5Go 1.24.7 bbolt 升级到 v1.4.3v3.6.6 ~ v3.6.8Go 1.24.10 → 1.24.11 → 1.24.13后者同时修复 Go 语言本身的 3 个 CVEv3.6.9 ~ v3.6.12Go 1.25.8 → 1.25.10v3.6.13 ~ v3.6.14Go 1.25.11 → 1.25.12v3.6.15TBCGo 1.25.13。五、升级与核对建议基于以上变更日志与仓库证据面向 v3.6 的运维决策可以归纳为三点升级路径从 v3.5 升级到 v3.6 前先清理 2.2 节列出的已移除 flag、把etcdctl snapshot脚本迁移到etcdutl snapshot并确认 Go 构建链满足要求跨大版本回退前先评估数据目录格式必要时使用etcdutl migrate版本选型生产环境建议直接采用包含 4.1 节全部安全修复的 v3.6.14 及以上版本当前最新条目为 v3.6.15/TBC尤其当集群启用了 auth 与 TLS CRL 时v3.6.13 与 v3.6.14 的修复不可跳过特性核对通过 Feature Gate 与endpoint status的DowngradeInfo/storageVersion字段确认集群特性状态与存储版本结合etcd_disk_defrag_inflight、etcd_server_range_duration_seconds等新指标完善监控。更早期的版本历史可查阅 CHANGELOG-3.5.md各版本对应的代码结构与参数实现可在 server/etcdmain、server/features/etcd_features.go、etcdutl/etcdutl/snapshot_command.go 等路径中继续核对。【免费下载链接】etcdDistributed reliable key-value store for the most critical data of a distributed system项目地址: https://gitcode.com/GitHub_Trending/et/etcd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
