📚 课程目录第4章 Jetson容器镜像基础

4. Jetson容器镜像基础

在Jetson上做容器化部署，第一件事不是写Dockerfile，而是搞清楚“镜像从哪来、由什么组成、为什么必须是ARM64、标签怎么选”。这四点决定了后续所有构建与运行能否成功。Jetson的容器镜像与普通x86服务器镜像最大的区别在于：它必须与板载的L4T（Linux for Tegra）版本、CUDA驱动、JetPack版本严格对应，否则会出现驱动不匹配、GPU不可用甚至容器无法启动的问题。

一、L4T基础镜像从哪里获取

L4T是NVIDIA为Tegra系列SoC提供的Linux BSP（板级支持包），包含内核、驱动、CUDA、cuDNN、TensorRT等组件。Jetson容器的基础镜像本质上就是“L4T根文件系统 + 容器运行时所需的最小用户空间”。获取途径主要有三类：

NVIDIA NGC官方镜像仓库：如 nvcr.io/nvidia/l4t-base:r35.4.1、nvcr.io/nvidia/l4t-cuda:11.4.19-runtime、nvcr.io/nvidia/l4t-pytorch:r35.4.1-pth2.0-py3。这是最推荐的方式，镜像已针对Jetson做过ARM64适配与驱动对齐。
NVIDIA官方文档提供的Dockerfile模板：在Jetson Linux Developer Guide中，NVIDIA给出了基于 nvcr.io/nvidia/l4t-base 自行构建CUDA、cuDNN、TensorRT镜像的Dockerfile，适合需要裁剪或定制组件的场景。
本地已有镜像导出：通过 docker save 将已调通的镜像打包为tar，再 docker load 到离线设备，适合无外网的产线环境。

拉取前建议先确认板端L4T版本，命令为 cat /etc/nv_tegra_release，输出中 R35 (release), REVISION: 4.1 即对应r35.4.1。镜像标签中的 r35.4.1 必须与板端一致，否则CUDA驱动层会拒绝加载。

二、镜像分层结构：为什么Jetson镜像“又大又讲究”

Docker镜像由一系列只读层叠加而成，每一层对应Dockerfile中的一条指令。Jetson镜像的分层有其特殊性：底层是L4T根文件系统（约1.5～2GB），其上依次叠加CUDA运行时、cuDNN、TensorRT、Python环境、应用代码。理解分层对优化构建和排查问题非常关键。

以 l4t-pytorch:r35.4.1-pth2.0-py3 为例，其分层大致为：L4T base → CUDA runtime → cuDNN → TensorRT → PyTorch wheel → 示例代码。当你在Dockerfile中执行 RUN pip install 时，只会在最上层新增一层，不会破坏底层驱动层。这也是为什么“容器内升级CUDA”几乎不可能成功——CUDA驱动与内核模块在L4T base层，容器无法替换宿主内核。

判断镜像层是否被复用，可用 docker history <image> 查看每层大小与创建指令。若发现某一层异常大（如超过2GB），通常是pip安装时未清理缓存或把数据集打进了镜像。

三、ARM64架构适配：不是“换个平台”那么简单

Jetson是ARM64（aarch64）架构，而绝大多数开发机是x86_64。这意味着：在x86上 docker build 出来的镜像默认是amd64，直接推到Jetson上会报 exec format error。适配ARM64有三条路径：

在Jetson本机构建：最直接，docker build 默认产出aarch64镜像，无需额外配置。
在x86上使用buildx交叉构建：docker buildx build --platform linux/arm64 -t myimg:1.0 .，需要QEMU模拟，构建速度较慢，且部分依赖（如TensorRT）在模拟环境下可能编译失败。
使用NVIDIA NGC的ARM64基础镜像：直接 FROM nvcr.io/nvidia/l4t-base:r35.4.1，避免从零搭建ARM64用户空间。

此外，Python wheel、apt源、pip源都必须使用aarch64版本。例如安装PyTorch时不能直接 pip install torch，而应使用NVIDIA提供的Jetson专用wheel，或从 https://developer.download.nvidia.com/compute/redist/jp/ 获取对应版本。

四、镜像标签与版本管理：把“对应关系”固化下来

NGC上的Jetson镜像标签通常遵循 r<L4T版本>-<组件><版本>-<语言><版本> 的命名规则。例如 r35.4.1-pth2.0-py3 表示L4T r35.4.1、PyTorch 2.0、Python 3。这种命名把“板端BSP版本”和“容器内软件版本”绑定在一起，避免混用。

在实际项目中，建议建立一张版本对应表，把JetPack、L4T、CUDA、cuDNN、TensorRT、PyTorch、镜像标签一一列出。例如：JetPack 5.1.2 → L4T r35.4.1 → CUDA 11.4 → cuDNN 8.6 → TensorRT 8.5 → PyTorch 2.0 → 镜像标签 r35.4.1-pth2.0-py3。当板端升级JetPack时，镜像标签必须同步升级，不能只改应用代码。

对于自建镜像，推荐使用“基础镜像标签 + 应用版本”的双段标签，如 myapp:r35.4.1-v1.2.0，并在Dockerfile中显式写死基础镜像的完整标签，避免使用 latest。因为 latest 在不同时间拉取可能对应不同L4T版本，导致产线设备行为不一致。

不要在同一台Jetson上混用不同L4T版本的容器镜像。例如板端为r35.4.1，却运行r35.2.1的镜像，CUDA驱动层会因ABI不匹配而报 CUDA driver version is insufficient for CUDA runtime version。排查时先用 cat /etc/nv_tegra_release 确认板端版本，再核对镜像标签。

五、一次可复现的拉取与验证流程

下面给出一个在Jetson上拉取并验证L4T基础镜像的最小流程，参数为示例，实际请按板端版本替换。

# 1. 确认板端L4T版本
cat /etc/nv_tegra_release
# 输出示例：R35 (release), REVISION: 4.1, GCID: 32630139, ...

# 2. 登录NGC（需NVIDIA账号并生成API Key）
docker login nvcr.io
# Username: $oauthtoken
# Password: <你的NGC API Key>

# 3. 拉取与板端匹配的L4T基础镜像
docker pull nvcr.io/nvidia/l4t-base:r35.4.1

# 4. 验证架构与基础环境
docker run --rm --runtime nvidia nvcr.io/nvidia/l4t-base:r35.4.1 \
  bash -c "uname -m && cat /etc/nv_tegra_release"

# 期望输出：aarch64 以及 R35 (release), REVISION: 4.1

验证时重点关注两点：uname -m 必须输出 aarch64；--runtime nvidia 必须能正常挂载GPU设备。若报 unknown runtime nvidia，说明 /etc/docker/daemon.json 中未配置nvidia runtime，需先执行 sudo nvidia-ctk runtime configure --runtime=docker 并重启Docker。

完成这一步后，你就拥有了一个与板端L4T严格对齐的ARM64基础镜像。后续所有应用镜像都应基于它或它的衍生镜像构建，并在标签中保留L4T版本信息，形成可追溯、可复现的版本管理链路。