WuKongIM 节点下线终局:Stage 5A removed 墓碑写路径的实现计划与落地验证
WuKongIM 节点下线终局:Stage 5A removed 墓碑写路径的实现计划与落地验证
本篇技术指南围绕 WuKongIM 动态节点生命周期 Stage 5 的第一份子计划(5A)展开:为控制面增加 MarkNodeRemoved 写路径,把一个已经完成外部排空(drain)安全检查的 leaving 数据节点固化为 removed 墓碑状态。读完本文,你能完整掌握这一控制面写操作的三层结构——Controller 运行时状态机、clusterv2 control 泛化控制写(control write)转发、根级 Node 门面委托——以及它如何通过 TDD 验证、幂等语义、controller-voter 保护与 revision fencing 保证 fail-closed 安全。
一、Stage 5A 在动态节点生命周期中的位置
WuKongIM 的集群成员生命周期状态机定义在设计文档 dynamic-node-lifecycle-design 中,membership 与 health 是两个正交维度:
membership: joining -> active -> leaving -> removed
health: alive | suspect | down
其中 removed 被明确设计为墓碑(tombstone)状态而不是物理删除。设计文档第 5 节指出:直接删除节点身份不如保留墓碑安全,因为墓碑可以防止旧的 node_id 被意外复用。因此 V1 不要求把 removed 节点从 cluster-state.json 中物理移除。
Stage 5 的总体目标是把 Stage 4 的“缩容准备”(scale-in preparation)收敛为一条最终的 safe-to-remove 门。为了避免单分支改动过大,Stage 5 被拆成五个可独立评审、独立合并的子阶段,总索引见 stage5 plan index:
| 顺序 | 子阶段 | 产出 |
|---|---|---|
| 5A | Removed Lifecycle Tombstone | 控制面可以把已排空的 leaving 数据节点标记为 removed |
| 5B | Channel Drain Inventory | scale-in 状态报告包含有界的 Channel leader/replica/ISR 阻塞项 |
| 5C | Gateway Drain Mode | manager 可将节点 gateway 置为 drain 模式并上报 drain 阻塞项 |
| 5D | Safe Remove Route | manager remove 路由仅在 safe_to_remove=true 时调用 MarkNodeRemoved |
| 5E | Remove Smoke And FLOW Docs | e2ev2 证明已排空节点可被移除,FLOW 文档描述完整路径 |
Stage 5A(本文主题)是五个子阶段中唯一的“纯控制面”子阶段。 原计划文档 stage5a-removed-lifecycle 明确了它的边界:
- Goal:为 Controller 和 clusterv2 控制面增加把已排空 leaving 数据节点标记为
removed的能力; - Architecture:只新增
MarkNodeRemoved——位于 Controller 运行时、clusterv2/control 转发、以及根级clusterv2.Node管理委托三处;不暴露 manager HTTP remove 路由,也不改变 scale-in 安全状态; - 明确排除项:本阶段不得新增
/scale-in/remove路由、gateway drain 模式、Channel inventory,或 manager 的 safe-to-remove 逻辑。
跨子阶段规则(来自 Stage 5 索引)对 5A 同样有约束:removed 保持墓碑语义、不动态增删 Controller Raft voter、不直接改写 Slot DesiredPeers、每个分支只实现并合并一个子阶段。
命名沿革说明:本文档写作时仓库内存在 v2 时代的包名(
pkg/controllerv2、pkg/clusterv2),当前仓库中该控制面的最终落位路径为 pkg/controller 与 pkg/cluster。下文以当前仓库的实际路径为准,并标注与原计划路径的对应关系。
二、入口门:开始前必须通过的验证
计划采用 TDD 流程,入口门(Entry Gate)要求两项前置检查:
- Stage 4 已合并进本地
main; - 既有 leaving 生命周期测试全部通过:
GOWORK=off go test ./pkg/controllerv2 ./pkg/clusterv2/control ./pkg/clusterv2 \
-run 'TestRuntimeMarkNodeLeaving|TestNodeMarkNodeLeaving|TestControlWrite.*MarkNodeLeaving|TestNewControlWriteHandler.*MarkNodeLeaving' \
-count=1
期望结果:PASS。这条命令覆盖三个层级(Controller 运行时、control 转发、根节点门面)的 MarkNodeLeaving,确认 5A 所依赖的“前一个状态迁移”是健康的。按当前仓库路径,等价测试位于 pkg/controller、pkg/cluster/control、pkg/cluster 包内。
三、目标文件结构:计划中的十个触点
原计划给出的文件改动清单如下(v2 路径 → 当前仓库落位):
| 计划文件 | 职责 | 当前仓库对应实现 |
|---|---|---|
pkg/controllerv2/runtime_node_lifecycle.go |
新增 MarkNodeRemoved,仅允许对已处于 leaving 的非 controller 数据节点生效 |
runtime_node_lifecycle.go |
pkg/controllerv2/runtime_test.go |
验证 leaving→removed、幂等 removed、拒绝 active、拒绝 controller voter、拒绝不存在的节点 | runtime_integration_test.go |
pkg/clusterv2/control/node_lifecycle.go |
removed 写的 control DTO 与转换辅助函数 | node_lifecycle.go |
pkg/clusterv2/control/codec.go |
mark_node_removed 控制写动作与 snake_case 线格式 |
codec.go |
pkg/clusterv2/control/control_write.go |
ControlWriteApplier.MarkNodeRemoved 接口方法与分发 |
control_write.go |
pkg/clusterv2/control/runtime.go |
本地/转发双路径的 Runtime.MarkNodeRemoved |
runtime.go |
pkg/clusterv2/control/transport.go |
removed 写的 transport 处理器分发 | transport.go |
pkg/clusterv2/control/*_test.go |
codec、运行时转发、处理器分发验证 | codec_test.go、runtime_integration_test.go |
pkg/clusterv2/node_management.go |
暴露根级 Node.MarkNodeRemoved |
node_management.go |
pkg/clusterv2/node_management_test.go |
根节点委托与 foreground 检查验证 | node_management_test.go |
三个任务(Task 1/2/3)分别对应上表中的三层。以下按任务顺序展开:先讲清每层“要做什么、验证什么”,再用当前仓库源码印证实际实现。
四、Task 1:Controller 运行时状态机——leaving → removed
4.1 请求与结果模型
计划要求新增的请求/结果结构与其约束完全对齐 Stage 4 的 MarkNodeLeaving 形态:
// MarkNodeRemovedRequest identifies a leaving node that passed external drain safety.
type MarkNodeRemovedRequest struct {
// NodeID is the stable node identity to tombstone.
NodeID uint64
}
// MarkNodeRemovedResult describes the node record after the transition.
type MarkNodeRemovedResult struct {
// Changed reports whether the request changed ControllerV2 state.
Changed bool
// Node is the durable node record after the request.
Node Node
// Revision is the observed ControllerV2 state revision after the write.
Revision uint64
}
MarkNodeRemoved 的运行时流程要求(计划原文):
- 响应
ctxErr(ctx); - 运行时/Raft 不可用时返回
ErrNotStarted; - 读取
LocalState; - 使用
buildMarkNodeRemoved计算目标节点记录; - 以带
ExpectedRevision的command.KindUpsertNode提案提交; - 调用
publishFromState发布状态变更; - 重读
LocalState,返回最终持久化节点与 revision。
buildMarkNodeRemoved 的状态机规则是安全性的核心:
NodeID == 0→ 描述性错误;- 目标是 controller voter →
ErrNodeLifecycleConflict; - 已是
removed→ 幂等返回 unchanged; - 非
leaving(含active、joining)→ErrNodeLifecycleConflict; JoinState置为NodeJoinStateRemoved,Status置为NodeStatusDown;- 节点不存在 →
ErrNodeLifecycleNotFound。
4.2 失败先行(RED)→ 实现(GREEN)的测试
计划 Task 1 Step 1 要求在 runtime_test.go 追加四个失败测试,其中主路径测试为:
func TestRuntimeMarkNodeRemovedTurnsLeavingNodeRemoved(t *testing.T) {
runtime := startSingleVoterRuntime(t, "cluster-mark-removed")
joinAndActivateNode(t, runtime, 4, "n4")
if _, err := runtime.MarkNodeLeaving(context.Background(), MarkNodeLeavingRequest{NodeID: 4}); err != nil {
t.Fatalf("MarkNodeLeaving() error = %v", err)
}
result, err := runtime.MarkNodeRemoved(context.Background(), MarkNodeRemovedRequest{NodeID: 4})
if err != nil {
t.Fatalf("MarkNodeRemoved() error = %v", err)
}
if !result.Changed || result.Node.JoinState != NodeJoinStateRemoved || result.Node.Status != NodeStatusDown {
t.Fatalf("MarkNodeRemoved() = %#v, want changed removed down node", result)
}
second, err := runtime.MarkNodeRemoved(context.Background(), MarkNodeRemovedRequest{NodeID: 4})
if err != nil {
t.Fatalf("MarkNodeRemoved() second error = %v", err)
}
if second.Changed || second.Revision != result.Revision || second.Node.JoinState != NodeJoinStateRemoved {
t.Fatalf("MarkNodeRemoved() second = %#v, want idempotent removed node", second)
}
}
三个拒绝用例分别断言:对 active 节点调用返回 ErrNodeLifecycleConflict、对 controller voter(NodeID: 1)返回 ErrNodeLifecycleConflict、对不存在的节点(NodeID: 99)返回 ErrNodeLifecycleNotFound。RED 步骤为:
GOWORK=off go test ./pkg/controllerv2 -run 'TestRuntimeMarkNodeRemoved' -count=1
# Expected: FAIL because `MarkNodeRemoved` is not defined.
实现完成后 GREEN 步骤回归 leaving + removed 两组测试:
GOWORK=off go test ./pkg/controllerv2 -run 'TestRuntimeMarkNodeRemoved|TestRuntimeMarkNodeLeaving' -count=1
4.3 当前源码印证:状态机与提交路径
当前仓库 runtime_node_lifecycle.go 中,MarkNodeRemoved 完整实现了计划的六步流程:
// MarkNodeRemoved marks an already-drained leaving data node as a removed tombstone.
func (r *Runtime) MarkNodeRemoved(ctx context.Context, req MarkNodeRemovedRequest) (MarkNodeRemovedResult, error) {
if err := ctxErr(ctx); err != nil {
return MarkNodeRemovedResult{}, err
}
service := r.raftService()
if service == nil {
return MarkNodeRemovedResult{}, ErrNotStarted
}
st, err := r.LocalState(ctx)
if err != nil {
return MarkNodeRemovedResult{}, err
}
node, changed, err := buildMarkNodeRemoved(st, req)
if err != nil {
return MarkNodeRemovedResult{}, err
}
if !changed {
return MarkNodeRemovedResult{Changed: false, Node: node, Revision: st.Revision}, nil
}
if req.ExpectedRevision != 0 && st.Revision != req.ExpectedRevision {
return MarkNodeRemovedResult{}, ErrExpectedRevisionMismatch
}
expectedRevision := st.Revision
proposal, err := service.ProposeResult(ctx, command.Command{
Kind: command.KindUpsertNode,
IssuedAt: r.cfg.Now().UTC(),
ExpectedRevision: &expectedRevision,
Node: &node,
})
if err != nil {
return MarkNodeRemovedResult{}, err
}
if err := r.publishFromState(ctx); err != nil {
return MarkNodeRemovedResult{}, err
}
updated, err := r.LocalState(ctx)
if err != nil {
return MarkNodeRemovedResult{}, err
}
finalNode, ok := findLifecycleNode(updated, req.NodeID)
if !ok {
return MarkNodeRemovedResult{}, fmt.Errorf("controller: node %d not found after removed proposal", req.NodeID)
}
return MarkNodeRemovedResult{Changed: proposal.Changed, Node: finalNode, Revision: updated.Revision}, nil
}
与 MarkNodeLeaving 逐行对照可以看出:两者共享“读状态 → 构建 → 乐观提案 → 发布 → 重读”的同一提交骨架,removed 路径只多了一个 revision 检查。而 buildMarkNodeRemoved 实现了计划要求的全部六条状态机规则:
func buildMarkNodeRemoved(st ClusterState, req MarkNodeRemovedRequest) (Node, bool, error) {
if req.NodeID == 0 {
return Node{}, false, fmt.Errorf("controller: mark node removed requires node id")
}
for _, existing := range st.Nodes {
if existing.NodeID != req.NodeID {
continue
}
if existing.HasRole(NodeRoleControllerVoter) {
return Node{}, false, fmt.Errorf("%w: controller voter %d cannot be marked removed", ErrNodeLifecycleConflict, req.NodeID)
}
if existing.JoinState == NodeJoinStateRemoved {
return existing, false, nil
}
if existing.JoinState != NodeJoinStateLeaving {
return Node{}, false, fmt.Errorf("%w: node %d is %s", ErrNodeLifecycleConflict, req.NodeID, existing.JoinState)
}
next := existing
next.JoinState = NodeJoinStateRemoved
next.Status = NodeStatusDown
return next, true, nil
}
return Node{}, false, fmt.Errorf("%w: node %d", ErrNodeLifecycleNotFound, req.NodeID)
}
注意幂等分支(JoinState == NodeJoinStateRemoved 时提前返回 unchanged)位于 revision 检查之前——这意味着重复移除不会消耗一次 Raft 提案,也不会触发 ErrExpectedRevisionMismatch。
实现相对计划的增量演进有两点值得注意:
ExpectedRevisionfencing:计划版本只有NodeID uint64;当前实现的请求结构增加了ExpectedRevision字段,注释说明其用途是“把 remove 写栅栏到安全检查所使用的那个控制 revision”。这与 Stage 5 索引中“removed的写必须停留在 fail-closed 证据之后”、设计文档中“所有存活的 or suspect 节点都必须已应用目标节点进入 leaving 时的控制 revision”的要求呼应——manager 层在做安全检查时读到的StateRevision会一路透传到这里,作为乐观并发控制(OCC)的栅栏。- gofail 故障注入钩子:提交后重读之前留有
wkMarkNodeRemovedPostCommitFault注释标记(见 gofail_markers_test.go),为 Stage 8 的缩容故障注入测试预留了注入点,说明该路径被设计为可以被混沌测试反复演练的边界。
对应测试也在当前仓库可验证(runtime_integration_test.go):TestRuntimeMarkNodeRemovedTurnsLeavingNodeRemoved、TestRuntimeMarkNodeRemovedRejectsActiveNode、TestRuntimeMarkNodeRemovedRejectsControllerVoter、TestRuntimeMarkNodeRemovedRejectsMissingNode,以及针对 fencing 的两个补充用例 TestRuntimeMarkNodeRemovedRejectsStaleExpectedRevision、TestRuntimeMarkNodeRemovedAllowsStaleExpectedRevisionWhenAlreadyRemoved——后者正是 4.3 节中“幂等路径先于 revision 检查”这一顺序的测试证据。
五、Task 2:clusterv2 control 转发层——DTO、线格式与 Leader 转发
5.1 control DTO 与转换
计划要求 control 包新增与 Controller 侧同形的 DTO,并加上 wire JSON 标签:
// MarkNodeRemovedRequest identifies a leaving node that should become a removed tombstone.
type MarkNodeRemovedRequest struct {
// NodeID is the stable node identity to mark removed.
NodeID uint64 `json:"node_id"`
}
// MarkNodeRemovedResult describes the removed node record.
type MarkNodeRemovedResult struct {
// Changed reports whether control state changed.
Changed bool `json:"changed"`
// Node is the durable node record after the request.
Node Node `json:"node"`
// Revision is the observed control-state revision.
Revision uint64 `json:"revision"`
}
当前实现(node_lifecycle.go)在计划基础上扩展了 fencing 字段,并提供成对的转换辅助函数:
// MarkNodeRemovedRequest identifies a leaving node that should become a removed tombstone.
type MarkNodeRemovedRequest struct {
// NodeID is the stable node identity to mark removed.
NodeID uint64 `json:"node_id"`
// StateRevision fences the remove write to the safety-check control revision.
StateRevision uint64 `json:"state_revision,omitempty"`
}
func controllerMarkNodeRemovedRequest(req MarkNodeRemovedRequest) controller.MarkNodeRemovedRequest {
return controller.MarkNodeRemovedRequest{NodeID: req.NodeID, ExpectedRevision: req.StateRevision}
}
func markNodeRemovedResultFromController(result controller.MarkNodeRemovedResult) MarkNodeRemovedResult {
return MarkNodeRemovedResult{
Changed: result.Changed,
Node: controlNodeFromControllerNode(result.Node),
Revision: result.Revision,
}
}
可以看到 control 层用 StateRevision(wire 语义名)承载 Controller 层的 ExpectedRevision(执行语义名),语义不变但各自表达本层职责:control 层关心“安全报告基于哪个 revision”,Controller 层关心“提案栅栏在哪个 revision”。
5.2 线格式:mark_node_removed 动作与 snake_case 负载
control 写采用“一个通用信封 + 按 Action 选择的负载分支”的编解码设计。计划 Task 2 Step 3 要求新增 ControlWriteActionMarkNodeRemoved = "mark_node_removed"、扩展请求/响应 wire 结构、并在 SubmitControlWrite 中分发。当前 codec.go 的实现:
const (
// ...
// ControlWriteActionMarkNodeLeaving submits a node leaving intent.
ControlWriteActionMarkNodeLeaving ControlWriteAction = "mark_node_leaving"
// ControlWriteActionMarkNodeRemoved submits a node removed intent.
ControlWriteActionMarkNodeRemoved ControlWriteAction = "mark_node_removed"
// ...
)
请求信封只在 Action 选中的分支上序列化负载(MarshalJSON 内 case ControlWriteActionMarkNodeRemoved: wire.MarkNodeRemoved = &req.MarkNodeRemoved),响应信封同理。wire 键全部使用 snake_case(node_id、state_revision、changed、node、revision),而不是 Go 字段名——这是计划中明确要求的断言点。
5.3 分发、转发与测试断言
计划的 Task 2 测试要求(Step 1)包含四条断言,全部可在当前仓库测试中核对:
- JSON 使用
mark_node_removed而非 Go 字段名:codec_test.go 的TestEncodeControlWriteMarkNodeRemovedUsesSnakeCaseJSON,以MarkNodeRemovedRequest{NodeID: 4, StateRevision: 9}构造请求并校验 wire 键; - follower 转发
Runtime.MarkNodeRemoved:runtime_integration_test.go 的TestRuntimeMarkNodeRemovedReturnsControlWriteAfterForward,在 3 节点本地网络上验证 follower 节点提交后集群收敛到removed; NewControlWriteHandler调用ControlWriteApplier.MarkNodeRemoved:control_write.go 中case ControlWriteActionMarkNodeRemoved:分支调用applier.MarkNodeRemoved(ctx, req.MarkNodeRemoved),ControlWriteApplier接口同时声明了该方法,配套测试TestNewControlWriteHandlerMarkNodeRemovedCallsApplier(见 control_write_test.go);ProbePropose未启动路径对 removed 写返回cv2.ErrNotStarted:同样在 control_write 测试组中覆盖。
运行时侧的 leader 转发模式(runtime.go):
// MarkNodeRemoved submits a node removed intent.
func (r *Runtime) MarkNodeRemoved(ctx context.Context, req MarkNodeRemovedRequest) (MarkNodeRemovedResult, error) {
if err := ctxErr(ctx); err != nil {
return MarkNodeRemovedResult{}, err
}
if r == nil || r.backend == nil {
return MarkNodeRemovedResult{}, controller.ErrNotStarted
}
if r.canForwardControlWriteToLeader() {
resp, err := r.forwardControlWrite(ctx, ControlWriteRequest{
Action: ControlWriteActionMarkNodeRemoved,
MarkNodeRemoved: req,
})
if err != nil {
return MarkNodeRemovedResult{}, err
}
return resp.MarkNodeRemoved, nil
}
result, err := r.backend.MarkNodeRemoved(ctx, controllerMarkNodeRemovedRequest(req))
if shouldForwardControlWrite(err) {
resp, err := r.forwardControlWriteAfterError(ctx, ControlWriteRequest{
Action: ControlWriteActionMarkNodeRemoved,
MarkNodeRemoved: req,
}, err)
if err != nil {
return MarkNodeRemovedResult{}, err
}
return resp.MarkNodeRemoved, nil
}
if err != nil {
return MarkNodeRemovedResult{}, err
}
return markNodeRemovedResultFromController(result), nil
}
这正是计划 Step 4 所描述的“与 Runtime.MarkNodeLeaving 相同的 leader 转发模式”:本地是 leader 时走 backend(Controller 运行时)直提;canForwardControlWriteToLeader() 判定为非 leader 时先转发;本地写返回 ErrNotLeader/ErrNotStarted(shouldForwardControlWrite)时再走一次错误后的转发兜底。这一层保证了任意节点上的调用方都能以同一入口完成提交,而 Raft 提案永远只由 leader 产生。
Task 2 的验证命令(计划原文,v2 路径):
GOWORK=off go test ./pkg/clusterv2/control \
-run 'TestRuntimeMarkNodeRemoved|TestControlWrite.*MarkNodeRemoved|TestEncodeControlWrite.*MarkNodeRemoved|TestNewControlWriteHandler.*MarkNodeRemoved' -count=1
六、Task 3:根级 Node 门面——委托与 foreground 检查
计划 Task 3 要求把 MarkNodeRemoved 暴露为根级 Node 的方法,使上层(internalv2 管理 usecase)不必直接导入 Controller 内部实现。计划的失败测试与实现骨架:
func TestNodeMarkNodeRemovedDelegatesToControl(t *testing.T) {
controller := &recordingMarkNodeRemovedController{
StaticController: control.NewStaticController(control.Snapshot{}),
result: control.MarkNodeRemovedResult{
Changed: true,
Node: control.Node{NodeID: 4, JoinState: control.NodeJoinStateRemoved, Status: control.NodeDown},
Revision: 22,
},
}
node := &Node{foreground: newForegroundNode(foregroundNodeOptions{controller: controller})}
got, err := node.MarkNodeRemoved(context.Background(), control.MarkNodeRemovedRequest{NodeID: 4})
if err != nil {
t.Fatalf("MarkNodeRemoved() error = %v", err)
}
if !got.Changed || got.Node.JoinState != control.NodeJoinStateRemoved || controller.requests[0].NodeID != 4 {
t.Fatalf("MarkNodeRemoved() = %#v requests=%#v, want removed node 4", got, controller.requests)
}
}
实现要求先过 checkForeground(或等价的 foreground 前置检查)、在 controller 不可用或类型断言失败时返回 ErrNotStarted,然后委托给写入器:
// MarkNodeRemoved submits a Controller-backed node removed intent.
func (n *Node) MarkNodeRemoved(ctx context.Context, req control.MarkNodeRemovedRequest) (control.MarkNodeRemovedResult, error) {
if err := n.checkForeground(ctx); err != nil {
return control.MarkNodeRemovedResult{}, err
}
foreground := n.foreground
if foreground == nil || foreground.controller == nil {
return control.MarkNodeRemovedResult{}, ErrNotStarted
}
writer, ok := foreground.controller.(interface {
MarkNodeRemoved(context.Context, control.MarkNodeRemovedRequest) (control.MarkNodeRemovedResult, error)
})
if !ok {
return control.MarkNodeRemovedResult{}, ErrNotStarted
}
return writer.MarkNodeRemoved(ctx, req)
}
当前仓库 node_management.go 的实现保留了同一委托契约(foreground 前置检查 + 动态接口断言 + 未就绪返回 ErrNotStarted),并补充了 ctxErr 响应与 normalizeControlWriteError 错误归一化;node_management_test.go 中 TestNodeMarkNodeRemovedDelegatesToControl 与 TestNodeMarkNodeRemovedRequiresForegroundNode 分别验证委托成功路径与 foreground 缺失时的 fail-closed 行为。从源码结构看,这个“窄门面 + 类型断言”模式让 Node 只依赖 control 包公开接口,static controller(只读快照控制器)由于不满足写入器接口会稳定地落到 ErrNotStarted,从而在门面层就拒绝了读模型上的写操作。
七、验证门、提交与退出门
7.1 Stage 5A 完整验证(Task 3 Step 3)
GOWORK=off go test ./pkg/controllerv2 ./pkg/clusterv2/control ./pkg/clusterv2 \
-run 'TestRuntimeMarkNodeRemoved|TestNodeMarkNodeRemoved|TestControlWrite.*MarkNodeRemoved|TestEncodeControlWrite.*MarkNodeRemoved|TestNewControlWriteHandler.*MarkNodeRemoved' \
-count=1
git diff --check
7.2 提交(Task 3 Step 4)
git add pkg/controllerv2 pkg/clusterv2/control pkg/clusterv2/node_management.go pkg/clusterv2/node_management_test.go
git commit -m "feat: mark drained nodes removed"
7.3 退出门(Exit Gate)
GOWORK=off go test ./pkg/controllerv2 ./pkg/clusterv2/control ./pkg/clusterv2 -count=1
git diff --check
rg -n "MarkNodeRemoved|mark_node_removed|NodeJoinStateRemoved" pkg/controllerv2 pkg/clusterv2
退出标准有两条:所有命令通过;并且此时 manager HTTP remove 路由尚不存在。最后一条是 5A 边界性的最终确认——removed 写能力已经落在控制面内部,但外部入口被有意保留给 Stage 5D 的安全门去接。当前仓库的 rg 结果与此一致:除上述 pkg 层实现外,MarkNodeRemoved 还出现在 internalv2 管理 usecase(internal/usecase/management 的 scale_in.go)与 manager 路由(internal/access/manager 的 scale_in_remove.go)中——这些正是后续 5D 子阶段在 safe-to-remove 报告之上建立的显式入口,属于 5A 之后的演进,不在本阶段范围内。
八、纵深解读:墓碑、幂等与 fencing 为何是 fail-closed
把三层实现放在一起看,Stage 5A 用最小的代码面完成了三个安全性目标:
- 状态机封闭:
buildMarkNodeRemoved只接受leaving → removed这一条迁移边,active/joining/不存在的节点各自得到可errors.Is判定的专用错误(ErrNodeLifecycleConflict/ErrNodeLifecycleNotFound)。controller voter 被显式排除,这与 Stage 5 索引“不动态增删 Controller Raft voter”的规则在状态机层面强制落实——即使上层误调,Controller 层也会拒绝。 - 幂等且无副作用:重复调用在
!changed分支提前返回,不消耗 Raft 提案、revision 不变。对自动化运维工具而言,remove 操作可以安全重试;对 fencing 而言,幂等路径不触发ErrExpectedRevisionMismatch(由TestRuntimeMarkNodeRemovedAllowsStaleExpectedRevisionWhenAlreadyRemoved固化该行为)。 - revision fencing 打通安全检查与最终写:control 层 DTO 的
StateRevision字段把“安全报告基于哪个控制 revision”的信息从 manager 安全检查一路带到 Controller 层的乐观提案栅栏。设计文档第 11 节要求“最终MarkNodeRemoved必须是显式的,且只允许在safe_to_remove=true之后”,而 5A 提供的正是这条链路上最后一段可被栅栏约束的写原语;Stage 5D 的 manager 路由则负责在safe_to_remove为 false 时根本不调用它。
此外,墓碑语义(removed 而非物理删除)与 discovery 行为联动:设计文档第 9 节指出,节点进入 removed 后,现有排空安全完成时 discovery 应停止解析该节点;节点身份在 cluster-state.json 中保留,防止旧 node_id 被复用。
九、适用前提与延伸阅读
- 适用前提:本文描述的是当前仓库
main分支上已经落地的控制面实现;计划文档中的包路径(pkg/controllerv2、pkg/clusterv2)对应 v2 命名时期,阅读计划原文时请按第三节的映射表对照当前路径。GOWORK=off前缀用于隔离 workspace,保证测试只编译本模块。 - 阅读顺序建议:
- 总设计:dynamic-node-lifecycle-design(状态机、fail-closed 安全清单、Stage 划分);
- Stage 5 索引:stage5 plan index(子阶段顺序与跨子阶段规则);
- 本阶段计划:stage5a-removed-lifecycle;
- 实现与测试:runtime_node_lifecycle.go、codec.go、control_write.go、runtime.go、node_management.go,以及对应测试 runtime_integration_test.go、codec_test.go、runtime_integration_test.go、node_management_test.go。
- 后续子阶段:Stage 5B(Channel 排空清单)、5C(gateway drain 模式)、5D(safe remove 路由)、5E(移除冒烟与 FLOW 文档)在 internalv2-dynamic-node 主索引中按序串联,共同把 5A 的底层写原语包装为对操作员暴露的完整缩容流程。