文档中心

Appearance

✨费用中心控制台

基于 Dockerfile 构建自定义镜像 ​

提示

本文中的平台预置镜像地址是示例。使用前，请在镜像中心或当前实例的预置镜像列表中确认当前可用区提供了对应仓库及 tag；如果列表中不存在，请改用页面显示的可用镜像地址。替换 Registry 域名并不能保证相同仓库或 tag 在其他环境或可用区中存在。

基于 Dockerfile 适合需要版本化镜像定义、精确控制镜像层、配置 ENTRYPOINT / CMD / ENV，或复用一份长期维护的镜像构建脚本的场景。

这种方式同样会在镜像中心执行一次受控的镜像构建任务，并把构建结果直接保存到租户私有镜像仓库。与基于现有镜像构建自定义镜像相比，这种方式更适合把构建逻辑完整写成一份 Dockerfile。

警告

首次在镜像中心构建镜像前，租户必须先完成个人认证或企业认证。如果未完成认证就点击 构建镜像 按钮，会提示错误：Invalid operation [building image is not allowed for this tenant]

构建镜像

选择基础镜像 ​

  1. 进入镜像中心，切换到 自定义镜像 标签页，点击 构建镜像。
  2. 填写镜像名称、Tag、可用服务和可用区。
  3. 在 构建方式 中选择 基于 Dockerfile。

如果您已经确定目标运行环境，建议优先选择一个最接近目标环境的基础镜像地址作为 FROM 起点，例如平台预置 Ubuntu、CUDA、PyTorch 或已有自定义镜像。

编写 Dockerfile ​

在镜像中心的 Dockerfile 输入框中，直接粘贴完整的 Dockerfile 内容即可。建议先从最小可用版本开始，再逐步增加依赖和配置。

从现有镜像开始 ​

推荐使用 FROM ＜image＞ 明确指定基础镜像。例如：

language-dockerfile
FROM cr.infini-ai.com/infini-ai/ubuntu:22.04-20240429

如果您需要复用平台预置镜像或租户已有自定义镜像，请先在镜像中心确认镜像地址，再写入 Dockerfile。

安装系统依赖 ​

推荐把系统依赖安装写入 RUN 指令，并尽量使用非交互式安装方式。例如：

language-dockerfile
RUN apt-get update \
    && DEBIAN_FRONTEND=noninteractive apt-get install -y curl jq python3-pip \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

安装语言依赖 ​

安装 Python 或其他语言运行时依赖时，建议显式指定命令、版本和清理策略。例如：

language-dockerfile
RUN python3 -m pip install --no-cache-dir "xinference[vllm]"

写入环境变量和配置 ​

如果您希望环境变量直接成为镜像的一部分，推荐使用 ENV。如果您需要生成配置文件，也可以通过 RUN 或 heredoc 写入。例如：

language-dockerfile
ENV UV_LINK_MODE=copy

RUN cat > /etc/profile.d/10-project-env.sh <<'EOF'
export UV_LINK_MODE=copy
EOF

设置启动命令 ​

如果您的镜像需要预设启动行为，可以使用 Dockerfile 的 ENTRYPOINT 或 CMD。但最终是否能直接用于开发机、任务或推理服务，还需要结合平台实际启动方式验证。

例如：

language-dockerfile
CMD ["python3", "--version"]

减少镜像体积 ​

建议把清理缓存、删除临时文件等步骤写入 Dockerfile，避免无意义地增加镜像体积。例如：

  • 清理 apt 缓存
  • 为 pip 使用 --no-cache-dir
  • 删除仅构建阶段需要的临时文件

在镜像中心填写 Dockerfile ​

编写完成后，将 Dockerfile 全文粘贴到镜像中心的 Dockerfile 输入框即可。

如果您希望从一份现成示例出发，平台已提供部分可直接复制的 Dockerfile：

补齐开发机基础组件 ​

如果您计划将新镜像用于开发机，请在 Dockerfile 中一并安装基础组件。否则平台虽然会尝试自动修复，但仍可能导致开发机无法正常启动，或 SSH 登录功能受限。

  • 基于 Ubuntu 22.04 的自定义镜像：

    language-dockerfile
    RUN apt-get update \
    && DEBIAN_FRONTEND=noninteractive apt-get install -y openssh-server sudo runit runit-systemd

  • 基于 Ubuntu 24.04 的自定义镜像：

    language-dockerfile
    RUN apt-get update \
    && DEBIAN_FRONTEND=noninteractive apt-get install -y openssh-server sudo runit runit-helper runit-run

检查哪些 Dockerfile 写法适合镜像中心 ​

镜像中心中的 Dockerfile 构建更适合以下类型的写法：

  • 只依赖基础镜像和网络下载内容的 Dockerfile
  • 能够从头自动构建、无需人工干预的 Dockerfile
  • 安装、配置、清理步骤都写在 Dockerfile 中的可重复构建流程

如果您希望让镜像构建更稳定，建议：

  • 使用明确的版本号
  • 把高频变化步骤放在后面
  • 避免把临时调试命令长期保留在 Dockerfile 中

检查哪些场景不适合只用 Dockerfile ​

需要 COPY 本地文件时改用开发机内构建 ​

在镜像中心中，您只能粘贴 Dockerfile 文本，不能直接把本地目录、共享存储目录或开发机文件作为构建上下文上传。如果您需要使用 COPY 打包应用代码、配置文件或模型文件，请改用在开发机内构建自定义镜像。

需要本地构建上下文时改用开发机内构建 ​

如果您的 Dockerfile 依赖本地构建上下文，例如：

  • 多个本地文件协同构建
  • 本地脚本、二进制、压缩包
  • 需要 docker build 当前目录内容

也应改用在开发机内构建自定义镜像。

需要直接保存当前环境时改用现有开发机 ​

如果您不是想维护一份 Dockerfile，而是想直接固化当前开发机里已经调试好的环境，请改用基于现有开发机构建自定义镜像。

查看构建日志 ​

构建开始后，镜像会出现在 自定义镜像 标签页中。点击列表中的 构建日志，即可查看完整日志。

建议按以下顺序排查：

  1. 先看失败发生在哪一条 Dockerfile 指令。
  2. 再看是否是网络、软件源、命令语法或依赖下载问题。
  3. 如果构建时间过长，请检查是否执行了不必要的大型编译步骤，或依赖了缓慢的外部下载。

验证新镜像 ​

镜像状态变为 构建成功 后，建议先做一次小范围验证，再大规模复用：

  1. 用新镜像创建一个测试开发机、任务或推理服务。
  2. 验证关键软件、脚本、环境变量和启动命令是否符合预期。
  3. 如果镜像将用于开发机，重点验证 SSH 登录、启动速度和基础命令是否正常。
  4. 验证通过后，再将该镜像用于更多资源池或团队环境。