Go net/http/pprof 怎样给诊断入口加访问控制

我第一次把 Go 的 pprof 接进服务时，最容易忽略的不是怎么采样，而是“谁能访问采样入口”。net/http/pprof 方便，却不适合跟公开业务路由一起匿名暴露。更稳妥的做法是把诊断请求单独放进一个监听器或至少一个专用 ServeMux，先经过访问控制，再交给 pprof 生成数据。

官方文档：https://pkg.go.dev/net/http/pprof

核心原则：先隔离诊断入口，再在 pprof handler 外层做鉴权；不要把令牌校验写进 profile 采样逻辑，也不要把调试数据当普通业务响应处理。

先画清 pprof 诊断数据的流向

pprof 的请求链可以拆成六段：请求进入诊断监听器，访问控制判断是否放行，专用 mux 找到对应处理器，pprof 读取请求参数并生成 profile，调用方保存或分析结果，最后结束本次采集。业务监听器不应该直接连接到这条链上。

官方文档说明，空白导入 net/http/pprof 会把处理器注册到默认 mux；如果程序使用自己的 mux，就要显式注册需要的 handler。这个区别决定了访问控制应该放在哪里：最外层是监听器或反向代理，应用内还可以再加一层专用中间件。

用专用 ServeMux 接管诊断路由

下面的示例不把 pprof 挂到业务 mux，而是单独构造诊断服务。令牌来自环境变量，示例中的监听地址只用于说明边界；生产环境还应配合内网、TLS 或统一身份认证。

package main

import (
    "crypto/subtle"
    "net/http"
    "os"

    "net/http/pprof"
)

// requireToken 在 pprof 生成数据前拦截请求，避免匿名调用诊断处理器。
func requireToken(next http.Handler) http.Handler {
    expected := []byte(os.Getenv("PPROF_TOKEN"))
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 只接受 Bearer 令牌；不要把令牌写进日志或错误响应。
        const prefix = "Bearer "
        actual := r.Header.Get("Authorization")
        if len(expected) == 0 || len(actual) 

这里的关键不是把 pprof 路径改得多隐蔽，而是让请求在进入 pprof.Index、pprof.Profile 或 pprof.Trace 前已经完成判断。路径隐藏不能代替鉴权，公开监听地址也不能只靠“别人不知道端口”来保护。

在数据生成前做访问控制

中间件至少要处理三种情况：没有 Authorization 头、头部格式不是 Bearer、令牌不匹配。响应可以统一为 401，避免把“路径存在但令牌错误”和“路径不存在”混成调试信息。真正上线时，令牌轮换、TLS 终止和审计字段应该交给现有的身份系统，而不是把长期秘密硬编码在程序里。

如果前面还有反向代理，建议形成两道边界：代理限制来源网络和身份，Go 服务再次限制 Authorization。这样即使代理配置误放，也不会让 pprof 直接变成匿名入口。审计日志可以记录请求路径、调用方身份、结果码和采集耗时，但不要记录 Authorization 原文。

区分 profile 输出与采集动作

pprof 的不同路径并不是同一种数据。heap、goroutine、allocs 等偏向当前运行状态或累计数据；profile?seconds=N 和 trace?seconds=N 会在请求期间持续采集。调用方要限制 seconds 的上限，避免一次诊断请求占用过长时间。

# 先设置临时令牌，再只从受保护的本地诊断入口采集 5 秒 CPU profile。
export PPROF_TOKEN='change-me-before-use'
curl -H "Authorization: Bearer ${PPROF_TOKEN}" \
  -o cpu.pprof \
  'http://127.0.0.1:6060/debug/pprof/profile?seconds=5'

# 用 go tool pprof 读取生成的 profile；文件用完后按项目策略清理。
go tool pprof cpu.pprof

命令里的令牌只是占位值，不能直接复制到生产环境。采集完成后，文件可能包含函数名、调用栈和运行时信息，应放在受控目录并设置合理权限；如果只是临时排查，分析结束就删除或按审计制度归档。

拒绝、清理和上线边界

我会把上线前的检查压缩成四件事：业务端口访问不到 /debug/pprof/；诊断端口缺少令牌得到 401；不允许的方法按 HTTP 规则处理；诊断服务关闭后不再接受新的 profile 请求。Go 官方文档说明 pprof 路径使用 GET 请求，因此不要为了“方便调试”把它改成任意方法都能访问。

退出流程也要包含诊断服务。使用独立的 http.Server 后，可以在收到关闭信号时调用 Shutdown，等待正在生成的 profile 结束，再关闭监听器。这样既不会留下半截采样文件，也不会因为进程退出把未完成的诊断请求误判成业务故障。

// shutdownDiagnostic 在退出时给正在生成 profile 的请求一个有限收尾时间。
func shutdownDiagnostic(srv *http.Server, ctx context.Context) error {
    // Shutdown 会停止接收新连接，并等待已有请求结束或 ctx 超时。
    return srv.Shutdown(ctx)
}

上面的函数需要额外导入 context；这里只展示关闭边界，实际程序应把返回的错误交给统一退出流程记录。不要在清理阶段打印令牌、完整请求头或 profile 原文。

几个容易混淆的问题

只把 pprof 监听在 localhost 就够了吗？

它能缩小网络暴露面，但不等于完整鉴权。宿主机上的其他进程、端口转发和容器网络配置仍可能改变访问边界，内部诊断服务仍应保留身份校验。

为什么不用随机路径代替令牌？

随机路径只能增加猜测成本，不能表达调用者身份，也不能可靠轮换权限。路径可以作为路由设计，不能作为唯一安全控制。

是否应该一直开启 trace？

不建议把长时间 trace 当成常驻业务能力。它会产生采集成本和敏感运行信息，应该在受控窗口、受保护入口和明确的保存策略下使用。

总结一下：pprof 的安全边界要沿着“监听器—路由—鉴权—profile 输出—分析文件—关闭清理”整条生命周期设计。专用 mux 负责把可用能力列清，中间件负责在生成诊断数据前拒绝匿名请求，网络隔离和 TLS 负责继续收窄入口。这样排查性能问题时仍然方便，也不会把运行时内部信息当成公开 API。