Slurm GPU Widget：macOS 桌面端超算 GPU 队列状态监视工具

提交 GPU 作业之前，需要确认各分区的空闲卡数。常规流程依次包括连接 VPN、SSH 登录、执行 scontrol 与 squeue，并对输出人工统计。Slurm GPU Widget 将上述流程封装为一个后台采集脚本，以 Übersicht 桌面卡片和 SwiftBar 菜单栏两种形式常驻显示各分区的占用情况；单次刷新耗时约 0.7–1.3 s，默认刷新周期为 15 s。项目以 MIT 协议开源：Yu-Xiang-Yang/slurm-gpu-widget。

1 背景与动机

GPU 集群通常以分区（partition）为单位组织资源，不同分区的 GPU 型号、节点数量与负载差异显著。提交作业前，需要回答以下三个问题：

• 哪个分区仍有空闲 GPU；
• 单个节点上最多有多少空闲 GPU，该数值决定多卡作业能否立即启动；
• 自身作业的运行时长、时间限制与排队状态。

对于需经 VPN 接入的集群，获取上述信息的常规流程存在三方面不便：

• 流程冗长：依次完成 VPN 连接、SSH 登录、命令执行三个步骤，每次查询均需重复；
• 原始输出不含汇总值：scontrol show node 按节点逐行输出，GPU 总数位于 Gres 字段，已分配数位于 AllocTRES 字段，需解析后累加；
• 节点状态需剔除：处于 DOWN、DRAIN 等状态的节点不可调度，若计入总量将高估可用资源。

Slurm GPU Widget 的目标是将该流程自动化，并以常驻界面呈现结果，使资源状态无需登录集群即可读取。

2 功能概述

图 1 Übersicht 桌面卡片界面（模拟数据，由仓库 mock/ 数据与前端源码渲染，启用 SHOW_MY_JOBS=1 与 JOB_GPU_USAGE=1）。上部为各分区的运行/排队/本人作业数、GPU 与内存占用条及单节点最大空闲卡数；下部“我的作业”列出作业 ID、名称、已运行时间/时限，以及各 GPU 的显存占用与利用率。

主要功能如下：

3 系统架构

项目由一个采集脚本与两个前端组成，数据流如下：

Tunnelblick（VPN 状态检测 / 自动连接）
        │
        ▼
cluster-status.sh ── ssh（BatchMode, ControlMaster）──▶ 登录节点：scontrol / squeue
        │  本地 awk 聚合
        ├──── JSON ─────────────▶ Übersicht 桌面卡片
        └──── --swiftbar-stream ▶ SwiftBar 菜单栏

两个前端调用同一采集脚本 cluster-status.sh，二者可单独或同时安装。采集脚本提供四种调用方式：

JSON 结构是采集层与展示层之间的接口约定，替换任一侧不影响另一侧。

4 数据采集方法

采集流程分为五个步骤：

1. VPN 状态：osascript -e 'tell application "Tunnelblick" to get state of first configuration where name = "…"'。
2. 数据获取：ssh -o BatchMode=yes $SSH_HOST "scontrol show node -o; squeue -h -o '%P|%T|%u'"，两条命令共用一次 SSH 往返。
3. GPU 明细（可选，GPU_DETAIL=1）：登录节点并行对各 GPU 节点执行 nvidia-smi --query-gpu=index,name,memory.used,memory.total,utilization.gpu，单节点超时由 GPU_DETAIL_TIMEOUT 限定。在启用 pam_slurm_adopt 的集群上，仅用户有运行作业的节点接受连接，其余节点回退为 Slurm 给出的统计值。
4. 本人作业：squeue -u $USER -t R 提供作业 ID、名称、已运行时间、时限、节点与每节点 GPU 数。
5. 本地聚合：由 awk 完成，规则见下。

聚合规则：

• CPU 使用量取自 CPUAlloc/CPUTot；
• GPU 总数由 Gres 字段解析，支持 gpu:a100:8(S:0-1)、gpu:4、gpu:2g.20gb:12,gpu:1g.20gb:4 等格式；已分配数取自 AllocTRES 中的 gres/gpu=N（数量为零时该字段缺省）；
• Partitions 字段按逗号拆分，隶属多个分区的节点在各分区内分别计数，全局 GPU 总量中仅计一次；
• 处于 DOWN、DRAIN、FAIL、MAINT、NOT_RESPONDING 状态的节点不计入可用容量；
• 主机内存使用量按 RealMemory − FreeMem 计算，原因是未对内存调度的集群上 AllocMem 恒为 0。

4.1 单节点最大空闲卡数

输出中的 gpu_max_free_node 表示单个节点上空闲 GPU（或 MIG 实例）的最大数目，该值给出可立即启动的单节点作业规模上限。图 1 中 gpu 分区空闲 10/16，但单节点最多空闲 8 卡；gpu-v100 分区空闲 0/4，单节点最多空闲 0 卡。全局空闲数与单节点空闲数需结合判读：前者反映总量，后者决定多卡作业能否一次性获得所需节点。

4.2 作业 GPU 使用情况

JOB_GPU_USAGE=1 时，对每个运行中的作业（至多 8 个）在其既有资源分配内执行 srun --jobid=<id> --overlap -N1 -n1 nvidia-smi …。在 ConstrainDevices=yes 的集群上，该命令仅能看到作业持有的 GPU，无需额外的索引映射，也不会申请新的资源。该路径不受 pam_slurm_adopt 限制，但每次查询会在 sacct 中记录为一个作业步（<jobid>.0、<jobid>.1 等），因此默认关闭，并由 JOB_GPU_INTERVAL（默认 30 s）限制查询频率，使小组件产生的作业步数量有界。

