COPT计算集群服务

COPT计算集群服务器，COPT Compute Cluster，是一个由杉数求解器提供的，允许用户通过局域网在服务器端执行优化计算的服务。该服务支持在Windows、Linux和MacOS三大系统下运行。

如果COPT计算集群服务器成功启动，可以对装有适配版本的杉数求解器客户端提供优化计算服务，不需要客户端具有任何授权文档。也就是说，COPT计算集群客户端可以在本地建模，然后远程求解，最后交互式地从服务器端获得求解结果。

显然，服务器端同时允许的优化任务数目受限于服务器自己的算力。同时，多台服务器允许组成树状网络拓扑结构的COPT计算集群，从而实现在服务器端横向拓展集群算力。

服务器端安装说明

COPT计算集群服务器对应的可执行文件是 copt_cluster 。其启动时需要验证具有集群类型的许可文件，读取服务器运行所需的配置文件 cls.ini ，以及在杉数授权服务器进行远程验证，例如需要验证服务器IP符合注册信息中要求的IP范围。集群版的许可文件需要通过 copt_licgen 工具和注册后得到的许可凭证，由杉数授权服务器远程自动生成。详情描述如下或者参考前文如何申请与配置许可文件。

安装步骤

杉数提供的COPT远程服务安装包，包含了COPT计算集群服务器端的程序。用户需先通过客服申请注册并获取 COPT远程服务安装包后，可直接将安装包解压缩并放置于自定义路径下。过程属于绿色安装，无需配置环境变量，具体安装步骤演示如下：

对于Windows用户

请使用ZIP解压软件将软件解压至任意目录，推荐软件解压缩到 C:\Program Files 目录下。

对于Linux用户

鼠标操作解压缩COPT远程服务安装包，或在终端上输入下述命令解压缩：

tar -xzf CardinalOptimizer-Remote-8.0.5-lnx64.tar.gz

解压缩后在当前目录下得到 copt_remote80 文件夹，用户可以将它移动到其它自定义路径下。对于Admin用户我们推荐移动到 /opt 目录下，对于非Admin用户可以放在 $HOME 目录下。即在终端下输入下述命令（以Admin用户为例）

sudo mv copt_remote80 /opt

注意，执行该命令需要 root 权限。

对于MacOS用户

鼠标操作解压缩COPT远程服务安装包，或在终端上输入下述命令解压缩：

tar -xzf CardinalOptimizer-Remote-8.0.5-universal_mac.tar.gz

解压缩后在当前目录下得到 copt_remote80 文件夹，用户可以将它移动到其它自定义路径下。对于 root 用户我们推荐移动到 /Applications 目录下，对于非 root 用户可以放在 $HOME 目录下。即在终端下输入下述命令（以 root 用户为例）

mv copt_remote80 /Applications

如果在安装或使用杉数求解器时出现如下错误：

"libcopt.dylib" cannot be opened because the developer cannot be verified.
macOS cannot verify that this app is free from malware.

或者出现类似的动态库签名问题。则使用管理员权限，在终端上执行如下命令，以绕过 MacOS 系统关于动态库的加载检查。

xattr -d com.apple.quarantine CardinalOptimizer-Remote-8.0.5-universal_mac.tar.gz

或者：

xattr -dr com.apple.quarantine /Applications/copt_remote80

许可文件

在成功安装COPT远程服务包后，还需配置集群许可文件。我们推荐把获得的许可文件 license.dat 和 license.key 放置在COPT远程服务安装路径下的 cluster 目录。

下面讲解在不同系统下，如何通过 copt_licgen 工具和许可凭证信息 key 来获取许可文件。

注意

如果用户已经获取到 license.dat 和 license.key 这两个授权文档，则无需重复获取了。可以跳过如下获取许可文件的步骤，直接参阅配置文件。

对于Windows用户

需要打开命令行工具，也就是 cmd 。假如COPT远程服务已安装在 "C:\Program Files" ，在命令行工具窗口输入如下命令后，进入COPT远程服务安装路径下的 cluster 目录：

cd "C:\Program Files\copt_remote80\cluster"

假如用户的许可凭证信息为 7483dff0863ffdae9fff697d3573e8bc ，因为生成许可文件的 copt_licgen 在COPT远程服务安装路径下的 tools 文件夹内，则可以在命令行工具窗口输入下述命令获取杉数COPT的许可文件 license.dat 和 license.key 。

..\tools\copt_licgen -key 7483dff0863ffdae9fff697d3573e8bc

对于Linux和MacOS用户

假如COPT远程服务安装在 "/Applications" 目录下，在终端输入以下命令进入集群服务端目录（以MacOS系统为例）：

cd /Applications/copt_remote80/cluster

假如用户的许可凭证信息为 7483dff0863ffdae9fff697d3573e8bc ，则可以在终端输入下述命令获取杉数COPT的许可文件 license.dat 和 license.key 。

../tools/copt_licgen -key 7483dff0863ffdae9fff697d3573e8bc

特别地，如果用户不是在COPT远程服务安装路径下的 cluster 目录下配置的许可文件，建议将 license.dat 和 license.key 两个许可文件移至此路径下。可手动将这两个文件放到 cluster 目录下，也可以输入下述命令移动这两个许可文件（以MacOS系统为例）。

mv license.* /Application/copt_remote80/cluster

配置文件

COPT计算集群服务器的配置文件 cls.ini ，如下表所示。

[Main]
Port = 7878
# number of total tokens, which copt jobs can run simultaneously up to
NumToken = 3
# password is case-sensitive and empty by default
# it applies to both copt clients and cluster nodes
PassWd =
# data folder of cluster relative to its binary folder,
# where various of copt libraries and temporary job files reside.
DataFolder = ./data

[Memory]
# Example memory management configuration
# memory watermark defense
MemGuard = true
MemSoft = 0.80
MemHard = 0.92
MemFatal = 0.97
MemEvictPolicy = largest
# automatic per-task memory cap
MemLimitAuto = true
MemUsableRatio = 0.90
MemInflation = 1.35
MemOvercommit = 1.50
# 0 means detecting physical memory from the system
MemPhysicalMB = 0

[SSL]
# needed if connecting using SSL
CaFile =
CertFile =
CertkeyFile =

