etcd 特性生命周期管理：Alpha/Beta/GA 三阶段模型与 Feature Gate 机制实现

本文围绕 etcd 官方的特性（Feature）开发指南展开，系统讲解 Alpha、Beta、GA 三阶段特性生命周期模型、Kubernetes KEP 流程在 etcd 中的落地要求，以及特性晋升与废弃的标准操作。结合仓库中 server/features/etcd_features.go 的 gate 注册表和 pkg/featuregate/feature_gate.go 的核心实现，你可以掌握从"提出新特性"到"废弃移除"的完整工程流程，以及 --feature-gates 命令行参数的具体用法与底层解析逻辑。

特性三阶段模型：Alpha、Beta、GA

etcd 将特性划分为三个成熟度阶段，这是整个特性治理的骨架。三个阶段的核心差异可归纳为：

阶段	默认状态	支持级别	移除策略
Alpha	默认禁用	可能因缺少用户测试而有 bug，启用后行为可能不符合预期	可随任意版本不另行通知移除；相关 issue 优先级可能较低；除非晋升到更稳定的阶段，否则可在下一个 minor/major 版本直接删除，无需遵循废弃策略
Beta	默认启用	作为受支持版本的一部分提供保障	停止支持必须遵循特性废弃（deprecation）策略
GA	始终启用，无法关闭	作为受支持版本的一部分提供保障	停止支持必须遵循特性废弃策略；对应的 feature gate 不再需要

这个模型在代码中有直接映射：pkg/featuregate/feature_gate.go 中定义了 prerelease 常量：

const (
	// Values for PreRelease.
	Alpha = prerelease("ALPHA")
	Beta  = prerelease("BETA")
	GA    = prerelease("")

	// Deprecated
	Deprecated = prerelease("DEPRECATED")
)

GA 阶段对应空字符串值，废弃阶段（Deprecated）则是废弃策略中用于标记即将移除的 gate 的第四种状态——这正是"废弃流程"章节中会修改的状态值。

Feature Gate 的核心数据结构与实现

FeatureSpec：每个 gate 的元信息

每个 feature gate 的规格由 FeatureSpec 结构体描述：

type FeatureSpec struct {
	// Default is the default enablement state for the feature
	Default bool
	// LockToDefault indicates that the feature is locked to its default and cannot be changed
	LockToDefault bool
	// PreRelease indicates the maturity level of the feature
	PreRelease prerelease
}

三个字段的含义与特性生命周期紧密对应：

• Default：默认启用状态。Alpha 特性默认 false，Beta 特性默认 true，这直接体现了三阶段模型中"Alpha 默认禁用、Beta 默认启用"的差异；
• LockToDefault：是否锁定为默认值、禁止用户修改。GA 特性"始终启用且无法关闭"，以及废弃流程第二阶段"锁定为 false"，都通过该字段实现；
• PreRelease：成熟度阶段，即上表中的 Alpha/Beta/GA/Deprecated。

AllAlpha / AllBeta 全局开关

feature_gate.go 定义了两个特殊的全局 gate：

// allAlphaGate is a global toggle for alpha features. Per-feature key
// values override the default set by allAlphaGate.
allAlphaGate Feature = "AllAlpha"
// allBetaGate is a global toggle for beta features.
allBetaGate Feature = "AllBeta"

单个特性的显式配置优先级高于全局开关。例如 AllAlpha=true,NewFeature=false 最终结果为 NewFeature=false；AllAlpha=false,NewFeature=true 则结果为 NewFeature=true。这个覆盖逻辑由 setUnsetAlphaGates / setUnsetBetaGates 实现——它们只设置那些未被显式指定（not found in enabled map）的 Alpha/Beta gate。pkg/featuregate/feature_gate_test.go 中的 TestFeatureGateFlag 用例对上述四种组合逐一做了断言验证。

解析、校验与警告

--feature-gates 的值以 key1=value1,key2=value2,... 格式传入，由 Set 方法 按逗号拆分、按第一个 = 切分键值并做布尔解析，随后交给 SetFromMap 处理。其中包含几处关键校验：

1. 未知 gate 报错：unrecognized feature gate，拼写错误的 gate 名会在启动阶段直接暴露；
2. 锁定 gate 报错：若 LockToDefault 为 true 且传入值与默认值不同，返回 cannot set feature gate %v to %v, feature is locked to %v；
3. Deprecated/GA gate 警告：当用户显式设置一个处于 Deprecated 或 GA 阶段的 gate 时，会记录警告日志（L235-L239）：Setting deprecated feature gate %s=%t. It will be removed in a future release. —— 这就是废弃策略中"被废弃的 feature gate 在被使用时必须返回警告"要求的直接实现。

此外，Enabled 查询对已注册的 gate 返回用户配置值或默认值（L334-L343）；而 KnownFeatures（L366-L376）在生成帮助文本时会过滤掉 GA 和 Deprecated gate，只展示 Name=true|false (STAGE - default=x) 形式的 Alpha/Beta 选项——GA 特性"无需 gate"的模型在 CLI 层面也得到了体现。值得注意的是，该包文件头注释说明它是从 k8s.io/component-base 拷贝而来，目的是避免 etcd 与 k8s 之间的循环依赖。

