WuKongIM 节点下线终局:Stage 5A removed 墓碑写路径的实现计划与落地验证

原创2026-10-15 15:10:031,660 阅读
文章标签:即时通讯后端

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)要求两项前置检查:

  1. Stage 4 已合并进本地 main;
  2. 既有 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 的状态机规则是安全性的核心:

  1. NodeID == 0 → 描述性错误;
  2. 目标是 controller voter → ErrNodeLifecycleConflict;
  3. 已是 removed → 幂等返回 unchanged;
  4. 非 leaving(含 active、joining)→ ErrNodeLifecycleConflict;
  5. JoinState 置为 NodeJoinStateRemoved,Status 置为 NodeStatusDown;
  6. 节点不存在 → 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。

实现相对计划的增量演进有两点值得注意:

  1. ExpectedRevision fencing:计划版本只有 NodeID uint64;当前实现的请求结构增加了 ExpectedRevision 字段,注释说明其用途是“把 remove 写栅栏到安全检查所使用的那个控制 revision”。这与 Stage 5 索引中“removed 的写必须停留在 fail-closed 证据之后”、设计文档中“所有存活的 or suspect 节点都必须已应用目标节点进入 leaving 时的控制 revision”的要求呼应——manager 层在做安全检查时读到的 StateRevision 会一路透传到这里,作为乐观并发控制(OCC)的栅栏。
  2. 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 用最小的代码面完成了三个安全性目标:

  1. 状态机封闭:buildMarkNodeRemoved 只接受 leaving → removed 这一条迁移边,active/joining/不存在的节点各自得到可 errors.Is 判定的专用错误(ErrNodeLifecycleConflict / ErrNodeLifecycleNotFound)。controller voter 被显式排除,这与 Stage 5 索引“不动态增删 Controller Raft voter”的规则在状态机层面强制落实——即使上层误调,Controller 层也会拒绝。
  2. 幂等且无副作用:重复调用在 !changed 分支提前返回,不消耗 Raft 提案、revision 不变。对自动化运维工具而言,remove 操作可以安全重试;对 fencing 而言,幂等路径不触发 ErrExpectedRevisionMismatch(由 TestRuntimeMarkNodeRemovedAllowsStaleExpectedRevisionWhenAlreadyRemoved 固化该行为)。
  3. 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 被复用。

九、适用前提与延伸阅读

登录后查看全文
WuKongIM