cbatch - 提交批处理作业¶

cbatch 主要是将用户描述整个计算过程的脚本传递给作业调度系统，并为作业分配作业号，等待作业调度系统为其分配资源并执行。

鹤思系统中必须有用户和账号才能提交作业，添加用户和账户请参考 cacctmgr 教程。

快速开始¶

首先介绍一个简单的单节点作业的例子：

下列作业将申请一个节点，一个 CPU 核心，并在计算节点上运行 hostname 并退出

#!/bin/bash
#CBATCH --ntasks-per-node 1
#CBATCH --nodes 1
#CBATCH -c 1
#CBATCH --mem 20M
#CBATCH --time 00:30:01
#CBATCH -o job.out
#CBATCH -p CPU
#CBATCH -J Test_Job

hostname

假设上面作业脚本的文件名为 cbatch_test.sh，通过 cbatch 命令提交：

cbatch cbatch_test.sh

cbatch 运行结果展示

[cranetest@crane01 ~]$ cbatch cbatch_test.sh
Job id allocated: 30687

[cranetest@crane01 ~]$ cqueue -p CPU
JOBID PARTITION NAME     USER     ACCOUNT   STATUS TYPE TIME    TIMELIMIT NODES NODELIST/REASON
30685 CPU       Test_Job cranetest CraneTest Pending Batch -      00:30:01   1     Priority
30686 CPU       Test_Job cranetest CraneTest Pending Batch -      00:30:01   1     Priority
30687 CPU       Test_Job cranetest CraneTest Pending Batch -      00:30:01   1     Priority
30683 CPU       Test_Job cranetest CraneTest Running Batch 00:00:12 00:30:01   1     crane[02-03]
30684 CPU       Test_Job cranetest CraneTest Running Batch 00:00:10 00:30:01   1     crane[02-03]

命令行选项¶

资源规格¶

-N, --nodes uint32: 作业要运行的节点数量（默认值：1）
-c, --cpus-per-task float: 每个任务所需的 CPU 核心数（默认值：1）
--ntasks-per-node uint32: 每个节点要调用的任务数量（默认值：1）
--mem string: 最大实际内存量，支持 GB（G，g）、MB（M，m）、KB（K，k）和字节（B），默认单位是 MB
--gres string: 每个任务所需的通用资源，格式：gpu:a100:1 或 gpu:1
--L, --licenses: 作业要使用的许可证，格式：lic1:2,lic2:4或lic1:2|lic2:4

作业信息¶

-J, --job-name string: 作业名称
-A, --account string: 提交作业的账户
-p, --partition string: 请求的分区
-q, --qos string: 作业使用的服务质量（QoS）
-t, --time string: 时间限制，格式：[day-]hours:minutes:seconds（如 5-0:0:1 表示 5 天 1 秒，或 10:1:2 表示 10 小时 1 分钟 2 秒）
--comment string: 作业注释

节点选择¶

-w, --nodelist string: 要分配给作业的节点（逗号分隔的列表）
-x, --exclude string: 从分配中排除特定节点（逗号分隔的列表）

I/O 重定向¶

-o, --output string: 脚本标准输出的重定向路径
-e, --error string: 脚本错误日志的重定向路径
--open-mode string: 打开输出和错误文件的模式。支持的值：append（追加）、truncate（截断，默认）

环境变量¶

--get-user-env: 加载用户的登录环境变量
--export string: 传播环境变量

调度选项¶

--begin string: 作业的开始时间。格式：YYYY-MM-DDTHH:MM:SS
-d, --dependency string: 作业依赖关系。格式：<type>:<job_id>[+<delay>][:<job_id>][,<type>:<job_id>[:<job_id>]] 或 <type>:<job_id>[:<job_id>][?<type>:<job_id>[:<job_id>]]。支持的类型：after、afterok、afternotok、afterany。注意：<delay> 必须使用带单位的时间格式（如 10s、5m、2h），不要使用 HH:MM:SS 格式，因为 : 是作业 ID 分隔符。详见作业依赖
--exclusive: 请求独占节点资源
-H, --hold: 以挂起状态提交作业
-r, --reservation string: 使用预留资源

邮件通知¶

--mail-type string: 当特定事件发生时，向用户发送邮件通知。支持的值：NONE、BEGIN、END、FAIL、TIMELIMIT、ALL（默认：NONE）
--mail-user string: 通知接收者的邮件地址

