构建自定义镜像
非预置镜像均称为自定义镜像，存储在租户的私有租户镜像仓库中。本文描述如何在 AIStudio 平台通过多种方式创建自定义镜像。
注意
当前租户的自定义镜像，均会展示在镜像中心的自定义镜像标签页。如果在创建开发机、任务、推理服务时，无法在自定义镜像列表中无法找到自定义镜像，请检查创建实例的资源池与该镜像的可用资源池是否一致。
镜像大小限制
单个镜像大小不能超过 50 GiB。
镜像基础组件要求
如果您的镜像用于开发机，推荐在镜像中包含平台要求的必要组件：
以 Ubuntu 为例：
基于 Ubuntu 22.04 的自定义镜像，必须安装以下组件：
shellapt update && apt install openssh-server sudo runit runit-systemd -y基于 Ubuntu 24.04 的自定义镜像，必须安装以下组件：
shellapt update && apt install openssh-server sudo runit runit-helper runit-run -y
如果镜像中缺失上述组件，在启动开发机时平台会尝试安装，但仍可能安装失败导致开发机无法正常启动，或 SSH 远程连接功能受限。以下为推荐的处理方案：
如果仅针对当前开发机作一次性修复，可直接安装基础组件，重启开发机。
推荐永久修复当前自定义镜像，操作方式：
- 在镜像中心构建自定义镜像，选择「基于现有镜像」中安装
- 在「安装命令」中输入以下安装命令，以 Ubuntu 22.04 为例：shell
DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install openssh-server sudo runit runit-systemd -y - 重启开发机，选择更新后的新版镜像。
在镜像中心快速构建镜像
AIStudio 镜像中心支持多种从网页端快捷创建自定义镜像的方式，包括基于现有的预置镜像或自定义镜像、基于 dockerfile，或直接保存运行中的开发机为镜像。
这种方式构建的镜像将直接保存到租户私有镜像仓库，无需推送。
切换到自定义镜像标签页后，点击构建镜像。进入创建页面后，请根据页面提示，完成以下配置。
镜像名称及 tag：填写符合要求的名称与镜像标签。
可用服务：如果您希望镜像被用于开发机和任务，可根据需要进行勾选。
镜像构建资源池：选择可使用该镜像的资源池。如果下拉列表只有一项，选择默认值即可。如果有多项，说明您的计算资源分布在多个可用区（例如，宁夏、广东等）。列表中的每一行为该可用区中的所有资源池，请选择希望使用该镜像的资源池。单次构建操作仅支持选择一个可用区的所有资源池。
构建方式：自定义镜像的构建方式有如下三种，下文中提供了具体示例。
方式 说明 基于现有镜像 可使用平台预置镜像，或镜像中心的自定义镜像。在基础镜像上，可使用 apt-get、pip install安装其他软件。基于 dockerfile 直接编写 dockerfile 。 基于现有开发机 导出开发机 rootfs 并另存为自定义镜像，仅支持选择正在运行的开发机。保存开发机为镜像时，请停止开发机内的读写操作。
基于现有镜像
如果您对某个现有的预置镜像或自定义镜像比较熟悉，需要扩展该镜像，可在该镜像基础上使用 apt-get、pip install 等方式安装其他软件。
填写自定义镜像的基础信息后，选择基于现有镜像，在「安装命令」输入框中编写需要执行的 Shell 命令。以下示例以平台预置 Ubuntu 22.04 镜像为基础，安装了一些网络工具、传输工具、开发工具等。
# 更新APT包列表
apt-get update
# 安装系统工具
# -y: 自动确认所有提示，避免交互式输入
# --no-install-recommends: 仅安装核心依赖，不安装推荐的附加包（本脚本中已省略该选项，因此会安装推荐依赖）
apt-get install -y htop # 系统资源监控工具，比 'top' 更直观
apt-get install -y dnsutils # DNS工具包，提供 nslookup 和 dig 等DNS查询工具
apt-get install -y traceroute # 网络路径跟踪工具，用于跟踪数据包的传输路径
apt-get install -y netcat-openbsd # 网络工具包，提供 nc 命令，支持端口扫描和网络连接测试
apt-get install -y tcpdump # 网络数据包分析工具，用于抓包和分析网络流量
apt-get install -y host # 简单的DNS查询工具
apt-get install -y whois # 域名注册信息查询工具
apt-get install -y emacs-nox # Emacs命令行版本（不包含图形界面）
apt-get install -y nano # 简单易用的文本编辑器
apt-get install -y rsync # 高效的文件同步和传输工具
# 清理APT缓存以减少空间占用
apt-get clean
rm -rf /var/lib/apt/lists/*
# 使用pip安装Python包
# --quiet: 减少安装过程的输出信息
# --no-cache-dir: 不缓存下载的包
python3 -m pip install --quiet --no-cache-dir --upgrade pip # 升级 pip
python3 -m pip install --quiet --no-cache-dir ipython # 增强的交互式Python解释器
python3 -m pip install --quiet --no-cache-dir jupyterlab # 基于Web的交互式开发环境基于 Dockerfile
Dockerfile 是一个文本文件，其内包含了一条条的指令(Instruction)，每一条指令构建一层。使用 Dockerfile 定制镜像，可以很好解决镜像构建透明性、镜像体积等问题。
填写自定义镜像的基础信息后，选择基于 Dockerfile，在「Dockerfile」输入框中编写文件内容。
# 以平台预置镜像为基础，在其上进行定制（可从镜像中心获取镜像地址）
FROM cr.infini-ai.com/infini-ai/ubuntu:22.04-20240429
# --no-cache-dir: 不缓存下载的包，减少镜像体积
RUN python3 -m pip install --no-cache-dir "xinference[vllm]" \
&& python3 -m pip install --no-cache-dir flashinfer -i https://flashinfer.ai/whl/cu121/torch2.4/如何编写 Dockerfile 不在本文档范围以内，您可以参考网络资源。
提示
您可以使用 Dockerfile 方便地构建系统级 CUDA / cuDNN 环境。
基于现有开发机
如果您希望保存开发机中环境配置，以便复用环境，可以直接将运行中的开发机保存为自定义镜像。
填写自定义镜像的基础信息后，选择基于现有开发机，在下拉列表中选择可见的开发机即可。如果填写排除的路径，镜像中将不会保存该路径的数据。
警告
使用 Docker 命令构建镜像
如果您更习惯使用 Docker CLI，也可在 AIStudio 开发机中构建镜像。
您需要为开发机启用Docker 容器功能，随后可在开发机中使用 docker pull/push/build 等命令制作镜像，并可推送到租户镜像仓库。详见 制作镜像。
管理构建结果
镜像构建开始后，在自定义镜像标签页中就会生成您的镜像。您可以在此关注构建进度、构建结果。在必要时，可通过构建日志排查问题。
查看镜像构建结果
构建镜像时间与具体操作有关，可能从几分钟到几十分钟不等。如果自定义镜像列表中「状态」变更为「构建成功」，则表示镜像已经可以使用。
如果您关注自定义镜像构建进度与过程，可实时查看构建日志。
查看镜像构建日志
镜像构建过程中以及构建完成后，均可以在自定义镜像标签页中查看镜像构建日志。点击列表中的构建日志可展开日志面板，可根据日志根据构建进度，或分析镜像构建失败的原因。
镜像构建日志支持全文查询、短语查询、正则表达式搜索日志。支持以下查询方式：
- 全文查询：输入关键字进行整条日志搜索。如果一条日志中出现所有关键词，则为一次匹配。支持模糊匹配。
- 短语查询：用户指定必须在日志中完整出现的「短语」。如果一条日志中完整「短语」，则为一次匹配。例如用户输入
http error，如果一条日志中出现http error，则为一次匹配。大小写不敏感。 - 正则表达式匹配：如果一条日志符合表达式要求，则为一次匹配。例如，输入
[0-9]+查询连续数字。
注意
只有在镜像中心快速构建的镜像才有构建日志。使用其他方式并推送到租户镜像仓库的镜像无构建日志。
限制可用服务范围
租户自定义镜像默认可用于开发机、推理服务、任务。如需限制该镜像的可用服务，请通过页面上的编辑按钮修改可用服务。
常见故障排查
超时错误
镜像构建时间过长时，会直接超时并失败（默认 30 分钟）。
- 如果使用运行中的开发机构建镜像，建议您排查以下内容：
- 镜像构建过程中是否有密集读写操作。如有，建议停止相关进程。
- 开发机 rootfs 大小。建议尽量清理无用数据，保持系统盘较小。
- 如果使用其他方式构建镜像，请排查是否依赖外部数据，导致网络超时。
镜像仓库空间不足
列表中的可用区一栏展示了该镜像所属的可用区。点击可用区名称，展示可使用该镜像的资源池名称（当前可用区所有资源池），和当前可用区镜像仓库的存储剩余额度。
软件安装问题
如果直接构建镜像失败，可尝试在开发机内安装依赖项目，再将开发机保存为自定义镜像。如果问题持续，请联系商务或售后服务。