Go net/http/pprof 怎样暴露 goroutineleak 诊断入口

我排查 goroutine 数量持续上涨时，最先想看的通常不是 CPU，而是每类 goroutine 当前卡在什么调用栈。Go 的 net/http/pprof 可以直接提供这份资料，但“能访问”不等于“应该公开”。比较稳妥的做法是：单独建立诊断监听器，只注册需要的 goroutine handler，把端口限制在本机或受控网络，再按采集窗口记录访问和关闭动作。

用 pprof.Handler("goroutine") 暴露一个窄入口，能完成 goroutine 快照采集；真正的安全边界来自监听地址、网络访问控制、身份校验和下线流程，而不是 pprof 路径本身。

官方资料入口：https://pkg.go.dev/net/http/pprof@go1.27.3。本文只讨论暴露 goroutine 诊断入口，不把一次 profile 快照直接等同于已经确认的 goroutine 泄漏。

先界定要保护的诊断资产

net/http/pprof 通过 HTTP 提供运行时 profiling 数据；导入包的副作用会把一组路径注册到默认 mux，路径通常以 /debug/pprof/ 开头。官方文档还说明，Go 1.22 起这些路径都应使用 GET。对本题来说，最有用的资产是 goroutine profile：它展示当前 goroutine 的堆栈，适合回答“哪些调用点正在积累”。

我第一次接入时容易犯的错误，是把空白导入和业务服务器放在一起，然后顺手把整个默认 mux 暴露出去。这样虽然代码短，却让诊断路径和业务端口共享同一个入口，后续很难解释谁访问过、何时应该撤掉、是否会把其他 profile 一并带出去。更窄的边界是只注册一个命名 handler。

这张图里最重要的关系不是箭头方向，而是边界：业务 HTTP 服务不必直接承载调试入口；诊断监听器只挂自定义 mux；handler 产生的 profile 再交给 go tool pprof 分析。

用独立监听器和自定义 mux 暴露入口

下面的最小写法只注册 /debug/pprof/goroutine，并把诊断服务绑定到 127.0.0.1:6060。这样默认情况下只有本机能连接；如果生产环境需要远程采集，应把远程访问放在已有的受控跳板或内网边界后面，而不是把地址改成公网监听。

package main

import (
    "context"
    "errors"
    "log"
    "net/http"
    "net/http/pprof"
    "time"
)

func startDiagnostics() *http.Server {
    mux := http.NewServeMux()

    // 只暴露 goroutine profile，避免把不需要的调试资源一并注册。
    mux.Handle("/debug/pprof/goroutine", pprof.Handler("goroutine"))

    server := &http.Server{
        // 绑定回环地址，默认不让业务网卡直接接收诊断请求。
        Addr:    "127.0.0.1:6060",
        Handler: mux,
    }

    go func() {
        // 监听失败要进入服务日志，不能静默丢掉诊断入口状态。
        if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            log.Printf("diagnostic server stopped: %v", err)
        }
    }()
    return server
}

func stopDiagnostics(server *http.Server) {
    // 退出服务时主动关闭诊断端口，避免遗留调试入口。
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    if err := server.Shutdown(ctx); err != nil {
        log.Printf("diagnostic shutdown failed: %v", err)
    }
}

这里故意没有使用匿名导入。匿名导入适合快速启用默认 mux，但隔离监听器需要显式调用 pprof.Handler。如果还要展示 profile 列表，可以在同一个自定义 mux 中额外注册 pprof.Index；如果只需要一个 goroutine 入口，少一个索引页面也意味着少一个暴露面。

按 GET 参数收集资料，不把快照当结论

拿到入口后，常见的两种采集方式分别对应两个问题：不带参数的 goroutine profile 更像当前堆栈快照；带 seconds=N 时，官方文档把它定义为一段时间的 delta profile。后者更适合观察一段窗口里 goroutine 状态的变化，但仍需要结合业务指标、重复采样和代码路径分析。

# 采集当前 goroutine 堆栈快照，保存到本地供 go tool pprof 分析。
go tool pprof "http://127.0.0.1:6060/debug/pprof/goroutine"

# 采集 30 秒窗口的 goroutine 增量资料，避免把一次瞬时峰值当成泄漏。
go tool pprof "http://127.0.0.1:6060/debug/pprof/goroutine?seconds=30"

判断“泄漏”至少要问三件事：数量是否在多个业务周期后仍只增不减；增长的堆栈是否集中在同一个等待点；采集窗口是否覆盖了请求、重试、队列消费或定时任务的完整生命周期。一次 profile 只告诉你采集时刻看到了什么，不会自动证明根因。

官方诊断文档还提醒，不同 profiling 工具可能互相影响，建议一次只收集一种 profile。排查 goroutine 问题时，我会先固定采集窗口和样本命名，再决定是否需要额外的 CPU、block 或 mutex 资料，避免把多个观测动作混成一个无法解释的结果。

按威胁路径收紧发布与审计

pprof 端点返回的是进程诊断资料，可能包含包名、函数名、调用关系和运行状态。它不是登录页，也不会因为路径叫 debug 就自动获得鉴权。因此安全设计要围绕攻击路径展开：谁能连到端口、谁能发起 GET、谁能拿走 profile、访问是否被记录、采集完成后入口何时消失。

• 网络边界：优先回环地址或仅允许诊断网段，避免把 /debug/pprof/ 直接挂在公网业务域名下。
• 身份控制：需要远程访问时，在网关或专用诊断服务层增加现有身份认证；不要把“路径足够难猜”当作权限。
• 访问日志：记录请求来源、操作者、profile 类型和采集窗口，方便把一份资料与故障时间线对应起来。
• 采集窗口：明确谁在什么时间收集什么 profile，避免长期开放和重复采集造成额外开销。
• 下线动作：问题定位后调用 Shutdown 关闭独立诊断服务，或者撤掉临时路由；不要把调试入口留到下一次发布。

这套控制也解释了为什么我更偏好独立监听器：业务服务的路由、审计和发布生命周期可以保持不变，诊断端口则有自己的 owner、采集窗口和关闭动作。

我的收尾清单：适合谁，什么时候别这样做

如果你维护的是可控网络内的 Go 服务，正在定位 goroutine 持续增长、请求等待或后台任务未退出，以上方案通常足够轻量。它的优点是改动小、资料格式与官方工具链直接衔接，且可以只暴露一个 profile。它的代价是需要额外管理端口、认证、日志和关闭动作；若团队没有明确的诊断访问流程，独立端口也可能变成遗留风险。

发布前我会逐项确认：

1. 是否只绑定了需要的 goroutine handler，而不是无意带上默认 mux 的全部路径？
2. 监听地址是否仍在本机或受控网络，远程访问是否经过既有身份控制？
3. 是否区分了快照与 seconds=N 增量资料，并保存了采集时间和窗口？
4. 是否一次只采集一种 profile，并把输出交给 go tool pprof 做后续分析？
5. 是否有访问记录、负责人和明确的 Shutdown 下线动作？

相关问题：

• 为什么不直接导入 net/http/pprof？因为匿名导入会面向默认 mux 注册整套路径，隔离场景更适合显式注册。
• seconds=30 是不是一定能证明泄漏？不是，它只是一个时间窗口的增量资料，仍需多次采样和业务生命周期对照。
• goroutine profile 能替代 block profile 吗？不能；它们回答的观测问题不同，按一次只采集一种 profile 的原则分别使用。