Go GOMAXPROCS:cgroup与CPU配额管理

摘要: 本篇讲解GOMAXPROCS的默认行为与runtime.NumCPU的关系，剖析容器CFS配额不被NumCPU感知的根因，演示automaxprocs读取cgroup v1/v2配额自动设置GOMAXPROCS的用法，介绍Go 1.25运行时原生感知容器CPU限制的新特性，分享K8s里CPU limit=1却开64个P导致调度风暴与CFS throttling的踩坑经历，对比默认NumCPU、automaxprocs、Go 1.25原生、手动设置四种方案。

开篇故事

去年一个API网关迁到K8s，每个Pod限1个CPU。节点是64核的大机器，上面挤了二十多个Pod。上线第二天，P99延迟从20ms飙到300ms，CPU throttling告警刷屏。看容器监控，CPU使用率才60%，远没到1核上限，但延迟就是降不下来。

用pprof抓了goroutine profile，发现调度器开了64个P，goroutine在64个P之间疯狂切换。runtime.GOMAXPROCS返回64，等于宿主机核数，根本没认容器的1 CPU限制。64个系统线程抢1核的时间片，光上下文切换就吃掉大量CPU，再叠加CFS带宽限制的节流，延迟自然爆炸。

当时Go版本是1.22，runtime不感知cgroup配额。引入automaxprocs，GOMAXPROCS降到1，延迟立刻回到20ms。后来升级到Go 1.25，运行时原生就读cgroup了，automaxprocs都可以摘掉。这篇把GOMAXPROCS和容器CPU配额的关系讲清楚。

一、GOMAXPROCS与runtime.NumCPU的默认行为

GOMAXPROCS控制Go调度器同时执行用户代码的P数量，也就是逻辑处理器个数。P越多，能并行的goroutine越多，但每个P都绑定一个系统线程，P太多会让线程互相抢CPU。GOMAXPROCS的默认值是runtime.NumCPU()的返回值。

runtime.NumCPU()在Linux上调sched_getaffinity查询进程可用的CPU集合。这套机制能识别cpuset类型的cgroup(CPU绑定)，但识别不了CFS带宽配额(cpu.cfs_quota_us)。K8s的CPU limit走的是CFS配额，限制的是时间片总量，不是核数。于是NumCPU看到的是宿主机64核，GOMAXPROCS默认成64。

package main

import (
	"fmt"
	"runtime"
)

func main() {
	// 打印逻辑CPU数, 容器里通常等于宿主机核数
	fmt.Println("NumCPU:", runtime.NumCPU())
	// 打印当前GOMAXPROCS, 默认等于NumCPU
	fmt.Println("GOMAXPROCS:", runtime.GOMAXPROCS(0))

	// 模拟容器场景: 一个限制1 CPU的Pod跑在64核节点上
	// NumCPU返回64, GOMAXPROCS默认64
	// 64个P抢1核时间片, 调度风暴 + CFS节流

	// runtime.NumCPU不读cgroup CFS配额, 这是问题根源
	// cpu.cfs_quota_us=100000, cpu.cfs_period_us=100000
	// 表示每100ms周期内只能用100ms CPU时间, 即1核
}

CFS配额的算法是quota除以period。cpu.cfs_quota_us=100000、cpu.cfs_period_us=100000，意思是每100毫秒周期里允许用100毫秒CPU时间，相当于1核。但NumCPU对这些文件视而不见，只看affinity。这就是容器里GOMAXPROCS偏高的根因。

二、容器CPU limit感知:automaxprocs与Go 1.25原生

Go 1.25之前，标准库不读cgroup配额，业界用uber的automaxprocs库补这个缺口。它通过init函数读取cgroup文件，算出配额对应的核数，再调用runtime.GOMAXPROCS设置。

package main

import (
	"fmt"
	"runtime"
	_ "go.uber.org/automaxprocs" // 空白导入, init里自动设置GOMAXPROCS
)

// automaxprocs读取cgroup的逻辑:
// v1: /sys/fs/cgroup/cpu/cpu.cfs_quota_us 和 cpu.cfs_period_us
// v2: /sys/fs/cgroup/cpu.max (格式: "quota period")
// GOMAXPROCS = quota / period, 向下取整, 最小1
// 启动日志会打印: maxprocs: Updating GOMAXPROCS=1: determined from CPU quota

func main() {
	// 这时GOMAXPROCS已经是配额算出来的值
	fmt.Println("GOMAXPROCS:", runtime.GOMAXPROCS(0))
	// 1 CPU limit的Pod里, 这里输出1而不是64

	// 关键: GOMAXPROCS要和容器实际能用的CPU匹配
	// 配额1核就开1个P, 配额2.5核开2个P(automaxprocs向下取整)
}

automaxprocs的空白导入是惰性的，配额文件读不到(比如裸机部署)就不改GOMAXPROCS，保持NumCPU默认值，向后兼容。生产里基本是无脑加这个依赖。

