主题
运行环境与环境变量
Web 控制台会为每个角色生成 Kubernetes StatefulSet Task。角色中填写的环境变量会进入该角色 main 容器的 Pod 模板，并由全部副本使用。提交前，可在 Job YAML 预览的容器 env 中逐项核对。
环境变量只会改变容器进程的环境。只有 RLinf、Hydra、准备脚本或运行脚本显式读取变量时，变量才会改变业务行为。
不要用环境变量传递凭据
环境变量值会直接写入 Job 的 Pod 模板，并显示在 YAML 预览中。不要填写密码、访问令牌、私钥或对象存储 Secret；敏感值必须使用组织批准的密钥管理方式。
为每个角色添加变量
在创建或编辑 Job 的 Worker 配置步骤中，为角色逐项添加键和值。变量只属于该角色；多个角色需要同一变量时，要分别添加并核对。
适合在这里配置的内容包括：
- 应用明确读取的非敏感运行参数；
- 数据、模型和输出在容器中的路径；
- 已确认可用于本次运行的功能开关；
RAY_TEMP_DIR，用于替换 Ray 包装脚本默认使用的/tmp/ray。
设置 RAY_TEMP_DIR 前，确认该角色的每个副本都能写入目标路径，且空间充足。包装脚本没有为该变量添加 shell 引号，因此只能使用符合 ^/[A-Za-z0-9._/-]+$ 的简单绝对路径，例如 /mnt/ray-tmp。路径中不能包含空格、引号、反斜杠、$、;、&、|、<、>、括号、*、?、[ 或其他 shell 元字符。
RAY_TEMP_DIR 只改变 Ray 临时目录，不会改变训练输出、checkpoint 或 TensorBoard 目录。
避开平台保留变量
| 名称 | 平台用途 | 用户操作 |
|---|---|---|
RLARK_TASK_ROLE | 保存角色显示名称 | 不要自定义。同名输入会被移除，再由 RLark 写入角色名称。 |
RLINF_NODE_RANK | 根据 Task 的 rank 起点和 Pod 序号计算节点编号 | 可以读取，不要覆盖，也不要假设它等于节点名称。 |
RAY_TEMP_DIR | 指定 Ray 临时目录 | 可以按本页规则设置；未设置时使用 /tmp/ray。 |
Ray 端口、Head 地址、Pod 身份、节点总数、准备脚本、运行脚本和 SSH 公钥等信息还会使用其他 RLARK_* 变量。包装脚本也会读取 POD_NAME 和 WAIT_NETWORK_SCRIPT。
保留平台变量名称
不要自定义 RLARK_*、RLINF_NODE_RANK、POD_NAME 或 WAIT_NETWORK_SCRIPT。覆盖这些名称可能破坏准备脚本、Ray 组网、rank 或 SSH 公钥注入。用户可调的例外只有 RAY_TEMP_DIR；RLARK_TASK_ROLE 由 RLark 生成。
除本页说明的变量外，不要让业务脚本长期依赖其他平台变量。确有需要时，先由平台管理员确认目标版本是否支持。
了解变量何时生效
Kubernetes Task 的 main 容器按以下顺序启动：
- 计算并导出
RLINF_NODE_RANK。 - 等待平台网络就绪，并处理可选的 SSH 公钥注入。
- 执行对应角色的准备脚本。
- 确认镜像中存在 Ray CLI。
- Head 启动 Ray 并检查预期节点；其他副本解析并连接 Head。
- Head Task 的每个副本执行 Job 运行脚本；非 Head Task 的副本保持 Ray Worker 进程。
准备脚本失败后，Ray 不会继续启动。Head Task 中的运行脚本失败后，对应包装脚本会进入清理流程。日志阶段和判断方法见训练任务与 Worker 排障。
Head Task 必须只有一个副本
Head Task 的每个副本都会启动 Ray Head 并执行运行脚本。提交前必须确认完整选择器在全部 Node 中恰好匹配 1 个节点，并在 YAML 预览中确认副本数为 1。
理解 Ray 集群的生命周期
控制台创建的 Kubernetes Job 不会连接已有 Ray 集群。工作负载每次启动时：
- Head 包装脚本先执行
ray stop，再执行ray start --head。 - RLark 为 Head Task 创建无头 Service。
- 其他 Task 解析该 Service，并执行
ray start --address=... --block加入本次 Job 的 Ray 集群。 - 停止、删除或重建 Pod 会终止其中的 Ray 进程；再次启动会创建新的 Pod 和 Ray 运行时。
因此，“启动已停止任务”不会恢复原来的 Ray actor 或容器内存。应用必须从外部配置和持久 checkpoint 恢复状态。参见保留并恢复 RLinf 训练。
RLINF_NODE_RANK 会在准备脚本前按以下方式计算：
text
Task 在 Job 中的 rank 起点 + StatefulSet Pod 序号Task 的 rank 起点由此前 Task 的副本数累加得到。这个编号不会读取 RLinf node_groups、component_placement 或 hardware rank；提交前需要把两边的放置顺序逐项核对。参见任务创建字段。
每个角色都要验证 Python 和 Ray 环境
包装脚本直接调用 PATH 中的 bash、ray 和 python。准备脚本可以在同一个 shell 中激活环境，但控制台不会检查最终使用的解释器或 Ray 版本。提交前，应在每个角色的镜像中分别验证；只验证 Head 镜像还不够。
提交前检查变量
在 YAML 预览中确认：
- 每个变量只出现在预期角色的
main容器中； - 没有用户定义的平台保留名称；
- 没有凭据或其他敏感值；
- 路径变量与该角色的 volumeMount 一致；
RAY_TEMP_DIR是符合^/[A-Za-z0-9._/-]+$的单个简单绝对路径。
任务运行后，只检查明确、非敏感的单个变量。不要使用一次打印全部环境的命令，也不要把变量值复制到截图或工单。发现值不符时，回到 Job 配置、YAML 预览和角色日志定位来源；容器内的临时修改不会成为持久配置。