📚 课程目录第4章容器镜像构建与优化

4. 容器镜像构建与优化

IGX Orin 平台的计算核心是 ARM64 架构的 NVIDIA Grace 或 Orin SoC，其 GPU 驱动、CUDA 运行时与 TensorRT 库都以 aarch64 版本分发。这意味着在 x86 开发机上直接 docker build 得到的镜像无法在 IGX 上运行，必须显式指定目标平台并选用 ARM64 基础镜像。本节围绕“如何构建一个能在 IGX 上稳定运行、体积可控、版本可复现的推理镜像”展开，重点讲清多阶段构建的组织方式、CUDA 与 TensorRT 依赖的安装顺序，以及镜像瘦身与版本锁定的具体手段。

一、ARM64 镜像构建的基本约束

构建 ARM64 镜像有三条路径：在 IGX 设备本机直接构建、在 ARM64 服务器上构建、在 x86 主机上通过 QEMU 模拟或交叉构建。本机与 ARM64 服务器构建速度最快，但 CI 环境通常只有 x86 机器，因此需要启用 buildx 并注册 binfmt 模拟器：

# 在 x86 构建机上注册 QEMU 模拟器（一次性）
docker run --privileged --rm tonistiigi/binfmt --install arm64

# 创建并使用支持多平台的 builder
docker buildx create --name igx-builder --use
docker buildx inspect --bootstrap

# 构建并加载到本地，目标平台为 linux/arm64
docker buildx build \
  --platform linux/arm64 \
  --tag igx-infer:0.1.0 \
  --load .

需要注意，QEMU 模拟下 RUN 指令的执行速度可能只有原生构建的十分之一到五分之一，因此应尽量把耗时的编译步骤放在 ARM64 原生节点上，或通过 --cache-from 复用远端缓存。另一个常见坑是基础镜像的 manifest 选择：nvcr.io/nvidia/l4t-cuda:12.2.12-runtime 这类标签本身已限定 aarch64，而 nvidia/cuda:12.2.0-runtime 是多架构 manifest，必须配合 --platform 才会拉取 ARM64 变体，否则会静默拉到 x86_64 层，最终在 IGX 上以 exec format error 启动失败。

二、多阶段构建：把编译工具链留在构建阶段

推理镜像里真正需要的是运行时库和模型文件，而不是 gcc、cmake、头文件和 pip 缓存。多阶段构建的核心思路是：在 builder 阶段完成依赖编译与 wheel 构建，在 runtime 阶段只拷贝产物。下面是一个面向 IGX 的典型骨架，builder 使用带完整 CUDA 开发工具链的镜像，runtime 使用仅含运行时库的镜像：