容器支持¶

容器相关选项用于创建支持容器运行的 Pod 作业。详细使用方法参见 ccon 命令手册和容器快速上手。

--pod: 启用容器模式，将作业创建为 Pod 作业。启用后可在脚本中使用 ccon run 启动容器
--pod-name string: Pod 名称（默认使用作业名）
--pod-port string: Pod 端口映射，格式：HOST:CONTAINER 或 PORT。可多次使用
--pod-user string: 以指定 UID[:GID] 运行 Pod（默认：当 --pod-userns=false 时使用当前用户）
--pod-userns: 启用 Pod 用户命名空间（默认：true，容器内用户映射为 root）
--pod-host-network: 使用宿主机网络命名空间（默认：false）
--pod-dns: 为 Pod 设置 DNS 服务器（仅支持 IPv4）。指定的 DNS server 会被添加到系统默认 DNS 之前（优先级更高，默认使用配置文件 Container.Dns.Servers）

其他选项¶

--interpreter string: 指定脚本解释器（如 /bin/bash、/usr/bin/python3）
-D, --chdir string: 作业的工作目录
--extra-attr string: 作业的额外属性（JSON 格式）
--repeat uint32: 多次提交作业（默认值：1）
--wrap string: 将命令字符串包装到 shell 脚本中并提交
--json: 以 JSON 格式输出
-C, --config string: 配置文件路径（默认：/etc/crane/config.yaml）
-h, --help: 显示帮助信息
-v, --version: 显示 cbatch 版本
--signal: 发送信号给作业

使用示例¶

基本作业提交¶

提交批处理脚本：

cbatch cbatch_test.sh

[cranetest@crane01 ~]$ cbatch cbatch_test.sh
Job id allocated: 30725

帮助信息¶

显示帮助：

cbatch -h

[cranetest@crane01 ~]$ cbatch -h
Submit batch job

Usage:
  cbatch [flags] file

Flags:
  -A, --account string           Account used for the job
  -b, --begin string             Defer job until specified time.
  -D, --chdir string             Working directory of the job
      --comment string           Comment of the job
  -C, --config string            Path to configuration file (default "/etc/crane/config.yaml")
  -c, --cpus-per-task float      Number of cpus required per job (default 1)
  -d, --dependency string        Conditions for job to execute
  -e, --error string             Redirection path of standard error of the script
  -x, --exclude string           Exclude specific nodes from allocating (commas separated list)
      --exclusive                Exclusive node resources
      --export string            Propagate environment variables
      --extra-attr string        Extra attributes of the job (in JSON format)
      --get-user-env             Load login environment variables of the user
      --gpus-per-node string     Gpus required per node, format: [type:]<number>[,[type:]<number>...]. eg: "4" or "a100:1,volta:1"
      --gres string              Gres required per task,format: "gpu:a100:1" or "gpu:1"
  -h, --help                     help for cbatch
  -H, --hold                     Hold the job until it is released
      --interpreter string       Interpreter used to run the script
  -J, --job-name string          Name of job
      --json                     Output in JSON format
  -L, --licenses string          Licenses used for the job
      --mail-type string         Notify user by mail when certain events occur, supported values: NONE, BEGIN, END, FAIL, TIMELIMIT, ALL (default is NONE)
      --mail-user string         Mail address of the notification receiver
      --mem string               Maximum amount of real memory, support GB(G, g), MB(M, m), KB(K, k) and Bytes(B), default unit is MB
      --mem-per-cpu string       Maximum amount of real memory per CPU, support GB(G, g), MB(M, m), KB(K, k) and Bytes(B), default unit is MB
  -w, --nodelist string          Nodes to be allocated to the job (commas separated list)
  -N, --nodes uint32             Number of nodes on which to run (N = min[-max]) (default 1)
      --ntasks-per-node uint32   Number of tasks to invoke on each node (default 1)
      --open-mode string         Set the mode for opening output and error files, supported values: append, truncate (default is truncate) 
  -o, --output string            Redirection path of standard output of the script
  -p, --partition string         Partition requested
      --pod                      Submit as container enabled job (pod will be created)
      --pod-dns strings          Configure DNS server(s) for pod (comma-separated or repeated)
      --pod-host-network         Use host network namespace for the pod
      --pod-name string          Name of pod (defaults to job name)
      --pod-port strings         Publish pod port(s) in HOST:CONTAINER or PORT form
      --pod-user string          Run pod as UID[:GID] (default: current user when --pod-userns=false)
      --pod-userns               Enable pod user namespace (default true)
  -q, --qos string               QoS used for the job
      --repeat uint32            Submit the job multiple times (default 1)
  -r, --reservation string       Use reserved resources
  -s, --signal string            Send signal when time limit within time seconds, format: [{R|B}:]<sig_num>[@sig_time]
  -t, --time string              Time limit, format: "day-hours:minutes:seconds" 5-0:0:1 for 5 days, 1 second or "hours:minutes:seconds" 10:1:2 for 10 hours, 1 minute, 2 seconds
  -v, --version                  version for cbatch
      --wckey string             Wckey of the job
      --wrap string              Wrap command string in a sh script and submit