[Licensing]
# if empty or default license name, it is from binary folder
# to get license files from cwd, add prefix "./"
# full path is supported as well
LicenseFile = license.dat
PubkeyFile = license.key

[WLS]
# WebServer have a default host and no need to edit in most scenarios
# Must specify WebLicenseId and WebAccesskey to trigger web licensing
# If specified, ignore settings in Licensing section
WebServer =
WebLicenseId =
WebAccessKey =
WebTokenDuration = 300

[FLS]
# Lease token from floating server
# If specified, ignore settings in Licensing section and WLS section
TokenServer =
TPort = 7979

[Cluster]
# host name and port of parent node in cluster
# If specified or changed on fly, connect to parent node
Parent =
PPort = 7878

[Filter]
# default policy 0 indicates accepting all connections, except for ones in blacklist
# otherwise, denying all connections except for ones in whitelist
DefaultPolicy = 0
UseBlackList = true
UseWhiteList = true
FilterListFile = clsfilters.ini

[Logs]
LogsFolder = ./logs

Main:

在配置文件的 [Main] 部分中，用户可以配置如下连接信息：

Port ：设置集群服务器连接端口，客户端需要连接这个端口才能通讯和获得服务；
NumToken ：设置当前COPT计算集群服务器允许同时求解的优化任务数目。这个数目可以按照本服务器的算力来估算，可由用户自行设置，默认为3，无并发数上限。
PassWd ：设置客户端连接集群服务器的密码，默认为空，表示客户连接不需要设定密码。更安全的连接方式是通过下面的 [SSL] 部分，用户可以通过RSA证书来加密通讯内容。
DataFolder ：设置服务器端安装的COPT求解器所在路径。

COPT计算集群服务器上可以预先安装多个版本的COPT求解器，只有版本匹配的COPT客户端才会被接受求解任务请求。服务器端安装的COPT求解器所在路径由 DataFolder 设定。COPT计算集群服务端安装包中默认预装了当前版本的COPT求解器，用户可以根据使用需求，参照着来设置所需的不同版本。

比如，如果集群服务器端预安装版本号为v8.0.5的COPT求解器，还想安装版本为 v6.0.7的COPT求解器，只需要将COPT v6.0.7客户端安装包中的C算法库，放到 DataFolder 的子目录 ./data/copt/6.0.7/中即可，并且这个安装过程不需要重启服务器即可生效。

以Linux平台为例，用户需要做的操作是从COPT v6.0.7的客户端安装包目录 $COPT_HOME/lib/ 中，复制C算法库 libcopt.so 到集群服务器程序的子目录./data/copt/6.0.7/。

值得注意的是，如果集群服务器的版本是v8.0.5，但用户需要比当前安装版本更新的COPT求解器，比如COPT v9.0.1求解器，也是允许的。这时候，除了需要把COPT v9.0.1的C算法库放入./data/copt/9.0.1/之外，还需要配置对应的单机版授权文档才能加载COPT v9.0.1求解器，所以需要复制一份v9.0.1的单机授权文档到子目录 ./data/copt/9.0.1/。当然如果杉数求解器有重大改动，上述简单安装的方式可能不可行，那么用户需要升级集群服务器到最新版本才可以。

以下示例是Linux系统里的集群服务器的安装目录结构，如下的配置方式可以支持三个版本的COPT求解器，默认的v8.0.5，旧版本v6.0.7，和新版本v9.0.1。

~/copt_remote80/cluster
|  cls.ini
|  copt_cluster
|  license.dat -> cluster license v8.0.5
|  license.key
|
|_ data
    |_ copt
        |_ 6.0.7
            libcopt.so
        |_ 8.0.5
            libcopt.so
        |_ 9.0.1
            libcopt.so
            license.dat -> license v9.0.1
            license.key

Memory:

在配置文件的 [Memory] 部分中，用户可以配置COPT计算集群服务器的单任务内存限额和内存水位防护功能。

注意

上述 [Memory] 配置中的数值仅为示例，不表示程序的默认值。

单任务内存限额：

MemLimitAuto：是否启用自动单任务内存限额，默认为 true。该参数是自动单任务内存限额的总开关：设为 true 时，服务器在每次求解开始时计算并施加单任务内存限额；设为 false 时，服务器不计算也不施加该限额，求解任务仅受客户端自行设置的 MemLimit 和内存水位防护约束。此外，当Token数为0时，服务器不施加单任务内存限额；
MemUsableRatio：可供求解任务使用的物理内存比例；
MemInflation：求解器统计内存用量与实际常驻内存用量之间的换算系数；
MemOvercommit：单个任务可使用的内存相对于平均内存份额的倍数；
MemPhysicalMB：服务器物理内存大小，单位为MB。设为 0 时，由服务器自动检测；在受内存限制的容器中，以cgroup内存限额为准。

内存水位防护：

MemGuard：是否启用内存水位防护；
MemSoft：软水位。达到该水位时，服务器暂停接收新任务；
MemHard：硬水位。达到该水位时，服务器选择一个正在求解的任务并将其中断；
MemFatal：紧急水位。达到该水位时，服务器中断所有正在求解的任务；
MemEvictPolicy：达到硬水位时待中断任务的选择策略，支持以下取值：
- largest：选择当前内存用量最大的任务，为默认策略；
- longest：选择求解时间最长的任务；
- youngest：选择最近开始求解的任务；
- random：随机选择一个正在求解的任务。

MemSoft、MemHard 和 MemFatal 均表示已用物理内存占总物理内存的比例，取值范围为 0.0 至 1.0。

有关单任务内存限额的计算方式、内存水位触发机制、内存限额豁免、旧版本兼容性及部署建议，请参见服务器端内存管理。

Licensing:

在配置文件的 [Licensing] 部分中，用户可以自定义授权文档的读取路径。如上面注释描述，默认为空缺或者为默认的授权文档名（即 license.dat 和 license.key ），这表示COPT计算集群服务器从可执行程序（即 copt_cluster ）所在目录下读取授权文档。

如果用户在当前目录下启动集群服务器，并且许可文件也在当前目录下，通过修改 LicenseFile = ./license.dat 和 PubkeyFile = ./license.key ，可以让COPT计算集群服务器从当前目录读取授权文档。