# ---------- 阶段 1：builder ----------
FROM nvcr.io/nvidia/l4t-cuda:12.2.12-devel AS builder
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
      python3-pip python3-dev build-essential cmake git \
    && rm -rf /var/lib/apt/lists/*
WORKDIR /build
COPY requirements.txt .
# 编译带 CUDA 扩展的 Python 包，产物落到独立目录
RUN pip3 install --no-cache-dir --prefix=/install -r requirements.txt

# ---------- 阶段 2：runtime ----------
FROM nvcr.io/nvidia/l4t-cuda:12.2.12-runtime AS runtime
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
      python3 python3-distutils libgomp1 \
    && rm -rf /var/lib/apt/lists/*
# 只拷贝已编译好的 Python 包，不带编译器与源码
COPY --from=builder /install /usr/local
WORKDIR /app
COPY app/ /app/
COPY models/ /models/
ENV PYTHONUNBUFFERED=1
ENTRYPOINT ["python3", "/app/serve.py"]

这里的关键判断是“哪些东西必须在 builder 里做”。凡是需要 nvcc、头文件或编译器的步骤——例如编译自定义 TensorRT 插件、构建 pycuda 扩展、量化校准工具——都应放在 builder；凡是纯 Python 依赖、模型权重、配置文件，可以直接在 runtime 阶段安装或拷贝。把 pip install 的 --prefix 指向 /install 再整体拷贝，可以避免把 pip 缓存和 .egg-info 带进最终镜像。

三、CUDA 与 TensorRT 依赖管理

IGX 上的 CUDA 与 TensorRT 版本必须与设备端 L4T（Linux for Tegra）BSP 中的驱动版本匹配。驱动由宿主系统提供，容器内只装用户态运行时，因此镜像里不应再安装 nvidia-driver 或 libcuda.so 的驱动部分。依赖安装顺序建议为：先 CUDA runtime，再 cuDNN，再 TensorRT，最后才是上层框架（PyTorch / TensorRT Python API）。TensorRT 的 Python 绑定在 ARM64 上通常通过 tensorrt wheel 或 L4T 自带的 python3-libnvinfer 包提供，二者不要混装，否则会出现 libnvinfer.so 版本冲突。

版本锁定是这一节最容易被忽视、却最影响可复现性的部分。基础镜像不要用 latest，应写成 l4t-cuda:12.2.12-runtime 这样的精确标签；Python 依赖用 requirements.txt 固定到补丁号，并配合哈希校验：

# requirements.txt（节选，示例版本）
tensorrt==8.5.2.2
pycuda==2022.2.2
numpy==1.24.4
opencv-python-headless==4.8.1.78

如果使用 pip install --require-hashes，还需为每个包附上 --hash=sha256:...，这样即使上游重新发布同名版本，构建结果也不会漂移。对于从源码编译的 TensorRT 插件，应在镜像标签或环境变量中记录对应的 TensorRT 版本，例如 ENV TRT_VERSION=8.5.2.2，便于运行时自检。

四、镜像瘦身：从 8 GB 到 3 GB 的常见手段

一个未经优化的 IGX 推理镜像很容易超过 8 GB，主要来自 devel 基础镜像、apt 缓存、pip 缓存和重复的 CUDA 库。瘦身不是简单删文件，而是按“层”来设计。以下手段按收益从高到低排列：

换用 runtime 基础镜像：devel 与 runtime 镜像体积差通常在 3～5 GB，这是最大的一笔。
合并 apt 操作并清理：apt-get update && apt-get install && rm -rf /var/lib/apt/lists/* 必须写在同一条 RUN 里，否则删除动作发生在下一层，缓存仍然留在镜像中。
pip 使用 --no-cache-dir，并在多阶段构建中通过 --prefix 只拷贝安装结果。
删除测试与文档：TensorRT 的 samples、doc、python/tensorrt_dispatch 等目录在推理镜像中通常无用，可在 COPY 后用 rm -rf 清理。
模型权重外置：把 /models 改为运行时挂载卷，镜像只保留代码，可再省下数百 MB 到数 GB。

瘦身之后必须验证功能没有缺失。推荐用 docker run --rm igx-infer:0.1.0 python3 -c "import tensorrt; print(tensorrt.__version__)" 做最小导入检查，再跑一次真实推理请求，确认 libnvinfer.so、libcudart.so 都能被动态链接器找到。可以用 ldd 检查关键 so 的解析情况，若出现 not found，说明瘦身时误删了运行时库。

五、版本锁定与可复现构建

版本锁定要覆盖四个层面：基础镜像标签、系统包、Python 包、模型文件。基础镜像建议同时记录标签与 digest，例如 nvcr.io/nvidia/l4t-cuda:12.2.12-runtime@sha256:...，这样即使上游重推同名标签，构建结果也不变。系统包可通过 apt-get install pkg=version 固定，或在构建后导出 dpkg -l 清单存档。Python 包用 requirements.txt 加哈希。模型文件记录 SHA256 并在启动时校验。

建议在镜像中写入构建元数据，便于运维排查：LABEL org.igx.cuda="12.2.12" org.igx.trt="8.5.2.2" org.igx.arch="arm64"。远程运维时用 docker inspect 即可确认设备上运行的镜像是否与预期版本一致。

不要在 IGX 容器内安装 NVIDIA 驱动或 nvidia-container-toolkit 的宿主组件。容器只负责用户态 CUDA/TensorRT，驱动由 L4T BSP 提供。混装驱动会导致 CUDA driver version is insufficient for CUDA runtime version 一类错误，且难以在容器内修复。

把上述内容串起来，一个可复现的构建流程是：固定基础镜像 digest → builder 阶段编译并安装依赖到 /install → runtime 阶段只拷贝产物与代码 → 清理 apt/pip 缓存与无用目录 → 写入版本 LABEL → 用 docker buildx build --platform linux/arm64 产出镜像 → 在 IGX 上做导入与推理冒烟测试。这样得到的镜像既能在 ARM64 上正确运行，又具备可追溯的版本信息，体积也控制在合理范围内，适合后续批量部署到多台 IGX 设备。