指定账户¶

使用特定账户提交作业：

cbatch -A=acct-test cbatch_test.sh

[cranetest@crane01 ~]$ cbatch cbatch_test.sh
Job id allocated: 30726

[cranetest@crane01 ~]$ cqueue -j=30726
JOBID PARTITION NAME     USER     ACCOUNT   STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
30726 CPU       Test_Job cranetest acct-test Running Batch 00:01:23 00:30:01   2     crane[02-03]

节点排除¶

从分配中排除节点：

cbatch -x crane01,crane02 cbatch_test.sh

[cranetest@crane01 ~]$ cbatch -x crane01,crane02 cbatch_test.sh
Job id allocated: 30727

[cranetest@crane01 ~]$ cqueue -j=30727
JOBID PARTITION NAME     USER     ACCOUNT   STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
30727 CPU       Test_Job cranetest CraneTest Running Batch 00:00:02 00:30:01   1     crane03

作业名称¶

指定作业名称：

cbatch -J testjob01 cbatch_test.sh

[cranetest@crane01 ~]$ cbatch -J testjob01 cbatch_test.sh
Job id allocated: 30728

[cranetest@crane01 ~]$ cqueue -j=30728
JOBID PARTITION NAME     USER     ACCOUNT   STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
30728 CPU       testjob01 cranetest CraneTest Running Batch 00:00:10 00:30:01   1     crane02

节点选择¶

请求特定节点：

cbatch -w crane01,crane03 cbatch_test.sh

[cranetest@crane01 ~]$ cbatch -w crane01,crane03 cbatch_test.sh
Job id allocated: 30729

[cranetest@crane01 ~]$ cqueue -j=30729
JOBID PARTITION NAME     USER     ACCOUNT   STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
30729 CPU       Test_Job cranetest CraneTest Running Batch 00:00:04 00:30:01   1     crane03

分区选择¶

提交到特定分区：

cbatch -p GPU cbatch_test.sh

[cranetest@crane01 ~]$ cbatch -p GPU cbatch_test.sh
Job id allocated: 30730

[cranetest@crane01 ~]$ cqueue -j=30730
JOBID PARTITION NAME     USER     ACCOUNT   STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
30730 GPU       Test_Job cranetest CraneTest Running Batch 00:00:03 00:30:01   1     crane03

时间限制¶

设置时间限制：

cbatch -t 00:25:25 cbatch_test.sh

[cranetest@crane01 ~]$ cbatch -t 00:25:25 cbatch_test.sh
Job id allocated: 30731

[cranetest@crane01 ~]$ cqueue -j=30731
JOBID PARTITION NAME     USER     ACCOUNT   STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
30731 CPU       Test_Job cranetest CraneTest Running Batch 00:00:06 00:25:25   1     crane02

CPU 核心¶

请求特定数量的 CPU 核心：

cbatch -c 2 cbatch_test.sh

[cranetest@crane01 ~]$ cbatch -c 2 cbatch_test.sh
Job id allocated: 30752

[cranetest@crane01 ~]$ cqueue -j 30752
JOBID PARTITION NAME     USER     ACCOUNT   STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
30752 CPU       Test_Job cranetest CraneTest Running Batch 00:02:40 00:30:01   1     crane02

[cranetest@crane01 ~]$ ccontrol show node crane02
NodeName=crane02 State=alloc CPU=2.00 AllocCPU=2.00 FreeCPU=0.00
  RealMemory=2048M AllocMem=1024M FreeMem=1024M
  Partition=CPU RunningJob=1

