🔴 故障诊断报告 — Circular Reference Leak (PID 1261)

报告编号：RCA-20260604-003
故障级别：P1（高）
报告时间：2026-06-04 02:09 UTC
报告生成 Agent：Baize (witty-diagnosis-agent)
当前状态：🟢 已恢复（进程已退出，OS 已回收泄漏内存）

一、故障概览

置信度说明

二、根因速览

根本原因：fault_circular_ref.cpp 使用 shared_ptr<Node> 构建双向链表（NodeA.next = NodeB, NodeB.prev = NodeA），形成循环引用 —— 两个 shared_ptr 的引用计数均为 1，且相互持有对方。当外部容器 clear() 后，循环引用导致两个节点的引用计数无法归零，~Node() 析构函数不被调用，200 KB × 2000 对 ≈ 400 MB 的堆内存中约 203 MB 持久泄漏（剩余部分因内部共享机制不重复计账）。

事故时间线与故障传导链路

时间                              事件                                           性质          溯源路径
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
2026-06-04 02:08:xx               fault_circular_ref 启动，PID=1261                📈 触发      [/tmp/fault_circular_ref]
  │
  ▼
2026-06-04 02:08:xx (T0+~2s)      创建 2000 节点（10 轮 × 200 节点）               🟡 分配中     [circular_ref.log]
  │                               NodeA.next = NodeB (shared_ptr)
  │                               NodeB.prev = NodeA (shared_ptr)  → 循环引用
  ▼
2026-06-04 02:08:xx (T0+~2s)      RSS 攀升至 203 MB (VmRSS=203520 kB)              🔴 峰值       [rss_trend.csv]
  │                               pmap: [anon] 200312 kB 占 98.4%
  ▼
2026-06-04 02:08:xx ~ +32s        "Root references NOT cleared -> circular refs     🔴 稳态泄漏    [circular_ref.log]
  │                                prevent destruction"
  │                               "Holding for 30s..." RSS 稳定 203 MB 不动
  ▼
2026-06-04 02:09:xx (T0+~32s)     进程退出（"Done."），RSS 归零                    🟢 已恢复     [诊断采样显示 N/A]

故障因果链

fault_circular_ref 启动
    └─► for (10 轮) { for (200 节点) { 创建 Node 对 } }
            └─► struct Node { shared_ptr<Node> next, prev; }
                    └─► NodeA.next = NodeB → ref_count(B)=1
                    └─► NodeB.prev = NodeA → ref_count(A)=1
                            └─► std::vector::clear() 触发析构
                                    └─► NodeA 析构 → 释放 next → ref_count(B) 从 1→0?
                                    └─► 但是: NodeB.prev 仍持有 NodeA → ref_count(A)=1
                                    └─► NodeB 无法析构 → NodeB.prev 不释放
                                    └─► NodeA 引用计数永不归零 → ~Node() 不被调用
                                            └─► 2000 节点的堆内存（~200 KB/对）泄漏
                                                    └─► RSS 稳定在 203 MB (98.4% 为匿名堆)
                                                            └─► 进程退出 → OS 回收 ✅

三、排查过程

3.1 初始现象

• 观测指标：PID 1261 的 VmRSS 启动后迅速升至 203 MB 并完全稳定（4 个采样点均为 203520 kB）
• 诊断脚本：bash diagnose_rss_growth.sh -p 1261 -i 2 -c 5（分支 A）+ bash diagnose_heap_profiler.sh -p 1261 -b /tmp/fault_circular_ref（分支 C3）
• 可疑特征：RSS 一次性攀升后完全不动（区别于线性泄漏），堆占 98.4%，日志明确提示循环引用

3.2 假设驱动排查

假设 C3：C++ shared_ptr 循环引用泄漏 ✅ 确认根因

🧪 假设：shared_ptr<Node> 构建双向环后引用计数无法归零，析构函数不被执行

✅ 结论：循环引用导致 ~Node() 不执行，203 MB 堆内存泄漏。

假设 C1：常规堆泄漏 ❌ 排除

假设 C4：RAII 异常路径泄漏 ❌ 排除

3.3 排查结论与逻辑树

PID 1261 VmRSS 203 MB 稳定
├─► 假设 C1: 常规堆泄漏                → ❌ 排除 (所有 new 由 shared_ptr 管理)
├─► 假设 C4: RAII 异常路径泄漏         → ❌ 排除 (正常执行，无异常)
└─► 假设 C3: 循环引用泄漏              → ✅ 确认 (源码+日志+pmap 证据)
        └─► 🎯 根因: shared_ptr 双向引用 → 引用计数永不归零 → 析构不执行

四、关键证据

五、反事实验证

三条全 ✅ → 根因确认 🟢

六、排除的替代假设

七、修复建议

应急处置

1. 无需操作：进程已正常退出，泄漏内存由 OS 回收
2. 生产环境：若发现类似 shared_ptr 构成环的应用，需定位容器/根对象引用链并手动 reset() 断开

永久修复

1. 关键修复 — 使用 weak_ptr 打破循环（推荐方案）

   cpp

   // Before (leak):
   struct Node {
       std::shared_ptr<Node> next;
       std::shared_ptr<Node> prev;  // ← 双向 shared_ptr 形成循环
   };
   
   // After (fixed):
   struct Node {
       std::shared_ptr<Node> next;
       std::weak_ptr<Node> prev;    // ← weak_ptr 打破循环，引用计数不增加
   };

   原理：weak_ptr 不增加引用计数，NodeA 析构时 next 释放使 NodeB 引用归零 → NodeB 正常析构 → prev 自动失效

2. 显式断开：在 clear() 前手动遍历容器 reset() 每个节点的 next/prev

   cpp

   for (auto &node : nodes) {
       node.next.reset();
       node.prev.reset();
   }
   nodes.clear();  // 此时所有 shared_ptr 引用归零

3. 使用 Valgrind/ASan 检测：

   bash

   # Valgrind 检测循环引用泄漏
   valgrind --tool=memcheck --leak-check=full --show-leak-kinds=all ./fault_circular_ref
   
   # AddressSanitizer 编译检测
   g++ -fsanitize=address -g -o fault_circular_ref fault_circular_ref.cpp

预防措施

1. 代码审查规则：所有 shared_ptr 双向/环形引用必须使用 weak_ptr 打断循环
2. CI 集成：
   bash

   # GitLab CI / GitHub Actions step
   - run: valgrind --tool=memcheck --leak-check=full --error-exitcode=1 ./fault_circular_ref

3. 智能指针规范：
   • 所有权唯一/独占 → unique_ptr
   • 共享所有权无环 → shared_ptr
   • 共享所有权且可能成环 → shared_ptr + weak_ptr
4. 培训：C++ 开发团队应接受 RAII 和智能指针最佳实践培训

八、附件

• 诊断报告源：PID_1261_circular_ref/diagnosis_report.md
• 进程日志：PID_1261_circular_ref/circular_ref_process.log
• RSS 趋势数据：PID_1261_circular_ref/rss_diag/rss_trend.csv
• 进程内存基线：PID_1261_circular_ref/rss_diag/proc_status_base.txt
• Heap 段 pmap 详情：PID_1261_circular_ref/pmap_heap.txt
• VmData 确认：PID_1261_circular_ref/vmdata.txt
• 诊断采集脚本：diagnose_rss_growth.sh -p 1261 -i 2 -c 5 + diagnose_heap_profiler.sh -p 1261 -b /tmp/fault_circular_ref
• 技能参考：memory-leak-diagnosis → 分支 C3