构建自定义镜像

自定义镜像用于沉淀自有运行环境。当内置镜像不满足框架版本、系统依赖、Python 包或工具链要求时，您可以基于已有镜像、Dockerfile、第三方镜像仓库或已构建镜像创建自定义镜像。构建完成后，自定义镜像可在开发环境、训练任务和推理服务中选择使用。

镜像命名与 URL

自定义镜像通常通过名称、版本和提交 ID 区分不同迭代。镜像 URL 由镜像仓库地址、项目名称、镜像名称、版本和提交 ID 组成：

<harbor_url>/<project_name>/<name>:<version>-<commit_id>

字段	说明
`harbor_url`	镜像仓库地址，由平台根据区域和集群生成。
`project_name`	镜像仓库项目，通常由平台根据租户或项目归属生成。
`name`	镜像名称。建议使用小写英文、数字、中划线或下划线，并能体现框架、用途或项目。
`version`	镜像版本，用于管理同一镜像的不同版本。
`commit_id`	镜像标签或提交标识，用于区分同名同版本下的不同迭代。

同一名称和版本下可以有多个标签版本。创建开发环境、训练任务或推理服务时，通常按镜像名称和版本选择镜像；如果同一版本存在多个标签，以当前页面实际选择和展示的镜像 URL 为准。

创建自定义镜像

构建镜像会消耗实例资源。创建前，请确认当前区域和集群有可用的构建资源，并关注镜像仓库存储用量。若镜像后续需要在多个集群使用，请在创建或构建完成后配置镜像同步。

1. 进入创建页

进入 镜像管理 > 自定义镜像。
在 可用镜像列表 页签，单击新建。

2. 填写配置信息

基本信息

配置项	说明
区域	选择镜像构建所在区域。
集群	选择镜像构建所在集群。
分享项目组	配置镜像可见范围。需要共享给其他项目组时，单击新增项目组添加；不添加时，通常按构建用户所在项目组的默认范围授权。
名称	镜像名称。建议使用小写英文、数字、中划线或下划线，并能表达框架、用途或项目。
版本	镜像版本，用于同一镜像的多版本管理。建议使用稳定、可排序的版本号，避免使用空格、斜杠或特殊符号。
提交 ID	镜像标签或代码提交标识，用于区分同名同版本的不同迭代。建议使用代码仓库提交 ID 的前几位，便于追溯来源。
镜像类型	镜像分类，例如 `pytorch`、`base`、`python`、`LLM` 等，以对镜像进行分类和管理。
标签	用于检索和归类镜像。
描述	说明镜像来源、用途、框架版本、依赖或使用限制。

运行信息

配置项	说明
资源类型	选择构建任务使用的资源计费类型，例如预留实例、按量实例或 Spot。
实例	使用预留实例时，选择资源池。
实例类型、数量	支持 GPU 和 CPU。在实例列表中勾选构建任务使用的实例规格，并配置单节点实例规格数。选择实例时，重点关注用户剩余配额和资源池可用量。
资源优先级	勾选实例后配置调度优先级。按优先级从高到低排序，调度时优先使用排在前面的实例。

编译配置

先选择编译方法，再填写对应的构建配置。

基于已有镜像
基于编译文件
第三方镜像仓库
导入现有镜像

基于已有镜像适合在内置镜像或已有自定义镜像上补充依赖。

配置项	说明
基础镜像	选择内置或自定义镜像作为基础镜像。
依赖库包	添加系统依赖和 Python 依赖，支持以下方式：在 apt 中添加系统包，例如 `vim`。在 pip3 中添加 Python 3 依赖和版本。上传 `apt.txt`、`pip.txt` 批量导入依赖。

apt.txt 和 pip.txt 是文本文件，每行填写一个依赖项。依赖安装方式需要与基础镜像匹配。apt 通常适用于 Ubuntu 系统依赖，yum 通常适用于 CentOS 系统依赖；pip2 和 pip3 分别对应 Python 2 和 Python 3 依赖。

apt.txt 示例：

python3=3.8.2-0ubuntu2
python3-pip=20.0.2-5ubuntu1.11
curl=7.68.0-1ubuntu2.25
wget=1.20.3-1ubuntu2.1

