特性介绍
资源启动命令
资源停止命令
查询资源实例pid
查询资源实例进程状态
僵死检查和处理
首次检测到资源僵死，将首次检测到僵死的时间写入僵死时间存储文件
firstphonytime为用于保存当前资源实例僵死时间的变量名称，
若当前节点存在多个自定义资源实例，该名称需要指定为不同的名称
若僵死时间大于等于用户设定的最大僵死时间，则立即杀死资源实例，否则不做处理正常退出
未处于僵死状态清理环境后正常退出
以下为固定接口无需更改，必须实现

特性介绍

cm_agent

cm_agent是部署在数据库每个主机上，用来启停和监控各个数据库实例进程的数据库管理组件。

主要功能有：

数据库实例启动和停止时负责拉起和停止本主机上部署的实例进程。
监控本主机上运行的实例状态并将状态上报发送给CM Server。
执行CM Server仲裁下发的命令。

命令说明：

公共选项：
-V, –version

打印cm_agent版本信息，然后退出。 - -?, -h,–help

显示关于cm_agent命令行参数的帮助信息，然后退出。 - 日志信息记录的位置选项：
0

记录在设定的日志文件中。 - 1

记录在syslog文件中。 - 2

记录在设定的日志文件中。 - 3

空文件，即不记录日志信息。 - 启动模式选项：
normal

正常模式启动。 - abnormal

非正常模式启动。

cm_server

cm_server是用来进行数据库实例管理和实例仲裁的组件。主要功能有：

接收各个节点上cm_agent发送的数据库各实例状态。
提供数据库实例整体状态的查询功能。
监控实例的状态变化并进行仲裁命令的下发。

命令说明：

公共选项：
-V, –version

打印cm_server版本信息，然后退出。 - -?, -h,–help

显示关于cm_server命令行参数的帮助信息，然后退出。 - 日志信息记录的位置选项：
0

记录在设定的日志文件中。 - 1

记录在syslog文件中。 - 2

记录在设定的日志文件中。 - 3

空文件，即不记录日志信息。

自定义资源

当前CM支持对无状态资源（即各资源实例角色平等，不区分主备，或资源自身就能够自行进行主备仲裁）进行监控，主要功能包括：

资源配置

资源配置文件cm_resource.json，文件包含所有自定义资源的相关属性，可以通过cm_ctl res命令对配置文件修改。不支持动态生效，修改配置文件后需要重启cm才能生效。 - 客户端

CM提供客户端动态库给资源进行集成，提供集群状态查询、状态变更通知、集群锁能力。 - 自动启停资源

资源需要提供脚本，脚本包含启停、检测等能力，脚本路径需要配置在资源配置文件中。 - 手动启停资源

可以通过cm_ctl start/stop -n -I命令实现资源实例的启停操作，详细参见工具介绍。 - 自定义资源状态

自定义资源有四种状态：online，offline，deleted，unknown。可以通过cm_ctl查询。

### 配置方法

安装好自定义资源后，若要使用自定义资源监控功能，需要配置两个文件：

资源脚本主要用于指定资源的启停、状态检查等指令，一个样例如下：