内存规格¶

指定内存需求：

cbatch --mem 123M cbatch_test.sh

[cranetest@crane01 ~]$ cbatch --mem 123M cbatch_test.sh
Job id allocated: 30755

[cranetest@crane01 ~]$ cqueue -j 30755
JOBID PARTITION NAME     USER     ACCOUNT   STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
30755 CPU       Test_Job cranetest CraneTest Running Batch 00:00:12 00:30:01   1     crane02

[cranetest@crane01 ~]$ ccontrol show node crane02
NodeName=crane02 State=mix CPU=2.00 AllocCPU=1.00 FreeCPU=1.00
  RealMemory=2048M AllocMem=123M FreeMem=1925M
  Partition=CPU RunningJob=1

多节点作业¶

请求多个节点并指定每个节点的任务数：

cbatch -N 2 --ntasks-per-node 2 cbatch_test.sh

[cranetest@crane01 ~]$ cbatch -N 2 --ntasks-per-node 2 cbatch_test.sh
Job id allocated: 30756

[cranetest@crane01 ~]$ cqueue -j 30756
JOBID PARTITION NAME     USER     ACCOUNT   STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
30756 CPU       Test_Job cranetest CraneTest Running Batch 00:00:25 00:30:01   2     crane[02-03]

[cranetest@crane01 ~]$ ccontrol show node
NodeName=crane02 State=alloc CPU=2.00 AllocCPU=2.00 FreeCPU=0.00
  RealMemory=2048M AllocMem=1024M FreeMem=1024M
  Partition=CPU RunningJob=1

NodeName=crane01 State=mix CPU=2.00 AllocCPU=1.00 FreeCPU=1.00
  RealMemory=2048M AllocMem=1024M FreeMem=1024M
  Partition=CPU RunningJob=1

NodeName=crane03 State=alloc CPU=2.00 AllocCPU=2.00 FreeCPU=0.00
  RealMemory=2048M AllocMem=1024M FreeMem=1024M
  Partition=GPU,CPU RunningJob=1

工作目录¶

指定工作目录：

cbatch -D /path test.sh

[root@cranetest01 zhouhao]# cbatch -e test_error.log -D /nfs/home/zhouhao/test --export ALL cbatch_test.sh
Job id allocated: 196.

[root@cranetest01 zhouhao]# cqueue
JOBID PARTITION NAME     USER ACCOUNT STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
196   CPU       Test_Job root ROOT    Running Batch 00:00:03 00:03:01   1     cranetest02

错误日志¶

重定向错误输出：

cbatch -e error.log test.sh

[root@cranetest01 zhouhao]# cbatch -e test_error.log -D /nfs/home/zhouhao/test --export ALL cbatch_test.sh
Job id allocated: 196.

[root@cranetest01 zhouhao]# cqueue
JOBID PARTITION NAME     USER ACCOUNT STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
196   CPU       Test_Job root ROOT    Running Batch 00:00:03 00:03:01   1     cranetest02

环境变量¶

导出所有环境变量：

cbatch --export ALL test.sh

[root@cranetest01 zhouhao]# cbatch -e test_error.log -D /nfs/home/zhouhao/test --export ALL cbatch_test.sh
Job id allocated: 196.

[root@cranetest01 zhouhao]# cqueue
JOBID PARTITION NAME     USER ACCOUNT STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
196   CPU       Test_Job root ROOT    Running Batch 00:00:03 00:03:01   1     cranetest02

用户环境¶

加载用户的登录环境：

cbatch --get-user-env test.sh

[root@cranetest01 zhouhao]# cbatch --get-user-env -N 1 --ntasks-per-node 2 cbatch_test.sh
Job id allocated: 154.

[root@cranetest01 zhouhao]# cqueue
JOBID PARTITION NAME     USER ACCOUNT STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
154   CPU       Test_Job root ROOT    Running Batch 00:00:04 00:03:01   1     cranetest02

输出重定向¶

重定向标准输出：

cbatch -o output.out test.sh

[root@cranetest01 zhouhao]# cbatch -o test_out.out cbatch_test.sh
Job id allocated: 176.

服务质量¶

指定 QoS：

cbatch -q qos_test test.sh

[root@cranetest01 zhouhao]# cbatch -q test_qos cbatch_test.sh
Job id allocated: 177.