pip.txt 示例：

requests==2.31.0
flask==2.3.3

基于编译文件适合通过 Dockerfile 沉淀完整构建逻辑。选择该方式后，请填写 Dockerfile 内容和构建参数。构建参数用于在构建过程中动态传入变量，并在 Dockerfile 中引用。如果需要安装 apt 或 pip 依赖，可以使用以下方式：

直接在 Dockerfile 中编写安装命令。
在依赖库包中添加依赖，或上传 apt.txt、pip.txt。平台返回对应安装命令后，将命令复制到 Dockerfile 中的适当位置。

示例：

FROM ubuntu:18.04

RUN apt-get update && apt-get install -y --no-install-recommends \
    python3-pip \
    vim && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

RUN pip3 install \
    numpy==1.19.5 \
    scipy==1.5.4

RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime

当前暂不支持在构建过程中将内容复制到共享目录中。如果构建依赖大文件、私有代码或模型文件，建议先确认这些内容是否应放入镜像，还是通过 Volume 在负载运行时挂载。

3. 提交创建

配置完成后，单击新建提交构建任务。提交后，您可以在 构建任务列表 中查看构建状态和构建日志。构建成功后，镜像会出现在 可用镜像列表 中。

从开发环境保存镜像

您也可以将开发环境保存为自定义镜像。该操作适合把已经调试好的开发环境沉淀为可复用镜像；保存完成后，可回到镜像管理中查看和管理。保存镜像期间，开发环境可能暂时不可用。建议在无交互操作时执行，并确认需要保留的文件、依赖和配置已经写入镜像或持久化存储。具体操作请参考使用 JupyterLab 开发环境或使用 VSCS 开发环境。

查看构建结果

构建任务提交后，在 构建任务列表 中查看状态。构建失败时，优先查看构建日志中的报错，再结合调度信息判断是依赖安装、Dockerfile、镜像拉取、资源调度还是同步配置导致失败。

操作	说明
编译日志	查看镜像构建日志。构建失败时，优先通过日志定位依赖安装、Dockerfile、镜像拉取或命令执行问题。
编译配置	查看构建任务的配置，包括基础镜像、Dockerfile、依赖组件、构建参数和资源配置等。
更新配置	修改构建任务配置。更新前请确认镜像不在构建中，等待构建成功、失败或停止后再操作。更新影响通常如下：名称、版本、构建区域和构建集群通常不可修改。修改构建方式、基础镜像、Dockerfile、构建参数、依赖、同步配置、提交 ID、实例配置或资源池等构建相关字段，可能会触发重新构建。只修改描述、镜像类型、框架版本、Python / CUDA / NCCL 版本、芯片类型、标签或项目组等元数据，通常不需要重新构建。通过开发环境保存或镜像仓库同步生成的镜像，可能只允许更新元数据。
查看镜像	跳转查看构建完成后生成的镜像。若构建尚未成功，可能无法查看可用镜像。
克隆	基于当前构建任务的配置创建新的构建任务，适合复用基础镜像、依赖和构建参数。
停止	停止正在进行的构建任务。停止后镜像不会继续构建，是否已有可用镜像以当前构建结果为准。
删除	删除不再需要的构建任务记录。删除前，请确认不再需要查看该任务的构建日志或配置。

后续操作

管理自定义镜像

开始使用

资源准备

开发与训练

模型与推理

运维与治理

开发者接入

构建自定义镜像

镜像命名与 URL

创建自定义镜像

1. 进入创建页

2. 填写配置信息

基本信息

运行信息

编译配置

3. 提交创建

从开发环境保存镜像

查看构建结果

后续操作

​镜像命名与 URL

​创建自定义镜像

​1. 进入创建页

​2. 填写配置信息

​基本信息

​运行信息

​编译配置

​3. 提交创建

​从开发环境保存镜像

​查看构建结果

​后续操作

镜像命名与 URL

创建自定义镜像

1. 进入创建页

2. 填写配置信息

基本信息

运行信息

编译配置

3. 提交创建

从开发环境保存镜像

查看构建结果

后续操作