我们知道杉数求解器还允许客户通过环境变量 COPT_LICENSE_DIR 设置授权文档所在的路径。详情可参考如何安装杉数求解器。在这种情况下，需要修改配置文件为完整的环境变量路径，COPT计算集群服务器才能读取环境变量下的授权文档。

Cluster:

在配置文件的 [Cluster] 部分中，用户可以设置当前集群服务器连接的父节点（IP和端口），默认为空缺，表示不和其他节点连接。

Parent ：父节点在局域网内的IP地址
PPort ：父节点的端口号

若只有单台集群服务器，或者当前服务器就是根节点，则不需要设置该部分；若有多台集群服务器，则可以通过指定父节点来组成树状网络拓扑结构的COPT计算集群，当前服务器可以通过这个设置来加入到父节点所在的集群中去。COPT支持在多任务计算场景下进行集群负载均衡，从而在各服务器之间合理分配计算任务，提高计算资源利用率。

Filter:

在配置文件的 [Filter] 部分中，用户可以配置集群服务器的过滤策略。

DefaultPolicy ：默认设为0，表示除了在黑名单里的客户端，其他均允许连接到本集群服务器；反之若设为非0取值，则表示除了在白名单中的客户端，其他设备均无法连接到本集群服务器。
UseBlackList ：若设置为 True ，则表示使用黑名单列表，
UseWhiteList ：若设置为 True ，则表示使用白名单列表。
FilterListFile ：用于设置集群服务器的过滤配置文件名，默认为 clsfilters.ini 。其格式举例如下：

[BlackList]
# 127.0.*.* + user@machine*

[WhiteList]
# 127.0.1.2/16 - user@machine*

[ToolList]
# only tool client at server side can access by default
127.0.0.1/32

[MemWhiteList]
# 127.0.0.1/32

BlackList 和 WhiteList 分别用于设置黑名单和白名单规则； ToolList 用于限制集群管理工具的访问，添加相关IP地址表示允许对应的远程机器访问； MemWhiteList 用于设置单任务内存限额豁免规则。

匹配 MemWhiteList 中任意一条规则的客户端不受服务器自动计算的单任务内存限额约束，但仍受客户端自行设置的 MemLimit 和内存水位防护约束。 MemWhiteList 使用与黑名单和白名单相同的 IP + user@machine 规则格式。该部分不影响客户端能否连接集群服务器，并且不受连接过滤模式影响，始终处于启用状态。

具体来说，过滤配置中的规则格式以IP地址开头。要指定IP范围，可以在IP地址中使用通配符（*），或者使用CIDR表示法，即IPv4地址及其相关的网络前缀。另外，IP地址后面还可以包括（+）或者排除（-）给定用户名和给定机器名，形如 127.0.1.2/16 - user@machine 。其中用户名 user 是指用户名，MacOS/Linux系统用户可以在终端通过命令 whoami 来查询；机器名 machine 是指机器名，MacOS/Linux系统用户可以在终端通过命令 hostname 来查询。

需注意的是，配置文件 clsfilters.ini 更改之后，可使用 ResetFilters 命令把当前的规则重置为过滤配置文档里的规则。也可使用 WriteFilters 命令把当前的规则输出到过滤配置文档。

Logs:

在配置文件的 [Logs] 部分中，用户可以设置集群服务器的日志存储路径，默认存放在集群服务器安装包的 ./logs 路径下。

在线集群许可

除了上述的本地集群许可证外，用户还可以使用在线许可（Web License）来运行计算集群服务。此方案要求运行计算集群服务的机器必须具有互联网访问权限，但是不再需要绑定硬件信息。也就是说，用户可以自由地将计算集群服务部署到任何云机器或容器上，只要它们能够连接到互联网。有关详细信息，请参考 COPT Web Licenses 。

以下是简要步骤：

按照步骤注册账户并申请在线集群许可。

审核通过后，系统会为用户生成一个 Web License ID 。

在 API Keys 页面，使用给定的 Web License ID 创建 Web Access Key 。

之后，用户需要编辑配置文件 cls.ini ，并将 Web License ID 和 Web Access Key 的值添加到 WLS 部分的相关字段。例如：

[WLS]
# WebServer have a default host and no need to edit in most scenarios
# Must specify WebLicenseId and WebAccesskey to trigger web licensing
WebServer =
WebLicenseId =
WebAccessKey =
WebTokenDuration = 300

目前，计算集群服务器通过 COPT Web Licenses 进行授权。用户可以在线监控其令牌使用情况及其他信息。

使用示例

如果正确的集群版授权文档安装在集群服务器可执行文件所在的目录下，要启动COPT计算集群服务器，只需在Windows的命令行或者Linux和MacOS的终端中输入下述命令：

./copt_cluster

若屏幕输出如下，则表示成功启动集群服务器，启动后会监视和管理客户端的申请。如果用户输入字符 Q ，则集群服务器会关闭退出。

> ./copt_cluster
  [ Info] start COPT Compute Cluster, v8.0.5 20240304
  [ Info] [NODE] node has been initialized
  [ Info] server started at port 7878

如果本地集群版授权文档验证不通过，或者远程杉数授权服务器连接错误，则可能出现如下输出。

> ./copt_cluster
  [ Info] start COPT Compute Cluster, v8.0.5 20240304
  [Error] Invalid signature in public key file
  [Error] Fail to verify local license

和

> ./copt_cluster
  [ Info] start COPT Compute Cluster, v8.0.5 20240304
  [Error] Error to connect license server
  [Error] Fail to verify cluster license by server

服务端内存管理

COPT计算集群服务器通过单任务内存限额和内存水位防护两种机制管理内存。单任务内存限额用于控制单个求解任务的内存用量；内存水位防护用于监控服务器的整体物理内存使用情况，并在达到设定水位时采取相应措施。

单任务内存限额

启用 MemLimitAuto 后，服务器在每次求解开始时，根据服务器的物理内存、当前占用Token的会话数及相关配置计算单任务内存限额。该限额在本次求解期间保持不变，并在下一次求解开始时重新计算。

服务器按照以下公式计算单任务内存限额：

