构建自定义镜像

非预置镜像均称为自定义镜像。镜像中心提供了多种在网页端快速创建自定义镜像的选项。

信息

• 平台提供租户私有租户镜像仓库服务，可用于存储自定义镜像。
• 租户的自定义镜像，均会展示在镜像中心的 自定义镜像 标签页。如果在创建开发机、任务、推理服务时，无法在自定义镜像列表中无法找到自定义镜像，请检查创建实例的资源池与该镜像的 可用资源池 是否一致。

镜像大小限制

单个镜像大小不能超过 50 GiB。

镜像基础组件要求

如果您的镜像用于开发机，推荐在镜像中包含平台要求的必要组件：

以 Ubuntu 为例：

• 基于 Ubuntu 22.04 的自定义镜像，必须安装以下组件：

  apt update && apt install openssh-server sudo runit runit-systemd -y

• 基于 Ubuntu 24.04 的自定义镜像，必须安装以下组件：

  apt update && apt install openssh-server sudo runit runit-helper runit-run -y

如果镜像中缺失上述组件，在启动开发机时平台会尝试安装，但仍可能安装失败导致开发机无法正常启动，或 SSH 远程连接功能受限。以下为推荐的处理方案：

• 如果仅针对当前开发机作一次性修复，可直接安装基础组件，重启开发机。
• 推荐永久修复当前自定义镜像，操作方式：

  1. 在镜像中心构建自定义镜像，选择 基于现有镜像

  2. 在 安装命令 中输入以下安装命令，以 Ubuntu 22.04 为例：

     DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install openssh-server sudo runit runit-systemd -y

  3. 重启开发机，选择更新后的新版镜像。

在镜像中心快速构建镜像

AIStudio 镜像中心支持多种从网页端快捷创建自定义镜像的方式，包括基于现有的预置镜像或自定义镜像、基于 Dockerfile，或直接保存运行中的开发机为镜像。

这种方式构建的镜像将直接保存到租户私有镜像仓库，无需推送。

警告

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

构建镜像

切换到 自定义镜像 标签页后，点击 构建镜像。进入创建页面后，请根据页面提示，完成以下配置。

• 镜像名称及 tag：填写符合要求的名称与镜像标签。
• 可用服务：如果您希望镜像被用于开发机和任务，可根据需要进行勾选。
• 可用区：选择可使用该镜像的可用区。如果下拉列表只有一项，选择默认值即可。如果有多项，说明您的计算资源分布在多个可用区（例如，宁夏、广东等）。列表中的每一行为该可用区中的所有资源池，请选择希望使用该镜像的资源池。单次构建操作仅支持选择一个可用区的所有资源池。不同可用区的镜像不会自动同步，详见镜像仓库地址与可用区。
• 构建方式：自定义镜像的构建方式有如下三种，下文中提供了具体示例。

  方式	说明
  基于现有镜像	可使用平台预置镜像，或镜像中心的自定义镜像。在基础镜像上执行非交互式 Shell 命令，安装依赖、写入配置并生成新镜像。
  基于 Dockerfile	直接编写 Dockerfile。
  基于现有开发机	导出开发机 rootfs 并另存为自定义镜像，系统盘中的新增、修改和删除会保存在新镜像中。仅支持选择正在运行的开发机；保存开发机为镜像时，请停止开发机内的读写操作​。

基于现有镜像

如果您对某个现有的预置镜像或自定义镜像比较熟悉，需要继续安装软件、写入配置、补齐基础组件，推荐优先使用这种方式。

填写自定义镜像的基础信息后，选择 基于现有镜像，在 安装命令 输入框中编写需要执行的非交互式 Shell 命令即可。

详见基于现有镜像构建自定义镜像。

基于 Dockerfile

如果您希望把镜像构建步骤完整写成一份 Dockerfile，并精确控制基础镜像、环境变量、启动命令和镜像层，推荐优先使用这种方式。

详见基于 Dockerfile 构建自定义镜像。

基于现有开发机

如果您希望保存当前开发机中已经调试好的环境，以便快速复用，可直接将运行中的开发机保存为自定义镜像。

详见基于现有开发机构建自定义镜像。

管理构建结果

镜像构建开始后，在 自定义镜像 标签页中就会生成您的镜像。您可以在此关注构建进度、构建结果。在必要时，可通过构建日志排查问题。

查看镜像构建结果

