企业官网建设流程全解析

• 机器学习
• 深度学习
• 数据可视化
• 可观测性

导读：numcpus是一个专注于"系统有多少个 CPU"这一基础问题的轻量 Go 库，它把 Linux、BSD、Darwin、Solaris、Windows 各平台底层获取 CPU 拓扑信息的方式统一为六个语义明确的查询函数。本文以当前仓库中 vendor 化的 numcpus README 为主体，结合其在 wandb 项目中作为间接依赖（github.com/tklauser/numcpus v0.12.0，见 go.mod）的源码级实现，讲解 online/offline/present/possible 等概念的准确含义、各平台实现机制与可运行的实战代码，帮助你在自己的 Go 程序中正确处理 CPU 数量探测与并发度决策。

numcpus 是什么：只做一件事的 CPU 数量查询库

numcpus包提供关于系统 CPU 数量的信息，它不做监控、不做调度，只回答一个精确的问题：系统里有多少个 CPU，以及它们处于什么状态。它在 Linux、Darwin、FreeBSD、NetBSD、OpenBSD、DragonflyBSD、Solaris/Illumos 以及 Windows 上，分别返回 CPU 的 online（在线）、offline（离线）、present（存在）、possible（可能）、configured（已配置）与 kernel maximum（内核上限）六种计数。

其包级文档（见 numcpus.go）明确了各平台的数据来源：

• Linux：读取/sys/devices/system/cpu下对应的 CPU 拓扑文件；
• BSD 系（含 Darwin）：读取hw.ncpu与hw.ncpuonlinesysctl（若内核支持）；
• Windows：调用GetActiveProcessorCount与GetMaximumProcessorCount；
• Solaris/Illumos：调用sysconf相关常量。

并不是所有函数在所有平台都受支持，不支持的平台上会返回ErrNotSupported。

六种 CPU 计数的准确语义

numcpus的核心价值在于它把"CPU 数量"这个看似简单的概念拆成了六个互不相同的维度。理解它们之间的差异，是正确使用该库的前提。以下语义均来自 numcpus.go 中的函数文档：

对照 sysfs 拓扑文件可以更直观地理解这几层关系：possible是硬件上电后系统"可能"使用的全部 CPU 范围，present是已检测到的物理 CPU，online是其中当前被内核调度器使用的部分，而offline则是possible减去online后因热插拔或内核参数限制而未在线的部分。GetKernelMax返回的则是编译/引导内核时配置的硬上限（Linux 下对应/sys/devices/system/cpu/kernel_max文件）。

需要特别说明的是函数返回的错误：

• ErrNotSupported在某个函数不被当前平台支持时返回，定义于 numcpus.go，例如在 Linux 之外的平台调用GetOffline；
• 其余错误通常来自底层系统调用或文件读取失败。

列表 API：不止计数，还能拿到具体 CPU 编号

除了返回数量的Get*系列，numcpus还提供了返回[]int的List*系列，可用于需要精确到具体 CPU 编号的场景：

• ListOffline()→ 离线 CPU 编号列表；
• ListOnline()→ 在线 CPU 编号列表；
• ListPossible()→ 可能 CPU 编号列表；
• ListPresent()→ 存在 CPU 编号列表。

它们在 Linux 上解析 sysfs 中形如0-3,7的 CPU range 字符串（实现见 numcpus_linux.go）：按逗号分段，a-b展开为闭区间，单个数字视为单元素；若last < first会返回错误。值得注意的是空文件被视作合法输入并返回空列表——例如系统没有离线 CPU 时/sys/devices/system/cpu/offline为空文件，此时ListOffline()返回[]int{}而不是报错。

各平台底层实现机制

Linux：sysfs 文件 + sched_getaffinity

Linux 实现（numcpus_linux.go）是所有平台中最丰富的，数据源是/sys/devices/system/cpu目录下的online、offline、possible、present、kernel_max文件：

• GetConfigured通过os.ReadDir遍历目录，统计所有cpu<数字>形式的子目录；
• GetKernelMax读取kernel_max文件；
• GetOnline有个值得一提的细节：它优先调用unix.SchedGetaffinity(0, &cpuSet)读取当前进程的 CPU 亲和性集合并返回cpuSet.Count()，只有该调用失败时才回退到读取online文件（见 numcpus_linux.go）。从源码结构看，这意味着在容器或 cgroup 限制、taskset指定亲和性的环境下，GetOnline返回的是当前进程实际可用的 CPU 数，而非宿主机的全部在线 CPU——这与runtime.NumCPU()（GOMAXPROCS 初始值，同样受 CPU 亲和性影响）的语义是一致的，对并发度决策更实用。

BSD 系（含 Darwin）：sysctl

numcpus_bsd.go 覆盖darwin、dragonfly、freebsd、netbsd、openbsd：

• GetConfigured/GetPossible/GetPresent读取hw.ncpu；
• GetOnline在 NetBSD/OpenBSD 上优先读hw.ncpuonline，失败则回退到hw.ncpu，其余平台直接读hw.ncpu；
• GetKernelMax仅 FreeBSD 支持，读取kern.smp.maxcpus；
• GetOffline不支持，返回ErrNotSupported。

Windows：处理器组 API

numcpus_windows.go 基于golang.org/x/sys/windows：GetConfigured/GetOnline/GetPossible/GetPresent均调用windows.GetActiveProcessorCount(windows.ALL_PROCESSOR_GROUPS)（覆盖全部处理器组），GetKernelMax调用windows.GetMaximumProcessorCount，GetOffline返回ErrNotSupported。

