Docker Sandboxes

IMPORTANT

GPU 直通仍处于实验阶段。--gpu 标志、驱动捆绑包以及本页的设置步骤都可能发生变化。

本地 Docker Sandboxes 中的 GPU 直通让工作负载运行在物理 NVIDIA GPU 上。

Docker 沙箱中的 GPU 直通通过 VFIO 实现，这是一项 Linux 特性，可把 PCI 设备直接分配给虚拟机。GPU 绑定到 VFIO 而不是 宿主机驱动，沙箱内的工作负载自行驱动该硬件。

环境要求 ​

基于 VFIO 的 GPU 直通仅支持配备 NVIDIA GPU 的 x86_64 Linux 宿主机（不支持 Arm）， 并且要求这块 GPU 没有被其他任何东西占用：带 GPU 的无头宿主机，或一块额外的 GPU。

宿主机还需要在 BIOS 中开启 IOMMU，并加载 iommufd 和 vfio_pci 内核模块：

console
sudo modprobe -a iommufd vfio_pci

要让沙箱驱动该 GPU，需要：

  • 为 Docker Sandboxes 客户机内核构建的 nvidia 和 nvidia-uvm 内核模块
  • NVIDIA 用户态驱动库和固件

Docker Sandboxes 会在 /usr/libexec/nerdbox-nvidia-bundle.erofs 查找这些依赖， 它们被打包成 EROFS 镜像。该捆绑包不随 Docker Sandboxes 一起分发。要构建它， 请参阅构建捆绑包。

启用该功能 ​

在你开启实验性功能和 GPU 功能标志之前，--gpu 标志是隐藏的：

console
sbx settings set platform.allowExperimentalFeatures true
sbx settings set feature.sandbox-gpu true

构建捆绑包 ​

每个 Docker Sandboxes 发布版本都会附带一个包含构建捆绑包所需全部组件的 zip 压缩包， 名为 nerdbox-nvidia-modules-x86_64.zip。该压缩包包含内核模块（nvidia.ko 和 nvidia-uvm.ko）、它们构建时所针对的驱动版本（VERSION），以及一个构建脚本。

构建脚本会运行一个 linux/amd64 容器，下载匹配的 NVIDIA 驱动、组装捆绑包，并把它 安装到 /usr/libexec/nerdbox-nvidia-bundle.erofs。写入该路径需要 root 权限，因此 下面命令中带有 sudo。

前置条件：

  • 能访问 download.nvidia.com 的网络
  • Docker

下载并解压压缩包，然后在解压出的目录中运行脚本：

console
curl -fSLO https://github.com/docker/sbx-releases/releases/latest/download/nerdbox-nvidia-modules-x86_64.zip
unzip nerdbox-nvidia-modules-x86_64.zip -d nvidia-modules
cd nvidia-modules
sudo ./prepare-nvidia-bundle.sh

如果脚本无法写入输出路径，它会把捆绑包留在当前目录，并打印完成该工作所需的 install 命令。

有两个环境变量可以覆盖脚本的默认行为：

变量默认值用途
OUTPUT/usr/libexec/nerdbox-nvidia-bundle.erofs写入完成版捆绑包的位置。
ACCEPT_NVIDIA_LICENSE无设为 1 可在非交互方式下接受 NVIDIA 许可证，适用于脚本或 CI。

例如，下面的命令把完成版捆绑包写入 /mnt/some-place/nerdbox-nvidia-bundle.erofs：

console
OUTPUT=/mnt/some-place/nerdbox-nvidia-bundle.erofs ./prepare-nvidia-bundle.sh

安装捆绑包 ​

如果你在运行 GPU 沙箱的 x86_64 Linux 宿主机上运行了脚本，并且没有覆盖 OUTPUT， 捆绑包就已经就位。如果你在别处构建，请把它生成的 nerdbox-nvidia-bundle.erofs 文件 复制到那台宿主机的 /usr/libexec 目录。

运行带 GPU 的沙箱 ​

要运行带 GPU 直通的沙箱，传入 --gpu 标志：

console
sbx create --gpu claude .

sbx run 命令接受同样的标志：

console
sbx run --gpu claude

该标志在创建沙箱时生效。重新连接到已有沙箱时传入它不会产生任何效果。

IMPORTANT

每个 Docker Sandboxes 发布版本都使用特定的客户机内核。你的捆绑包中的 NVIDIA 内核模块必须与该内核匹配。升级 Docker Sandboxes 之后，请下载新发布版本的 nerdbox-nvidia-modules-x86_64.zip 压缩包，并再次运行脚本重新构建捆绑包。

故障排查 ​

脚本报告 ... not found in the driver download ​

解压得到的驱动中缺少预期的库文件或固件文件。确认下载已经完成。如果你的驱动版本中 某个库的名称不同，请在脚本中调整 DRIVER_LIB_FAMILIES。

升级 Docker Sandboxes 后 GPU 工作负载失败 ​

客户机内核或固定的驱动版本很可能发生了变化。下载新发布版本的压缩包，重新运行脚本， 并重新安装捆绑包。