Budget = PhysicalMemory * MemUsableRatio / MemInflation
Share  = Budget / SessionsHoldingToken
Cap    = min(MemOvercommit * Share, Budget / 2)

其中：

PhysicalMemory 表示服务器物理内存；
SessionsHoldingToken 表示当前占用Token的会话数；
Budget 表示可供求解任务使用的内存预算；
Share 表示每个占用Token的会话对应的平均内存份额；
Cap 表示服务器自动计算的单任务内存限额。

当前仅有一个会话占用Token时，新开始的求解任务最多可获得内存预算一半的内存限额。随着占用Token的会话数增加，新开始的求解任务将获得较小的内存限额。

客户端仍通过常规COPT参数接口设置 MemLimit，不需要使用专门的集群客户端接口。如果客户端同时设置了 MemLimit，则单次求解期间实际采用的内存限额为客户端设置值与服务器自动计算值中的较小值。客户端设置的 MemLimit = 0 表示严格的零内存限额。

求解结束后，服务器恢复客户端原先设置的 MemLimit。下一次求解开始时，服务器会重新计算单任务内存限额。

MemInflation 用于换算求解器自身统计的内存用量与操作系统观察到的实际常驻内存用量。例如，设为 1.35 表示求解器每统计1字节内存，预计对应约1.35字节的实际常驻内存。该数值仅用于说明参数含义，不表示程序默认值。

内存水位防护

启用 MemGuard 后，服务器约每500毫秒检查一次系统物理内存使用率，并根据当前内存使用率采取以下措施：

达到软水位 MemSoft 时，服务器暂停接收新任务，但不影响正在运行的任务。当内存使用率降至 MemSoft - 0.03 以下时，服务器恢复接收新任务；
达到硬水位 MemHard 时，服务器根据 MemEvictPolicy 选择一个正在求解的任务并将其中断。中断一个任务后，服务器至少等待5秒，并等待该任务实际停止。如果内存使用率仍在下降，则不会立即中断下一个任务；
达到紧急水位 MemFatal 时，服务器中断所有正在求解的任务，并持续检查，直至内存使用率降至该水位以下。

服务器通过调用 COPT_Interrupt 中断任务，求解将在下一个可中断点停止。如果求解器已经获得当前最好可行解，客户端仍可获取该解及相应的中断状态。任务所属会话保持连接，之后仍可再次发起求解。

只有正在执行求解的任务才会被选择。空闲会话即使仍持有模型，也不会被选择，因为对空闲会话调用 COPT_Interrupt 无法释放其模型内存。

内存限额豁免

用户可以在过滤配置文件 clsfilters.ini 的 [MemWhiteList] 部分中设置单任务内存限额豁免规则。匹配任意一条规则的客户端不受服务器自动计算的单任务内存限额约束，但仍受客户端自行设置的 MemLimit 和内存水位防护约束。

[MemWhiteList] 使用与黑名单和白名单相同的 IP + user@machine 规则格式。该部分不影响客户端能否连接集群服务器，并且不受连接过滤模式影响，始终处于启用状态。建议尽可能将豁免规则限定到具体IP地址或子网。

例如，可以在 clsfilters.ini 中添加以下规则：

[MemWhiteList]
192.168.1.*
10.0.0.0/16+batch@prod-*
*.*.*.*+alice@*

上述示例中：

192.168.1.*：豁免来自该IP地址范围的客户端；
10.0.0.0/16+batch@prod-*：豁免来自该子网，且用户名为 batch、机器名匹配 prod-* 的客户端；
*.*.*.*+alice@*：豁免用户名为 alice 的客户端，不限制其IP地址和机器名。

多条规则相互独立。客户端只要匹配其中任意一条规则，即可获得单任务内存限额豁免。对于同时包含IP地址、用户名和机器名的规则，客户端需要同时匹配该条规则中的各个部分。

兼容旧版本COPT

集群服务器会根据每个任务实际加载的COPT版本，检查相关内存管理功能是否可用：

软水位和紧急水位不依赖特定的COPT版本；
longest、youngest 和 random 策略不依赖特定的COPT版本；
largest 策略要求任务所加载的COPT版本支持 COPT_GetMemUsage。如果不支持，达到硬水位时无法通过该策略选择待中断任务，但紧急水位仍然有效；
自动单任务内存限额要求任务所加载的COPT版本支持 MemLimit 参数。如果不支持，该任务将不受服务器自动计算的内存限额约束；
如果任务所加载的COPT版本不支持获取当前内存用量、峰值内存用量或内存限额， GetJobs 将在相应列中显示 -。

当集群服务器需要加载不支持 COPT_GetMemUsage 的旧版本COPT时，可将 MemEvictPolicy 设置为 longest、youngest 或 random。

部署建议

以下配置可用于进一步降低服务器内存耗尽的风险。其中各项数值仅供参考，不表示程序默认值：

[Memory]
MemGuard = true
MemSoft = 0.70
MemHard = 0.80
MemFatal = 0.90
MemLimitAuto = true
MemUsableRatio = 0.75
MemInflation = 1.50
MemOvercommit = 1.00

通过调整 MemUsableRatio、 MemInflation 和 MemOvercommit，可以控制自动计算的单任务内存限额，并为服务器的其他内存开销预留空间。具体配置值应根据服务器资源和实际任务的内存使用情况确定。

当 MemOvercommit = 1.00 时，即使在满并发的情况下，所有任务的内存限额之和也不会超过 MemUsableRatio / MemInflation 所对应的物理内存比例；在上述示例中为物理内存的50%。

如果需要由操作系统进一步限制集群服务的最大内存用量，可以使用cgroup，或者通过systemd的 MemoryMax= 为服务设置低于物理内存总量的内存限额。

客户端使用说明

COPT计算集群客户端可以是COPT命令行交互工具，或者通过接口调用杉数求解器动态库的方式，比如COPT Python接口。如果客户没有任何单机许可，那么集群许可是一种更灵活的替代方式。所有使用COPT的客户端都可以通过集群服务器来合法使用杉数求解器。

安装和配置

通过配置文件