``` 1. #!/bin/bash 2. #set -ex #取消该行注释可帮助调试脚本 3. #资源名称 4. resName=sharding 5. #资源binpath 6. shardingPath=/home/test/home/apache-shardingsphere-5.1.1-shardingsphere-proxy-bin/bin 7. #用于过滤资源实例的命令关键词 8. cmdKey=org.apache.shardingsphere.proxy.Bootstrap 9. #用于保存首次检测到资源僵死时间的文件 10. phony_dead_time_file=.sharding_phony_dead_time 11. #最长僵死时间，单位为s 12. PHONY_MAX_TIME=20

function exec_start
{
资源启动命令
sh ${shardingPath}/start.sh; exit $?
}
function exec_stop
{
资源停止命令
sh ${shardingPath}/stop.sh; exit $?
}
function exec_check
{
查询资源实例pid
pid=ps x | grep "$cmdKey" | grep -v grep | awk '{print $1}'
if [ "${pid}" == "" ]; then
echo "$resName is not running."
exit 1
fi
查询资源实例进程状态
state=cat /proc/$pid/status | grep "State" | awk '{print $2}'
if [ "$state" == "T" ]; then
僵死检查和处理
if [ ! -f $phony_dead_time_file ]; then
touch ./${phony_dead_time_file}
echo "export firstphonytime=''" > ./${phony_dead_time_file}
fi
source ./$phony_dead_time_file;
curtime=$(date +%s);
if [ "$firstphonytime" == "" ]; then
首次检测到资源僵死，将首次检测到僵死的时间写入僵死时间存储文件
firstphonytime为用于保存当前资源实例僵死时间的变量名称，
若当前节点存在多个自定义资源实例，该名称需要指定为不同的名称
echo "export firstphonytime=$curtime" > ./$phony_dead_time_file;
exit 0;
fi
dead_time=$(( $curtime - $firstphonytime ));
若僵死时间大于等于用户设定的最大僵死时间，则立即杀死资源实例，否则不做处理正常退出
if [ $dead_time -ge $PHONY_MAX_TIME ]; then
echo "$resName is detected in a state of phony dead(T) and will be forcibly killed!"
kill -9 $pid
rm ./${phony_dead_time_file} -f
sh ${shardingPath}/start.sh; exit $?
else
exit 0
fi
elif [ "$state" == "S" ]; then
未处于僵死状态清理环境后正常退出
rm ./${phony_dead_time_file} -f
exit 0
fi
}
以下为固定接口无需更改，必须实现
if [ $1 == '-start' ]; then
exec_start $2
elif [ $1 == '-stop' ]; then
exec_stop $2
elif [ $1 == '-check' ]; then
exec_check $2
elif [ $1 == '-clean' ]; then
exec_stop $2
elif [ $1 == '-reg' ]; then
exit 0
elif [ $1 == '-unreg' ]; then
exit 0
elif [ $1 == '-isreg' ]; then
exit 11
else
echo "Please confirm the input parameters."
exit 1
fi ```

以上样例可以作为模板使用，用户主要需要修改的地方包括：资源名称、资源binPath、用于过滤资源实例的命令关键词、用于保存首次检测到资源僵死时间的文件（可选）、最长僵死时间、记录首次僵死时间的变量名（如果同一节点存在多个不同的自定义资源实例）

自定义资源配置文件cm_resource.json 该文件位置为cmdir/cm_agent/cm_resource.json，配置该文件后需要重启集群

1. { 2. "resources": [ 3. { 4. "name": "sharding", 5. "resource_type": "APP", 6. "instances": [ 7. { 8. "node_id": 1, 9. "res_instance_id": 1 10. }, 11. { 12. "node_id": 2, 13. "res_instance_id": 2 14. } 15. ], 16. "script": "/usr2/omm/install/cm/cm_agent/sharding.sh", 17. "check_interval": 1, 18. "time_out": 5, 19. "restart_delay":3, 20. "restart_period":5, 21. "restart_times":10 22. }, 23. { 24. "name": "test", 25. "resource_type": "APP", 26. "instances": [ 27. { 28. "node_id": 1, 29. "res_instance_id": 1 30. }, 31. { 32. "node_id": 2, 33. "res_instance_id": 2 34. } 35. ], 36. "script": "/usr2/omm/install/cm/cm_agent/test.sh", 37. "check_interval": 1, 38. "time_out": 5, 39. "restart_delay":0, 40. "restart_period":0, 41. "restart_times":1000 42. } 43. ] 44. }

配置说明：

resources: 自定义资源对象列表，名称固定不能更改。
name: 自定义资源对象名称，字符串类型，最大长度为32（包含末尾’\0’）。
resource_type: 资源类型，取值[“APP”, “DN”]，APP表示为自定义资源，DN表示为数据库资源
instances: 自定义资源所在节点列表。
node_id: 资源实例所在节点的node_id。
res_instance_id: 资源实例id，大于等于0，同一种资源的不同实例id不同。
script: 资源脚本位置。
check_interval: 上报资源状态时间间隔，大于等于0，单位s。
time_out: 脚本执行的超时时间，大于等于0，单位s。
restart_delay: 故障之后重启延迟时间，单位为s，取值范围[0,1800]。
restart_period: 当前时间-最近重启时间若大于restart_period，则再次重启资源重启次数加1。
restart_times: 周期内最多重启次数，超过则不再重启，并将资源标记为不可用，取值范围[0,9999]，0表示无限重启。

注意： 资源配置文件需要在所有节点上都有，且保持一致。

用户需要保证资源脚本能够正确运行。

共享存储

