在现代容器化部署中，准确评估系统可用并行度是优化运行时性能的关键课题。Bun 作为新一代 JavaScript 运行时，在 Linux 平台上实现了 cgroup 感知的 AvailableParallelism 机制，能够自动识别容器资源限制并动态调整硬件并发度。这一特性避免了传统运行时在不同部署环境下盲目使用全部 CPU 核心导致的资源争抢和性能下降问题。
AvailableParallelism 的定位与职责
Bun 通过暴露 node:os.availableParallelism() 接口实现了与 Node.js 兼容的并行度查询能力。该函数的返回值代表运行时建议用于并行任务的默认并发数量，通常对应系统中可用的逻辑 CPU 核心数。在传统实现中，运行时往往直接读取 /proc/cpuinfo 或调用系统接口获取 CPU 核心总数，然后将其作为 worker pool 规模或并发任务数的上限。这种做法在裸金属服务器上运行良好，但在容器化环境中会产生严重偏差。
当 Bun 运行在 Docker、Podman 或 Kubernetes 等容器运行时中时，容器的 CPU 配额往往受到 cgroup 的严格限制。例如，一个配置了 cpu.cfs_quota_us=100000 和 cpu.cfs_period_us=100000 的容器，其可用 CPU 带宽仅为单核心的处理能力；即使宿主机的物理服务器拥有 32 个核心，容器内的任务调度器也应当将并行度限制在 1 左右。传统运行时如果不感知这一限制，仍然会尝试创建数十个并发 worker，最终导致频繁的上下文切换和 CPU 资源争抢，吞吐量不升反降。
cgroup CPU 限制的读取机制
Linux cgroup 提供了两种主要的 CPU 资源控制机制：cgroup v1 和 cgroup v2。两种版本在接口路径和命名上存在差异，但核心逻辑一致 —— 通过配额（quota）和周期（period）的组合来限制单位时间内可使用的 CPU 时间。cgroup v2 使用统一的 /sys/fs/cgroup/cpu.max 文件，格式为 <quota>/<period>，如 100000/100000 表示仅允许使用一个 CPU 核心的资源。cgroup v1 则分别使用 cpu.cfs_quota_us 和 cpu.cfs_period_us 两个文件进行配置。
Bun 运行时在初始化 AvailableParallelism 时，会尝试读取这些 cgroup 配置文件以获取容器的实际 CPU 配额。如果检测到配额限制小于容器所在宿主机的实际核心数，则使用配额计算得出的有效核心数作为并行度上限。这一逻辑与 Go 语言运行时在 1.21 版本后引入的 GOMAXPROCS 自动调整机制类似，都是通过感知容器资源边界来避免过度分配。
具体实现上，Bun 调用了底层 libuv 库的 uv_available_parallelism() 函数。该函数在 Linux 平台上会依次尝试以下数据源：首先检查 cgroup v2 的 CPU 配额配置，若不存在则回退至 cgroup v1 的对应接口；若 cgroup 信息不可用或配额未设置，则使用系统报告的逻辑核心数作为兜底。这种优先级设计确保了在标准容器环境、标准虚拟机以及裸金属服务器上都能得到合理的并行度估计。
实践中的关键监控指标
在生产环境中部署 Bun 应用时，建议通过以下指标验证 cgroup 感知机制是否生效。首先检查容器层面的 CPU 配额配置：对于 cgroup v2 环境，查看 /sys/fs/cgroup/cpu.max 的值；对于 cgroup v1 环境，分别读取 cpu.cfs_quota_us 和 cpu.cfs_period_us 并计算 quota/period 的比值。如果配额值为 -1，表示未设置上限，容器可以使用宿主机的全部 CPU 资源。
其次，在 Bun 运行时内部，可以通过编程方式验证返回值。将 console.log(os.availableParallelism()) 写入启动脚本，观察输出的数值是否与容器的 CPU 配额相匹配。例如，一个配置为 2 CPU 的 Kubernetes Pod 在理论上有 4 个逻辑核心，但若容器被限制为 2 个 CPU 核心，则 availableParallelism() 应返回 2 而非 4。
第三，建议结合实际负载进行端到端验证。在高并发场景下，使用 top 或 htop 观察 Bun 进程的 CPU 使用率是否被限制在预期范围内。如果并行度设置过高，进程总 CPU 使用率会接近或超过配额上限，导致节流（throttling）现象，表现为请求延迟升高和吞吐量下降。如果并行度设置合理，CPU 使用率应稳定在配额限制附近，且不会触发 cgroup 的 CPU 带宽控制警告。
工程落地的推荐参数
基于 cgroup 感知的并行度调度机制，工程实践中有几个值得关注的调优点。在容器编排层面，确保 CPU 配额与分配给 Bun 工作负载的资源请求相匹配。Kubernetes 的 resources.limits.cpu 字段直接映射为容器的 CPU 配额，设置时应考虑应用的实际负载特征 ——CPU 密集型应用可以设置较高的配额上限，而 I/O 密集型应用则可以适度降低，因为这类应用的并发收益主要来自等待 I/O 完成而非 CPU 计算。
在 Bun 运行时层面，虽然 availableParallelism() 提供了自动感知的默认值，但在某些场景下可能需要手动覆盖。例如，在同一容器内运行多个 Bun 实例时，自动感知的并行度可能导致总计 CPU 使用超过配额，此时应通过环境变量或代码显式指定每个实例的 worker 数量。另外，对于已知延迟敏感的应用，可以考虑将并行度设置为略低于配额值（如配额为 4 时设置为 3），为系统调度和突发请求留出缓冲空间。
监控体系的建设同样重要。建议在 Bun 应用的 Prometheus 指标中采集 availableParallelism 的初始值，并将其与容器 CPU 配额的监控数据关联。当两者出现显著偏差时，可能意味着运行时未正确识别 cgroup 配置，需要检查容器运行时的 cgroup 挂载是否正确以及 Bun 版本是否包含 cgroup 感知补丁。
总结
Bun 在 Linux 上实现的 cgroup 感知 AvailableParallelism 机制，为容器化部署环境提供了开箱即用的自适应并发调度能力。通过读取 cgroup CPU 配额信息并动态调整运行时建议的并行度，Bun 能够避免传统实现中盲目使用全部 CPU 核心导致的资源争抢问题。在实际工程中，开发者应结合容器资源配置、运行时参数调优和监控告警，建立起完整的资源感知闭环，确保 Bun 应用在不同部署环境下都能发挥最优性能。
参考资料
- Bun 官方文档：os.availableParallelism（https://bun.sh/reference/node/os/availableParallelism）
- Libuv uv_available_parallelism () 实现机制