[root@cranetest01 zhouhao]# cqueue
JOBID PARTITION NAME     USER ACCOUNT STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
177   CPU       Test_Job root ROOT    Running Batch 00:00:14 00:03:01   1     cranetest02

重复提交¶

多次提交作业：

cbatch --repeat 3 test.sh

[root@cranetest01 zhouhao]# cbatch --repeat 3 cbatch_test.sh
Job id allocated: 175, 174, 173.

[root@cranetest01 zhouhao]# cqueue
JOBID PARTITION NAME     USER ACCOUNT STATUS TYPE    TIME      TIMELIMIT NODES NODELIST/REASON
173   CPU       Test_Job root ROOT    Running Batch 00:00:02 00:03:01   1     cranetest02
175   CPU       Test_Job root ROOT    Running Batch 00:00:02 00:03:01   1     cranetest04
174   CPU       Test_Job root ROOT    Running Batch 00:00:02 00:03:01   1     cranetest03

环境变量¶

批处理脚本中可用的常用环境变量：

变量	说明
CRANE_JOB_NODELIST	作业分配的节点列表
%j	作业号（用于文件模式）

多节点并行作业¶

下面介绍提交一个跨节点多核心的例子：

下列作业将在三个节点上运行，每个节点使用 4 个 CPU 核心：

#!/bin/bash
#CBATCH -o crane_test%j.out
#CBATCH -p CPU
#CBATCH -J "crane_test"
#CBATCH --nodes 3
#CBATCH --ntasks-per-node 4
#CBATCH -c 4
#CBATCH --time 50:00:00

# 生成作业分配的节点的 machinefile
echo "$CRANE_JOB_NODELIST" | tr ";" "\n" > crane.hosts

# 加载 MPI 运行环境
module load mpich/4.0 

# 执行跨节点并行任务
mpirun -n 13 -machinefile crane.hosts helloWorld > log

高级功能¶

延迟启动¶

将作业调度到特定时间启动：

cbatch --begin 2024-12-31T23:00:00 my_script.sh

挂起作业¶

以挂起状态提交作业：

cbatch --hold my_script.sh

使用 ccontrol release <job_id> 释放挂起的作业。

邮件通知¶

接收电子邮件通知：

cbatch --mail-type=ALL --mail-user=user@example.com my_script.sh

JSON 输出¶

以 JSON 格式获取提交结果：

cbatch --json my_script.sh

包装命令¶

提交简单命令而无需创建脚本文件：

cbatch --wrap "echo Hello && sleep 10 && echo Done"

Signal信号¶

当作业距离结束时间还有 sig_time 秒时，系统会向其发送信号 sig_num。sig_num 可以是信号编号或名称（如 "10" 或 "USR1"）。sig_time 必须是 0 到 65535 之间的整数。默认情况下，作业结束前不会发送任何信号。如果只指定了 sig_num 而未指定 sig_time，则默认提前 60 秒发送信号。

默认情况下，除了batch shell 本身，其他所有作业步骤都会收到信号。使用 "B:" 选项可以只向 batch shell 发送信号，其他进程不会收到信号。

# 在timelimit前60秒发送SIGUSR1信号，除batch进程外其他step都会收到该信号
cbatch --signal=SIGUSR1@60 my_script.sh

# 在timelimit前60秒发送SIGUSR1信号，只有batch进程会收到信号
cbatch --signal=B:SIGUSR1@60 my_script.sh

容器作业¶

使用 --pod 选项创建支持容器的 Pod 作业：

#!/bin/bash
#CBATCH --pod
#CBATCH -N 2
#CBATCH -c 4
#CBATCH --mem 8G
#CBATCH -p GPU
#CBATCH --gres gpu:1
#CBATCH -J container_training

# 在 Pod 内启动容器
ccon run -d -v /data:/data pytorch/pytorch:latest -- python /data/train.py

# 等待所有容器完成
ccon wait

或通过命令行指定容器选项：

cbatch --pod --pod-name my-training --pod-host-network train_job.sh

更多容器使用示例，参见容器使用示例。

另请参阅¶

cqueue - 查看作业队列
ccancel - 取消作业
cacct - 查看作业统计信息
ccontrol - 控制作业和系统资源
ccon - 容器作业管理
容器功能概览 - 容器功能介绍
creport - 查询作业相关统计信息