Go GOMAXPROCS 与容器 CPU 配额不一致时怎么观察

Go 容器里的 GOMAXPROCS 不一定等于宿主机的逻辑 CPU 数，也不一定等于 Kubernetes 的 requests.cpu。排查时要同时看三件事：Go 进程实际采用的并行度、容器所在 cgroup 的 CPU quota，以及 Pod 的 limits.cpu 配置。Go 1.25 及以后，在没有手动覆盖的情况下，Linux 运行时会把 cgroup CPU 吞吐上限纳入默认值；显式设置 GOMAXPROCS 环境变量或调用 runtime.GOMAXPROCS 后，自动更新就不会继续替你调整。

官方地址：https://pkg.go.dev/runtime/

先分清 GOMAXPROCS、CPU limit 和 CPU request

GOMAXPROCS 是 Go 同时执行用户级 Go 代码的最大并行度；被系统调用阻塞的线程不受这个数直接限制。Kubernetes 的 limits.cpu 则是容器可消耗的 CPU 时间上限，Linux 通常通过 cgroup 施加；requests.cpu 更接近调度时的资源保证和节点争用权重。一个容器可以 request 2、limit 4，也可以只设置 request 而不设置 limit，这两种配置对 Go 默认值的含义不同。

在 Go 进程内打印实际运行时视图

先把程序实际看到的值记录下来，避免只在宿主机上执行 lscpu 就下结论。下面的代码不改变并行度，GOMAXPROCS(0) 只读取当前设置；输出中的 NumCPU 是进程可见的逻辑 CPU 数，版本信息用来判断是否具备 Go 1.25 的容器感知默认。

package main

import (
    "fmt"
    "runtime"
)

func main() {
    // 只读取当前并行度，不调用 GOMAXPROCS(n) 修改运行时设置。
    maxProcs := runtime.GOMAXPROCS(0)
    // NumCPU 用来和 GOMAXPROCS 对照，不能单独代表 cgroup quota。
    visibleCPU := runtime.NumCPU()
    // 版本信息帮助判断是否启用了 Go 1.25 的容器感知默认逻辑。
    fmt.Printf("GOMAXPROCS=%d NumCPU=%d Go=%s\n", maxProcs, visibleCPU, runtime.Version())
}

如果结果是 GOMAXPROCS=8、NumCPU=8，只能说明两者当前相同，不能证明容器没有 CPU 上限；如果是 GOMAXPROCS=2、NumCPU=8，优先检查 quota 是否约为 2、是否设置了环境变量，或是否由启动代码主动调用过 runtime.GOMAXPROCS。

从 cgroup CPU quota 侧复核容器约束

Linux cgroup v2 通常从 /sys/fs/cgroup/cpu.max 读取 quota 和 period，格式是 quota period；quota 为 max 表示没有该层级的硬上限。cgroup v1 则常见 cpu.cfs_quota_us 与 cpu.cfs_period_us 两个文件。下面只展示检查命令，路径在不同容器运行时和挂载方式下可能不同。

# cgroup v2：先查看 CPU quota/period，max 表示没有硬上限
if [ -r /sys/fs/cgroup/cpu.max ]; then
  cat /sys/fs/cgroup/cpu.max
fi

# cgroup v1：分别查看 quota 与 period，-1 通常表示不限制
if [ -r /sys/fs/cgroup/cpu/cpu.cfs_quota_us ]; then
  cat /sys/fs/cgroup/cpu/cpu.cfs_quota_us
  cat /sys/fs/cgroup/cpu/cpu.cfs_period_us
fi

例如 quota 为 250000、period 为 100000，代表平均吞吐上限约为 2.5 个 CPU。Go 的 GOMAXPROCS 必须是正整数，官方运行时文档说明小数 quota 会向上取整，并且默认值通常不会低于 2，除非可见逻辑 CPU 或 affinity 本身少于 2。因此 quota、NumCPU 和 GOMAXPROCS 不相等并不自动等于配置错误。

根据结果处理版本与手动覆盖

最后查三处配置。第一处是镜像实际使用的 Go 版本：Go 1.24 及更早版本不会按 Go 1.25 的新默认读取 cgroup quota；第二处是 GOMAXPROCS 环境变量；第三处是启动代码、依赖库或 GODEBUG=containermaxprocs=0、GODEBUG=updatemaxprocs=0。任何显式覆盖都可能让你看到“容器 limit 已改，但 GOMAXPROCS 没变”。

若应用没有明确的并行度策略，通常先升级到满足项目兼容要求的 Go 1.25+，撤销旧的固定值，让运行时重新采用默认更新；若业务确实需要固定并行度，就保留显式设置，但把它当成容量决策，配套观察 CPU throttling、P95/P99 延迟和吞吐。Go 1.25 新增的 runtime.SetDefaultGOMAXPROCS() 可在程序明确知道环境发生变化时恢复运行时默认逻辑，不过它不是替代压测的“自动修复键”。

复查时把三组信息放进同一条日志：runtime.Version()、runtime.GOMAXPROCS(0)、runtime.NumCPU()，再附上 Pod 的 limit/request 和 cgroup 文件内容。这样才能区分“默认值变了”“quota 变了”和“应用自己覆盖了设置”。

常见问题

只设置 CPU request，Go 会按 request 设置 GOMAXPROCS 吗？

不会。Go 1.25 的容器感知默认关注 Linux cgroup CPU bandwidth limit，Kubernetes 的 request 主要参与调度和竞争权重。

为什么 CPU quota 是 0.5，却没有看到 GOMAXPROCS=1？

默认值需要是正整数，运行时对小数 quota 向上取整，并通常保留不低于 2 的下限；还要结合可见 CPU、affinity 和是否存在手动覆盖一起判断。

修改 limits.cpu 后 GOMAXPROCS 会立刻变化吗？

Go 默认会周期性检查逻辑 CPU、affinity 或 cgroup quota 的变化，但不是每次配置变更都同步瞬时完成；如果设置过固定值，自动更新还会被禁用。

观察这类“不一致”时，最有价值的不是追求三个数字完全相同，而是确认它们分别代表什么、由哪一层决定，再用延迟和 throttling 指标验证修改是否真的改善了服务。