磁盘心跳

各节点cm_agent定时向投票盘写入心跳，cm_server获取投票盘中的磁盘心跳，作为主备共享模式下的仲裁依据。 - 网络心跳

节点间的连通性网络心跳检测的主逻辑在cma实现。为了避免频繁建连，心跳采用长连接的方式，即cma之间通过TCP长连接，进行心跳交互，由每个cma节点定时广播，并周期性将列表信息上报给cms，此功能依赖各个节点的时钟完全同步。 - 仲裁最大集群

cms根据网络心跳数据、磁盘心跳数据、共享盘状态等进行仲裁，选主子集群。

子集群满足条件：

实例正常；
相互网络通信正常；
磁盘心跳正常；

不满足条件的剔除集群。

子集群仲裁规则：

拥有节点多的子集群胜出；
如果节点数一样多，则节点号小的胜出。
约束：
集群节点时钟同步。
CM使用的共享盘在安装之前请确保至少150M为空，否则可能会有历史数据影响。
CM使用的投票盘在安装之前请确保已清空，否则可能会有历史数据影响。
由于心跳是集群所有节点间进行的，在大集群的情况下可能会对网络产生一定影响，因此，最多只会启动64个节点的心跳检测（DMS最多只支持64节点，满足使用要求）。
由于CM集群规模最多只支持8个备机，因此当前部署最多支持9副本的集群。
Voting disk和share disk确保包括至少1G空间，由CM独占，其他应用不能使用。
在共享存储架构仲裁模式下，才启用磁盘心跳。

CM支持DN仲裁

CM支持的DN仲裁模式主要分为：
Quorum 模式：基于多数派模式仲裁，选出同步备
- 简介：CM 基于Quorum模式进行仲裁，当DN分片处于无主场景时，CM在多数派DN redo完成后，选择 term和lsn最大的节点(同步备)发送failover升主。
- 约束：最小满足一主两备集群
- DCF 模式：
- 自动选主模式：基于paxos 协议：
- 简介：dcf模式自动选主，在此场景下，CM不再进行对DN选主，只负责数据采集，假死检测等。
- 约束：switchover只能使用cm_ctl switchover -n NODEID -D DATADIR
- CM配置：enable_dcf=ON、dn_arbitrate_mode=paxos
- DN配置：enable_dcf=ON
- 总体约束：
- 最小满足一主两备集群
- 默认安装：DCF自动选主模式
- 共享存储模式：
- 简介：在此场景下，CM不再进行对DN选主，只负责数据采集，假死检测等。
- CM配置：dn_arbitrate_mode=share_disk
- 介绍和约束：参考共享存储

支持集群信息查询和推送

功能介绍： 通过运行组件CMRestAPI，CM能够支持：

通过http/https服务远程查询到集群的状态，便于管理人员、运维平台等监控集群状态。
在数据库集群发生切主事件时，通过http/https服务及时地将集群最新的主备信息推送到应用端注册的接收地址，便于应用端及时的感知到集群的主备变化，从而能够快速的连接到新的主机和备机。

参数说明：

-e 数据库环境变量文件，必须指定。
-w 访问来源ip白名单，如果不需要设置白名单则可以不用指定。启动命令：

1. java -jar cmrestapi-xxx.jar -e envFile [-w appWhiteList]

接口说明：