Go 1.25把这套能力收进运行时。启动时runtime读cgroup v1和v2的CPU限制，GOMAXPROCS默认取CPU配额和核数的较小值。分数配额向上取整，2.5 CPU的limit会设成3，最低保底2个P。运行时还会定期重新检查配额，配额变了运行中动态调整GOMAXPROCS，不用重启进程。

package main

import (
	"fmt"
	"runtime"
)

// Go 1.25+容器感知行为演示
// 无需任何额外依赖, 运行时自动处理
func main() {
	// Go 1.25在容器里: GOMAXPROCS = min(宿主机核数, cgroup配额)
	// 1 CPU limit的Pod: GOMAXPROCS=2 (最低保底2, 避免单P卡死)
	// 2.5 CPU limit: GOMAXPROCS=3 (向上取整)
	// 无limit的裸机: GOMAXPROCS=NumCPU (老行为不变)
	fmt.Println("GOMAXPROCS:", runtime.GOMAXPROCS(0))

	// 如果配额在运行时变化(动态扩缩容), 运行时会自动重算
	// 这是Go 1.25相比automaxprocs的优势: 支持运行时调整
	// automaxprocs只在启动时设置一次, 之后不跟踪变化

	// 手动覆盖优先级最高: 显式设置或环境变量GOMAXPROCS=N
	// 运行时的cgroup感知不会覆盖用户显式指定的值
	runtime.GOMAXPROCS(4) // 手动设4, cgroup感知让位
}

判断要不要装automaxprocs的依据就是Go版本。1.25及以上用原生能力，依赖能省则省。1.24及以下，automaxprocs仍然是标配。混合版本的项目，统一加automaxprocs也无害，1.25上它检测到运行时已经处理就跳过，不会重复设置。

三、踩坑经验:容器里GOMAXPROCS取宿主机CPU导致调度风暴

回到开头那个网关。Go 1.22部署在1 CPU limit的Pod里，GOMAXPROCS=64。症状是P99延迟飙高、CPU throttling告警。排查分三步。

第一步确认GOMAXPROCS实际值。在容器里跑一段诊断代码。

package main

import (
	"fmt"
	"runtime"
	"time"
)

func main() {
	// 打印GOMAXPROCS, 64说明没感知容器配额
	fmt.Printf("GOMAXPROCS=%d NumCPU=%d\n",
		runtime.GOMAXPROCS(0), runtime.NumCPU())

	// 观察线程数, M数量远超CPU配额就是病态
	ticker := time.NewTicker(time.Second)
	defer ticker.Stop()
	for i := 0; i < 3; i++ {
		<-ticker.C
		// 打印当前OS线程数, 容器里动辄上百
		fmt.Printf("threads=%d\n", runtime.NumCPU())
	}

	// 临时手动压到1, 看延迟是否回落
	// 验证GOMAXPROCS是不是元凶
	runtime.GOMAXPROCS(1)
	fmt.Println("手动设GOMAXPROCS=1, 观察延迟")
}

诊断输出GOMAXPROCS=64，NumCPU=64，确认没读容器配额。手动设成1，延迟立刻回落，锁定了元凶。

第二步引入automaxprocs修复。在main包加空白导入，重新部署。启动日志打出maxprocs: Updating GOMAXPROCS=1: determined from CPU quota，配额识别成功，P99延迟回到20ms。

第三步理解为什么1核开64个P会出问题。P多意味着绑定的M(系统线程)多，64个线程在1核上轮转，上下文切换开销巨大。CFS还要在100ms周期里给这64个线程分100ms时间片，线程们排队等调度，每个goroutine的实际执行时间被切碎，延迟被拉长。GOMAXPROCS和实际CPU配额匹配后，线程数和核数一致，切换开销消失。

补一条经验: GOMAXPROCS不要盲目往大调。有人觉得大一点吞吐高，结果在配额1核的容器里设成8，反而因为8个P互相抢占让延迟更差。默认值用配额算出来的就够，除非有实测数据支撑才往上调。

四、对比分析

默认NumCPU在容器里是错的，只适合裸机。automaxprocs是1.24及以下的稳定方案，缺点是只在启动时读一次，配额动态变化跟不上。Go 1.25原生最省心，启动和运行时都感知，配额变了自动调整，也覆盖动态扩缩容场景。手动设置适合压测对比或特殊调优，但要自己负责值对不对。新项目直接上1.25，老项目过渡期挂automaxprocs，迁移完再摘。

总结

GOMAXPROCS默认取runtime.NumCPU()，而NumCPU只认cpuset不认CFS配额，容器里会偏大。配额感知有两套方案: 1.24及以下用automaxprocs，启动时读cgroup文件算配额核数; 1.25运行时原生读cgroup v1和v2，还能在运行时跟踪配额变化。容器里GOMAXPROCS偏大会导致P和M过多，上下文切换叠加CFS节流把延迟拉爆。诊断时先打印GOMAXPROCS确认是否等于宿主机核数，再匹配到容器配额。新项目上Go 1.25能省掉automaxprocs依赖，老项目过渡期挂上automaxprocs即可，配额变化频繁的动态扩缩容场景优先选1.25的原生方案。