Go goroutine 泄漏剖析实战：GoKer 真实缺陷用例库与 runtime 泄漏检测机制

本文围绕 Go 源码树中的 goker 用例文档 展开：介绍这套源自 GoBench 论文的真实并发缺陷用例库如何组织、如何被 goroutine 泄漏剖析器 驱动，并深入到 runtime 的 _Gleaked 状态与 goroutineleak profile 的实现。读完后你能掌握如何用 pprof.Lookup("goroutineleak") 主动暴露泄漏的 goroutine，理解 63 个真实并发 bug 的分类学与典型交错（interleaving）模式，并能在本地复现、扩展这些用例。

一、GoKer：从 GoBench 论文到 runtime 测试语料

goker 目录 中的示例来自论文 "GoBench: A Benchmark Suite of Real-World Go Concurrency Bugs"（doi:10.1109/CGO51591.2021.9370317），由中科院计算所、新南威尔士大学等作者团队整理，涉及 CockroachDB、etcd、gRPC-Go、Kubernetes、Moby、Istio、Hugo、Knative Serving、Syncthing 等真实项目的 goroutine 泄漏缺陷。目录中的每个案例程序都带有 MIT 许可头（见 goker/LICENSE）。

README 中明确了这批示例为适配 goroutine leak profiler 所做的改造方式，这些改造策略本身就是很好的"泄漏可复现化"方法论：

• 从单元测试中剥离出独立程序：有 bug 的片段被移出原单元测试，变成可独立执行的应用（每个案例一个 main 注册函数）；
• 同一程序内并发多副本：同一个有 bug 的程序可能以多份拷贝同时运行，以增加调度交错（interleaving）的覆盖；
• 等待 + 主动采集：主程序设置一段等待期（通常为 1ms），然后发起一次 goroutine 泄漏 profile 请求；
• 注入 runtime.Gosched()：为了让有 bug 的交错更可靠地出现，会在关键路径注入调度让出；
• 缩短 time.Sleep 的等待时间：降低整体测试耗时；
• 去除数据竞争：数据竞争会导致 flaky 测试失败，而这里只关心泄漏本身，因此示例中移除了竞争；
• 结果校验策略：分析生成的泄漏 profile，确认"不该发生的泄漏没发生、该发生的泄漏发生了"。如果某个泄漏本身是 flaky 的，expected leak 列表的作用就退化为"只防止出现意外的泄漏"。

从源码结构看，每个案例文件头部注释还记录了原始项目的缺陷编号、出问题的版本 commit、修复 commit 以及 flaky 概率（如 cockroach10214.go 标注 Flaky: 3/100），这些元数据是判断用例可信度的重要依据。

二、63 个真实缺陷的分类学总表

README 按项目逐个记录了每个泄漏的 Bug ID、上游 PR/patch、类型（Type）与子类型（Sub-type）。泄漏根因分为三大类：

• Resource：锁相关的死锁/泄漏。子类型包括 AB-BA（顺序死锁）、Double Locking（同一锁被递归获取）、RWR Deadlock（读写锁上先 RLock 再 Lock，或写锁优先级导致的递归读锁死锁）、Missing Unlock（某执行路径漏解锁）；
• Communication：通道与条件变量。子类型包括 Channel（无人接收/发送、select 选错分支）、Channel & Context（context 取消导致某条路径不排空通道）、Condition Variable（Wait 没有对应的 Signal/Broadcast）；
• Mixed：锁与通道/WaitGroup 混合。子类型包括 Channel & Lock、Channel & WaitGroup、Misuse WaitGroup（Wait 的调用时机与 Done 次数不匹配）。

完整清单如下（源码文件均位于 goker 目录，与文档条目一一对应）：

