主题
训练任务与 Worker 排障
按 Job → Task → Worker/Pod → 外部依赖的顺序排查。先记录各层状态、时间和错误信息，不要反复删除、恢复或修改数据面对象来试错。
如果这是第一次提交该工作负载，请先按首次运行问题排查找到最后一个成功阶段，再用本页检查对应环节。
创建任务弹窗无法进入下一步或提交
创建任务弹窗会在四个步骤之间执行部分校验。请按页面错误依次检查：
- 任务名称为 1–63 位小写字母、数字或连字符，且不以连字符开头或结尾。
- 至少有一个角色；角色名非空，且忽略大小写后不重复。
- 已选择一个 Header 角色。
- 每个角色都选择了集群并填写镜像。
- 每个角色在所选集群中至少匹配一个节点。
- GPU 请求没有超过页面能够计算出的上限。
- 每个挂载都有容器挂载目录；hostPath 还需要主机目录，对象存储挂载还需要 StorageClass。
- 公共配置中已填写运行命令。
即使页面允许继续，提交前仍要确认 Header 角色只有 1 个 Worker，并让平台管理员核对完整的单值节点选择条件不会跨集群命中其他 Node。这两项不会由页面自动完成。
如果 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 可分配资源。
- 多个角色的选择条件是否命中同一个节点；如果存在重叠，按角色合计该节点可能承载的 GPU、设备和其他资源需求。
- 镜像是否能在该集群拉取。
- PVC 是否能通过所选 StorageClass 创建和挂载。
hostPath是否存在于实际调度节点，并具备容器所需权限。- 初始化或准备脚本是否仍在执行。
判断调度条件时，请分别检查节点是否在线、可分配资源是否充足，以及是否存在阻止调度的污点。判断应用是否已经启动时，请继续检查容器日志和任务约定的业务信号。
Worker 异常或日志显示进程失败
- 在 Job 详情的日志页先选择出错角色和 Worker。
- 关闭实时滚动或使用文本过滤，定位第一条错误，而不是只看最后一行。
- 导出日志，记录失败时间、角色和 Worker 信息。
- 区分失败发生在镜像/挂载、准备脚本、Ray 集群建立，还是 Head Task 的运行命令。
- 核对脚本使用的路径是否为容器挂载路径，环境变量名是否正确。
日志页显示 Pod 主容器的日志。请逐个查看预期 Worker，并结合 Pod 阶段和已有的 Task status.message；某个 Worker 没有日志时，其他 Worker 仍可能记录了更早的失败。控制台不显示容器重启次数、终止详情或 previous logs；需要这些信息时，请让获授权的运维人员在数据面 Kubernetes 中检查。
以 Pod 和日志确认进程状态
Job 状态反映 RLark 是否仍在协调这项任务。当前 StatefulSet Task 只会上报 Pending、Running 或 Stopped；准备脚本、Ray 进程或运行脚本失败时，错误可能只出现在 Pod 阶段和日志中，而 Job 继续显示 Running。发现这些错误后，请保存运行证据并按实际错误处理。
修复配置前，先记录错误、状态、时间和相关对象名称。直接编辑 Job 会重新协调 Task 和 Pod，原来的失败信息可能随之变化。
按错误类型排查
控制台不会自动把错误分类为镜像、GPU、NCCL、共享内存或机器人故障。请结合 Pod 阶段、状态消息和应用日志判断，不要只看 Job 颜色。
| 现象或日志线索 | 优先判断 | 下一步 |
|---|---|---|
| 长时间 Pending，尚无 Pod 日志 | 选择器、不可调度节点、CPU/内存/GPU、PVC 或镜像拉取 | 记录 Task/Pod 消息，由管理员检查数据面调度事件；不要连续停止和启动。 |
| 镜像拉取、权限或不存在错误 | 镜像引用、仓库凭据、目标集群网络 | 对照本次提交记录中的镜像地址和版本。凭据只通过组织允许的 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 节点已加入，再核对每个角色镜像和工作负载版本要求的通信网卡。RLark 不自动诊断 NCCL。 |
| Ray 只看到部分节点 | Head Service、DNS、端口、Worker 包装脚本或网络域 | 对照 Head ray status 和每个预期 Worker 的连接日志；不要只凭 Head 的 ready 文本判断集群完整。 |
| Worker 或 Ray 节点数变成预期数量的 2 倍、3 倍等整数倍 | 多个角色选择了同一批节点，匹配数量在每个角色中分别转为 Worker 数 | 查看每个角色的已选节点数和 YAML 中各 Task 模板的副本数，把它们相加后与 cluster.num_nodes 比较。继续按Ray 节点数量与配置不一致处理。 |
| Ray 已就绪，但组件数量、GPU 使用或显存占用不符合预期 | Worker 规模、RLINF_NODE_RANK、component_placement、资源共享或 offload 配置 | 对照本次运行记录和规划多节点和异构 Worker，确认没有把资源编号当作 Worker 编号，也没有为共享 GPU 的组件重复申请资源。 |
| 运行命令已经开始，但使用了错误配置或一直没有业务信号 | RLinf 代码版本、Hydra 组合、命令行 override、数据路径或镜像内容 | 对照镜像地址和版本、代码 ref、最终 Hydra 配置、运行命令和业务信号，找到与预期运行记录不一致的第一项。 |
| 日志显示文件不存在、权限不足、PVC 或挂载错误 | StorageClass、PVC、hostPath、容器挂载路径或应用实际读写路径 | PVC 尚未创建或绑定时，检查PVC 无法创建、绑定或挂载；Pod 已运行但路径或内容异常时，继续查看存储排障。 |
| 机器人 SDK、连接、超时或设备错误 | 外部设备、驱动、权限和现场链路 | 停止自动重试，通知现场操作员；继续按设备资源或设备列表异常核对只读信息。日志错误分类不能替代急停、断能或安全状态确认。 |
问题需要 CPU、内存、/dev/shm、额外容器、探针或其他创建任务弹窗无法配置的 Pod 字段时，不要通过编辑或复制弹窗处理。先保存 Job YAML，再向平台管理员确认可用的配置方式。
设备资源或设备列表异常
先区分问题发生在调度阶段，还是 Worker 已经运行后的设备发现阶段。设备资源名称、具体设备 ID 和查询范围的区别见查看机器人和摄像头资源。
Worker 因设备资源长时间 Pending
- 在 Job YAML 中记录该角色申请的
rlinf.io/*资源名称和数量。 - 确认 Worker 的节点选择命中了预期 Node，并按角色合计同一 Node 上所有 Worker 的设备请求。
- 记录 Pending Worker、目标 Node 和状态消息，请平台管理员核对该 Node 上报的可分配资源和调度事件。
创建页面中的设备资源名称来自所选集群的 Node 上报信息。提交前，还需确认目标 Node 的可用容量，以及该资源名称对应的物理设备可以用于本次任务。
Worker 已运行但无法列出设备
在真实设备处于允许查看状态，且你已获准使用 WebTerminal 时，执行设备指南中的只读 list 或 status 命令。如果命令、/opt/rlinf/bin 或对应 socket 不存在，请检查当前环境采用的是 controller 接入还是直接设备挂载，并确认 Job 是否申请了正确的设备资源。
不要在 Worker 中临时安装 CLI、启动设备控制器或修改 socket 路径来试错。保存 Worker、Node、设备资源名称和脱敏后的错误信息，请设备运行时维护人员确认目标环境的接入方式。
设备列表为空或设备不符合预期
空列表只表示当前 Worker 所连接的控制器没有返回设备。它不能用来判断其他 Node 或其他集群是否有设备。核对 Worker 的实际 Node、资源到物理设备的映射和当前任务允许使用的设备 ID。
设备 ID、型号或状态与预期不一致时，停止后续设备操作，不要尝试启动、复位或切换设备。通知现场人员，并提供 Job、角色、Worker、Node、设备资源名称和只读命令输出。恢复操作前仍需完成使用真实设备前的安全要求。
Ray 节点数量与配置不一致
RLark 不会按物理节点合并不同角色创建的 Worker。先在 Job YAML 中把各 Task 模板的副本数相加，再与 RLinf cluster.num_nodes 比较：
text
Job YAML 中的预期 Worker 总数 = 所有角色的已选节点数之和
预期 Ray 节点总数 = cluster.num_nodes如果三个角色各匹配 4 个节点，RLark 会尝试创建 12 个 Worker Pod。即使这些 Pod 最终分布在同样的 4 台物理机器上，它们仍会分别启动 Ray 节点、申请 GPU 和获得 RLINF_NODE_RANK；RLinf 不会按 hostname 把它们合并为 4 个节点。
实际 Ray 节点多于 cluster.num_nodes 时，RLinf 可能记录警告后只采用节点编号最靠前的部分节点。其余 Worker Pod 和资源不会因此自动消失，组件也可能没有使用到预期节点。实际节点少于配置值时，RLinf 可能继续等待节点加入。不要依赖这些行为修正错误的角色规划。
处理步骤：
- 保存当前 Job YAML、各角色的已选节点数和 Head 的
ray status。 - 确认 Header 角色只创建 1 个 Worker。
- 如果只是把 Actor、Rollout、Environment 机械拆成了多个角色，按照规划多节点和异构 Worker重新规划。
- 如果已有 RLinf 配置确实需要多个 Worker 组，核对共享物理节点上的合计 GPU 和设备请求，并让所有角色的 Worker 数之和与
cluster.num_nodes一致。 - 使用新的 Job 验证修正后的布局，不要通过修改
cluster.num_nodes接受意外创建的 Worker。
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 副本缺陷处理，不要继续判断业务命令。 |
用 Ray 成员信息确认集群完整
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 process 退出码非零时，应按失败处理；不要仅凭容器最终退出码或汇总状态判断 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 私钥、完整签名下载链接或其他凭据。