首先用户需要确保已在客户端正确安装杉数求解器，详情可参考如何安装杉数求解器。成功安装COPT客户端后，用户不需要配置本地的许可文件，但需要自行新建COPT计算集群客户端的配置文件 client.ini，并配置对应的连接信息，如下表所示：

Cluster = 192.168.1.11
Port = 7878
WaitTime = 600
Passwd =

上述配置文件表示客户端会尝试和 192.168.1.11:7878 连接，且排队等待时间最多为600秒。

这里，如果 Cluster 内容空缺，默认设为 localhost 。 WaitTime （或 QueueTime ）空缺则认为是0，即如果集群服务器的Token数目已经被占满就不等待，直接错误退出。 Port 如果空缺，则设为默认的7878，但要确保和集群服务器的配置文件里设的端口一致。注意客户端配置文件中的关键词并不区分大小写。

此外，用户还可以通过 Passwd 来设置远程服务器的访问密码；可以通过 Priority 来设置集群求解任务的优先级，可取值为0-99，取值越大表示优先级越高。如果任务有在排队，按优先级设置可在下个任务优先处理，但不改变已在运行的任务。

使用COPT计算集群服务的前提是客户端首先发现的是配置文件 client.ini ，而不是本地许可文件。但和寻找本地许可文件的途径一样，客户端会从当前目录，环境变量目录 COPT_LICENSE_DIR 和客户端可执行文件所在目录，依次查看是否有连接服务器的配置文件 client.ini 。所以，如果用户想使用COPT计算集群服务，需要确保COPT客户端优先找到的是配置文件，而不是本地授权许可（如果有的话）。比如，用户已经在环境目录下有了本地许可，那么用户还可以在当前目录（不同于环境目录）下，建立配置文件 client.ini 来优先使用集群服务的方式。

如果是调用杉数求解器动态库方式，比如COPT Python接口，在建模中创建COPT优化求解环境时，会按照配置文件 client.ini 的设置，从集群服务器获取求解服务。这里，每个COPT求解环境对象需要建立和集群服务器的连接并占用一个Token，建模结束后释放COPT求解环境对象时，会通知服务器释放占用的Token。

通过API函数配置

除了上述 client.ini 的方式之外，用户还可以在代码中通过API函数配置客户端。以COPT Python接口为例，对应的类为 EnvrConfig类，其他编程语言也类似。如下所示：

# 设置客户端的配置参数
envconfig.set(COPT.CLIENT_CLUSTER, "192.168.1.11")
envconfig.set(COPT.CLIENT_PORT, "7878")
envconfig.set(COPT.CLIENT_WAITTIME, "600")

高可用性

在拥有多台集群服务器的情况下，客户端可以通过在 client.ini 的 Cluster 字段配置多个 Cluster服务器IP地址来实现高可用性，如下表所示：

Cluster = 192.168.1.11; 192.168.1.22; 192.168.1.33
Port = 7878
WaitTime = 600
Passwd =

其中， Cluster 字段中第一个IP为集群的根节点IP，若集群其他子节点的端口号不是 7878 ，可以在IP地址后加上端口号。上述配置文件表示客户端会先尝试和根节点 192.168.1.11:7878 连接，如果该根节点不可用，则会尝试和 192.168.1.22:7878 的子节点连接；依次类推，直到和集群服务器连接成功。

如果某个集群节点在执行计算任务时出现故障，那么客户端会按配置文件中的替补节点重新分配可用集群节点。这样可以使得集群服务具备一定的灾备能力，从而提高COPT计算集群服务的高可用性。

使用示例

假如用户在当前目录下创建了客户端配置文件 client.ini （同时没有本地许可文件），下面以交互式命令行工具 copt_cmd 为例，演示如何建立与集群服务器的连接。首先，在Windows的命令行或者Linux和MacOS的终端中输入下述命令：

copt_cmd

若屏幕输出如下，则表示客户端成功连接到集群服务器，可以在本地建模，然后远程求解。

> copt_cmd
  Cardinal Optimizer v8.0.5. Build date Mar 04 2024
  Copyright Cardinal Operations 2025. All Rights Reserved

  [ Info] initialize cluster client with ./client.ini

  [ Info] wait for server in 0 / 39 secs
  [ Info] connecting to cluster server 192.168.1.11:7878
COPT>

若屏幕输出如下，则表示客户端连接到集群服务器，但由于Token数目有限，需要排队等待。

> copt_cmd
  Cardinal Optimizer v8.0.5. Build date Mar 04 2024
  Copyright Cardinal Operations 2025. All Rights Reserved

  [ Info] initialize cluster client with ./client.ini

  [ Info] wait for server in 0 / 39 secs
  [ Info] connecting to cluster server 192.168.1.11:7878

  [ Warn] wait in queue of size 5
  [ Info] wait for license in  2 / 39 secs
  [ Info] wait for license in  4 / 39 secs
  [ Info] wait for license in  6 / 39 secs
  [ Info] wait for license in  8 / 39 secs
  [ Info] wait for license in 10 / 39 secs
  [ Info] wait for license in 20 / 39 secs
  [ Info] wait for license in 30 / 39 secs
  [Error] timeout at waiting for server approval
  [Error] Fail to initialize copt command-line tool

若屏幕输出如下，则表示客户端连接到集群服务器，但用户拒绝排队等待。然后客户端立即返回错误后退出。

> copt_cmd
  Cardinal Optimizer v8.0.5. Build date Mar 04 2024
  Copyright Cardinal Operations 2025. All Rights Reserved

  [ Info] initialize cluster client with ./client.ini

  [ Info] wait for server in 0 / 9 secs
  [ Info] connecting to cluster server 192.168.1.11:7878
  [ Warn] server error: "no more token available", code = 129
  [Error] Fail to initialize copt command-line tool

若屏幕输出如下，则表示客户端无法连接集群服务器，超时后退出。

> copt_cmd
  Cardinal Optimizer v8.0.5. Build date Mar 04 2024
  Copyright Cardinal Operations 2025. All Rights Reserved

  [ Info] initialize cluster client with ./client.ini

  [ Info] wait for server in 0 / 39 secs
  [ Info] connecting to cluster server 192.168.1.11:7878
  [ Info] wait for license in  2 / 39 secs
  [ Info] wait for license in  4 / 39 secs
  [ Info] wait for license in  6 / 39 secs
  [ Info] wait for license in  8 / 39 secs
  [ Info] wait for license in 10 / 39 secs
  [ Info] wait for license in 20 / 39 secs
  [ Info] wait for license in 30 / 39 secs
  [Error] timeout at waiting for server approval
  [Error] Fail to initialize copt command-line tool