Bug ID	Type	Sub-type	源码文件
Cockroach/10214	Resource	AB-BA leak	cockroach10214.go
Cockroach/1055	Mixed	Channel & WaitGroup	cockroach1055.go
Cockroach/10790	Communication	Channel & Context	cockroach10790.go
Cockroach/13197	Communication	Channel & Context	cockroach13197.go
Cockroach/13755	Communication	Channel & Context	cockroach13755.go
Cockroach/1462	Mixed	Channel & WaitGroup	cockroach1462.go
Cockroach/16167	Resource	Double Locking	cockroach16167.go
Cockroach/18101	Resource	Double Locking	cockroach18101.go
Cockroach/2448	Communication	Channel	cockroach2448.go
Cockroach/24808	Communication	Channel	cockroach24808.go
Cockroach/25456	Communication	Channel	cockroach25456.go
Cockroach/35073	Communication	Channel	cockroach35073.go
Cockroach/35931	Communication	Channel	cockroach35931.go
Cockroach/3710	Resource	RWR Deadlock	cockroach3710.go
Cockroach/584	Resource	Double Locking	cockroach584.go
Cockroach/6181	Resource	RWR Deadlock	cockroach6181.go
Cockroach/7504	Resource	AB-BA Deadlock	cockroach7504.go
Cockroach/9935	Resource	Double Locking	cockroach9935.go
Etcd/10492	Resource	Double locking	etcd10492.go
Etcd/5509	Resource	Double locking	etcd5509.go
Etcd/6708	Resource	Double locking	etcd6708.go
Etcd/6857	Communication	Channel	etcd6857.go
Etcd/6873	Mixed	Channel & Lock	etcd6873.go
Etcd/7492	Mixed	Channel & Lock	etcd7492.go
Etcd/7902	Mixed	Channel & Lock	etcd7902.go
Grpc/1275	Communication	Channel	grpc1275.go
Grpc/1424	Communication	Channel	grpc1424.go
Grpc/1460	Mixed	Channel & Lock	grpc1460.go
Grpc/3017	Resource	Missing unlock	grpc3017.go
Grpc/660	Communication	Channel	grpc660.go
Grpc/795	Resource	Double locking	grpc795.go
Grpc/862	Communication	Channel & Context	grpc862.go
Hugo/3251	Resource	RWR deadlock	hugo3251.go
Hugo/5379	Resource	Double locking	hugo5379.go
Istio/16224	Mixed	Channel & Lock	istio16224.go
Istio/17860	Communication	Channel	istio17860.go
Istio/18454	Communication	Channel & Context	istio18454.go
Kubernetes/10182	Mixed	Channel & Lock	kubernetes10182.go
Kubernetes/11298	Communication	Channel & Condition Variable	kubernetes11298.go
Kubernetes/13135	Resource	AB-BA deadlock	kubernetes13135.go
Kubernetes/1321	Mixed	Channel & Lock	kubernetes1321.go
Kubernetes/25331	Communication	Channel & Context	kubernetes25331.go
Kubernetes/26980	Mixed	Channel & Lock	kubernetes26980.go
Kubernetes/30872	Resource	AB-BA deadlock	kubernetes30872.go
Kubernetes/38669	Communication	Channel	kubernetes38669.go
Kubernetes/5316	Communication	Channel	kubernetes5316.go
Kubernetes/58107	Resource	RWR deadlock	kubernetes58107.go
Kubernetes/62464	Resource	RWR deadlock	kubernetes62464.go
Kubernetes/6632	Mixed	Channel & Lock	kubernetes6632.go
Kubernetes/70277	Communication	Channel	kubernetes70277.go
Moby/17176	Resource	Double locking	moby17176.go
Moby/21233	Communication	Channel	moby21233.go
Moby/25384	Mixed	Misuse WaitGroup	moby25384.go
Moby/27782	Communication	Channel & Condition Variable	moby27782.go
Moby/28462	Mixed	Channel & Lock	moby28462.go
Moby/30408	Communication	Condition Variable	moby30408.go
Moby/33781	Communication	Channel & Context	moby33781.go
Moby/36114	Resource	Double locking	moby36114.go
Moby/4951	Resource	AB-BA deadlock	moby4951.go
Moby/7559	Resource	Double locking	moby7559.go
Serving/2137	Mixed	Channel & Lock	serving2137.go
Syncthing/4829	Resource	Double locking	syncthing4829.go
Syncthing/5795	Communication	Channel	syncthing5795.go

