Jetson NX启动tetraai_service_nx容器报NVIDIA runtime错误如何解决

DevOps 小满

2026-8-26

问题场景与报错信息

运行环境：SSH连接NVIDIA Jetson NX设备，设备运行基于Ubuntu 18.04定制的Tegra系统
历史正常操作：执行docker exec -it tetraai_service_nx /bin/bash可正常进入名为tetraai_service_nx的目标容器
首次异常：执行上述容器进入命令时返回报错：
```
Error response from daemon: Container 0feeb9be5a251bb9ce45ed9a05d24a86e5a77ef9d93439c717fdef9f7a6560d4 is not running
```
经核对，返回的容器ID与目标容器ID完全匹配。

重启容器报错：执行容器重启操作时返回报错：

Error response from daemon: Cannot restart container tetraai_service_nx: failed to create shim: OCI runtime create failed: container_linux.go:380: starting container process caused: process_linux.go:545: container init caused: Running hook #0:: error running hook: exit status 1, stdout: , stderr: Auto-detected mode as 'csv' invoking the NVIDIA Container Runtime Hook directly (e.g. specifying the docker --gpus flag) is not supported. Please use the NVIDIA Container Runtime instead.: unknown

报错含义与故障根因

该报错和容器内部文件损坏、业务服务异常无直接关联，核心是NVIDIA容器运行时调用逻辑不符合Jetson Tegra系统要求，容器启动流程被runtime钩子主动拦截。

报错核心含义：NVIDIA容器运行时自动检测到当前工作在csv设备挂载模式，直接通过Docker --gpus参数调用NVIDIA容器钩子的方式不被Tegra系统支持，必须使用提前注册到Docker的NVIDIA标准运行时启动容器。
高频触发根因：
- Docker守护进程配置异常：/etc/docker/daemon.json中默认运行时未设置为nvidia，退回使用默认runc，而目标容器创建时携带了--gpus相关参数，触发直接调用钩子的禁止逻辑。该问题常出现在Docker版本升级、nvidia-container-toolkit组件升级、手动修改Docker配置之后。
- 容器启动参数冲突：Jetson为统一内存架构，GPU对所有容器默认全局可见，不需要使用x86平台常用的--gpus参数显式分配GPU资源，添加该参数反而会触发runtime校验失败。
- 组件安装异常：nvidia-container-runtime、nvidia-container-toolkit组件安装不完整或依赖缺失，导致钩子执行逻辑出错。
- 版本兼容性问题：宿主机L4T驱动版本和容器内CUDA、TensorRT、JetPack组件版本不匹配，触发runtime安全拦截。

分步解决方案

按优先级从高到低执行操作，每步完成后执行docker restart tetraai_service_nx验证容器是否能正常启动：

修复Docker守护进程运行时配置
编辑/etc/docker/daemon.json文件，确保配置包含正确的NVIDIA运行时注册与默认运行时设置，参考最小可用配置如下：
```
{
    "default-runtime": "nvidia",
    "runtimes": {
        "nvidia": {
            "path": "nvidia-container-runtime",
            "runtimeArgs": []
        }
    }
}
```
保存文件后依次执行以下命令重载配置、重启Docker服务：
```
sudo systemctl daemon-reload
sudo systemctl restart docker
```
校验NVIDIA容器组件安装状态
执行以下命令修复安装NVIDIA容器相关组件，解决依赖缺失、版本不匹配问题：
```
sudo apt-get update
sudo apt-get install -y --reinstall nvidia-container-toolkit nvidia-container-runtime
```
安装完成后重新执行上一步的Docker服务重启操作。

修复容器启动参数冲突
如果上述操作后仍报错，执行以下命令检查容器是否携带冲突的--gpus参数：

docker inspect tetraai_service_nx | grep -i gpu

若返回结果中存在--gpus相关配置，需要重新创建容器移除冲突参数（Jetson平台不需要该参数），操作步骤如下：

# 提交当前容器状态为临时镜像，保留容器内已部署的业务内容
docker commit tetraai_service_nx tetraai_service_nx:fixed
# 强制删除异常状态的旧容器
docker rm -f tetraai_service_nx
# 从docker inspect结果中复制原有容器的端口映射、目录挂载、环境变量等启动参数，重新创建容器，不要添加--gpus参数
docker run -d --name tetraai_service_nx [原有端口/挂载/环境变量参数] tetraai_service_nx:fixed

校验版本兼容性
执行head -n 1 /etc/nv_tegra_release查看宿主机L4T版本，确认容器内使用的CUDA、JetPack组件版本与宿主机L4T版本匹配。Jetson平台不支持容器内运行高于宿主机驱动支持版本的CUDA组件，若版本不匹配需更换对应L4T版本的基础镜像重新部署业务。

同类场景通用规避规则

Jetson全系列嵌入式设备上使用Docker时，不需要在docker run命令中添加--gpus参数，只要将Docker默认运行时设置为nvidia即可自动完成GPU组件挂载。
升级Docker、NVIDIA容器组件、系统包后，必须检查/etc/docker/daemon.json配置，避免升级流程覆盖自定义运行时配置。
不要直接使用x86架构的CUDA镜像部署在Jetson设备上，必须使用NVIDIA官方发布的对应L4T版本的JetPack容器镜像。

内容的提问来源于stack exchange，提问作者Xiaoyu Sun