集群或节点状态查询。该接口使用GET方法，链接为<http://ip:port/CMRestAPI/keyword。> 其中：
ip为运行CMRestAPI的节点ip。
port为CMRestAPI服务的监听端口。
keyword为待查询的信息关键词，当前支持查询的信息即关键词包括：集群状态ClusterStatus，对应链接为<http://ip:port/CMRestAPI/ClusterStatus>。节点状态NodeStatus，对应链接为<http://ip:port/CMRestAPI/NodeStatus[?nodeId=n>]，指定nodeId等于n，则可以查询节点n的状态，若不指定nodeId，则默认返回提供服务的节点即链接中ip所指定节点的状态。
注册和更新主备机信息接收地址。如果应用端想要接收到CMRestAPI推送的集群当前最新的主备信息，需要向CMRestAPI注册一个信息接收地址并且需要在该地址上进行监听。接收到该请求后CMRestAPI会通过dcc将注册的接收地址保存到集群所在环境，dcc存储数据的形式为key-value形式，使用的key为/CMRestAPI/RecvAddrList/ip/app，其中ip为应用端所在机器的ip地址，app为用户自定义的应用名称，主要用于区分同一环境上的多个应用注册的接收地址。如果key已存在，即来源ip和应用名称均相同，则会更新key对应的主备信息接收地址。该接口需使用PUT方法，链接为<http://ip:port/CMRestAPI/RecvAddr，> 需要提供两个参数：
url——待注册的接收地址。
app——应用名称，若不提供该参数则以前缀+应用端ip为key。
删除主备机信息接收地址。该接口使用DELETE方法，链接为<http://ip:port/CMRestAPI/RecvAddr，> 需要提供一个参数： app——应用名称。若不提供该参数则以前缀+应用端ip为key。
信息接收地址说明。信息接收地址示例：<http://ip:port/CMRestAPI> , CMRestAPI使用PUT方法，推送主机信息context为MasterInfo，即链接为<http://ip:port/CMRestAPI/MasterInfo，> 发送对象类型为String，主机信息格式为ip:port，推送备机context为StanbyInfo，发送对象类型为String，备机信息格式为ip1:port1,ip2:port2,…,ipn:portn，一个应用端的demo参见CMRestAPI仓库中的applicationdemo，<https://gitee.com/opengauss/CM-RestAPI/tree/master/applicationdemo/src/main/java/com/application/applicationdemo。>

其他使用说明：

安全相关。 (1) CMRestAPI默认使用http服务，支持配置访问白名单，可通过启动参数-w配置访问来源ip的白名单文件，白名单文件配置格式为每行一个ip地址； (2) 若要使用https服务，则可以在启动时jar包时指定系统参数server.ssl相关参数来是CMRestAPI启动https服务，或将相关参数写入application.properties文件然后在启动命令中指定配置文件，或配置源码resource目录下的application.properties文件然后自行编译，自定义配置参数示例：

1. -Dserver.port=服务监听端口 -Dserver.ssl.key-store=秘钥文件路径 -Dserver.ssl.key-store-password=秘钥文件密码 -Dserver.ssl.key-store-type=秘钥类型
2. 如：
3. 指定参数方式：

5. 系统参数方式
6. java -jar -Dserver.port=8443 -Dserver.ssl.key-store=/home/omm/keystore.p12 -Dserver.ssl.key-store-password=Abcdef@123 -Dserver.ssl.key-store-type=PKCS12 cmrestapi-xxx.jar -e envFile
7. 指定配置文件方式
8. java -jar -Dspring.config.location=/configpath/application.properties cmrestapi-xxx.jar -e envFile

更多相关配置参数可自行搜索配置

内存相关。由于本程序使用了springboot框架，默认启动会占用较大内存（约1G左右），若并发量不大不希望该程序占用较大内存，则可以在启动时指定一些系统参数减小内存占用，启动参数示例：

1. -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=56m -Xms128m -Xmx128m -Xmn32m -Xss328k -XX:SurvivorRatio=8 -XX:+UseConcMarkSweepGC
2. 如：java -jar -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=56m -Xms128m -Xmx128m -Xmn32m -Xss328k -XX:SurvivorRatio=8 -XX:+UseConcMarkSweepGC cmrestapi-xxx.jar -e envFile

更多相关配置参数可自行搜索配置

自定义资源配置文件。本程序需要依赖cm相关进程和指令，所以必须与cm同时运行，需配置自定义资源配置文件，配置方法详见自定义资源监控特性相关内容。

操作步骤说明：

安装带cm的数据库集群，配置资源脚本和自定义资源文件，资源脚本示例如下： cmrestapi.sh

1. #!/bin/bash
2. #set -ex
3. #资源名称
4. resName=CM-RestAPI
5. #资源binpath
6. cmrestapiPath=/home/cmrestapi/cmrestapi-3.1.0-RELEASE.jar
7. #资源启动命令关键词
8. cmdKey=cmrestapi-3.1.0-RELEASE.jar
9. #用于保存首次检测到资源假死时间的文件
10. phony_dead_time_file=.cmrestapi_phony_dead_time
11. #最长假死时间，单位为s
12. PHONY_MAX_TIME=20
13. envFile=/home/cmrestapi/envfile
14. #appWhiteListFile=/home/cmrestapi/appWhiteListFile
15. source $envFile