三、典型缺陷的交错分析（Excerpt from README 执行轨迹）

README 的核心价值在于为每个缺陷给出了"示例执行"——多 goroutine 的交错时序图。以下精选四类代表性模式。

3.1 AB-BA 顺序死锁：Cockroach/10214

两个 goroutine 以相反顺序获取 coalescedMu（L1）与 raftMu（L2）：

G1                                      G2
------------------------------------------------------------------------------------
s.sendQueuedHeartbeats()                .
s.coalescedMu.Lock() [L1]               .
s.sendQueuedHeartbeatsToNode()          .
s.mu.replicas[0].reportUnreachable()    .
s.mu.replicas[0].raftMu.Lock() [L2]     .
.                                       s.mu.replicas[0].tick()
.                                       s.mu.replicas[0].raftMu.Lock() [L2]
.                                       s.mu.replicas[0].tickRaftMuLocked()
.                                       s.mu.replicas[0].mu.Lock() [L3]
.                                       s.mu.replicas[0].maybeQuiesceLocked()
.                                       s.mu.replicas[0].maybeCoalesceHeartbeat()
.                                       s.coalescedMu.Lock() [L1]
--------------------------------G1,G2 leak------------------------------------------

对应修复思路（README 原文）：重构 sendQueuedHeartbeats()，让它在获取 raftMu 之前先释放 coalescedMu。对照 cockroach10214.go 中的 sendQueuedHeartbeats/maybeCoalesceHeartbeat，可以看到示例精确保留了"L1 持有期间获取 L2 / L2 持有期间获取 L1"的交错结构。

3.2 漏解锁：Cockroach/584