构建镜像时间与具体操作有关，可能从几分钟到几十分钟不等。如果自定义镜像列表中 状态 变更为 构建成功，则表示镜像已经可以使用。

如果您关注自定义镜像构建进度与过程，可实时查看构建日志。

查看镜像构建日志

镜像构建过程中以及构建完成后，均可以在 自定义镜像 标签页中查看镜像构建日志。点击列表中的 构建日志 可展开日志面板，可根据日志根据构建进度，或分析镜像构建失败的原因。

镜像构建日志支持全文查询、短语查询、正则表达式搜索日志。支持以下查询方式：

• 全文查询：输入关键字进行整条日志搜索。如果一条日志中出现所有关键词，则为一次匹配。支持模糊匹配。
• 短语查询：用户指定必须在日志中完整出现的「短语」。如果一条日志中完整「短语」，则为一次匹配。例如用户输入 http error，如果一条日志中出现 http error，则为一次匹配。大小写不敏感。
• 正则表达式匹配：如果一条日志符合表达式要求，则为一次匹配。例如，输入 [0-9]+ 查询连续数字。

信息

只有在镜像中心快速构建的镜像才有构建日志。使用其他方式并推送到租户镜像仓库的镜像无构建日志。

限制可用服务范围

租户自定义镜像默认可用于开发机、推理服务、任务。如需限制该镜像的可用服务，请通过页面上的 编辑 按钮修改 可用服务。

常见故障排查

超时错误

镜像构建时间过长时，会直接超时并失败（默认 30 分钟）。

• 如果使用运行中的开发机构建镜像，建议您排查以下内容：

  • 镜像构建过程中是否有密集读写操作。如有，建议停止相关进程。
  • 开发机 rootfs 大小。建议尽量清理无用数据，保持系统盘较小。

• 如果使用其他方式构建镜像，请排查是否依赖外部数据，导致网络超时。

镜像仓库空间不足

列表中的 可用区 一栏展示了该镜像所属的可用区。点击可用区名称，展示可使用该镜像的资源池名称（当前可用区所有资源池），和当前可用区镜像仓库的存储剩余额度。

软件安装问题

如果直接构建镜像失败，可尝试在开发机内安装依赖项目，再将开发机保存为自定义镜像。如果问题持续，请联系商务或售后服务。

日志分析

• 日志搜索：镜像日志搜索支持全文查询、短语查询、正则表达式（语法与 OpenObserve 一致，参考 re_match）。详见上文查看镜像构建日志。

• 日志下载（需申请开通）：镜像日志支持下载，您可以进行离线分析。

  • 若您未对日志做任何筛选（时间筛选，实例筛选和搜索），则默认导出过去 30 天日志。
  • 若当前已经进行筛选、搜索，则下载筛选、搜索后的日志。

  导出日志量大时比较耗时，请耐心等待。平台将为您保存最近 5 条导出记录。

常见问题

首次使用平台时，镜像仓库无法使用，登录镜像中心出现报错

常见报错：Invalid operation building image is not allowed for this tenant

该问题通常是由于账号尚未完成实名认证所致。镜像仓库的使用需与实名认证信息绑定。如果租户未完成认证，将无法正常访问镜像仓库。

解决方案：

1. 自行完成个人认证或企业认证。详见 租户与用户账号。
2. 企业用户如需协助完成企业认证，请提交售后工单进行处理，并提供以下信息以便快速定位与配置：
   • 租户账号：用于识别具体租户身份
   • 企业名称：需确保与后续开具发票、签订合同所使用的企业认证信息保持一致，请务必填写真实有效的企业名称。提交后，售后团队将协助完成企业认证配置，恢复镜像仓库的正常使用。

在镜像中心构建镜像如何收费？

在镜像中心构建镜像不占用显卡资源，无需额外费用。

但如果您选择基于运行中的开发机构建镜像，在构建镜像过程中需要保持开发机为运行中状态，不可关机。如果开发机使用按量计费的算力资源，会产生 GPU 卡时费用。

怎么在镜像中打包代码等本地文件？

在平台镜像中心构建镜像时，只能粘贴 Dockerfile 文本，无法访问您的共享存储等目录中的文件。如果需要使用 COPY 命令将本地的应用程序、配置文件等打包进镜像，必须在开发机中使用本地构建。

您需要为开发机启用Docker 容器功能，随后可在开发机中使用 docker build 等命令制作镜像。详见 使用 AIStudio 开发机构建镜像。