镜像兼容性要求

并非所有容器镜像都能直接稳定用于极值算力实例。如果镜像缺少平台要求的基础组件，或镜像本身不适合当前运行方式，实例可能无法正常启动，SSH 远程连接也可能受限。

理解容器运行边界

极值算力实例基于容器运行，不等同于物理机或一台完整启动的 Linux 主机。制作镜像时，请把镜像当作文件系统和运行环境模板来准备，而不是把它当作已经启动的服务器来配置。

这会影响以下判断：

• 不要依赖 systemd 或 systemctl 管理服务。
• 不要把需要特权能力的内核、挂载、网络操作写成镜像启动前提。
• 不要假设镜像中的 Entrypoint 或 Command 会原样成为平台最终启动入口。
• 需要长期保留的环境、脚本和配置，应写入镜像文件系统；需要运行时启动的服务，应通过平台启动命令或容器环境可用的进程管理方式启动。

控制镜像大小

单个自定义镜像大小不能超过 100 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

如果镜像中缺失这些组件，平台在启动实例时会尝试安装，但仍可能失败，进而导致实例无法正常启动或登录。

处理启动命令和 Entrypoint

极值算力实例支持在平台侧配置启动命令，但平台不会直接以镜像中定义的 Entrypoint 或 Command 作为最终运行入口。

信息

如需自定义实例启动行为，请优先使用平台提供的“启动命令”能力，而不是依赖镜像中的 Entrypoint 或 Command。详见配置启动命令。

这也意味着，镜像中的启动逻辑如果强依赖特定 Entrypoint，可能需要在平台侧重新整理为可控的启动命令。平台侧“启动命令”更适合做轻量初始化或启动服务，不适合承担大规模环境安装工作。

为 RDMA 场景补充组件

如果您计划让多个实例之间通过 RDMA 进行通信（如 IB 或 RoCE），还应确认镜像中包含对应的 RDMA 组件。

以 Ubuntu 为例，可在已有镜像基础上补充安装：

apt update && apt install -y infiniband-diags perftest ibverbs-providers libibumad3 libibverbs1 libnl-3-200 libnl-route-3-200 librdmacm1

如果当前任务场景不依赖 RDMA，这部分通常不必额外处理。

不要把数据和缓存打进镜像

镜像更适合承载操作系统、运行时、框架和业务依赖，不适合长期保存大数据集、模型权重或临时缓存。

如果将大量业务数据直接打包进镜像，通常会带来以下问题：

• 镜像体积迅速增大
• 构建、传输和启动耗时明显变长
• 镜像版本管理变得困难

如需保存大体积数据，建议结合共享高性能存储使用，而不要将这些数据直接固化到镜像中。

固定依赖版本并清理缓存

构建镜像时，建议让安装逻辑尽量可复现：

• 固定关键依赖版本
• 只安装当前确实需要的软件
• 保持安装脚本简洁、可读
• 构建完成后清理缓存

如果镜像将被多人共用，建议使用清晰的名称和标签，并用新标签发布变更，而不是直接覆盖仍在使用的稳定版本。

用测试实例做最小验证

每次生成新镜像后，建议先用一个测试实例做最小验证，再投入正式使用。常见验证内容包括：

• 实例能否正常启动
• SSH 或 Web Terminal 是否可正常进入
• 关键依赖是否可导入、可执行
• 如果有 GPU 依赖，是否能完成基础检查

如果验证失败，建议优先回头检查镜像大小、基础组件、启动命令与系统依赖，再结合实例日志和故障排查文档进一步定位。