仓库当前的 Feature Gate 注册表

etcd 服务端的所有 gate 集中注册在 server/features/etcd_features.go。文件顶部（L26-L36）还内置了一份新 gate 的注释模板，要求每个 gate 注明 owner、KEP/issue 链接、首次出现的版本（alpha/beta），并规定 gate 按字母序（大小写敏感）排列以减少代码冲突。

当前注册表 DefaultEtcdServerFeatureGates 的完整清单如下：

Feature Gate	阶段	默认值	引入版本	功能说明
StopGRPCServiceOnDefrag	Alpha	false	v3.6	defragmentation 期间停止 gRPC 服务处理客户端请求
InitialCorruptCheck	Alpha	false	v3.6	在对外提供客户端/peer 流量之前检查数据损坏
CompactHashCheck	Alpha	false	v3.6	leader 周期性检查 follower 的 compaction hash
LeaseCheckpoint	Alpha	false	v3.6	leader 定期向其他成员发送 checkpoint，防止 leader 变更时租约剩余 TTL 被重置
LeaseCheckpointPersist	Alpha（已标记 Deprecated）	false	v3.6	持久化 remainingTTL，防止长寿命租约被无限自动续期；依赖 LeaseCheckpoint，注释标明"TODO: Delete in v3.7"
SetMemberLocalAddr	Alpha	false	v3.6	使用 --initial-advertise-peer-urls 中第一个非回环本地地址作为与 peer 通信的本地地址
TxnModeWriteWithSharedBuffer	Beta	true	v3.5	写事务在只读检查操作中使用共享 buffer
FastLeaseKeepAlive	Beta	true	v3.7	租约续约跳过等待 applied index
PriorityRequest	Alpha	false	v3.7	在过载条件下让特定请求（如 LeaseRevoke）获得更高优先级

注册完成后由 NewDefaultServerFeatureGate 注入 gate 实例，并作为 server/config/config.go 中 ServerConfig 的 ServerFeatureGate 字段下发到 etcdserver。

用户视角：--feature-gates 命令行与配置项

feature gate 通过 --feature-gates 命令行参数暴露。该参数名在 server/embed/config.go 中定义为常量 ServerFeatureGateFlagName = "feature-gates"，并在 embed config 的 flag 注册处 通过 AddFlag 挂到 pflag 上。etcd --help 中对应的输出见 server/etcdmain/help.go，选项列表由 KnownFeatures() 动态生成，因此随注册表自动更新。

典型用法（组合多个 gate）：

etcd --feature-gates=StopGRPCServiceOnDefrag=true,InitialCorruptCheck=true

这条命令也正是 server/etcdmain/config_test.go 中 TestFeatureGates 用例所验证的输入，测试断言了解析后每个 gate 的启用状态与预期一致。

除命令行外，etcd 还支持 JSON 配置形式。embed config.go 中 ConfigJSON 结构体包含 ServerFeatureGatesJSON string \json:"feature-gates"`字段，加载时在 [L779-L780](https://gitcode.com/GitHub_Trending/et/etcd/blob/5d8f9378b0024a33f4a6c6665173daac353c6441/server/embed/config.go?utm_source=gitcode_repo_files#L779-L780) 调用Set` 解析，格式与命令行值相同。

配置解析后，gate 的实际生效点遍布服务端各模块，例如：

• server/etcdserver/v3_server.go：写事务根据 TxnModeWriteWithSharedBuffer 选择是否使用共享 buffer；L511 的 FastLeaseKeepAlive 控制租约续约路径；L1062 用 PriorityRequest 决定过载下的请求优先级；
• server/etcdserver/server.go：按 LeaseCheckpointPersist 配置 lessor 的 CheckpointPersist；L396 按 LeaseCheckpoint 启动 checkpoint 流程；L2266 按 CompactHashCheck 决定是否执行 hash 检查；
• server/etcdserver/api/v3rpc/health.go：按 StopGRPCServiceOnDefrag 构造健康检查通知器；
• server/embed/etcd.go：成员初始化后若启用 InitialCorruptCheck，在对外服务前执行数据损坏检查。

gate 之间还存在依赖校验。embed config 的校验逻辑 强制要求 LeaseCheckpointPersist 与 LeaseCheckpoint 同开同关，否则启动失败——这对应了注册表中"Requires EnableLeaseCheckpoint featuragate to be enabled"的注释说明。

开发指南：添加一个新特性

按照贡献者指南，etcd 对任何新增强都默认以 Alpha 特性方式引入，并遵循 Kubernetes 的 KEP（Kubernetes Enhancement Proposal）流程。完整的开发要求如下：

1. 提出 KEP issue

• 必须清晰说明该特性的需求动机；
• 应使用复选框列出开发工作项，其中必须有一项指向未来向 Beta 晋升的工作；
• issue 需打上 /sig etcd 标签；
• 在晋升决策作出之前，issue 保持 open 状态用于跟踪。

2. 提交 KEP PR

