# 基于Ray Cluster的overlay计算集群方案
 **“中心化控制平面 + 分布式计算平面”** 的架构设计。系统基于 **Ray Cluster** 构建应用层调度器，利用 **SSH** 作为带外（Out-of-Band）节点发现机制，并在底层通过 **NFS** 实现数据一致性。

 ### 0\. 算力平台资源
 ![](./assets/layout.png)
 算力平台上可以申请单节点容器（有无GPU均可）以及分布式任务下多节点容器。
 
 初步设想，在同一个用户账户下预先申请一批分布式任务节点以及一批不同规格（GPU数量）的计算容器，
 并将这些计算容器全部纳管在一个CPU容器中的服务程序下，提供统一的访问入口，供云桌面多用户使用。

以下是该方案的**技术架构规范说明**：

### 1\. 架构拓扑 (Architectural Topology)

![arch.png](./assets/arch.png)

系统采用 **Hub-and-Spoke (星型)** 拓扑结构，逻辑上划分为控制平面（Control Plane）和计算平面（Data Plane）。

  * **控制平面 (Control Plane / Head Node)**

      * 部署于 **CPU 容器**。
      * 承载 **Ray GCS (Global Control Store)**：负责集群元数据管理、任务调度表维护、Actor 寻址。
      * 承载 **API Gateway (FastAPI)**：对外暴露 RESTful 接口，封装 Job Submission API。
      * 承载 **Node Provisioner (Bootstrap Daemon)**：负责节点生命周期管理的守护进程。

  * **计算平面 (Data Plane / Worker Nodes)**

      * 部署于 **GPU 容器池**。
      * 运行 **Raylet**：负责本地资源（GPU/CPU/RAM）管理和 Task 执行。
      * 集成 **Object Store (Plasma)**：负责节点间共享内存对象传输。
      * **IB Interconnect**：配置 NCCL 环境变量，绕过 TCP 协议栈，直接利用 InfiniBand 进行 GPU 显存直连通信（RDMA）。

  * **存储平面 (Storage Plane)**

      * **NFS Protocol**：全节点挂载 `/mnt/shared`。
      * **Artifacts Repository**：统一存储 Codebase、Datasets、Checkpoints、Logs。

### 2\. 核心机制设计 (Core Mechanisms)

#### 2.1 节点发现与纳管 (Node Discovery & Bootstrapping)

![](./assets/node_bootstrap.png)

采用 **SSH-based Side-channel Injection (SSH 侧信道注入)** 机制绕过 K8s 控制面限制。

  * **触发机制**：Provisioner 接收目标节点 IP 及凭证。
  * **握手流程**：
    1.  Provisioner 建立 SSH 连接 (TCP/22)。
    2.  注入 **Ray Runtime Config**，执行 `ray start --address=<HEAD_VIP>:6379`。
    3.  注入 **Custom Resources** (如 `{"node_id_xyz": 1}`) 用于后续的亲和性调度。
  * **状态同步**：Raylet 启动后通过 TCP 回连 GCS，建立长连接心跳。

#### 2.2 任务调度策略 (Scheduling Strategy)

![](./assets/scheduling.png)

系统针对不同负载类型，采用差异化的调度原语：

  * **Type A: SFT Workloads (Job-Level Scheduling)**

      * **调度模式**：**Driver-on-Worker**。
      * **资源原语**：使用 Ray Job Entrypoint 资源约束 (`entrypoint_num_gpus=8`)。
      * **调度逻辑**：
        1.  API Server 接收请求，提交 Job 到 GCS。
        2.  GCS 调度器执行 **Resource Matching**，寻找满足 GPU 数量及 Custom Resource (节点亲和性) 的 Worker。
        3.  将 Shell Command (`torchrun`) 下发至目标 Worker 的 Raylet 执行。
      * **进程模型**：`torchrun` 作为子进程运行，独占节点 GPU。

  * **Type B: RL Workloads (Actor-Level Scheduling)**

      * **调度模式**：**Driver-on-Head** (或 Driver-on-CPU-Worker)。
      * **资源原语**：使用 Ray **Placement Groups**。
      * **调度逻辑**：
        1.  Driver 进程在 Head 节点启动。
        2.  Driver 申请 Placement Group (例如：`{"CPU": 1}` for Controller, `{"GPU": 1} * N` for Rollout Workers)。
        3.  GCS 将不同的 Actors 实例化到集群内的各个 Worker 节点。
      * **通信模型**：Controller 与 Workers 通过 gRPC (Ray Protocol) 交换控制指令；Workers 之间通过 NCCL (IB) 交换 Tensor 数据。

#### 2.3 网络通信规范 (Networking Specification)

![](./assets/networking.png)

  * **Control Plane Traffic (TCP/IP)**

      * 范围：Head \<-\> Worker，Worker \<-\> Worker (非 Tensor 数据)。
      * 端口：6379 (Redis/GCS), 8265 (Dashboard), 10000-65535 (Ephemeral Ports)。
      * 要求：容器间 Overlay 网络互通。

  * **Data Plane Traffic (RDMA/IB)**

      * 范围：Worker \<-\> Worker (DDP/FSDP 通信)。
      * 协议：NCCL over IB Verbs。
      * 配置：通过 `runtime_env` 注入 `NCCL_IB_HCA` 等环境变量，确保训练流量卸载至 IB 网卡，不占用 Overlay 网络带宽。

### 3\. 工作流序列 (Workflow Sequence)

#### 3.1 节点上线流程

![](./assets/node_onboarding.png)

#### 3.2 任务提交流程 (以 SFT 为例)

![](./assets/task_submit.png)

### 4\. 数据持久化与隔离 (Persistence & Isolation)

  * **Runtime Environment Isolation**：
      * 利用 Ray 的 `runtime_env` 特性，在 Job 级别隔离 Python 依赖 (pip packages) 和环境变量。
      * 支持为每个 Job 指定独立的 `working_dir` (指向 NFS 上的特定版本代码库)。
  * **Log Persistence**：
      * Stdout/Stderr 重定向至 NFS 挂载路径 (`/mnt/shared/logs/{job_id}/`)，实现无状态容器的日志持久化。

### 5\. 总结

该架构通过**应用层集群化 (Application-Layer Clustering)** 技术，在异构且受限的 K8s 容器环境之上，构建了一套**逻辑上的 HPC 集群**。它解耦了底层基础设施管理（由 SSH 负责）与上层计算任务调度（由 Ray 负责），是处理 Verl/SkyRL 此类强耦合分布式应用的标准化解决方案。