主题
训练任务与 Worker 排障
按 Job → Task → Worker/Pod → 外部依赖的顺序排查。先记录各层状态、时间和错误信息，不要反复删除、恢复或修改数据面对象来试错。
如果这是第一次提交该工作负载，请先按首次运行问题排查找到最后一个成功阶段，再用本页检查对应环节。
创建器无法进入下一步或提交
创建器会在四个步骤之间执行校验。请按页面错误依次检查：
- 任务名称为 1–63 位小写字母、数字或连字符，且不以连字符开头或结尾。
- 至少有一个角色；角色名非空，且忽略大小写后不重复。
- 已选择一个 Header 角色；其完整选择器经管理员全局验证后恰好匹配 1 个 Node，YAML 中副本数也为 1。
- 每个角色都选择了集群并填写镜像。
- 每个角色的
nodeSelector非空且不含逗号分隔的多值；管理员已经从全局 Node 清单确认完整选择器至少匹配一个可用节点，并且不会跨集群。 - GPU 请求没有超过匹配节点显示的最大可用值。
- 每个挂载都有容器挂载目录；hostPath 还需要主机目录，对象存储挂载还需要 StorageClass。
- 公共配置中已填写运行命令。
如果 YAML 预览符合预期但提交返回 HTTP 错误，记录状态码和不含敏感信息的响应正文，并确认同名 Job 是否已存在。不要把 SSH 私钥、存储 Secret 或镜像仓库凭据加入工单。
Job 长时间处于 Pending
先打开 Job 详情，查看 Task/Worker 状态和消息。
尚未出现 Worker
这通常表示 Task 还没有创建 Pod：
- 检查角色选择的集群是否仍在线。
- 检查匹配节点是否为 Online 且没有被标记为不可调度。
- 核对 Task 的
nodeSelector。集群下拉框不会写入 Job；选择器为空时，任务可能落到默认命名空间。选择器跨集群命中时，任务也可能落到错误的集群。请改用管理员从全局 Node 清单确认过的单值条件组合。 - 核对副本数是否大于 0；Stopped Job 的 Kubernetes Task 会被协调为 0 副本。
- 核对镜像名称、拉取权限和目标集群的网络连通性。
- 核对对象存储配置是否已关联到该 Task 所在集群。
没有 Pod 时通常也没有可用的 Pod 日志或 WebTerminal。先解决调度或工作负载创建问题。
已出现 Worker，但仍为 Pending
记录 Worker 的 Pod 名称、目标节点和状态消息，然后按以下顺序检查：
- 节点是否有足够的 CPU、内存和 GPU 可分配资源。
- 镜像是否能在该集群拉取。
- PVC 是否能通过所选 StorageClass 创建和挂载。
hostPath是否存在于实际调度节点，并具备容器所需权限。- 初始化或准备脚本是否仍在执行。
不要把 Online 当作资源充足，也不要把 Pod 已创建当作应用已启动。
Worker 异常或日志显示进程失败
- 在 Job 详情的日志页先选择出错角色和 Worker。
- 关闭实时滚动或使用文本过滤，定位第一条错误，而不是只看最后一行。
- 导出日志，记录失败时间、角色和 Worker 信息。
- 区分失败发生在镜像/挂载、准备脚本、Ray 集群建立，还是 Head Task 的运行命令。
- 核对脚本使用的路径是否为容器挂载路径，环境变量名是否正确。
日志页显示 Pod 主容器的日志。某个 Worker 没有日志，不代表其他 Worker 没有失败信息；还应查看 Pod 阶段、其他 Worker 和已有的 Task status.message。控制台不显示容器重启次数、终止详情或 previous logs；需要这些信息时，请让获授权的运维人员在数据面 Kubernetes 中检查。
创建器生成 StatefulSet Task，这类 Task 只会上报 Pending、Running 或 Stopped。即使准备脚本、Ray 进程或运行脚本失败，Task 和 Job 也可能继续显示 Running。因此，任务没有进入 Failed 并不表示它运行正常。
修复配置前，先记录错误、状态、时间和相关对象名称。直接编辑 Job 会重新协调 Task 和 Pod，原来的失败信息可能随之变化。
按错误类型排查
控制台不会自动把错误分类为镜像、GPU、NCCL、共享内存或机器人故障。请结合 Pod 阶段、状态消息和应用日志判断，不要只看 Job 颜色。
| 现象或日志线索 | 优先判断 | 下一步 |
|---|---|---|
| 长时间 Pending，尚无 Pod 日志 | 选择器、不可调度节点、CPU/内存/GPU、PVC 或镜像拉取 | 记录 Task/Pod 消息，由管理员检查数据面调度事件；不要连续停止和启动。 |
| 镜像拉取、权限或不存在错误 | 镜像引用、仓库凭据、目标集群网络 | 对照启动清单中的 digest；凭据只通过组织允许的 Secret 方式处理。 |
No space left on device、/dev/shm 或 shared-memory 错误 | 容器临时空间或共享内存不足 | 创建器不能配置 /dev/shm 的 memory-backed volume。停止重试，保留日志并请平台管理员提供可用的 Pod 配置方式；不要直接挂载宿主机 /dev/shm 规避。 |
| NCCL 初始化、socket、timeout 或 collective hang | Worker 数量、GPU/CUDA/NCCL 兼容性、网卡和跨节点网络 | 先确认全部 Ray Worker 已加入，再核对每个角色镜像和工作负载版本要求的通信网卡。RLark 不自动诊断 NCCL。 |
| Ray 只看到部分节点 | Head Service、DNS、端口、Worker 包装脚本或网络域 | 对照 Head ray status 和每个预期 Worker 的连接日志；不要只凭 Head 的 ready 文本判断集群完整。 |
| 机器人 SDK、连接、超时或设备错误 | 外部设备、驱动、权限和现场链路 | 停止自动重试，通知现场操作员；日志错误分类不能替代急停、断能或安全状态确认。 |
问题需要 CPU、内存、/dev/shm、额外容器、探针或其他创建器不支持的 Pod 字段时，不要通过编辑或复制弹窗处理。先保存 Job YAML，再向平台管理员确认可用的配置方式。
Ray 初始化或组网失败
Kubernetes Task 会用 RLark 包装脚本替换 main 容器的启动命令。Head Task 和其他 Task 的 Worker 都先执行角色准备脚本，再检查 Ray CLI；Head Task 的每个副本都会在 Ray 检查阶段之后执行 Job 的运行脚本。环境变量的来源和保留名称见运行环境与环境变量。
开始排查前先看 YAML：head: true 的 Task 副本数必须为 1。如果大于 1，停止反复重试并先修正选择器；多个副本会分别启动 Ray Head 和运行脚本，可能造成重复训练及冲突日志。
排查时分别选择 Head 和异常 Worker，按日志中最后出现的阶段标记定位：
| 最后完成的阶段 | 日志信号 | 判断与下一步 |
|---|---|---|
| rank 计算或包装脚本准备 | RLINF_NODE_RANK:；可选的网络等待或 SSH 公钥注入信息 | 如果在准备脚本标记前终止，记录该 Worker 的第一条错误，检查包装脚本所需的 Pod 信息和所选平台配置，不要覆盖平台保留的环境变量。 |
| 角色准备脚本 | Executing prepare script... | 后续第一条错误来自该角色的 prepareScript。修复镜像、命令、路径或权限；准备脚本失败时 Ray 尚未启动。 |
| Ray CLI 检查 | Error: Ray CLI is not found. Please ensure Ray is installed. | 激活后的环境中没有可执行的 ray。使用已经固定版本且包含 Ray 的镜像，或通过准备脚本激活固定版本的环境。不要在 WebTerminal 中临时安装后继续运行。 |
| Head 启动和节点检查 | Waiting for ... nodes to join the Ray cluster... | 对照预期副本数检查各 Worker 是否已经产生 Pod、完成准备脚本并开始连接 Head。 |
| Worker 解析和连接 Head | Connecting to Ray head at ...，随后出现可达信息或重复等待信息 | 重复等待表示 Worker 尚未同时完成 Head 名称解析和端口连通。检查 Head Pod、Head Service、Agent 和所需网络域，不要只重启 Worker。 |
| Head 运行脚本 | Executing run script... | 对于合规的单副本 Head Task，Ray 包装脚本已经进入用户命令阶段。若多个 Pod 都出现该标记，先按多 Head 副本缺陷处理，不要继续判断业务命令。 |
不要只凭 Head 就绪文本判断集群完整
Head 的节点检查失败时，脚本会先记录 Warning: Ray cluster check failed, proceeding anyway.，然后继续打印集群信息并尝试运行用户脚本。因此，即使出现 “Ray cluster is ready” 或 “Executing run script”，也必须同时检查 Head 的 ray status 输出，以及每个预期 Worker 的连接日志和 Pod 状态。
检查日志中的 Worker 退出码
Worker 包装脚本会输出 Ray worker process exited with code ...，但随后自身以 0 退出。日志中的 Ray Worker 退出码非零时，应按失败处理；不要仅凭容器最终退出码或汇总状态判断 Worker 正常。
Head 和 Worker 默认把 Ray 临时文件放在 /tmp/ray。只有对应角色显式设置 RAY_TEMP_DIR 时才会改用其他路径。日志指向临时目录、权限或空间问题时：
- 核对该角色 YAML 中的
RAY_TEMP_DIR，不要检查或修改平台内部RLARK_*变量。 - 确认每个副本都能写入目标路径，并检查可用空间。
- 若路径来自挂载，确认实际 Pod 已挂载同一路径，且没有与其他任务意外共享不可并发使用的目录。
- 每次只修复一个已确认原因，然后重新比较同一阶段的日志。
联系平台管理员时，除本页末尾的通用信息外，再提供 Head 与首个异常 Worker 的脱敏日志、最后成功阶段、节点检查警告、Worker 进程退出码，以及是否设置了 RAY_TEMP_DIR。不要提供完整环境变量转储。
Job 与 Worker 状态不一致
状态需要经过数据面 Agent、Task 和 Job 逐层同步。刚完成以下操作时，短暂不一致是正常的：
- 创建 Job。
- Worker 启动或退出。
- 停止或恢复 Job。
- 数据面 Agent 重连。
先等待状态完成一次同步，再比较 Job、Task 和 Pod 阶段。如果只有一层长时间不更新，请记录该层最后更新时间、状态消息和 Agent/集群状态，然后联系平台管理员。
停止后仍看到 Worker
停止会设置 Job 的 stopped 标志，并把当前 Kubernetes Task 协调到 0 副本；不是立即删除所有页面记录。
- 确认 Job 已进入 Stopped，而不是提交请求失败。
- 等待工作负载完成缩容和状态回报。
- 重新打开 Job 详情，区分历史 Worker 信息与仍在运行的 Pod。
- 若 Pod 长时间仍在运行，记录 Job、Task、Pod 名称和时间点，交由平台管理员检查控制器与 Agent。
不要为了“加快停止”直接删除数据面 StatefulSet 或 Pod。这些对象可能被重新创建，也会让问题更难定位。
同名 Worker 同时出现多个 IP 或状态时，控制台不会自动把它们关联为一次重试。请按查看 Worker 与 Pod记录实例信息；需要还原替换时间线时，请让管理员查询数据面 Pod UID 和事件。
WebTerminal 无法打开
WebTerminal 需要 Worker 已关联实际 Pod。先确认 Worker 行中存在 Pod 名称，再检查：
- 目标集群和 Agent 是否可达。
- Pod 是否仍然存在，且未在打开弹窗前退出。
- 当前用户是否获准访问该作业。
- 浏览器是否拦截了连接或下载行为。
不要在终端排障时打印环境中的 Secret。需要上传或下载文件时，先确认目标容器和路径，避免覆盖作业输出。
联系平台管理员时提供
- Job 名称、阶段和操作时间。
- 角色、Task 名称、Worker/Pod 名称和目标节点。
- Task/Pod 状态消息。
- 经过脱敏的首条错误及前后日志。
- 相关集群、节点、镜像名称和 StorageClass 名称。
- 问题发生前的创建、编辑、停止或恢复操作。
不要附带 Access Key Secret、SSH 私钥、完整签名下载链接或其他凭据。