Solaris/Illumos：sysconf

numcpus_solaris.go 定义了取自/usr/include/sys/unistd.h的三个常量（_SC_NPROCESSORS_CONF=14、_SC_NPROCESSORS_ONLN=15、_SC_NPROCESSORS_MAX=516），并通过unix.Sysconf查询：GetConfigured/GetPossible/GetPresent返回_SC_NPROCESSORS_CONF，GetOnline返回_SC_NPROCESSORS_ONLN，GetKernelMax返回_SC_NPROCESSORS_MAX，GetOffline不支持。

实战代码：完整可运行的查询示例

原 README 给出的示例是入门入口，这里将其完整保留并扩展为覆盖全部核心 API 的版本：

package main import ( "fmt" "os" "github.com/tklauser/numcpus" ) func main() { // 在线 CPU：决定运行时并发度的关键指标 online, err := numcpus.GetOnline() if err != nil { fmt.Fprintf(os.Stderr, "GetOnline: %v\n", err) } fmt.Printf("online CPUs: %v\n", online) // 可能 CPU：系统资源层面允许的最大可用数 possible, err := numcpus.GetPossible() if err != nil { fmt.Fprintf(os.Stderr, "GetPossible: %v\n", err) } fmt.Printf("possible CPUs: %v\n", possible) // 已配置 CPU：与 `getconf _SC_NPROCESSORS_CONF` 一致 configured, err := numcpus.GetConfigured() if err != nil { fmt.Fprintf(os.Stderr, "GetConfigured: %v\n", err) } fmt.Printf("configured CPUs: %v\n", configured) // 存在 CPU：实际检测到的物理 CPU 数 present, err := numcpus.GetPresent() if err != nil { fmt.Fprintf(os.Stderr, "GetPresent: %v\n", err) } fmt.Printf("present CPUs: %v\n", present) // 内核最大 CPU 数（Linux/Windows 支持，其他平台返回 ErrNotSupported） kernelMax, err := numcpus.GetKernelMax() if err != nil { fmt.Fprintf(os.Stderr, "GetKernelMax: %v\n", err) } fmt.Printf("kernel max CPUs: %v\n", kernelMax) // 离线 CPU 数（仅 Linux 支持） offline, err := numcpus.GetOffline() if err != nil { fmt.Fprintf(os.Stderr, "GetOffline: %v\n", err) } fmt.Printf("offline CPUs: %v\n", offline) // 列表 API：拿到具体 CPU 编号 if list, err := numcpus.ListOnline(); err == nil { fmt.Printf("online CPU list: %v\n", list) } if list, err := numcpus.ListPossible(); err == nil { fmt.Printf("possible CPU list: %v\n", list) } }

一个典型的多核 Linux 机器上，输出类似：

online CPUs: 16 possible CPUs: 16 configured CPUs: 16 present CPUs: 16 kernel max CPUs: 8191 offline CPUs: 0 online CPU list: [0 1 2 ... 15] possible CPU list: [0 1 2 ... 15]

（注意kernel max通常远大于实际物理核数，它代表内核配置的理论上限，不应被当作可用核数使用。）

在 wandb 项目中的角色与引入方式

在 wandb 仓库中，numcpus以间接依赖（indirect）身份出现在 core/go.mod（github.com/tklauser/numcpus v0.12.0），其完整源码被 vendor 到 core/vendor/github.com/tklauser/numcpus 目录下。这意味着它被 wandb-core 的某个依赖链引用，为系统监控等场景提供跨平台的 CPU 数量探测能力；作为使用方，你也可以在任意 Go 项目中通过go get github.com/tklauser/numcpus直接引入它。

该库代码量极小（核心 API 集中在 numcpus.go 的 98 行内），无外部运行时依赖（仅依赖golang.org/x/sys），非常适合作为工具库嵌入。它采用 Apache License 2.0 许可（见 LICENSE）。

使用建议与注意事项

1. 不要忽略错误：跨平台代码中，ErrNotSupported是正常分支而非异常，务必像示例中那样检查并处理err，避免把 0 当作真实数量。
2. 区分六种语义：报告"机器有多少核"用GetConfigured；决定并发 worker 数量用GetOnline（Linux 下还会反映亲和性/cgroup 限制）；判断热插拔能力用GetPossible/GetOffline。
3. 平台差异先确认：GetKernelMax仅 Linux/Windows，GetOffline仅 Linux，编写跨平台逻辑时请先查阅各文件头的构建标签（如 numcpus_bsd.go 的//go:build darwin || dragonfly || freebsd || netbsd || openbsd）。
4. Linux range 解析是安全的：listCPURange对空文件返回空列表、对乱序 range 返回错误，解析逻辑严谨，可放心用于处理 sysfs 输出。
5. 在 wandb 仓库中深入阅读：若想继续研究其实现细节，可依次阅读 numcpus.go（API 定义）、numcpus_linux.go（Linux 实现）以及 numcpus_bsd.go、numcpus_windows.go、numcpus_solaris.go 三个平台实现文件。

总结：numcpus以极小的 API 面解决了"系统有多少 CPU"这一高频基础需求，其六种计数语义 + 四种列表接口 + 多平台统一实现，使其成为系统工具、监控采集与运行时资源探测的理想选择。理解其各平台数据来源与ErrNotSupported语义，你就能在 wandb 这类跨平台项目中可靠地做出并发度与资源相关的决策。

• 机器学习
• 深度学习
• 数据可视化
• 可观测性