G1
---------------------------
g.bootstrap()
g.mu.Lock() [L1]
if g.closed { ==> break
g.manage()
g.mu.Lock() [L1]
----------G1 leaks---------

缺陷是循环中 break 前缺少 mu.Unlock()。cockroach584.go 的 bootstrap() 中保留了 // Missing g.mu.Unlock 注释标记的 bug 路径：持锁 break 后，manage() 再次 Lock() 即永久卡死。

3.3 RWR 递归读锁：Cockroach/3710 与 Kubernetes/58107

sync.RWMutex 不支持同一 goroutine 递归 RLock。Cockroach/3710 的缺陷链条是一次调用链内两次 s.mu.RLock()：

G1                                      G2
------------------------------------------------------------
store.ForceRaftLogScanAndProcess()      .
s.mu.RLock()                            .
s.raftLogQueue.MaybeAdd()               .
bq.impl.shouldQueue()                   .
getTruncatableIndexes()                 .
r.store.RaftStatus()                    .
.                                       store.processRaft()
.                                       s.mu.Lock()
s.mu.RLock()
----------------------G1,G2 leak-----------------------------

Kubernetes/58107 则揭示了更隐蔽的写锁优先级问题（README 原文要点）：两个队列受同一读写锁 rq.workerLock 保护，取元素前先 RLock()，空队列时 cond.Wait()；另有 goroutine D 周期性 Lock()（写锁）。当队列 1 为空、部分 goroutine 持有 RLock 阻塞在 cond.Wait() 时，goroutine D 的写锁请求阻塞，而处理队列 2 的 goroutine 因"写锁优先"无法获得 RLock，三者互锁：

G3                      G4                      G5
--------------------------------------------------------------------
.                       .                       Sync()
rq.workerLock.RLock()   .                       .
q.cond.Wait()           .                       .
.                       .                       rq.workerLock.Lock()
.                       rq.workerLock.RLock()   .
.                       q.cond.L.Lock()
-----------------------------G3,G4,G5 leak-----------------------------

修复方向：从队列取数据时不持有 RLock，使 cond.Wait() 阻塞期间不占用读锁。这类缺陷的教训是：RLock + Cond.Wait 的组合在写锁竞争下天然不安全。

3.4 持锁 + 无对端通道操作：Etcd/6873

G1                      G2                  G3
--------------------------------------------------------------
newWatchBroadcasts()    .                   .
wbs.update()            .                   .
wbs.updatec <-          .                   .
return                  .                   .
.                       <-wbs.updatec       .
.                       wbs.coalesce()      .
.                       .                   wbs.stop()
.                       .                   wbs.mu.Lock()
.                       .                   close(wbs.updatec)
.                       .                   <-wbs.donec
.                       wbs.mu.Lock()       .
---------------------G2,G3 leak--------------------------------

G2 持有 mu.Lock() 之后阻塞在 updatec 的收发上，而能解除该阻塞的 G3 又需要获取同一把锁——锁与通道耦合的经典 Mixed 型泄漏。

此外，README 还详细记录了 Channel & Context 型（如 Cockroach/13197：(*Tx).awaitDone() 只等 context.Done()，context 永不取消则永久阻塞）、WaitGroup 误用（Moby/25384：n > 1 时每次迭代都调用 group.Wait()，但每轮只有 1 次 Done()）、Condition Variable 无 Signal（Moby/30408）等模式，全部 63 条均按"Bug ID + Type/Sub-type + Description + Example execution"的固定结构记录，可逐条查阅 README.md。

四、案例程序如何与 goroutineleak profiler 对接

4.1 统一的注册式入口

goker/main.go 实现了极简的命令分发：每个案例文件在 init() 中调用 register("Cockroach10214", Cockroach10214) 注册入口函数，main() 从 os.Args[1] 取名字执行。程序用法即：

# 在 goker 目录下构建并运行单个案例（输出泄漏 profile 到 stdout）
go build -o goker .
./goker Cockroach10214

4.2 采集泄漏 profile 的固定套路

每个案例函数都遵循同一模板：

prof := pprof.Lookup("goroutineleak")
defer func() {
    time.Sleep(100 * time.Millisecond)   // 等待泄漏的 goroutine 卡住
    prof.WriteTo(os.Stdout, 2)           // debug=2：打印完整堆栈
}()
// ... 启动多份并发有 bug 的逻辑 ...

例如 cockroach584.go 通过 defer 保证先让子 goroutine 运行（runtime.Gosched() 让出 yieldCount=10 次）再写 profile。prof.WriteTo(w, debug) 的 debug=2 会打印泄漏 goroutine 的完整调用栈，输出中每个泄漏 goroutine 的头部带 (leaked) 标记，例如：

goroutine 1 [chan receive (leaked)]:
main.leaked()
    ./testdata/testgoroutineleakprofile/foo.go:37 +0x100
created by main.main()
    ./testdata/testgoroutineleakprofile/main.go:10 +0x20

4.3 runtime 侧的实现：_Gleaked 状态与 profile 注册

从源码结构看，这套机制涉及四处关键实现：

1. goroutine 状态：runtime2.go 定义了 _Gleaked（状态值 10，注释为"被 GC 捕获的泄漏 goroutine"）及其扫描态 _Gscanleaked = _Gscan + _Gleaked；
2. GC 标记阶段判定：mgc.go 在扫描等待中的 goroutine 时，若判定其不可达/无正常唤醒路径，执行 casgstatus(gp, _Gwaiting, _Gleaked)（约 L1300），扫描结束后再 casgstatus(gp0, _Gleaked, _Gwaiting) 还原——也就是说"泄漏"是 GC 标记期间的瞬时观测状态，不改变 goroutine 的长期状态；
3. profile 注册：pprof/pprof.go 将 goroutineleak 注册为 profile 类型（name: "goroutineleak"，计数来自 proc.go 中的 goroutineleakcount()，即 work.goroutineLeak.count），因此 pprof.Lookup("goroutineleak")、net/http/pprof 路由及 go tool pprof 均可取用该 profile；
4. 栈回溯输出：traceback.go 在打印 goroutine 头部时，对 _Gleaked 状态追加 (leaked) 后缀，这正是测试断言所依赖的标记。

因此 goroutineleak profile 与常规 goroutine profile 的区别是：它只输出那些在 GC 扫描时被判定为泄漏的 goroutine 的堆栈，适合"程序仍在运行、只想看谁泄漏了"的场景。

五、测试驱动器：TestGoroutineLeakProfile 如何批量验证

goroutineleakprofile_test.go 是这整个语料库的执行引擎，值得逐点理解：

• 用例模型：testCase 包含 name（对应注册的命令名）、repetitions（重复次数，降低 flaky）、expectedLeaks（正则 → 是否命中的 map，要求"该泄漏必须出现"）与 flakyLeaks（正则集合，"出现不报错、不出现也不报错"）。注释特别强调：所有 flaky leak 都是 true positive（真实泄漏），只是检测因调度非确定性而不可靠；
• 构建与执行：测试程序只构建一次（buildTestProg），每个用例通过子进程执行，环境变量统一设 GODEBUG=asyncpreemptoff=1；对 simple 类微测试（如 simple.go 中的 NilRecv、ChanSend 等）额外加 GOMAXPROCS=1，把调度行为压到最可控；
• 输出解析：extractLeaks 按 "\n\ngoroutine" 切分输出，仅保留头部含 (leaked) 的段落，从头部提取 wait reason（如 [sync.Mutex.Lock]、[chan receive]），并从 created by 上方两行提取函数名，合成 函数名 + wait reason 字符串后与正则比对；
• 零容忍误报：对 expectedLeaks 与 flakyLeaks 均为空的用例（如 NoLeakGlobal），只要出现任何泄漏就立即判失败；
• GoKer 用例的筛选：注释说明 goker 列表"curated for tests that are not excessively flaky"，并剔除了冗余项。例如 Kubernetes/1321 因原始程序存在极小概率空指针竞争（会导致崩溃而非泄漏）而被注释保留"for posterity"，未纳入断言。

goker 侧的用例断言展示了泄漏签名的写法，例如 Cockroach584 期望 Cockroach584.func2(... [sync.Mutex.Lock])——即泄漏点必须落在 manage() 的 mu.Lock() 上，wait reason 与 3.2 节轨迹严格对应。

六、复现与延伸阅读

运行整个套件（在 Go 源码树中）：

cd src/runtime
go test -run TestGoroutineLeakProfile -v

注意两点适用前提：

1. 该测试依赖 goroutineleak profile，属于较新的 runtime 实验能力，请使用当前源码树对应的工具链构建测试二进制；
2. 测试开头显式跳过 mayMoreStackPreempt / mayMoreStackMove 两个 GOFLAGS 实验下的运行（issue 75729，可能存在 false negative），即这些实验开启时用例可能被跳过。

独立运行单个案例：按第 4.1 节方式构建 goker 二进制后传入案例名即可，profile 以 debug=2 打印到 stdout，可进一步用 go tool pprof 消费。

语料库的扩展方式：新增一个用例只需三步——在 goker 目录下新建 xxxN.go，头部注释记录项目/缺陷编号/版本 commit/修复 commit/Flaky 概率，init() 中注册命令名，函数体按"启动并发 bug 逻辑 → 等待 → prof.WriteTo(os.Stdout, 2)"模板编写；然后在 goroutineleakprofile_test.go 的 gokerTestCases 中以正则形式登记 expected（或 flaky）泄漏签名，并在 README.md 中按既有格式补充 Bug ID 表格、Description 与 Example execution。

同目录下还有两层配套语料，可与 goker 对照理解：simple.go（覆盖 nil chan、select、WaitGroup、Mutex/RWMutex、Cond 等每种并发原语的最小泄漏）与 commonpatterns.go、stresstests.go（来自另一篇动态分析论文的企业微服务常见泄漏模式与 GC 压力场景）。三者共同构成 runtime 泄漏剖析器从"原语级正确性"到"真实世界缺陷"的完整回归层。