此外，用户还可以通过如下方式在客户端启动COPT命令行工具，表示连接指定IP地址的集群服务器：

> copt_cmd -cluster <ip>

集群服务器管理工具

COPT计算集群服务器同时提供了一个对服务器端进行管理的工具 copt_clstool ，用来查看集群服务器的配置信息，并且具有在线修改的功能。

工具说明

在Windows的命令行或者Linux和MacOS的终端中输入下述命令：

> ./copt_clstool

屏幕输出如下:

> ./copt_clstool
  COPT Cluster Managing Tool

  copt_clstool [-s server ip] [-p port] [-x passwd] command <param>

  commands are:   addblackrule <127.0.0.1/20[-user@machine]>
                  addwhiterule <127.0.*.*[+user@machine]>
                  addmemexempt <127.0.*.*[+user@machine]>
                  delmemexempt <127.0.*.*[+user@machine]>
                  getfilters
                  getinfo
                  getnodes
                  getjobs
                  interrupt
                  reload
                  resetfilters
                  setparent <xxx:7878>
                  setpasswd <xxx>
                  settoken <num>
                  setmemguard <on|off>
                  setmemlimitauto <on|off>
                  setmemevictpolicy <largest|longest|youngest|random>
                  toggleblackrule <n-th>
                  togglewhiterule <n-th>
                  writefilters

上面是这个工具的使用格式说明。用户通过 -s 和 -p 来设置目标服务器的IP地址和端口。如果不写，则默认是本地服务器和端口7878。如果服务器设置了非空密码，那么需要通过 -x 来设置密码后才能成功连接。

这个工具提供的命令包括：

AddBlackRule: 添加一条黑名单规则。规则以IP地址开头，可以使用通配符或CIDR表示法指定IP地址范围。 IP地址后还可以使用 + 或 - 包含或排除指定用户名和机器名。
AddWhiteRule: 添加一条白名单规则。白名单规则的格式与黑名单规则相同。
AddMemExempt: 添加一条单任务内存限额豁免规则。匹配该规则的客户端不受服务器自动计算的单任务内存限额约束，但仍受客户端自行设置的 MemLimit 和内存水位防护约束。该命令修改内存中的规则并立即生效。
DelMemExempt: 删除指定的单任务内存限额豁免规则。该命令修改内存中的规则并立即生效。
GetFilters: 获取当前的黑名单、白名单、集群管理工具访问规则和单任务内存限额豁免规则。黑名单和白名单中的每条规则均带有序号，可分别作为 ToggleBlackRule 和 ToggleWhiteRule 命令的参数。
GetInfo: 获取服务器的基本信息，包括Token使用情况、已连接的客户端、支持的COPT版本，以及内存水位防护状态、下一个求解任务的预计内存限额和当前的内存限额豁免客户端。
GetNodes: 获取服务器作为集群节点的连接信息，包括父节点和子节点。
GetJobs: 获取当前服务器上的任务信息，包括任务编号TID、运行时长（单位为秒）、客户端ID、当前内存用量、峰值内存用量和内存限额。内存相关信息的单位为MB。如果任务所加载的COPT版本不支持获取相应的内存信息，则对应列显示 -。
Interrupt: 中断当前服务器上指定TID的任务。执行该命令后，客户端上对应的求解任务将停止，并返回相应的中断状态。
Reload: 动态更新当前服务器所有子节点的Token占用情况。当节点之间的占用信息不一致时，可以使用该命令重新加载。
ResetFilters: 根据过滤配置文件重新加载当前的过滤规则。
SetParent: 动态更新并连接当前服务器的父节点。
SetPasswd: 动态更新当前服务器的连接密码。
SetToken: 动态更新当前服务器的Token数。
SetMemGuard: 启用或禁用内存水位防护。可选值为 on 和 off。
SetMemLimitAuto: 启用或禁用自动单任务内存限额。可选值为 on 和 off。修改后的设置适用于之后开始的求解任务。
SetMemEvictPolicy: 设置达到硬水位时选择待中断任务的策略。可选值为 largest、 longest、youngest 和 random。
ToggleBlackRule: 根据 GetFilters 返回的序号启用或禁用一条黑名单规则。
ToggleWhiteRule: 根据 GetFilters 返回的序号启用或禁用一条白名单规则。
WriteFilters: 将当前内存中的全部过滤规则写入过滤配置文件，包括黑名单、白名单、集群管理工具访问规则和单任务内存限额豁免规则。

通过 SetMemGuard、 SetMemLimitAuto 和 SetMemEvictPolicy 对内存管理配置所作的修改仅在当前服务器运行期间有效，不会写入 cls.ini。服务器重新启动后，将重新采用 cls.ini 中的配置。

使用示例

下面的命令列出了服务器为 192.168.1.11 的基本信息。

> ./copt_clstool -s 192.168.1.11 GetInfo

[ Info] COPT Cluster Managing Tool, COPT v8.0.5 20240304
[ Info] connecting to 192.168.1.11:7878
[ Info] [command] wait for connecting to cluster
[ Info] [cluster] general info
  # of available tokens is 3 / 3, queue size is 0
  # of active clients is 0
  # of installed COPT versions is 1
    COPT v8.0.5  Physical Memory: 71.8% used, Defense Status: [OK] (soft 80% / hard 92% / fatal 97%)
  Per-task Memory Cap: 5461 MB (by demand with N=3)
  Memory exempt clients: 127.0.0.1, 127.0.0.*

下面的命令列出服务器上的任务及其内存信息：

./copt_clstool -s <ip> -p <port> getjobs

输出中包含以下字段：

ThreadID  Duration(s)  MemUsage(MB)  MemPeak(MB)  MemLimit(MB)  ClientID

其中：

