导入或跨可用区迁移镜像

使用镜像中心 上传镜像 功能，可以将本地已有镜像或远程镜像 URL 导入目标可用区的租户私有镜像仓库，也可以将一个可用区中已有的镜像迁移到另一个可用区。

图表预览

重要

从平台外部推送镜像，或从一个可用区向另一个可用区迁移镜像，都需要使用目标可用区 Registry 公网访问地址。实际推送速度受网络带宽影响。

前提条件

租户镜像仓库：如需获得租户私有镜像仓库，满足以下任一条件即可：

• 已购买预付费资源（包年包月资源）
• 曾使用弹性资源创建开发机，且仓库未被收回

使用地址前请先阅读镜像仓库地址与可用区，确认命令运行位置、目标可用区和登录凭证范围。

选择导入方式

根据镜像当前的存放位置和可用工具，选择对应的操作：

• 镜像位于公网可访问的容器镜像仓库：通过镜像地址和访问凭证（如有）抓取镜像。转到通过 URL 导入公网镜像。
• 从可访问源端和目标可用区 Registry 的本地设备中转远程镜像：优先使用 regctl，也可以沿用经过验证的 crane 流程。转到选择 Registry 命令行工具。
• 镜像位于本地设备，或需要从其他可用区迁移：使用 Docker 将镜像推送到目标可用区。转到通过命令行推送镜像。
• 手头只有容器镜像 .tar 文件：镜像中心不能直接接收 .tar 文件，需要先在启用 Docker 容器功能的开发机中载入镜像。转到关于容器镜像 Tar 包的说明。

如果导入的镜像将用于开发机，还需要确认镜像包含平台所需的基础组件。转到为导入的镜像安装开发机基础组件。

通过 URL 导入公网镜像

对于存放在用户自建镜像仓库或第三方镜像仓库的远程镜像，只需填写相关 URL 和凭证信息即可。

警告

无论是自建镜像仓库 URL 或第三方镜像仓库 URL，请确保可从国内公网访问。如有登录认证，请提供正确的访问凭证。

由于运营商网络原因，无法从 Docker Hub（docker.io）导入镜像。这包括未指定 Registry 前缀的镜像 URL（默认使用 docker.io）和显式指定 docker.io 或 registry-1.docker.io 的 URL。如需导入 Docker Hub 镜像，请选用其他方式导入。

1. 在 AIStudio 的镜像中心，选择 上传镜像，打开 上传镜像 弹窗。

2. 在 选择资源池 的下拉列表中，选择一条记录后，表示镜像将上传到该可用区。如果使用该可用区的任何资源池创建开发机、任务、推理服务，均可使用该镜像。

   注意

   如果 选择资源池 的下拉列表有多行记录，每一行为一个可用区的所有资源池。选择一条记录后，表示镜像将上传到该可用区，单次仅能选择一个可用区。

3. 选择 URL上传，并填写镜像 URL。如需认证，务必填写凭证信息。

通过命令行推送镜像

对于存放在本地设备上的镜像，或需要从其他可用区迁移的镜像，需要获取目标可用区 Registry 的公网访问地址和登录凭证，并将镜像推送到目标命名空间（Namespace，使用租户 ID 作为命名空间）。

获取目标可用区 Registry 地址和凭证

注意

cr.infini-ai.com 不是公网访问入口。在平台外部，不保证可以解析或连接。要从本地设备访问平台 Registry，或从一个可用区向另一个可用区推送镜像，请在镜像中心选择目标可用区，并使用页面提供的目标可用区 Registry 公网访问地址和登录凭证。

1. 在 AIStudio 的镜像中心，选择 上传镜像。

2. 在 选择资源池 的下拉列表中，每一行记录为一个可用区的所有资源池。选择一条记录后，表示镜像将上传到该可用区，如果使用该可用区的任何资源池创建开发机、任务、推理服务，均可使用该镜像。

3. 选择 命令行上传。页面会显示目标可用区租户私有镜像仓库的 Registry 公网访问地址、登录凭证和完整命令。请复制当前页面显示的实际值，不要自行将平台内部 Registry 域名替换到这些命令中。

   警告

   选择可用区后再复制命令。不同可用区的公网 Registry 地址和凭证不同；登录可用区 A 的 Registry 不表示可以向可用区 B 推送。

登录并推送镜像

在存有待推送镜像且已安装 Docker 的设备或实例上，执行镜像中心提供的命令：

1. 查看待推送镜像 (docker images)。
2. 登录目标可用区的公网 Registry (docker login)。
3. 按镜像中心提供的目标地址为镜像打标签（docker tag）。
4. 将镜像推送至目标可用区 (docker push)。
5. 确认 docker push 输出镜像摘要且未报告错误，然后返回镜像中心，确认镜像出现在目标可用区。

选择 Registry 命令行工具

建议按以下方式选择工具：

• 镜像已存在于本地 Docker Engine：优先使用本节前述的 docker login、docker tag 和 docker push 流程。
• 本地未安装 Docker Engine，且需要在两个远程 Registry 之间复制镜像：优先使用 regctl。它可以保留镜像内容摘要、选择目标架构，并在需要时为目标 Registry 配置分块上传。
• 已有经过验证的 crane 脚本，或需要批量复制 tag：继续使用 crane；--all-tags 和 --no-clobber 适合既有的 Repository 批量迁移流程。
• 镜像可能包含单个大层，或上传链路较慢：使用 regctl 配置分块上传，让大层直接分块，缩短单次上传请求的持续时间。

实际速度取决于源和目标 Registry、网络路径、带宽以及目标仓库中是否已有相同镜像层。

📖 使用 regctl 将远程镜像复制到目标可用区 Registry

📖 使用 crane 检查、管理和传输容器镜像

关于容器镜像 Tar 包的说明

容器镜像 Tar 包本质上是一个被打包成标准 .tar 归档格式的容器镜像。一般情况下，推荐您通过 URL 或命令行（docker push）方式上传即可，不建议使用容器镜像 Tar 包。

使用容器镜像 .tar 备份文件的场景：

• 无法访问平台租户私有镜像仓库所属 Registry 的公网地址。
• 您手头只有一份历史遗留的 .tar 备份文件，希望导入为平台自定义镜像，且本地未安装 Docker 服务。
• 不经过任何镜像仓库，在两台机器之间 快速迁移镜像。
• 将本地构建的镜像 离线备份或归档，确保版本可追溯、可恢复。

镜像中心不支持直接上传容器镜像 Tar 包。如需使用容器镜像 .tar 备份文件，需要借助一台启用 Docker 容器功能的开发机，才能将容器镜像 Tar 包导入为镜像，并推送至平台租户私有镜像仓库。详见导入镜像 Tar 包。

为导入的镜像安装开发机基础组件

AIStudio 开发机依赖 sudo、runit 等基础组件，如果您的自定义镜像中缺乏必要依赖，可能无法用于运行开发机。详见开发机镜像基础组件要求。

如果镜像中缺失上述组件，在启动开发机时平台会尝试安装，但仍可能安装失败导致开发机无法正常启动，或 SSH 远程连接功能受限。建议您在导入之前处理镜像，确保镜像满足平台要求。如果导入的镜像已缺失组件，以下为推荐的修复方案：

• 为开发机作一次性修复：如果仅针对开发机作一次性修复，可直接登录开发机，安装基础组件，重启开发机。缺点是仅针对当前开发机有效。

• 永久修复镜像（推荐）：在镜像中心，基于已有镜像，通过安装组件，构建新的镜像。操作方式如下：

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

  2. 在 安装命令 中输入以下安装命令：

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

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

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

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

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

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

  3. 等待新版镜像构建完成。