图 1 下部为该功能的显示效果：作业 123456（train_llm，2 块 GPU）已运行 1:23:45，时限为 2 天；GPU0 显存占用 59.8/80 GB、利用率 97%，GPU1 显存占用 39.3/80 GB、利用率 88%。显存占用条按占比着色（低于 60% 为绿色，60%–90% 为黄色，90% 及以上为红色），已运行时间在两次集群查询之间由本地逐秒递增。

5 刷新机制与性能

性能方面采取三项措施：

• 连接复用：SSH 启用 ControlMaster=auto 与 ControlPersist=300，复用连接可省去握手开销，源码注释给出的量级为约 1 s 降至约 0.3 s；单次完整刷新耗时约 0.7–1.3 s。
• 查询合并：节点与队列信息在同一会话内一次获取。
• 重叠抑制：采集脚本以目录锁（mkdir）防止并发运行；上一次采集（如 VPN 或 SSH 响应较慢）尚未结束时，直接返回上一次的结果。残留超过 90 s 的锁视为进程异常退出所致，将被清除。

6 安装与配置

6.1 前提条件

1. 免密 SSH：小组件在后台运行，无法响应交互提示，须采用密钥认证。密钥带口令时，需在 ~/.ssh/config 中加入 UseKeychain yes 与 AddKeysToAgent yes；跳板机可通过 ProxyJump 声明。
2. 非交互 VPN：Tunnelblick 的凭据须存入 macOS 钥匙串。需要一次性口令的 VPN 无法自动连接，此时应设置 AUTO_CONNECT=0。
3. 自动化权限：首次运行时 macOS 询问是否允许 Übersicht 或 SwiftBar 控制 Tunnelblick，自动重连需授予该权限。

6.2 安装步骤

安装任一前端并启动一次（以生成其插件目录），随后执行：

git clone https://github.com/Yu-Xiang-Yang/slurm-gpu-widget.git
cd slurm-gpu-widget
bash install.sh
open -e ~/.config/cluster-widget/config

编辑配置后验证采集脚本，输出 JSON 即表明配置有效：

~/.config/cluster-widget/cluster-status.sh
~/.config/cluster-widget/cluster-status.sh --swiftbar

重复执行 install.sh 会更新脚本与小组件，但不会覆盖已有的配置文件。

6.3 配置项

配置文件位于 ~/.config/cluster-widget/config（模板为 config.example），命令行给出的环境变量优先于文件设置。常用配置项如下：

临时查看全部分区及节点明细时，可在命令行覆盖配置，不影响配置文件：

GPU_ONLY=0 SHOW_NODES=1 PARTITIONS=gpu,compute ~/.config/cluster-widget/cluster-status.sh --swiftbar

分区规模较大（约 100 个节点）时，SHOW_NODES=1 宜与 PARTITIONS 联用，以限制卡片高度。

7 输出格式

默认模式输出的 JSON 对象结构如下（节选）：

{
  "lang": "en", "cluster": "Demo", "time": "13:58:32",
  "vpn": "CONNECTED", "error": "",
  "gpu_used": 10, "gpu_total": 20,
  "partitions": [{
    "name": "gpu", "nodes": 3, "idle_nodes": 1, "down_nodes": 1,
    "cpu_used": 48, "cpu_total": 128, "gpu_used": 6, "gpu_total": 16,
    "gpu_max_free_node": 8, "running": 2, "pending": 1, "mine": 0, "mig": false,
    "model": "NVIDIA A100-SXM4-80GB", "mem_used": 1236992, "mem_total": 3072000
  }]
}

字段约定如下：

• 内存数值单位为 MiB；
• node_list 仅在 SHOW_NODES=1 时出现；
• 各节点的 gpus 数组仅在 GPU_DETAIL=1 且该节点接受查询时非空；
• SHOW_MY_JOBS=1 时，顶层对象附加 my_jobs 数组，每个作业含 elapsed_s、limit_s（UNLIMITED 记为 −1），顶层的 epoch 记录采集时刻，供本地计时使用。

8 无集群环境下的测试

仓库的 mock/ 目录提供合成的 scontrol 与 squeue 输出，可在没有集群的环境中验证采集与前端渲染：

MOCK_DIR=mock bash cluster-status.sh
MOCK_DIR=mock SHOW_NODES=1 CLUSTER_NAME=Demo bash cluster-status.sh --swiftbar

图 1 即由模拟数据渲染而成：采集脚本以 MOCK_DIR=mock、USER=testuser、SHOW_MY_JOBS=1、JOB_GPU_USAGE=1 与 PARTITIONS=gpu,gpu-v100 运行，输出的 JSON 交由仓库中的 Übersicht 前端源码渲染，因此图中的作业名称、显存与时间均为 mock/ 目录中的合成数值，不对应真实集群。

9 设计取舍

10 常见问题

11 向其他调度器的扩展

采集脚本中仅远程命令与 awk 解析部分与 Slurm 相关。PBS 对应 pbsnodes -a 与 qstat，LSF 对应 bhosts 与 bqueues。替换这两处后，JSON 结构与两个前端均无需改动。

12 项目地址

GitHub：https://github.com/Yu-Xiang-Yang/slurm-gpu-widget（MIT 协议，含中英文 README）。