ThreadID：任务编号；
Duration(s)：任务运行时长，单位为秒；
MemUsage(MB)：当前内存用量，单位为MB；
MemPeak(MB)：峰值内存用量，单位为MB；
MemLimit(MB)：当前设置在该问题上的内存限额，单位为MB。求解期间显示实际生效的限额，其他情况下显示客户端自行设置的值；
ClientID：客户端编号。

MemUsage 和 MemPeak 均来自求解器自身的内存统计，因此与操作系统观察到的实际常驻内存用量可能存在差异，二者之间的换算关系可参考 MemInflation。

如果任务所加载的COPT版本不支持获取某项内存信息，则相应列显示 -。

下面的命令演示如何在服务器运行期间启用内存水位防护和自动单任务内存限额，并将达到硬水位时的任务选择策略设置为 largest：

./copt_clstool -s <ip> -p <port> setmemguard on
./copt_clstool -s <ip> -p <port> setmemlimitauto on
./copt_clstool -s <ip> -p <port> setmemevictpolicy largest

如需禁用相应功能，可以分别执行：

./copt_clstool -s <ip> -p <port> setmemguard off
./copt_clstool -s <ip> -p <port> setmemlimitauto off

setmemevictpolicy 支持 largest、longest、youngest 和 random 四种策略。

这些命令所作的修改不会写入 cls.ini。服务器重新启动后，将重新采用 cls.ini 中的配置。

要在其他机器上运行集群管理工具，必须将该机器的IP地址添加到过滤配置文件 clsfilters.ini 中 ToolList 部分的规则中。下面的命令列出了服务器为 192.168.1.11 的集群连接信息。

> ./copt_clstool -s 192.168.1.11 GetNodes

[ Info] COPT Cluster Managing Tool, COPT v8.0.5 20240304
[ Info] connecting to 192.168.1.11:7878
[ Info] [command] wait for connecting to cluster
[ Info] [cluster] node info
  [Parent] (null):7878 (Lost)
  [Child] Node_192.168.1.12:7878_N0001, v2.0=3
  Total num of child nodes is 1

下面的命令把服务器为 192.168.1.11 的Token数目从原来的3，在线修改为目前的0。

> ./copt_clstool -s 192.168.1.11 SetToken 0

[ Info] COPT Cluster Managing Tool, COPT v8.0.5 20240304
[ Info] connecting to 192.168.1.11:7878
[ Info] [command] wait for connecting to cluster
[ Info] [cluster] total token was 3 and now set to 0

下面的命令列出了服务器为 192.168.1.11 的所有过滤规则，包括黑名单、白名单、集群管理工具访问规则和单任务内存限额豁免规则。

> ./copt_clstool -s 192.168.1.11 GetFilters

[ Info] COPT Cluster Managing Tool, COPT v8.0.5 20240304
[ Info] connecting to 192.168.1.11:7878
[ Info] [command] wait for connecting to cluster
[ Info] [cluster] filters info
[BlackList]

[WhiteList]

[ToolList]
  [1]  127.0.0.1

[MemWhiteList]

下面的命令演示了把IP地址为 192.168.3.133 用户加入到黑名单中。

> ./copt_clstool -s 192.168.1.11 AddBlackRule 192.168.3.133

[ Info] COPT Cluster Managing Tool, COPT v8.0.5 20240304
[ Info] connecting to 192.168.1.11:7878
[ Info] [command] wait for connecting to cluster
[ Info] [cluster] server added new black rule (succeeded)

此时 GetFilters 可得到本服务器的过滤规则，可以看到已经发生了改变。

> ./copt_clstool -s 192.168.1.11 GetFilters

[ Info] COPT Cluster Managing Tool, COPT v8.0.5 20240304
[ Info] connecting to 192.168.1.11:7878
[ Info] [command] wait for connecting to cluster
[ Info] [cluster] filters info
[BlackList]
  [1] 192.168.3.133

[WhiteList]

[ToolList]
  [1]  127.0.0.1

[MemWhiteList]

下面的命令演示了切换黑名单规则，把 192.168.3.133 从黑名单中去掉。

> ./copt_clstool -s 192.168.1.11 ToggleBlackRule 1

[ Info] COPT Cluster Managing Tool, COPT v8.0.5 20240304
[ Info] connecting to 192.168.1.11:7878
[ Info] [command] wait for connecting to cluster
[ Info] [cluster] server toggle black rule [1] (succeeded)

下面的命令为指定客户端添加单任务内存限额豁免规则。命令中的服务器IP、端口和规则应根据实际部署情况进行替换。

./copt_clstool -s <ip> -p <port> addmemexempt '127.0.*.*+user@machine*'

添加规则后，可以使用以下命令查看当前过滤规则：

./copt_clstool -s <ip> -p <port> getfilters

如需将当前内存中的过滤规则写入过滤配置文件，可以执行：

./copt_clstool -s <ip> -p <port> writefilters

下面的命令删除上述单任务内存限额豁免规则：

./copt_clstool -s <ip> -p <port> delmemexempt '127.0.*.*+user@machine*'

addmemexempt 和 delmemexempt 对内存中规则的修改会立即生效； writefilters 用于将包括内存限额豁免规则在内的全部过滤规则写入配置文件。

上述命令中的 <ip> 和 <port> 分别表示集群服务器的IP地址和端口，使用时需要替换为实际值，不需要保留尖括号。

服务方式启动

以系统服务的方式启动集群服务器，配置文件以 copt_cluster.service 为例，可通过查看 cluster 文件夹下的 readme.txt 来进行配置和操作。 readme.txt 中显示如下，分别列出了Linux和MacOS系统下的操作方式：

[Linux] To run copt_cluster as a service with systemd

Add a systemd file
    cp copt_cluster.service to /lib/systemd/system/
    sudo systemctl daemon-reload

Enable new service
    sudo systemctl start copt_cluster.service
    or
    sudo systemctl enable copt_cluster.service

Restart service
    sudo systemctl restart copt_cluster.service

Stop service
    sudo systemctl stop copt_cluster.service
    or
    sudo systemctl disable copt_cluster.service

Verify service is running
    sudo systemctl status copt_cluster.service

[MacOS] To run copt_cluster as a service with launchctrl

