数据湖计算 DLC 的内置镜像已预装 Ray 及常用数据处理、机器学习依赖。当您的业务需要额外的三方库、特定版本的框架或自研组件时，可基于 DLC 提供的 Ray 内置镜像构建自定义镜像，托管至容器镜像服务 TCR，并在 AI DLC 的数据实验室、Ray 作业、模型训练与推理服务中指定使用。
说明：
AI DLC 的自定义镜像能力基于容器镜像服务 TCR。使用自定义镜像前，需先完成 TCR 开通、公网访问配置、网络打通与白名单放行，任一环节未就绪都会导致镜像拉取失败。其中网络打通与白名单地址均需通过提交工单由后台处理。
前提条件
使用自定义镜像前，请确认已满足以下全部条件。
条件 | 说明 |
开通 TCR 并开启公网访问 | AI DLC 通过公网拉取您的镜像，TCR 实例必须开启公网访问入口，仅内网访问不可用 |
提交工单打通网络 | 当前版本需提交工单由后台完成网络打通，并由后台反馈 DLC 侧需放行的 IP 地址 |
白名单放行 DLC 访问地址 | 使用后台通过工单反馈的 IP 地址，在 TCR 侧的网络访问白名单中放行，否则请求会被拦截 |
镜像包含 Ray 相关组件 | 自定义镜像必须具备 Ray 运行环境，建议直接基于 DLC 提供的内置镜像叠加依赖，镜像选择与获取方式请参见步骤4 |
警告：
当前版本下，网络打通与白名单配置均依赖工单：
白名单需放行的 IP 地址无法自行获取，必须先提交工单，由后台反馈具体地址后才能配置。
即使已完成公网访问与白名单配置，仍须等待后台完成网络打通。未完成网络打通直接提交任务，会出现镜像拉取超时或失败。
操作步骤
步骤1：开通 TCR 服务并开启公网访问
1. 登录 容器镜像服务 TCR ，完成服务开通。
2. 在 镜像仓库 页面单击新建镜像仓库，创建用于存放自定义镜像的命名空间与镜像仓库。
3. 在 TCR 控制台 进入目标实例，在访问管理中开启公网访问，并记录镜像仓库的公网域名。
说明：
建议镜像仓库所在地域与 AI DLC 使用地域保持一致，可减少跨地域拉取带来的耗时。
步骤2：提交工单申请网络打通
网络需由后台打通，且白名单所需的 IP 地址也由后台通过工单反馈，因此提交工单是配置白名单的前置步骤。
1. 登录 腾讯云控制台 - 提交工单 ，产品选择数据湖计算 DLC。
2. 问题描述中请提供以下信息，并明确需要后台反馈白名单 IP 地址：
腾讯云账号 ID（APPID）与 DLC 所在地域。
TCR 实例 ID、镜像仓库公网域名与命名空间。
需要使用的自定义镜像完整地址（含版本 Tag）。
镜像使用场景：数据实验室、Ray 作业、模型训练或推理服务。
已开启公网访问的截图。
3. 后台完成网络打通并通过工单反馈 IP 地址后，再进行下一步。
步骤3：配置白名单放行
1. 在 TCR 控制台 进入目标实例，找到网络访问白名单配置入口。
2. 将后台通过工单反馈的 DLC 访问地址逐条加入白名单。
配置项 | 取值 |
需放行的地址 | 后台通过工单反馈的 DLC 访问地址（IP 或 IP 段），以工单回复为准 |
注意：
白名单地址以后台工单反馈为准，请勿自行填写其他地址。如后台后续变更访问地址，需同步更新白名单，否则可能出现已运行一段时间后突然拉取失败的情况。
步骤4：选择基础镜像
推荐直接基于 DLC 提供的内置镜像构建自定义镜像：在 Dockerfile 中
FROM 内置镜像，再叠加您自己的依赖和代码。内置镜像已包含 AI DLC 运行所需的 Ray 引擎，可避免环境不兼容。内置镜像类型
DLC 内置镜像可在控制台的 Ray 镜像 下拉列表中查看，名称形如
dlc-tcray2.57.0-py311-gpu-cu129-extra。镜像分为以下类型：镜像类型 | 名称特征 | 内容 | 适用场景 |
基础镜像 | 以 cpu 或 gpu-cu129 结尾 | Ray 开源原版镜像 + TCRay 引擎增强，不预装额外依赖包 | 已明确业务依赖、希望完全自行定制环境 |
增强镜像（推荐） | 以 -extra 结尾 | 在基础镜像上预装常见数据处理依赖，尽可能开箱即用 | 不确定该选哪个镜像时优先选择 |
推理服务镜像 | 以 -serve 结尾 | 面向推理服务场景的 GPU 镜像 | 部署推理服务 |
镜像名称中各部分的含义如下：
名称片段 | 含义 |
tcray2.57.0 | 基于 Ray 2.57.0 版本，并集成 TCRay 引擎 |
py311 | Python 3.11 |
cpu / gpu-cu129 | 面向无 GPU / 有 GPU 的节点，GPU 镜像基于 CUDA 12.9 |
选择建议：
不确定选哪个：优先选择
-extra 镜像。有 GPU 卡选 gpu-cu129-extra，无 GPU 卡选 cpu-extra。明确知道所需依赖：选择基础镜像（
cpu 或 gpu-cu129），自行安装全部依赖，镜像更精简。部署推理服务：选择
gpu-cu129-serve 镜像。注意：
请仅选用控制台列表中以
dlc- 开头的镜像。其他不带 dlc- 前缀的镜像仅供内部使用，不保证长期可用，请勿作为基础镜像。获取内置镜像
内置镜像托管在腾讯云容器镜像服务公共仓库，拉取地址格式如下：
docker pull ccr.ccs.tencentyun.com/emr-image/tcray:<镜像标签>
<镜像标签> 为控制台镜像名称去掉 dlc- 前缀后的部分。例如控制台中的 dlc-tcray2.57.0-py311-cpu-extra，对应的镜像标签为 tcray2.57.0-py311-cpu-extra。以 2.57.0 版本为例，拉取命令如下：
# CPU 基础镜像docker pull ccr.ccs.tencentyun.com/emr-image/tcray:tcray2.57.0-py311-cpu# GPU 基础镜像docker pull ccr.ccs.tencentyun.com/emr-image/tcray:tcray2.57.0-py311-gpu-cu129# CPU 增强镜像（推荐，无 GPU 时使用）docker pull ccr.ccs.tencentyun.com/emr-image/tcray:tcray2.57.0-py311-cpu-extra# GPU 增强镜像（推荐，有 GPU 时使用）docker pull ccr.ccs.tencentyun.com/emr-image/tcray:tcray2.57.0-py311-gpu-cu129-extra# GPU 推理服务镜像docker pull ccr.ccs.tencentyun.com/emr-image/tcray:tcray2.57.0-py311-gpu-cu129-serve
如需选用控制台列表中的其他版本，将命令中
tcray: 之后的内容替换为对应的镜像标签即可。说明：
如需了解增强镜像中预装的 Python 包及版本，可访问
https://tcray-release-wheels-1259353343.cos.ap-guangzhou.myqcloud.com/pip-freeze/<镜像标签>.txt 查看，例如 tcray2.56.1-py311-cpu-extra.txt。基于自有镜像安装 TCRay 引擎（不推荐）
如果您已有长期使用的自有镜像，且无法通过 Dockerfile 复现环境，也可以在自有镜像中直接安装 TCRay 引擎：
pip install "ray==2.57.0+tcray" --extra-index-url https://tcray-release-wheels-1259353343.cos.ap-guangzhou.myqcloud.com/simple/
注意：
此方式仅作兜底，推荐优先使用
FROM 内置镜像的方式，环境一致性与稳定性更有保障。命令中的版本号请替换为您需要使用的 TCRay 版本，并与 AI DLC 中选用的 Ray 版本保持一致。
安装包托管在广州地域的对象存储，请确保构建环境可访问公网。在网络隔离、无法访问公网的环境中无法通过该方式安装。
数据实验室场景下，镜像内仍需自行安装 WebIDE，并保证默认运行用户为
ray。步骤5：构建并推送自定义镜像
注意：
请基于 DLC 内置镜像构建自定义镜像，不要从裸基础镜像（如 ubuntu、python）开始构建。缺少 Ray 引擎的镜像无法被 AI DLC 正常拉起。
1. 准备 Dockerfile，以 DLC 内置镜像作为基础镜像叠加依赖。
# 基础镜像请使用 DLC 内置镜像，勿替换为其他基础镜像；不确定时推荐使用 extra 镜像FROM ccr.ccs.tencentyun.com/emr-image/tcray:tcray2.57.0-py311-cpu-extra# 如需安装系统级依赖，临时切换到 root，安装完成后必须切回 ray 用户USER rootRUN apt-get update && apt-get install -y <系统依赖包> && rm -rf /var/lib/apt/lists/*# 业务依赖请在 ray 用户下安装USER rayRUN pip install --no-cache-dir <业务依赖包># 确保镜像默认运行用户为 rayUSER ray
注意：
镜像的默认运行用户必须为
ray。若构建过程中切换到 root 安装依赖后未切回，运行时会出现文件权限错误。2. 在本地构建镜像。
docker build -t <镜像名>:<Tag> .
3. 登录 TCR 实例并推送镜像。
# 登录 TCR，用户名与密码可在 TCR 控制台的访问凭证中获取docker login <TCR 实例公网域名> -u <用户名> -p <密码># 打标签docker tag <镜像名>:<Tag> <TCR 实例公网域名>/<命名空间>/<镜像名>:<Tag># 推送docker push <TCR 实例公网域名>/<命名空间>/<镜像名>:<Tag>
说明：
镜像地址格式中的实例公网域名、命名空间与镜像名，均可在 TCR 控制台的镜像仓库详情页查看。
步骤6：在 AI DLC 中使用自定义镜像
完成网络打通与白名单配置后，可在以下场景中选择自定义镜像，填写镜像的完整地址（含版本 Tag）。
使用场景 | 配置位置 | 说明 |
数据实验室 | 创建实验室时，实验室镜像选择自定义镜像 | 镜像内需已安装 WebIDE（JupyterLab 与 VS Code Web），否则实验室启动后无法进入开发环境 |
Ray 作业 | 创建作业时，镜像配置中选择自定义镜像 | 用于通用 Ray 数据处理与计算任务 |
模型训练（Ray Train） | 创建训练作业配置时，镜像配置中选择自定义镜像 | 用于模型训练与微调任务 |
推理服务 | 创建推理服务时，镜像配置中选择自定义镜像 | 用于模型在线推理服务 |
注意：
请填写完整的镜像地址，包含版本 Tag。使用
latest 等浮动 Tag 可能导致不同节点拉取到不一致的镜像版本，建议使用固定版本 Tag。数据实验室场景请务必确认镜像内已包含 WebIDE 组件，该组件由 DLC 内置镜像提供，自行裁剪会导致实验室无法打开。
注意事项
镜像体积：镜像体积直接影响拉取耗时，进而影响任务启动速度。建议清理构建缓存，仅保留必要依赖。
版本兼容：自定义镜像中的 Ray（TCRay）版本、Python 版本需与所基于的 DLC 内置镜像保持一致，请勿在镜像中自行升级或替换 Ray，否则可能导致运行异常。
基础镜像更新：DLC 内置镜像会随版本迭代更新。升级基础镜像版本后，请重新构建并验证自定义镜像。
地域一致：建议 TCR 实例与 AI DLC 使用同一地域，避免跨地域拉取失败。
镜像更新：镜像内容更新后，需重新推送并确认新版本 Tag 可被拉取，正在运行的任务仍使用原镜像，不会自动生效。
常见问题
任务启动失败，日志提示镜像拉取失败或超时
请依次检查：
1. TCR 实例是否已开启公网访问。
2. 是否已提交工单，且后台已回复网络打通完成。
3. 白名单是否已放行后台通过工单反馈的全部 IP 地址。
4. 填写的镜像地址与 Tag 在 TCR 中是否真实存在。
如何获取白名单需要放行的 IP 地址
白名单 IP 地址由后台统一管理，不提供自助查询入口。请提交工单申请网络打通，并在工单中注明需要配置 TCR 白名单，后台会在回复中给出需要放行的 IP 地址。收到后在 TCR 实例的白名单配置中放行即可。
自定义镜像启动后立即退出
多数由镜像缺少 Ray 引擎，或 Ray 被覆盖、升级导致。请确认镜像基于 DLC 内置镜像构建（或已按步骤4安装 TCRay 引擎），且未覆盖或删除其中的 Ray 运行环境与启动脚本。
实验室创建成功但无法打开 WebIDE
数据实验室依赖镜像内的 WebIDE 组件。请确认自定义镜像在 DLC 内置镜像基础上构建时，保留了 JupyterLab 与 VS Code Web 相关文件与启动配置。
运行时报文件权限错误
请检查镜像默认运行用户是否为
ray。Dockerfile 中若曾切换到 root 安装依赖，需在安装完成后执行 USER ray 切回。
