在开发机中使用 Dockerfile 构建镜像
当无法访问公共 Docker 镜像仓库时，我们仍然可以通过平台预置镜像、导入镜像 tar 包（docker load） 等方式获取一个基础镜像。通过 Dockerfile 和 docker build，在这个基础镜像之上，添加我们自己的应用程序代码、依赖包和特定配置，将其构建成一个包含所有定制化内容、真正可运行的最终镜像。
在启用了「Docker 容器」功能的开发机上，支持使用 Dockerfile 和 docker build 构建镜像。
何时使用开发机内 docker build?
平台镜像中心提供了粘贴 Dockerfile 构建镜像功能（详见镜像中心 · 构建自定义镜像），您也可以在自己的开发机使用 docker build，两种方式各有适用场景。
本地 docker build 适合以下场景:
- 需要打包您的代码 - 如果需要使用
COPY命令将本地的应用程序、配置文件等打包进镜像，必须使用本地构建。在平台镜像中心构建镜像时，只能粘贴 Dockerfile 文本，无法访问您的项目文件。 - 需要高级构建特性 - 如果需要使用多阶段构建、构建参数、BuildKit 等高级功能,本地构建提供更完整的支持。
- 需要高效调试和迭代 - 本地构建失败时立即看到错误，修改后可秒级重试。适合需要反复调试 Dockerfile 的场景。
- 需要较长构建时间- 在开发机中构建不限制单个镜像构建总时长。
注意
利用开发机构建镜像时，运行中的开发机会独占用显卡资源。如果您使用的包年包月资源，可以考虑使用共享开发机。
镜像中心适合以下场景:
- 便利性：提供基于 Dockerfile、基于现有镜像安装软件、基于现有开发机构建镜像多种构建方式，构建后直接推送至租户私有镜像仓库。
- 低成本：使用镜像中心构建镜像为免费功能，且不会占用任何显卡资源（注意构建过程中无法访问 GPU）。
注意
镜像中心限制构建时长为 1 小时。超时后直接失败。如遇到超时问题，请检查是否存在耗时网络操作，尝试拆分构建过程。
环境要求
要求开发机已启用「Docker 容器」功能。
强烈推荐先安装
buildx，因为它基于更先进的 BuildKit 引擎，能提供更快的构建速度、更强大的功能以及旧版构建器所不支持的多平台镜像构建能力。详见 Buildkit。shellmkdir -p /usr/local/lib/docker/cli-plugins && curl -sSL https://ghfast.top/https://github.com/docker/buildx/releases/download/v0.29.1/buildx-v0.29.1.linux-amd64 -o /usr/local/lib/docker/cli-plugins/docker-buildx chmod +x /usr/local/lib/docker/cli-plugins/docker-buildx
自助构建 CUDA 镜像
在理想情况下，由 NVIDIA 官方维护的 nvidia/cuda 镜像是不错的选择。官方提供了 base/runtime/devel 版本镜像，预先配置好了所有版本兼容、极其复杂的 CUDA 运行时和 GPU 加速库，既保证了功能完整性又优化了镜像大小。
然而，鉴于绕过网络限制来拉取 nvidia/cuda 镜像非常麻烦，另外，许多用户在尝试（在开发机上）自行安装 CUDA 二进制文件时，会因复杂的驱动和库依赖问题而遇到障碍。因此，我们提供了这份官方的 CUDA 镜像构建说明。
在本指南中，我们将以 CUDA 12.9.1 和 cuDNN 9.x 版本为例进行说明。
创建开发机，并打开「Docker 容器」功能。
在启用「Docker 容器」功能的开发机上，创建一个空目录。
shellmkdir build-cuda创建 Dockerfile。
shellcd build-cuda touch cuda.dockerfile写入以下内容，该 Dockerfile 将下载安装
CUDA Toolkit 12.9 Update 1runfile 和最新版 cudnn。dockerfileFROM cr.infini-ai.com/infini-ai/ubuntu:22.04-20240429 # 设置环境变量 # DEBIAN_FRONTEND=noninteractive 防止安装过程中的交互式提示 # PATH 添加CUDA可执行文件路径 # LD_LIBRARY_PATH 添加CUDA库文件路径 # CUDA_HOME 设置CUDA根目录 ENV PATH=/usr/local/cuda/bin:/usr/local/cuda-12.9/bin${PATH:+:${PATH}} \ LD_LIBRARY_PATH=/usr/local/cuda/lib64:/usr/local/cuda-12.9/lib64:/usr/lib/x86_64-linux-gnu${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} \ CUDA_HOME=/usr/local/cuda \ CPATH=/usr/include${CPATH:+:${CPATH}} \ LIBRARY_PATH=/usr/lib/x86_64-linux-gnu${LIBRARY_PATH:+:${LIBRARY_PATH}} # 安装CUDA并配置系统环境 # 1. 更新apt并安装必要工具 # 2. 清理apt缓存减小镜像体积 # 3. 下载CUDA安装包 # 4. 静默安装CUDA工具包（请勿安装 driver） # 5. 配置动态链接库搜索路径 # 6. 更新动态链接库缓存 # 7. 清理安装包 RUN apt-get update && \ DEBIAN_FRONTEND=noninteractive apt-get install -y wget build-essential \ && rm -rf /var/lib/apt/lists/* \ && wget https://developer.download.nvidia.com/compute/cuda/12.9.1/local_installers/cuda_12.9.1_575.57.08_linux.run \ && sh cuda_12.9.1_575.57.08_linux.run --toolkit --silent --override \ && echo '/usr/local/cuda/lib64' >> /etc/ld.so.conf \ && echo '/usr/local/cuda-12.9/lib64' >> /etc/ld.so.conf \ && ldconfig \ && rm cuda_12.9.1_575.57.08_linux.run # 安装cuDNN并配置环境 # 1. 下载并安装NVIDIA CUDA仓库公钥 # 2. 更新apt源 # 3. 安装cuDNN # 4. 配置额外的库路径 # 5. 更新动态链接库缓存 # 6. 清理安装包和apt缓存 RUN wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb \ && dpkg -i cuda-keyring_1.1-1_all.deb \ && apt-get update \ && apt-get install -y cudnn-cuda-12 \ && echo '/usr/lib/x86_64-linux-gnu' >> /etc/ld.so.conf \ && ldconfig \ && rm cuda-keyring_1.1-1_all.deb \ && rm -rf /var/lib/apt/lists/*以上 Dockerfile 基于平台预置的 Ubuntu 22.04 基础镜像。该基础镜像也可以替换为自己的 Ubuntu 22.04 镜像。
执行构建镜像命令。推荐提前安装 buildkit。
shellexport BUILDKIT_STEP_LOG_MAX_SIZE=-1 docker buildx build -f cuda.dockerfile -t cuda-12.9:latest . 2>&1 | tee build.log若未安装 buildkit，可替换为
docker build命令。等待构建完成，检查本地镜像：
shellroot@is-db2g2ndlc7dyv2ho-devmachine-0:~# docker images REPOSITORY TAG IMAGE ID CREATED SIZE cuda-12.9 latest ce071c4b4884 1 hours ago 14.9GB（可选）如需在可用区内共享该镜像，可推送至开发机所在可用区的租户私有镜像仓库。
shelldocker tag cuda-12.9:latest cr.infini-ai.com/infini-ai/cuda-12.9:latest docker push cr.infini-ai.com/infini-ai/cuda-12.9:latest
自助构建 SGLang 镜像
您可以先构建一个自定义基础镜像（例如如包含系统级 CUDA 和 cudnn 的镜像，见上文自助构建 CUDA 镜像），然后在后续多个项目中都 FROM cuda-12.9:latest 来构建，实现环境复用和标准化。例如，假设平台预置的 SGLang 镜像不满足您的要求，您可以在开发机内编写 Dockerfile，指定需要的 SGLang 版本。
在以下步骤中，复用上文自助构建 CUDA 镜像中的开发机环境。
创建一个空目录
sglang。shellcd ~ && mkdir sglang创建 Dockerfile。
shellcd sglang touch sglang.dockerfile写入以下内容，该 Dockerfile 将下载安装 SGLang 0.5.5。
dockerfile# 基于开发机本地构建的 cuda-12.9:latest 镜像 FROM cuda-12.9:latest # 设置 uv 使用清华镜像源 ENV UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple # 安装Python包 RUN pip install --no-cache-dir --upgrade pip && \ pip install --no-cache-dir uv && \ uv pip install --system --verbose --no-cache \ "sglang==0.5.5" --prerelease=allow && \ uv cache clean && \ rm -rf ~/.cache/pip执行构建镜像命令。推荐提前安装 buildkit。
shellexport BUILDKIT_STEP_LOG_MAX_SIZE=-1 docker buildx build -f sglang.dockerfile -t sglang:0.5.5 . 2>&1 | tee build.log若未安装 buildkit，可替换为
docker build命令。等待构建完成，检查本地镜像：
shellroot@is-db2g2ndlc7dyv2ho-devmachine-0:~# docker images REPOSITORY TAG IMAGE ID CREATED SIZE sglang 0.5.5 ce071c5b4883 1 hours ago 25.9GB（可选）如需在可用区内共享该镜像，可推送至开发机所在可用区的租户私有镜像仓库。
shelldocker tag sglang:0.5.5 cr.infini-ai.com/infini-ai/sglnag:0.5.5 docker push cr.infini-ai.com/infini-ai/sglnag:0.5.5
限制与注意事项
由于运营商网络原因，无法拉取 Docker Hub 镜像。建议在使用
FROM指定基础镜像时，谨慎使用 Docker Hub 的容器镜像。如果您有可用的代理服务，可使用
--build-arg方式指定代理，例如docker build --build-arg HTTP_PROXY=https://my-proxy.example.com .。Docker 容器服务支持修改 docker 服务配置，添加
proxies或regestry-mirrors等。修改后请重启服务。详见 Dockerctl。/etc/docker/daemon.json/tmp/docker-config/config.json（该文件在开发机重启后会复原，无法持久化保存修改）
注意
如果没有稳定可靠且经过测试的第三方镜像站，建议不要使用
proxies或regestry-mirrors这种方式。您可以设法获取镜像，然后存入平台的租户私有镜像仓库，后续从租户私有镜像仓库拉取可提供更好的速率和稳定性。
常见问题
如何导入我的私有镜像？
- 使用镜像 tar 文件，上传至开发机后，通过
docker load命令加载该镜像。 - 通过镜像 URL 从其他仓库镜像拉取（或需要仓库凭证）
详见迁移外部镜像。
如何拉取 Docker Hub 的镜像？
由于运营商网络原因，直接拉取 Docker Hub 镜像时会失败。建议：
注意
智算云平台不提供官方加速或代理服务。您可以自行使用第三方镜像加速服务。如需修改 Docker 容器服务的配置，详见 Dockerctl。