Add a plist file
    cp copt_cluster.plist to /Library/LaunchAgents as current user
    or
    cp copt_cluster.plist to /Library/LaunchDaemons with the key 'UserName'

Enable new service
    sudo launchctl load -w /Library/LaunchAgents/copt_cluster.plist
    or
    sudo launchctl load -w /Library/LaunchDaemons/copt_cluster.plist

Stop service
    sudo launchctl unload -w /Library/LaunchAgents/copt_cluster.plist
    or
    sudo launchctl unload -w /Library/LaunchDaemons/copt_cluster.plist

Verify service is running
    sudo launchctl list shanshu.copt.cluster

Linux系统

下面以Linux系统为例，演示通过系统服务方式启动集群服务器。打开终端，输入以下命令进入集群服务所在路径（以COPT远程服务安装在 home 目录下的 eleven 路径为例）。

cd /home/eleven/copt_remote80/cluster

通过任意文本文件打开系统服务的配置文件 copt_cluster.service ，内容如下所示：

[Unit]
Description=COPT Cluster Server

[Service]
WorkingDirectory=/path/to/service
ExecStart=/path/to/service/copt_cluster
Restart=always
RestartSec=1

[Install]
WantedBy=multi-user.target

将路径修改为 copt_cluster 所在的实际路径，修改之后 copt_cluster.service 内容显示如下：

[Unit]
Description=COPT Cluster Server

[Service]
WorkingDirectory=/home/eleven/copt_remote80/cluster
ExecStart=/home/eleven/copt_remote80/cluster/copt_cluster
Restart=always
RestartSec=1

[Install]
WantedBy=multi-user.target

将 copt_cluster.service 文件复制到 /lib/systemd/system/ 路径下，命令如下：

sudo cp copt_cluster.service /lib/systemd/system/

初次启动系统服务，需要更新系统配置（之后再启动时无需更新），命令如下：

sudo systemctl daemon-reload

启动系统服务，命令如下：

sudo systemctl start copt_cluster.service

输入如下命令来验证下系统服务是否在运行：

sudo systemctl status copt_cluster.service

输入之后显示如下，表示集群服务器系统服务已启动：

copt_cluster.service - COPT Cluster Server
Loaded: loaded (/lib/systemd/system/copt_cluster.service; enabled; vendor preset: enabled)
Active: active (running) since Sat 2021-08-28 11:46:10 CST; 3s ago
Main PID: 3054 (copt_cluster)
    Tasks: 6 (limit: 4915)
CGroup: /system.slice/copt_cluster.service
          └─3054 /home/eleven/copt_remote80/cluster/copt_cluster

eleven-ubuntu systemd[1]: Started COPT Cluster Server.
eleven-ubuntu COPTCLS[3054]: LWS: 4.1.4-b2011a00, loglevel 1039
eleven-ubuntu COPTCLS[3054]: NET CLI SRV H1 H2 WS IPv6-absent
eleven-ubuntu COPTCLS[3054]: server started at port 7878
eleven-ubuntu COPTCLS[3054]: LWS: 4.1.4-b2011a00, loglevel 1039
eleven-ubuntu COPTCLS[3054]: NET CLI SRV H1 H2 WS IPv6-absent
eleven-ubuntu COPTCLS[3054]: [NODE] node has been initialized

若要停止集群服务器系统服务，则输入以下命令：

sudo systemctl stop copt_cluster.service

MacOS系统

下面以MacOS系统为例，演示通过系统服务方式启动集群服务器。打开终端，输入以下命令进入集群服务所在路径（以COPT远程服务安装在 "/Applications" 路径为例）。

cd /Applications/copt_remote80/cluster

通过任意文本文件打开系统服务的配置文件 copt_cluster.plist ，内容如下所示：

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>shanshu.copt.cluster</string>
        <key>Program</key>
        <string>/path/to/service/copt_cluster</string>
        <key>RunAtLoad</key>
        <true/>
        <key>KeepAlive</key>
        <true/>
    </dict>
</plist>

将路径修改为 copt_cluster 所在的实际路径，修改之后 copt_cluster.plist 内容显示如下：

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>shanshu.copt.cluster</string>
        <key>Program</key>
        <string>/Applications/copt_remote80/cluster/copt_cluster</string>
        <key>RunAtLoad</key>
        <true/>
        <key>KeepAlive</key>
        <true/>
    </dict>
</plist>

将 copt_cluster.plist 文件复制到 /Library/LaunchAgents 路径下，命令如下：

sudo cp copt_cluster.plist /Library/LaunchAgents

启动系统服务，命令如下：

sudo launchctl load -w /Library/LaunchAgents/copt_cluster.plist

输入如下命令来验证下系统服务是否在运行：

sudo launchctl list shanshu.copt.cluster

输入之后显示如下，表示集群服务器系统服务已启动：

{
    "LimitLoadToSessionType" = "System";
    "Label" = "shanshu.copt.cluster";
    "OnDemand" = false;
    "LastExitStatus" = 0;
    "PID" = 16406;
    "Program" = "/Applications/copt_remote80/cluster/copt_cluster";
};

若要停止集群服务器系统服务，则输入以下命令：

sudo launchctl unload -w /Library/LaunchAgents/copt_cluster.plist

若是需要指定此设备下的某一用户才有权限启动集群服务器系统服务，则需要将 UserName 添加到 copt_cluster.plist 中，以 UserName 为 eleven 为例，添加之后 copt_cluster.plist 内容显示如下：

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>shanshu.copt.cluster</string>
        <key>Program</key>
        <string>/Applications/copt_remote80/cluster/copt_cluster</string>
        <key>UserName</key>
        <string>eleven</string>
        <key>RunAtLoad</key>
        <true/>
        <key>KeepAlive</key>
        <true/>
    </dict>
</plist>

将添加 UserName 后的 copt_cluster.plist 文件复制到 /Library/LaunchDaemons 路径下，命令如下：

sudo cp copt_cluster.plist /Library/LaunchDaemons

启动系统服务，命令如下：

sudo launchctl load -w /Library/LaunchDaemons/copt_cluster.plist

若要停止集群服务器系统服务，则输入以下命令：

sudo launchctl unload -w /Library/LaunchDaemons/copt_cluster.plist