17. function exec_start
18. {
19. nohup java -jar -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=56m -Xms128m -Xmx128m -Xmn32m -Xss328k -XX:SurvivorRatio=8 -XX:+UseConcMarkSweepGC -Dserver.port=8080 $cmrestapiPath -e $envFile >> $GAUSSLOG/cm/cmrestapi/cmrestapi.log 2>&1 &
20. exit $?
21. }

23. function exec_stop
24. {
25. ps x | grep "$cmdKey" | grep -v grep | awk '{print $1}' | xargs kill -9; exit $?
26. }

28. function exec_check
29. {
30. pid=`ps x | grep "$cmdKey" | grep -v grep | awk '{print $1}'`
31. if [ "${pid}" == "" ]; then
32. echo "$resName is not running."
33. exit 1
34. fi
35. state=`cat /proc/$pid/status | grep "State" | awk '{print $2}'`
36. if [ "$state" == "T" ]; then
37. if [ ! -f $phony_dead_time_file ]; then
38. touch ./${phony_dead_time_file}
39. echo "export firstphonytime=''" > ./${phony_dead_time_file}
40. fi
41. source ./$phony_dead_time_file;
42. curtime=$(date +%s);
43. if [ "$firstphonytime" == "" ]; then
44. echo "export firstphonytime=$curtime" > ./$phony_dead_time_file;
45. exit 0;
46. fi
47. dead_time=$(( $curtime - $firstphonytime ));
48. if [ $dead_time -ge $PHONY_MAX_TIME ]; then
49. echo "$resName is detected in a state of phony dead(T) and will be forcibly killed!"
50. kill -9 $pid
51. rm ./${phony_dead_time_file} -f
52. exec_start
53. else
54. exit 0
55. fi
56. elif [ "$state" == "S" ]; then
57. rm ./${phony_dead_time_file} -f
58. echo "$resName is running normally."
59. exit 0
60. fi
61. }

63. if [ $1 == '-start' ]; then
64. exec_start $2
65. elif [ $1 == '-stop' ]; then
66. exec_stop $2
67. elif [ $1 == '-check' ]; then
68. exec_check $2
69. elif [ $1 == '-clean' ]; then
70. exec_stop $2
71. elif [ $1 == '-reg' ]; then
72. exit 0
73. elif [ $1 == '-unreg' ]; then
74. exit 0
75. elif [ $1 == '-isreg' ]; then
76. exit 11
77. else
78. echo "Please confirm the input parameters."
79. exit 1
80. fi

自定义资源文件cm_resource.json示例如下：

1. {
2. "resources": [
3. {
4. "name": "CM-RestAPI",
5. "resource_type": "APP",
6. "instances": [
7. {
8. "node_id": 1,
9. "res_instance_id": 1
10. },
11. {
12. "node_id": 2,
13. "res_instance_id": 2
14. },
15. {
16. "node_id": 3,
17. "res_instance_id": 3
18. }
19. ],
20. "script": "/home/cmrestapi/install/cm/cm_agent/cmrestapi.sh",
21. "check_interval": 1,
22. "time_out": 10,
23. "restart_delay":0,
24. "restart_period":0,
25. "restart_times":1000
26. }
27. ]
28. }

注意： 使用cm的自定义资源管理功能需将进程放到后台执行，所以需要将日志输出重定向至日志文件或配置日志输出相关选项，并且使用nohup和&将本程序放置到后台运行。本程序需要运行在有数据库的节点；如果在集群发生切换时需要使用主备信息主动推送功能，则需要将该程序运行在集群中所有数据库节点。

启动集群，即可通过浏览器等访问上述集群或节点信息查询接口查询对应信息。
应用端开发（可参考源码仓库的demo），启动应用端。
注册信息接收地址。

特性介绍

特性介绍

cm_agent

cm_server

自定义资源

资源启动命令

资源停止命令

查询资源实例pid

查询资源实例进程状态

僵死检查和处理

首次检测到资源僵死，将首次检测到僵死的时间写入僵死时间存储文件

firstphonytime为用于保存当前资源实例僵死时间的变量名称，

若当前节点存在多个自定义资源实例，该名称需要指定为不同的名称

若僵死时间大于等于用户设定的最大僵死时间，则立即杀死资源实例，否则不做处理正常退出

未处于僵死状态清理环境后正常退出

以下为固定接口无需更改，必须实现

共享存储

CM支持DN仲裁

支持集群信息查询和推送