---
name: go-performance-debug
description: 定位并修复 Go 服务的 OOM 与性能问题：采集并分析 pprof profile、定位内存增长点，结合代码与 commit 历史定位引入原因，产出根因 + 修复方案 + 测试方案。Use when a Go service is OOM, memory-leaking, or performance-degraded.
license: Apache-2.0
metadata:
  version: "0.1.0"
---

# Go 服务性能 / OOM 调试

对「服务 OOM / 内存泄漏 / 性能劣化」做端到端诊断。本 Skill 定义诊断流程与判断标准；数据采集用 `scripts/collect-go-profile.sh`，代码与历史通过 MCP（`filesystem` / `github`）获取。

## 何时使用

- 用户报告 Go 服务 OOM、被 OOM killer 杀掉、内存持续增长、GC 压力大、响应变慢。
- 需要从症状一路定位到「根因 + 修复方案 + 测试方案」。

## 前置阅读

- [pprof 使用指南](references/pprof-guide.md)
- [OOM 分析方法](references/oom-analysis.md)
- [诊断工作流（结合 MCP）](references/diagnostic-workflow.md)

## 工作流

### 阶段 1：收集证据

在分析前先确认现象，避免瞎猜：

1. 症状：是 OOM 被杀、内存持续增长、CPU 打满，还是延迟升高？
2. 时间线：什么时候开始、是否与某次发布 / 流量变化相关？
3. 现有数据：容器内存曲线、GC 日志、`runtime.MemStats`、监控指标。

产出：一段「现象 + 时间线」的客观描述。

### 阶段 2：采集 profile

用 [`scripts/collect-go-profile.sh`](scripts/collect-go-profile.sh) 采集：

```bash
# 从运行中的服务采集 heap 与 goroutine
./collect-go-profile.sh heap http://localhost:6060/debug/pprof ./pprof-out
./collect-go-profile.sh goroutine http://localhost:6060/debug/pprof ./pprof-out

# CPU 热点（抓取 30 秒）
./collect-go-profile.sh cpu http://localhost:6060/debug/pprof ./pprof-out
```

OOM 场景优先采集 **heap** 与 **goroutine**；CPU 场景采集 **cpu**。

### 阶段 3：分析 profile

按 [pprof-guide.md](references/pprof-guide.md) 与 [oom-analysis.md](references/oom-analysis.md)：

1. 看 `heap.top.txt` 找内存占用最大的函数与分配路径。
2. 看 `goroutine.top.txt` 找 goroutine 数量异常增长（泄漏信号）。
3. 区分：是「分配太多」还是「该释放的没释放」（泄漏）。

### 阶段 4：定位根因（代码 + 历史）

结合 MCP 获取外部信息：

1. 用 `filesystem` MCP 读 top 函数对应的源码，确认分配点 / 泄漏点。
2. 用 `github` MCP 查相关文件的 commit 历史，定位「哪个改动引入 / 放大」了问题。
3. 交叉验证：内存增长的时间线是否与某次提交 / 发布吻合。

产出：一条「分配点 → 持有路径 → 引入提交」的证据链。

### 阶段 5：制定修复方案

按根因类型给出可落地修复：

- 泄漏：补上退出信号（context / done）、释放引用、修正 defer 位置。
- 分配过多：预分配、复用 buffer（`sync.Pool`）、流式处理、去掉无界缓存。
- 大对象：分批 / 分页、减少一次性加载。

每条修复给代码片段，并说明预期内存收益。

### 阶段 6：制定测试 / 验证方案

1. 回归测试：覆盖触发 OOM 的场景。
2. 验证：`go test -bench -benchmem` 看分配下降；`go test -race` 排除竞态；压测 + 观察内存曲线是否平稳。

## 输出模板

```text
## Go 服务 OOM / 性能诊断报告

### 现象与时间线
<客观描述>

### 证据
- heap profile top: <摘要>
- goroutine 数量: <是否异常增长>
- 相关 commit: <引入 / 放大问题的提交>

### 根因
<一条清晰的因果链>

### 修复方案
- [ ] <修复点 1>（含代码片段与预期收益）
- [ ] <修复点 2>

### 测试 / 验证方案
- <回归测试>
- <压测 + 内存曲线观察>
- <go test -race / -benchmem>
```

## 约束与边界

- 只分析、不擅自修改运行中的服务；修复需用户确认后落地。
- 采集 profile 需服务已暴露 pprof 端点（或已有 profile 文件），否则标注「数据不可得」。
- 无法静态确认的根因，标注「需复现验证」。
- 不执行目标服务中的未审计脚本 / 构建。