• KEP 模板可针对 etcd 简化；
• 必须为每个阶段给出清晰的晋升（graduation）标准；
• KEP 文档需存放在 kubernetes/enhancements 仓库的 keps/sig-etcd/ 目录下。

3. 在 etcd 仓库提交实现 PR

• 提供单元测试，尽可能补充集成测试；
• 提供健壮的 e2e 测试覆盖；若特性复杂或时间紧迫，维护者可决定先以 e2e 基本覆盖起步，再在特性晋升为稳定特性之前补上完整覆盖；
• 提供用于调试的日志；
• 按需提供 metrics 与 benchmark；
• 添加一个 Alpha 阶段的 feature gate；
• 与该特性实现相关的所有代码改动或配置标志，都必须受 feature gate 控制，代码中体现为 if cfg.ServerFeatureGate.Enabled(features.FeatureName) 这类判断（上述"用户视角"小节列举的 v3_server.go、server.go 各调用点即为真实例子）；
• 添加 CHANGELOG 条目。

4. 审批门槛：至少两名维护者（maintainer）必须同时批准 KEP 和相关代码改动。

仓库中已有的 gate 实现与测试也印证了这套要求：每个 gate 都有对应的代码门控点（源码事实），server/embed/config_test.go 用表驱动用例覆盖各个 gate 的默认状态与显式配置结果，tests/e2e/etcd_config_test.go 则验证了 --feature-gates=SetMemberLocalAddr=true 在真实集群下的 e2e 行为。

开发指南：将特性晋升到下一阶段

指南强调：特性不应滞留在同一阶段。一旦满足 KEP 中列出的晋升标准，就应该重新审视并推进阶段；且一个特性应在当前阶段至少停留一个发布版本后才能晋升。

晋升操作（Alpha → Beta 或 Beta → GA）的具体步骤：

1. 打开一个 PR，更新 server/features/etcd_features.go 中该 gate 的 PreRelease 阶段（例如 {Default: false, PreRelease: featuregate.Alpha} 改为 {Default: true, PreRelease: featuregate.Beta}）；
2. 同步更新原 KEP issue 的状态。

同样要求至少两名维护者批准，且补丁版本（patch release）不作为晋升的载体——晋升只会发生在 minor/major 版本中。当前仓库中 TxnModeWriteWithSharedBuffer（v3.5 Beta）与 FastLeaseKeepAlive（v3.7 Beta）就是完成过晋升的实例，它们的注册项均为 {Default: true, PreRelease: featuregate.Beta}（见 etcd_features.go L93/L97）。

开发指南：废弃一个特性

废弃策略按阶段区分处理：

Alpha 特性的废弃

Alpha 特性可以直接移除，无需走废弃流程：

• 删除 server/features/etcd_features.go 中对应的 feature gate，并清理所有相关代码；
• 关闭原 KEP issue，说明废弃理由。

Beta/GA 特性的废弃

Beta/GA 特性的废弃是分两步、跨两个 minor/major 版本执行的渐进过程：

1. 前置条件：Beta/GA 特性只有在至少经过 2 个 minor 或 major 发布之后才可被废弃；
2. 若原 KEP issue 未关闭则更新它，否则新建一个 etcd issue，说明废弃理由与步骤；
3. 在下一个 minor/major 版本的 release notes 和 feature gates 文档中补充该特性的废弃说明；
4. 第一个废弃版本：将该 gate 在 server/features/etcd_features.go 中设置为 {Default: false, PreRelease: featuregate.Deprecated, LockedToDefault: false}。此时用户若仍在使用该 gate，会收到警告日志（即前文 SetFromMap 中的 Warn 分支）；若该特性已 GA 且原有 gate 控制的代码已被清理，则需要把禁用代码连同 gate 一起加回来；
5. 再下一个 minor/major 版本：将 gate 设置为 {Default: false, PreRelease: featuregate.Deprecated, LockedToDefault: true} 并开始清理代码——LockedToDefault: true 意味着用户此时无法再通过 --feature-gates 把它打开（尝试设置会被 SetFromMap 的锁定校验 直接报错拒绝）；
6. 至少两名维护者批准；补丁版本不作为废弃的载体。

仓库中 LeaseCheckpointPersist 是该流程的活样本：其注释标注"Deprecated: Enabled by default in v3.6, to be removed in v3.7"与"TODO: Delete in v3.7"（etcd_features.go L63-L70），展示了废弃 gate 从标记到清理的过渡状态。

小结

etcd 的特性治理可以概括为一条主线：新特性以 Alpha gate 形式引入（默认关闭、受 --feature-gates 控制、代码全部门控），满足标准后逐版本晋升到 Beta（默认开启）再到 GA（gate 消失、代码常驻），不再需要的特性则按"警告期 → 锁定期 → 清理"的节奏跨版本废弃。对使用者，这意味着在 server/features/etcd_features.go 中即可查到当前版本全部可用的 gate 及其默认状态，并用 --feature-gates 精确控制实验性能力；对贡献者，则意味着 KEP 流程、gate 模板注释、两级维护者审批和 CHANGELOG 是任何一个新特性从提议到落地不可跳过的环节。