# PR #51058 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Build] Upgrade runtime image to Ubuntu 24.04, pick up rdma-core > 44
- 合并时间：2026-08-09 09:17
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/51058

---

# 执行摘要

- 一句话：运行时镜像升级 Ubuntu 24.04，rdma-core 升至 50 支持 NCCL GIN
- 推荐动作：建议构建与发布相关工程师快速过一遍；变更本身机械（版本号升级），但评审中的内核 / 驱动兼容性调研与文档化处理值得借鉴，属于基础设施升级的标准操作范例。普通业务开发无需深入。

# 功能与动机

PR body 明确指出动机：NCCL GIN（NCCL_GIN_TYPE=3 即 GDA-KI）需要 rdma-core > 44，而 Ubuntu 22.04 只带 39，Ubuntu 24.04 提供 50.0；同时作者认为没有阻塞因素，升级后不再需要为需要 24.04 的用户分别构建镜像，可简化 build/release 流程。

# 实现拆解

1. 构建参数中枢 docker/versions.json：UBUNTU_VERSION 默认值从 22.04 改为 24.04；FINAL_BASE_IMAGE 同步切换到 nvidia/cuda:13.0.3-base-ubuntu24.04；GDRCOPY_OS_VERSION 改为 Ubuntu24_04。该文件是所有镜像构建分支默认参数的事实来源，一处修改即可让各 CUDA 版本构建默认落在 24.04。
2. 构建脚本 docker/Dockerfile：将 ARG UBUNTU_VERSION 默认值改为 24.04，并将接近文件尾部的 ARG GDRCOPY_OS_VERSION 改为 Ubuntu24_04，保证 tools/install_gdrcopy.sh 下载的预编译 gdrcopy 包与基础系统匹配，避免因版本不一致找不到 .deb 包。
3. 文档配套 docs/getting_started/installation/gpu.cuda.inc.md：在 CUDA compatibility 小节追加宿主内核要求说明——CUDA 13 镜像正常运行需要 R580 或更新驱动（内核不低于 4.15），VLLM_ENABLE_CUDA_COMPATIBILITY=1 兼容模式支持 R535/R570，其中 R535 可把内核下限降到 3.10，R570 仍要求 4.15；同时明确 userland 升级到 Ubuntu 24.04 不会抬高这些由驱动定义的内核要求。
4. 验证与发布边界：无新增单元测试，依赖 Buildkite CI（commit 3cd4c20295f4 触发构建 #82941）验证镜像构建；作者在讨论中说明 PyPI wheels 的构建通过 manylinux2_28 覆盖 OS 版本，不受本次变更影响。

关键文件：
- `docker/versions.json`（模块 镜像配置；类别 infra；类型 infrastructure）: 镜像构建参数中枢，UBUNTU_VERSION 默认值从 22.04 改为 24.04，并同步 FINAL_BASE_IMAGE 与 GDRCOPY_OS_VERSION，是整个升级的事实来源。
- `docker/Dockerfile`（模块 镜像构建；类别 infra；类型 infrastructure）: 消费 versions.json 的 ARG 默认值，本次同步 UBUNTU_VERSION 与 GDRCOPY_OS_VERSION，保证基础层与 gdrcopy 安装版本一致。
- `docs/getting_started/installation/gpu.cuda.inc.md`（模块 安装文档；类别 docs；类型 documentation）: 新增 CUDA 13 镜像宿主内核最低要求说明，回应评审中关于旧内核兼容性的关切，并明确 userland 升级不改变驱动定义的内核下限。

关键符号：未识别

## 关键源码片段

### `docker/Dockerfile`

消费 versions.json 的 ARG 默认值，本次同步 UBUNTU_VERSION 与 GDRCOPY_OS_VERSION，保证基础层与 gdrcopy 安装版本一致。

```dockerfile
# 以下 ARG 定义在 Dockerfile 中分布在不同位置，此处合并展示
ARG CUDA_VERSION=13.0.3
# 运行时基础镜像从 Ubuntu 22.04 升级到 24.04。24.04 自带 rdma-core 50.0，
# 满足 NCCL GIN（GDA-KI）对 rdma-core > 44 的要求，而 22.04 仅有 39
ARG UBUNTU_VERSION=24.04

# gdrcopy 预编译包按 OS 版本命名，必须与 UBUNTU_VERSION 保持一致，
# 否则 tools/install_gdrcopy.sh 会因找不到对应 .deb 包而失败
ARG GDRCOPY_CUDA_VERSION=12.8
ARG GDRCOPY_OS_VERSION=Ubuntu24_04

```

# 评论区精华

核心讨论围绕宿主内核兼容性展开：Harry-Chen 提出关键问题，询问 24.04 userland 的最小内核要求，担心用户把容器跑在非常老的内核上；作者调研后回复 Ubuntu 24.04 的 glibc floor 是 3.2，真正的下限由 CUDA 13 决定——正常运行需要 R580 驱动（内核 4.15），设置 VLLM_ENABLE_CUDA_COMPATIBILITY=1 可降到 R535 驱动（内核 3.10）；Harry-Chen 认可结论，指出现存最老内核可能来自 RHEL7（正好 3.10），随后与 mgoin 一起批准合并。作者还主动说明本次变更不影响 PyPI wheels，那些构建用 manylinux2_28 覆盖 OS 版本。

- Ubuntu 24.04 userland 对旧宿主内核的兼容性 (question): 作者核实：glibc floor 为 3.2；CUDA 13 正常运行需 R580 驱动（内核 4.15），VLLM_ENABLE_CUDA_COMPATIBILITY=1 可降至 R535 驱动（内核 3.10）；Harry-Chen 认可 RHEL7（3.10）为现存最老内核后放行。
- 变更是否影响 PyPI wheels (question): 不影响 PyPI wheels，二者发布路径独立。

# 风险与影响

- 风险：宿主内核兼容是主要风险：镜像 userland 切到 24.04 后，老内核主机需要确认驱动满足 CUDA 13 要求（正常运行 4.15+，兼容模式 3.10+），已通过文档降低误用风险。gdrcopy 安装存在版本联动风险：GDRCOPY_OS_VERSION 必须与 Ubuntu 版本保持一致，本次同步为 Ubuntu24_04 且 CI 构建通过。配置漂移风险：versions.json 中 UBUNTU_VERSION、FINAL_BASE_IMAGE、GDRCOPY_OS_VERSION 三个参数相互关联，未来若只改一处会导致镜像构建不一致。对 PyPI 无影响，manylinux2_28 构建路径独立。
- 影响：所有使用官方 Docker 镜像的 vLLM 用户默认获得 Ubuntu 24.04 userland 与 rdma-core 50.0，可直接使用 NCCL GIN（GDA-KI）等需要新版 rdma-core 的多节点通信方案；旧内核主机用户需在升级前核实驱动与内核版本。构建与发布流程简化，团队不再维护 22.04/24.04 双镜像线，镜像内部工具链（如 gdrcopy）随之切换。影响范围限于 Docker 镜像构建与发布主线，不涉及业务代码。
- 风险标记：基础镜像升级影响全量容器用户 , 宿主内核下限依赖 GPU 驱动版本 , gdrcopy 版本需与 Ubuntu 版本联动 , 无独立测试，依赖 CI 镜像构建验证

# 关联脉络

- PR #50805 [ROCm][CI] Baseline legacy extensions in the Torch ABI audit: 同属构建 /CI 基础设施维护方向，但无直接文件交集，仅作背景关联。