主题
迁移已有 RLinf 工作负载
按照本页把已经验证过的 RLinf 镜像、命令和配置整理成 RLark Job。页面中的结构示例不包含可直接运行的镜像、命令、算法配置或硬件参数，实际值需要来自你的工作负载和目标环境。
本文使用 Header 角色表示控制台选择的角色；它在 Job 中生成 head: true 的 Head Task。Header 角色不是具体 Node，也不会自动只选取第一个 Worker。
提交前需要管理员确认节点匹配结果
创建向导只显示所选集群中的匹配节点，不能确认同一组标签是否也会匹配其他集群。平台管理员确认选择器只匹配目标集群，而且 Header 角色只匹配 1 个 Node 后，才能提交任务。
适用条件
开始前，必须已经掌握以下信息：
- 一个经过团队验证的镜像 digest，或有不可变策略和实际 digest 记录的版本引用，以及镜像来源和联系人。
- 可以在该镜像中执行的精确启动命令。
- 工作负载实际读取的配置、数据、checkpoint 和输出路径。
- 每个进程角色需要的集群、节点标签、CPU、内存、GPU 或其他设备资源；其中当前控制台只能配置 GPU 和
rlinf.io/*设备资源。 - 需要的环境变量、准备脚本和挂载，以及它们的非敏感值来源。
- 多角色任务中唯一的 Header 角色，以及一组已经全局检查、恰好只匹配 1 个 Node 的选择器。
如果缺少其中任何一项，先在工作负载所属项目中补齐，不要用控制台默认值猜测。
提交前停止条件
出现以下任一情况时，不要提交：镜像内容、来源、实际 digest 或命令未经验证；不同角色的运行时兼容性不清楚；节点选择器为空、包含逗号分隔的多值，或没有全局唯一性验证；Header 角色的全局匹配数或 YAML 副本数不等于 1；资源数量没有写入已批准的部署参数；工作负载需要明确的 CPU 或内存请求，但尚未获得控制台之外的受支持配置路径；挂载源、目标路径或读写影响不清楚；需要跨集群通信但网络域未经平台管理员确认；需要访问真实机器人但没有完成独立的安全审批和现场准备。
准备启动清单和部署参数
迁移需要两份相互引用的记录，分别描述工作负载输入和目标环境条件：
- 启动清单记录 RLinf 来源、镜像 digest、Hydra 输入与 override、各角色入口、数据、模型、checkpoint、输出位置和预期业务信号。
- 部署参数由平台管理员确认，记录目标集群、经过全局检查的单值选择器及全部匹配 Node、每个角色的资源容量、StorageClass、可选 Domain 和目标环境限制。
两份记录都应包含对方的版本或固定链接。创建 Job 后，在团队运行记录中关联 Job 名称和复核后的 Job YAML。RLark 没有保存“启动清单 ID”或“部署参数 ID”的专用字段，因此请把这些链接保存在团队运行记录中，不要写入镜像、环境变量或脚本。
text
启动清单（任务要求） ─┐
├─ 逐项核对 → RLark Job YAML → 首次运行记录
部署参数（环境条件） ─┘确定配置如何进入任务
迁移前先确定每项配置的来源，以及它通过镜像、脚本、环境变量、挂载还是 Job 字段进入任务。RLark 会按 Job 内容创建并运行 Worker，但不会把表单内容写回 RLinf 或 Hydra 配置。
| 配置位置 | 包含的内容 | 迁移时怎么处理 |
|---|---|---|
| 镜像 | RLinf 代码、Python 和 Ray 环境、系统库、设备用户态依赖及稳定的基础文件 | 使用可追溯的不可变产物。Task 启动时会用 RLark Ray 脚本作为主容器命令，不要依赖镜像 ENTRYPOINT 执行初始化。 |
| 外部 RLinf/Hydra 配置 | 算法参数、模型和数据约定、RLinf 自身的组件或进程配置、业务输出约定 | 保留在工作负载所属项目中，并通过镜像或挂载提供。环境变量只有在配置或脚本显式读取时才会生效。 |
prepareScript | 该角色的每个 Worker 在 Ray 启动前需要的环境激活、配置复制和低风险检查 | 脚本应能重复执行并便于检查；稳定依赖应写入镜像，不要在每次启动时临时安装。 |
runScript | Head Task 在 Ray 启动和集群检查之后执行的工作负载入口 | 只有 Head Task 保存，但当前该 Task 的每个副本都会执行。必须把副本限制为 1；集群检查失败时仍会继续，因此运行脚本还须验证自身依赖是否就绪。 |
| 环境变量 | 非敏感且由程序或配置显式读取的运行参数 | 控制台把值写入 Pod 模板，但不验证变量名，也不会自动改写 RLinf/Hydra 文件；密钥使用组织批准的管理方式。 |
| 挂载 | 镜像外部的配置、数据、checkpoint 和需要持久化的输出 | 同时确认来源、容器路径和读写影响。挂载到已有目录可能遮蔽镜像内容；hostPath 还必须在每个匹配节点上成立。 |
| RLark Job | 角色和 Header、节点选择、副本、GPU/设备资源、镜像引用、脚本、环境变量、挂载、Domain、SSH 公钥和 TensorBoard 目录 | 表达调度与运行结构；提交前另外验证算法配置和镜像内容，运行后再检查训练结果或硬件行为。当前控制台不能填写 CPU 和内存请求。 |
同一项配置尽量只保留一个来源。例如，算法参数已经写入版本控制中的 Hydra 配置时，不要再在运行脚本中保留另一套默认值；需要覆盖时，请在启动清单中记录覆盖项、来源和原因。
控制台字段、CRD 路径，以及 node_groups、component_placement、env_configs 和 hardware rank 中需要手动配置的内容，见任务创建字段。
配置映射示例
下面以“一个单副本协调入口，加上一组并行采样进程，并把结果写入持久存储”为例，说明这些要求如何填写到 RLark。示例中的镜像、命令、标签、资源数量、路径和 Hydra 值都需要用本次任务的实际内容补充，不能直接提交。
| 任务要求 | 从哪里确认 | 在 RLark 中填写和检查 |
|---|---|---|
| RLinf 代码和配置版本 | 启动清单记录代码 commit、镜像 digest、Hydra 文件、override 和最终配置；部署参数确认目标集群可以拉取镜像 | 为每个角色填写对应镜像，并确认 Job YAML 与清单一致；通过镜像或挂载提供 Hydra 配置 |
| 单个协调或训练入口 | 启动清单指定唯一入口角色和 runScript；部署参数提供恰好匹配 1 个 Node 的完整选择器 | 选择该角色为 Header；确认 Head Task 副本数为 1，而且只有该 Task 包含运行脚本 |
| 并行采样或服务角色 | 启动清单记录角色职责、准备动作和兼容镜像；部署参数确认选择器、匹配节点和每个 Worker 的资源 | 为该角色创建独立 Task；确认副本数与全局匹配结果一致，并检查 Ray、Python 和通信协议兼容性 |
RLinf node_groups 与 placement | 启动清单记录预期进程、rank 和组件关系；部署参数提供实际节点、GPU 和设备拓扑 | 手动拆成角色、nodeSelector、副本和资源，再逐项核对；RLark 不会自动完成映射 |
| 每个进程的环境 | 启动清单记录非敏感 env_configs 含义和准备步骤；部署参数确认驱动、设备和运行限制 | 填写角色环境变量和 prepareScript；确认应用会读取变量，而且脚本可以重复执行 |
| 数据、checkpoint 与输出 | 启动清单记录输入版本、容器路径、对象前缀和完整性规则；部署参数确认 StorageClass 或每个节点上的 hostPath | 添加 PVC、对象存储或主机目录挂载；确认实际读写位于挂载内，并检查多 Worker 访问方式 |
| 跨集群通信 | 启动清单记录业务端口、拓扑和通信网卡；部署参数确认 Domain 和端到端连通性 | 选择 Job Domain，并在应用配置中设置通信网卡；Domain 不会替代 RLINF_COMM_NET_DEVICES 或端口检查 |
| 首次成功信号 | 启动清单记录预期日志、指标、checkpoint 或输出；部署参数说明可以从平台查看哪些 Pod 和 Ray 状态 | 没有对应的 Job 字段；第一次运行后，把平台状态和业务结果一起写入运行记录 |
这张表用于确认每个值从哪里取得、填入哪个 Job 字段，以及运行后到哪里验证。RLinf Node Group 需要手动转换为 RLark 角色；提交前还要验证多种镜像或多个节点可以组成预期的 Ray/RLinf 拓扑。
Job YAML 结构示例
示例包含占位符，不能直接提交
所有尖括号内容都需要使用本次启动清单和部署参数中的值填写，再与控制台生成的 YAML 逐项核对。请勿删除占位符后凭经验猜值。
yaml
apiVersion: rlinf.io/v1alpha1
kind: Job
metadata:
name: <JOB_DNS_NAME_FROM_REVIEW>
spec:
# 可选；仅在部署参数已经确认并完成连通检查时保留。
domain: <OPTIONAL_APPROVED_DOMAIN_NAME>
tasks:
- name: <HEAD_TASK_NAME>
head: true
agentType: Kubernetes
role: <ACTOR_OR_ROLLOUT_OR_ENV>
nodeSelector:
<ADMIN_VERIFIED_LABEL_KEY>: <ADMIN_VERIFIED_SINGLE_VALUE>
prepareScript: |-
<REVIEWED_HEAD_PREPARE_SCRIPT_OR_EMPTY>
runScript: |-
<REVIEWED_RLINF_ENTRYPOINT_FROM_LAUNCH_MANIFEST>
kubernetes:
workload:
kind: StatefulSet
replicas: <MUST_RESOLVE_TO_EXACTLY_1_FOR_HEAD_TASK>
template:
spec:
containers:
- name: main
image: <VERIFIED_IMMUTABLE_IMAGE_REFERENCE>
env:
- name: <NON_SECRET_VARIABLE_NAME>
value: <NON_SECRET_REVIEWED_VALUE>
- name: RLARK_TASK_ROLE
value: <HEADER_ROLE_DISPLAY_NAME_GENERATED_BY_UI>
resources:
requests:
<APPROVED_RESOURCE_NAME>: <APPROVED_PER_WORKER_QUANTITY>
limits:
<APPROVED_RESOURCE_NAME>: <APPROVED_PER_WORKER_QUANTITY>
volumeMounts:
- name: <GENERATED_VOLUME_NAME>
mountPath: <REVIEWED_CONTAINER_PATH>
volumes:
- name: <GENERATED_VOLUME_NAME>
<HOST_PATH_OR_PERSISTENT_VOLUME_CLAIM_BLOCK>: <GENERATED_MOUNT_SOURCE>
- name: <NON_HEAD_TASK_NAME>
head: false
agentType: Kubernetes
role: <ACTOR_OR_ROLLOUT_OR_ENV>
nodeSelector:
<ADMIN_VERIFIED_LABEL_KEY>: <ADMIN_VERIFIED_SINGLE_VALUE>
prepareScript: |-
<REVIEWED_WORKER_PREPARE_SCRIPT_OR_EMPTY>
kubernetes:
workload:
kind: StatefulSet
replicas: <MATCH_COUNT_CONFIRMED_IN_DEPLOYMENT_PROFILE>
template:
spec:
containers:
- name: main
image: <VERIFIED_IMMUTABLE_IMAGE_REFERENCE>
env:
- name: RLARK_TASK_ROLE
value: <NON_HEADER_ROLE_DISPLAY_NAME_GENERATED_BY_UI>
resources:
requests:
<APPROVED_RESOURCE_NAME>: <APPROVED_PER_WORKER_QUANTITY>
limits:
<APPROVED_RESOURCE_NAME>: <APPROVED_PER_WORKER_QUANTITY>
volumes: []创建向导还会根据挂载类型生成具体的 volumeMounts、volumes 和可选 pvcStorageMap。上面的示例没有展开 SSH 公钥和 TensorBoard 字段。请以控制台为本次任务生成的完整 YAML 为准，并逐项对照任务创建字段。非 Head Task 没有 runScript，因为创建向导只把公共运行脚本写入 Head Task。
从旧模型迁移到当前模型
旧版文档中的名称不能直接复制到当前 API。请根据任务的实际运行方式重新配置：
| 旧版表达 | 当前 RLark 表达 | 迁移规则 |
|---|---|---|
| 数据库中的 JobSpec | rlinf.io/v1alpha1 Job | 重新创建当前 Job；不要复制旧 JSON。 |
| Worker Group | spec.tasks[] 中的任务模板 | 每个需要独立资源、镜像或准备过程的角色使用一个模板。 |
| 显式节点名列表 | 每个任务模板的 nodeSelector 和副本数 | 通过当前节点标签表达调度范围，并在 YAML 预览中确认选择器和副本数。 |
| 每个节点的 GPU 或设备数量 | Pod 容器的资源 requests 和 limits | 按角色填写 GPU 和设备；不要从旧节点状态推断当前可用量。 |
| CPU 和内存请求 | Pod 容器的资源 requests | Job YAML 可以表达，但创建向导没有输入项；通过创建器编辑或克隆时也不会保留已有值。需要明确请求时停止使用本流程，并由平台管理员提供可用的提交方式。 |
| Head 节点和公共命令 | 一个 head: true 的任务模板及其 runScript | 选择唯一 Header 角色，并用经全局验证的选择器把它限制为 1 个副本。 |
| 角色初始化脚本 | 每个任务模板的 prepareScript | 只填写能够重复执行、便于检查，而且已在镜像中验证过的准备动作。 |
| 旧对象存储卷 ID | Pod volume、PVC 和 pvcStorageMap | 选择目标集群当前存在的存储类，并确认容器路径和数据来源。 |
| 旧后端生成的 RLinf 放置 YAML | 提交前的 Job CRD YAML 预览 | 预览用于确认 RLark 资源定义，不会替代工作负载自己的 RLinf/Hydra 配置。 |
旧版 worker_group、node_names、num_workers、disable_ray、submit_job、runtime_env_json、extra_files、rlinf_node_rank 和 run_on_host 不是当前控制台 Job CRD 的迁移接口。不要为它们编造同名字段或默认值。
Step 1 固化外部工作负载
在打开创建表单前，用启动清单记录并复核：
- 镜像引用、实际 digest、构建来源和联系人。
- 启动命令及其明确的工作目录。
- 配置文件、输入数据和输出目录。
- 启动前需要执行的准备动作。
- 启动成功、正常运行和运行失败时，日志或输出中分别会出现什么。
先在工作负载原有环境中验证这些内容，再把调度和运行配置填入 RLark 表单。算法配置、镜像内容或镜像入口存在问题时，请先在原有环境修复，不要通过提交 Job 试错。
按照提交训练任务前检查，分别检查表单结构、RLinf 工作负载和目标环境资源。启动清单没有定义不会占用资源的检查方法时，不要把直接启动 RLinf 命令当作预检查。
Step 2 规划角色和 Header
为每个需要不同镜像、资源、节点选择、准备脚本、环境变量或挂载的进程建立一个角色。单进程工作负载不需要为了模仿旧版 Actor、Rollout、Environment 结构而拆分角色。
多角色任务优先使用同一 digest 或同一构建链路的镜像。若角色确实需要不同镜像，逐对确认 Ray 版本和通信兼容性，并核对 Python、RLinf、配置格式、驱动和设备依赖。控制台允许填写不同镜像，但不会执行兼容性检查。
选择一个 Header 角色。当前控制台会把该角色标记为 head: true，并只在这个任务模板中写入运行脚本；但数据面会让该模板的每个副本都启动 Ray Head 并执行运行脚本。提交前确认 YAML 中只有一个任务模板的 head 为 true，且该模板副本数恰好为 1。
控制台允许编辑显示名称，但 Job YAML 中的 role 仍是 Actor、Rollout 或 Env。自定义名称不会自动产生新的运行时语义；必须在 YAML 预览中检查每个模板的 name、role 和 RLARK_TASK_ROLE 环境变量是否符合预期。
Step 3 选择集群、节点和资源
逐个角色完成以下配置：
- 选择目标集群。
- 使用当前节点标签构造节点选择器。每个键只能使用一个值；不要使用界面提供的同键多值组合。
- 让平台管理员在控制面的全局 Node 清单中应用完整选择器，记录所有匹配 Node 的名称和命名空间，并证明结果只属于目标集群。创建器只显示所选集群内的匹配结果，不能替代这一步。
- 确认表单显示的匹配节点数至少为 1，并确认副本数与管理员记录的目标集群匹配数一致。
- 对 Header 角色，匹配节点数和副本数必须恰好为 1。
- 填写 GPU 和其他设备资源。控制台会把非零 GPU 和设备同时写入 requests 与 limits。
- 记录工作负载所需的 CPU 和内存。当前控制台没有对应输入项；如果必须设置非空请求，停止本流程，不要把缺失字段当作平台默认值。
- 确认选择器命中的节点确实能够拉取镜像、访问存储并提供所需设备。
当前调度使用标签选择器，不保证落到旧任务使用过的具体节点。请勿使用逗号分隔的同键多值：这种写法在 Task 所属集群、实际调度和创建向导预览中的处理方式可能不一致。
不要只依赖集群下拉框
Job 任务模板没有独立的 cluster 字段。RLark 根据 nodeSelector 在所有命名空间匹配 Node，并使用第一个结果确定 Task 所在命名空间；选择器为空时会使用默认命名空间。创建器只显示下拉框所选集群内的 Node，也不会显示 rlark.io/cluster-id 标签，因此界面中的匹配数不能证明标签组合在全局唯一。必须取得管理员的全局匹配记录；无法证明时停止提交并补充合适的节点标签。
Step 4 配置镜像和运行环境
为每个角色填写已经验证且可追溯的镜像。优先使用 digest；若使用版本标签，先确认其不可变并记录解析出的 digest。不要从旧文档复制镜像标签，也不要把表单中的占位命令当作可运行示例。当前控制台只验证镜像字段非空，不验证镜像来源、内容或多角色兼容性。
RLark 会用 bash 启动 Ray Head 或 Worker 脚本，并以这段脚本替代镜像的 ENTRYPOINT。因此，每个角色镜像都必须提供 bash 和 Ray CLI，Head Task 使用的镜像还必须提供名为 python 的可执行文件供 Ray 节点检查使用；依赖入口完成的环境激活、目录切换或配置生成必须改为镜像构建步骤，或显式放入对应的准备脚本和 Head Task 的运行脚本。
按需填写：
prepareScript：该角色的每个 Worker 在 Ray 启动前执行的准备动作；保持可重复和低副作用，稳定依赖应固化进镜像。- 环境变量：非敏感、可审计且由程序或配置显式读取的运行参数；平台保留名称与作用域参见运行环境与环境变量。
- 主机目录挂载：目标节点上已确认存在、权限和影响范围清楚的路径。
- 对象存储挂载：目标集群中已经存在并经管理员确认的存储类。
挂载目标如果与镜像中已有的代码或配置目录重叠，容器看到的内容可能被挂载覆盖。提交前应明确哪些文件来自镜像、哪些来自外部配置或数据，并把需要保留的输出写入已经确认的持久路径。
对象存储、PVC、容器挂载和输出持久化的关系参见存储。
控制台会把环境变量值写入 Pod 模板。凭据和其他敏感值必须使用组织批准的 Secret 或密钥管理方式，不要直接填写到表单中。
主机目录
主机目录把节点文件系统暴露给工作负载。只有在平台管理员确认路径、权限、读写影响和清理方案后才能使用；不清楚影响时改用受管理的存储，或停止迁移。
Step 5 配置公共行为
在公共配置中：
- 再次确认唯一 Header 角色，并确认其全局匹配记录和 YAML 副本数都为 1。
- 仅当平台管理员已经创建并批准网络域，且工作负载确实需要跨集群通信时，选择 Domain。
- 仅当需要远程访问并且公钥已经在 SSH 公钥管理中登记时，选择公钥。
- 填写已经在镜像中验证的运行脚本，并显式进入所需工作目录。该脚本由 Head Task 的每个副本在 Ray 启动和集群检查之后执行，因此当前必须确保只有 1 个副本；由于检查失败时仍会继续，运行脚本还必须验证自身依赖是否就绪。不要依赖镜像
ENTRYPOINT。 - 只有在工作负载确实写出兼容事件文件且目录已确认时，填写 TensorBoard 目录。
不要从旧页面复制固定的 RLinf 命令或日志路径。这些值属于当时的工作负载版本，请从本次使用的代码、镜像和配置中确认。
Step 6 检查 YAML 后再提交
在 YAML 预览中至少检查：
apiVersion为rlinf.io/v1alpha1，kind为Job，名称符合预期。spec.tasks中每个预期角色恰好有一个任务模板。- 只有预期模板为
head: true，runScript只出现在该模板，且该模板的副本数恰好为 1。 - 每个模板的
nodeSelector非空且只含单值条件，并与管理员提供的全局匹配记录一致；副本数不为零。 kubernetes.workload的副本数、Pod 模板、容器镜像、GPU 和设备资源与确认结果一致；镜像引用与记录的 digest 或不可变版本一致。创建向导没有 CPU 或内存输入项，因此生成的 YAML 也不会包含这两项请求。- 环境变量、volume、volumeMount 和
pvcStorageMap没有意外路径或敏感值。 - 不同角色的镜像、Ray 和工作负载依赖已按兼容性记录完成核对，挂载没有意外遮蔽镜像内容。
- 可选的 Domain、SSH 公钥和 TensorBoard 目录只在确有需要时出现。
本流程只提交 Kubernetes StatefulSet 工作负载。Docker 和 Raw 运行时没有对应的控制台迁移步骤，请勿用于本流程。
YAML 预览是将要提交的 RLark 资源定义，不是 RLinf 算法配置。预览正确也不能证明镜像内的配置、命令或训练逻辑正确。
Step 7 把“已提交”和“已运行”分开验证
提交成功只表示 API 接受了 Job。随后还需要分别确认：
- Job 和各 Task 已创建，并记录当前状态与消息。当前 StatefulSet Task 不会上报 Succeeded 或 Failed，因此没有失败状态不等于运行正常。
- Task 实际观察到的节点和 Pod 符合选择器与副本设计。
- 镜像拉取、挂载和进程启动均成功。
- 任务自己的成功信号、日志、指标和输出符合所属项目的验收标准；不要等待 Job 自动进入成功或失败终态。
需要保留或恢复训练时，在停止前按保留并恢复 RLinf 训练验证 checkpoint 完整性；需要 TensorBoard、W&B 或 SwanLab 时，按配置实验追踪配置 RLark 入口和外部服务，并分别验证两端结果。
如果运行失败，请保留提交时的 YAML、API 错误、Job/Task 状态和第一条失败消息。一次只修改一个已经确认的问题，再重新执行对应检查；不要同时修改镜像、命令、资源和选择器后反复重试。
第一次运行没有达到预期时，使用首次运行问题排查整理必要信息，找到最早出现问题的环节。原因不明确时，不要通过编辑、停止、克隆或删除任务反复试错。
如果工作负载意外启动或产生非预期影响，先使用平台的停止操作，并确认相关 Task 和 Pod 不再运行。删除 Job 记录不会自动停止外部设备，也不会自动清理存储中的数据。
迁移真机任务前完成安全确认
Env 角色、机器人节点类别、设备资源或 Raw 运行时用于表达任务所需资源，不能代替真实机器人的安全控制。
任何可能连接或驱动真实机器人的迁移，都必须先由设备团队和安全审批人确认：
- 设备、固件、驱动、SDK、控制模式和镜像版本的兼容性。
- 现场操作员、隔离区域、人员进入控制和明确的安全责任人。
- 已测试的急停、断能、复位和通信中断处理。
- 速度、力、行程和工作空间限制，以及异常动作的停止条件。
- 数据和控制命令的审批、审计与恢复方案。
任一项尚未确认时，请停止迁移并继续使用仿真或隔离测试环境。全部确认后，再把批准结果和停止方案写入启动清单，然后进入提交检查。