· 后台执行 export ETCDCTL_API=2 && etcdctl cluster-health命令短暂性或持续性返回其中一个或多个member unhealthy状态。该故障多见于集群中一个或多个节点网络延迟大（延迟10ms以上）或性能不足（CPU频率低、磁盘IO负载高、IOPS性能低等）。

· 执行 kubectl get endpoints -nservice-software itom-central-login-svc 命令查看itom-central-login 服务对应的endpoints。若endpoints 依然保留异常节点上Pod IP 地址，则视为异常。

图2-1 查看itom-central-login服务对应的endpoints

2.2.2 故障处理步骤

(1) 找到异常节点：在三台Master节点后台执行curl http://localhost:2379/health命令，若只有1~2个节点命令返回{"health":"false","reason":"xxx"}、则认为该节点异常，若三个节点均返回{"health":"false","reason":"xxx"}、则认为ETCD集群主节点异常。

ETCD集群主节点查询方式：

a. 执行 export ETCDCTL_API=2 && etcdctl member list 命令查询成员列表，isLeader=true的为ETCD集群的主节点，如下matrix-node1为主节点。

[root@name3 tools]# etcdctl member list

2fb4df4b48851734: name=etcd2 peerURLs=http://matrix-node2:2380 clientURLs=http://matrix-node2:2379 isLeader=false

36bce94b1f1c6222: name=etcd3 peerURLs=http://matrix-node3:2380 clientURLs=http://matrix-node3:2379 isLeader=false

c7366883276d5740: name=etcd3 peerURLs=http://matrix-node1:2380 clientURLs=http://matrix-node1:2379 isLeader=true

b. 执行cat /etc/hosts 看节点IP域名映射关系，找到 a）中matrix-node1对应的节点IP，如下ETCD主节点IP为10.99.212.83。

[root@name3 tools]# cat /etc/hosts

127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4 name3

::1 localhost localhost.localdomain localhost6 localhost6.localdomain6 name3

10.99.212.83 matrix-apiserver

10.99.212.83 matrix-registry.h3c.com

10.99.212.83 etcd.matrix

10.99.212.87 matrix-node2

10.99.212.84 matrix-node3

10.99.212.83 matrix-node1

若集群中只有一个节点异常，则进行后续故障恢复，若集群中有2个及以上节点异常，请勿使用该故障恢复方式进行处理，否则可能导致集群无法恢复。

(2) 登录异常节点后台，执行systemctl stop etcd命令停掉问题节点的ETCD服务，并使用hostname命令获取主机名nodeName。其中，nodeName为异常节点的名称。

(3) 登录主节点后台，执行kubectl drain nodeName --ignore-daemonsets --force --delete-emptydir-data --timeout=1800s命令将所有Pod从异常节点上驱逐。

(4) 执行kubectl delete node nodeName命令删除异常节点。其中，nodeName为异常节点的名称。

(5) 修复异常断连的节点。若是服务器硬件故障无法恢复，必须更换节点服务器进行修复。

(6) 修复节点之后，登录Matrix界面，在[部署>集群]页面下，单击故障节点右上角的按钮，选择[重建]菜单项重建该节点。

(7) 如果上述操作完成后故障仍无法排除，请联系技术支持工程师。

2.3 磁盘空间不足导致容器运行异常，一直处于Evicted状态

2.3.1 故障描述

集群中某个节点磁盘空间已满，在该节点主机中使用kubectl get pods --all-namespaces命令，出现大量处于Evicted状态的容器，手动清理磁盘后容器仍保持该状态。

2.3.2 故障处理步骤

造成故障的原因：节点服务器磁盘空间不足的情况下，K8S自动清理机制会产生大量处于Evicted状态的容器。

故障处理步骤如下：

(1) 手动清理节点根分区的磁盘空间，例如/var/log路径下的日志压缩包、/opt/matrix/app/install/packages/路径下的老版本安装包，以降低磁盘使用率。

(2) 登录Matrix GUI界面，进入集群部署页面。在该页面选择待修复的节点并单击节点右上角的按钮，选择“修复”选项进行节点修复，修复完成后K8S会自动删除节点服务器中处于Evicted状态的容器。

2.4 修改巨页配置后导致K8s节点状态异常，一直处于Not Ready状态

修改操作系统巨页配置，如将/etc/default/grub文件中GRUB_CMDLINE_LINUX参数值从"crashkernel=auto rhgb quiet default_hugepagesz=2M hugepagesz=2M hugepages=8192"改为"crashkernel=auto rhgb quiet default_hugepagesz=1G hugepagesz=1G hugepages=16"后，引起K8s节点状态异常（Not Ready状态），重启系统后仍然无法恢复。

2.4.2 故障处理步骤

造成故障的原因：default_hugepagesz=1G时Linux内核在/sys/kernel/mm/hugepages/目录下仅保留了hugepages-1048576kB目录，Kubelet可以根据该目录读取系统巨页配置，并以patch方式添加新巨页，配置到集群。

若集群之前配置过2M巨页，则patch操作后，1G和2M两种巨页配置值将同时存在。而目前Kubelet并不支持同时存在1G和2M两种巨页配置，从而导致K8s节点状态同步失败，K8s节点状态变为Not Ready状态。

通过同时指定1G和2M的巨页数量（hugepages），并把其中一个巨页配置的巨页数量指定为0，如default_hugepagesz=1G hugepagesz=1G hugepages=16 hugepagesz=2M hugepages=0，可以解决两种巨页配置同时存在的问题。故障处理步骤如下：

(1) 修改巨页配置文件。

a. 通过vi编辑器打开巨页配置文件。

[root@node1 ~]# vi /etc/default/grub

b. 按[i]键进入编辑模式，按照如下所示修改文件配置。修改完成后，按[ESC]键退出编辑模式，再输入:wq，按回车，保存巨页配置文件并退出vi编辑器。

GRUB_TIMEOUT=5

GRUB_DISTRIBUTOR="$(sed 's, release .*$,,g' /etc/system-release)"

GRUB_DEFAULT=saved

GRUB_DISABLE_SUBMENU=true

GRUB_TERMINAL_OUTPUT="console"

GRUB_CMDLINE_LINUX="crashkernel=auto rhgb quiet default_hugepagesz=1G

hugepagesz=1G hugepages=16 hugepagesz=2M hugepages=0"

GRUB_DISABLE_RECOVERY="true"

(2) 使配置生效并重启节点服务器

¡ 若系统以UEFI模式启动，请使用如下方式保存配置并重启。

[root@node1 ~]# grub2-mkconfig -o /boot/efi/EFI/centos/grub.cfg

Generating grub configuration file ...

Found linux image: /boot/vmlinuz-3.10.0-862.el7.x86_64

Found initrd image: /boot/initramfs-3.10.0-862.el7.x86_64.img

Found linux image: /boot/vmlinuz-0-rescue-f2e062c5077847ae837b2f1cdb91104f

Found initrd image: /boot/initramfs-0-rescue-f2e062c5077847ae837b2f1cdb91104f.img

Done

[root@node1 ~]# reboot

¡ 若系统以Legacy模式启动，请使用如下方式保存配置并重启。

[root@node1 ~]# grub2-mkconfig -o /boot/grub2/grub.cfg

Generating grub configuration file ...

Found linux image: /boot/vmlinuz-3.10.0-862.el7.x86_64

Found initrd image: /boot/initramfs-3.10.0-862.el7.x86_64.img

Found linux image: /boot/vmlinuz-0-rescue-f2e062c5077847ae837b2f1cdb91104f

Found initrd image: /boot/initramfs-0-rescue-f2e062c5077847ae837b2f1cdb91104f.img

Done

[root@node1 ~]# reboot

(3) 验证巨页是否配置成功。若配置成功，则将显示default_hugepagesz=1G hugepagesz=1G hugepages=16 hugepagesz=2M hugepages=0。

[root@node1 ~]# cat /proc/cmdline

BOOT_IMAGE=/vmlinuz-3.10.0-862.el7.x86_64 root=UUID=f47e3128-e888-499e-b370-2b381b6f3134 ro crashkernel=auto rhgb quiet default_hugepagesz=1G hugepagesz=1G hugepages=16 hugepagesz=2M hugepages=0。

2.5 修改集群网络模式失败

2.5.1 故障描述

在Matrix集群参数页面修改集群网络模式失败。

2.5.2 故障处理步骤

造成故障的原因：主用Master节点ETCD服务异常，修改集群网络模式时需要请求两次ETCD服务，一次请求用于修改calico中的网络模式，另一次请求用于修改页面上显示的网络模式，此时分为两种情况：

· 第一种情况：页面显示集群网络模式已修改，但提示“修改失败”。

该种情况的原因为：由于ETCD服务异常导致两次请求一次成功一次失败，calico和页面显示的数据不一致。

以当前环境为单子网环境，需要修改网络模式为多子网模式为例，如果页面提示修改失败，但是集群参数配置页已修改为多子网模式，可以通过下述步骤进行故障处理。

故障处理步骤如下：

a. 进入主用Master节点服务器，查看主用Master节点的ETCD服务是否已经恢复正常。若已恢复正常可继续进行下列操作；若没有恢复正常请联系技术支持工程师。

[root@name1 1.0.0]# export ETCDCTL_API=2&&etcdctl cluster-health

member fb58b3b32bac01c is healthy: got healthy result from http:// matrix-node1:2379

member aa6e53b313aa741f is healthy: got healthy result from http:// matrix-node2:2379

member d1fcbe1f6db25390 is healthy: got healthy result from http:// matrix-node3:2379

b. 若主用Master节点的ETCD服务已恢复正常，请将集群网络模式修改为集群原有网络模式，例如上述环境需要改为“单子网”模式，单击应用后将提示修改失败，但是集群参数页面已经显示改为“单子网”模式。

c. 再次将网络模式修改为“多子网”模式，修改成功，即该故障已恢复。

· 第二种情况：页面显示集群网络模式没有修改，且提示“修改失败”。

该种情况的原因为：由于ETCD服务异常导致两次请求都没有成功。

故障处理步骤如下：

[root@name1 1.0.0]# export ETCDCTL_API=2&&etcdctl cluster-health

member fb58b3b32bac01c is healthy: got healthy result from http:// matrix-node1:2379

member aa6e53b313aa741f is healthy: got healthy result from http:// matrix-node2:2379

member d1fcbe1f6db25390 is healthy: got healthy result from http:// matrix-node3:2379

b. 再次修改集群网络模式，页面显示和提示都为修改成功，即该故障已恢复。

2.6 Matrix升级后，kube-apiserver、kube-scheduler或kube-controller-manager服务异常

2.6.1 故障描述

Matrix升级（单机或集群）后节点飘红，查看异常节点的详情信息，显示kube-apiserver、kubeScheduler或kubeControllerManager异常。登录异常节点后台，使用kubectl get pod -A -owide命令，异常节点上存在处于CrashLoopBackOff状态的Pod。

2.6.2 故障处理步骤

该故障现象及故障处理步骤有以下两种。

1. 第一种情况

· 故障现象

在异常Pod所在节点上执行netstat -anlp | grep -w 6443、netstat -anlp | grep -w 10251或netstat -anlp | grep -w 10252命令，存在kube-apiserver、kube-scheduler或kube-controller-manager服务端口被占用且存在处于LISTEN连接的现象。

· 故障原因

Matrix升级后，由于老的进程未正常退出，kube-apiserver的6443端口、kube-scheduler的10251端口或kube-controller-manager的10252端口未释放，导致新的Pod无法正常启动。后台执行kubectl logs -n kube-system $pod_name或docker logs $container_id命令可以查看端口被占用的相关日志。

· 故障处理步骤

以kube-scheduler Pod异常为例，在问题节点后台执行如下命令进行恢复。其他异常Pod（例如：kube-apiserver、kube-controller-manager）可参照如下步骤进行恢复。

a. 移除kube-scheduler Pod及容器。

[root@name ~]# mv /etc/kubernetes/manifests/kube-scheduler.yaml /opt/

b. 检查kube-scheduler容器是否全部退出，若已查询不到kube-scheduler容器，则进行下一步。若长时间查询仍然不退出，可尝试执行docker rm -f $container_id强制删除容器、或执行systemctl restart docker命令重启Docker服务。

[root@name ~]# docker ps | grep kube-scheduler

c. 执行netstat -anlp | grep -w 10251命令查询端口是否被释放，已释放现象为：命令查询结果中不存在LISTEN状态的连接。若已释放则进行下一步。

d. 启动kube-scheduler Pod。

[root@name ~]# mv /opt/kube-scheduler.yaml/etc/kubernetes/manifests/

e. 执行kubectl get pod -n kube-system -o wide 命令查询Pod状态

f. 如果上述操作完成后故障仍无法排除，请联系技术支持工程师。

2. 第二种情况

· 故障现象

在异常Pod所在节点上执行netstat -anlp | grep -w 6443、netstat -anlp | grep -w 10251或netstat -anlp | grep -w 10252命令，存在端口被占用且只存在TIME_WAIT状态的连接，且占用端口的不是kube-apiserver、kube-scheduler或kube-controller-manager进程。

· 故障原因

Matrix升级过程中，由于kube-apiserver、kube-scheduler或kube-controller-manager Pod重启，导致6443、10251或10252端口被GlusterFS抢占，进而导致Pod异常。

· 故障处理步骤

请联系技术支持工程师。

2.7 calico-node等Pod异常，报错Delegation not available for unit type

2.7.1 故障描述

页面上进行修改节点IP等操作后，节点飘红。登录异常节点后台，使用kubectl get pod -A -owide命令，发现集群中calico-node、calico-kube-controller等Pod异常。

kubelet日志中打印如下错误：

Error syncing pod 991e112f-c3a3-4c46-9a9b-dfde4ca0a27b ("calico-node-vlpz8_kube-system(991e112f-c3a3-4c46-9a9b-dfde4ca0a27b)"), skipping: failed to ensure that the pod: 991e112f-c3a3-4c46-9a9b-dfde4ca0a27b cgroups exist and are correctly applied: failed to create container for [kubepods burstable pod991e112f-c3a3-4c46-9a9b-dfde4ca0a27b] : Delegation not available for unit type

2.7.2 故障处理步骤

· 造成故障的原因：

containerd低版本开源问题导致该故障。

该问题从containerd-v1.3.0版本开始，已被解决。若存在该故障的环境中，containerd版本低于v1.3.0，则属于该故障。containerd版本查询方式为：后台执行containerd -v命令。

· 故障处理步骤

在异常Pod所在节点执行systemctl restart kubelet.service命令重启Kubelet服务即可。

2.8 系统节点长时间断电或异常致其他节点PostgreSQL数据目录占用大量磁盘空间

2.8.1 故障描述

集群环境某节点长时间不启动或节点异常，可能会引起某节点PostgreSQL实例Pod的数据目录占用磁盘空间不断增长。尤其在如果某节点因为宕机或者关闭长期不启动，同时另外两个节点正常提供服务，且PostgreSQL数据库进行大量插入、更新、删除等操作的情况。

2.8.2 故障处理步骤

1. 故障原因

PostgreSQL数据库集群因为备库需要从主库不断的同步数据，而同步的数据依赖主库上的wal日志，目前为了数据库集群各备库Pod的正常同步数据，主库虽然开启了wal日志的自动清理，但是也会保留备库一直未同步的wal日志，这样如果一个备库所在节点长时间处于未启动状态，并且当前PostgreSQL数据库不断进行insert、delete、udpate等操作，那么主库所在节点的wal日志目录占用磁盘会不断的增长。如下图所示，wal日志目录大小由原先的97M增长到11G。

如下图所示，wal日志目录大小由原先的97M增长到11G。

2. 故障处理步骤

本身PostgreSQL主库保留wal日志是为了备库的正常同步数据以及正常运行，所以此时只要启动当前关闭的节点，然后节点正常处于服务状态，同时该节点PostgreSQL 实例Pod正常运行，随着该节点备库Pod不断同步数据，主库会自动清理wal日志，然后所占用磁盘空间会慢慢降下来。如下图所示，wal日志所占用磁盘大小随着宕机节点的重启，逐渐由11G降到657M。

2.9 灾备环境主站点网络断开一段时间再恢复后，主站点中的部分节点状态为NotReady、大量Pod异常

2.9.1 故障描述

断开灾备环境主站点的网络，等待一段时间后恢复网络，主站点中的部分节点状态持续为NotReady，该节点上大量Pod异常、且无法自行恢复。

2.9.2 故障处理步骤

1. 故障原因

异常节点Docker日志中有大量的锁请求和等待，在网络恢复后，主站点恢复过程中，Docker执行Pod的terminating、启动等发生了进程、Pod的互锁，导致节点状态异常。该问题出现概率极低。

2. 故障处理步骤

在异常节点后台执行systemctl restart docker.service命令重启Docker服务即可。

3 集群拒绝所有访问Matrix服务故障处理

3.1 安全策略配置为全部拒绝后，集群拒绝所有访问Matrix服务的请求

3.1.1 故障描述

在安全策略页面，基本设置区域的默认动作设置为“拒绝”且删除规则信息区域的默认规则后，集群拒绝所有访问Matrix服务的请求。

3.1.2 故障处理步骤

造成故障的原因：默认动作为“拒绝”的情况下，Matrix默认放开8443端口的规则也被删除。

故障处理步骤如下：

(1) 登录任意一台Master服务器。

(2) 进入脚本目录。

[root@node1 ~]# cd /opt/matrix/k8s/disaster-recovery/

(3) 执行恢复安全策略脚本。

¡ root用户执行如下命令：

[root@node1 ~]# bash recover-security-policies.sh

¡ 非root用户执行如下命令：

[admin@node1 ~]$ sudo bash -c "source /etc/profile;bash recover-security-policies.sh"

(4) 脚本执行完成后，重新登录Matrix页面。

4 密码错误导致登录Matrix失败故障处理

4.1 admin用户输入错误的密码导致登录Matrix失败

4.1.1 故障描述

在登录Matrix页面，如果admin用户忘记登录密码等原因导致登录Matrix失败。

4.1.2 故障处理步骤

请根据集群情况执行对应脚本，进行重置密码的操作。

· 集群运行正常时重置密码。

a. 进入某一个Master节点的脚本存放目录，使用命令bash resetMatrixUserPassword.sh reset_password执行该脚本，其中resetMatrixUserPassword.sh为脚本名称，reset_password为新密码，例如：bash resetMatrixUserPassword.sh Pwd@123456。

[root@node1 ~]# cd /opt/matrix/k8s

[root@node1 k8s]# bash resetMatrixUserPassword.sh Pwd@123456

WARNING: Input userName is empty, use default userName "admin".

Password reset to Pwd@123456 for user admin succeeded

b. 脚本执行完成后，使用新密码重新登录Matrix页面即可。

· 集群紧急模式下重置密码。

c. 进入某一个Master节点的脚本存放目录，使用命令bash resetMatrixUserPassword_emergency.sh reset_password执行该脚本，其中resetMatrixUserPassword_emergency.sh为脚本名称，reset_password为新密码，例如：bash resetMatrixUserPassword_emergency.sh Pwd@123456。

[root@node1 ~]# cd /opt/matrix/k8s

[root@node1 k8s]# bash resetMatrixUserPassword_emergency.sh Pwd@123456

WARNING: Input userName is empty, use default userName "admin".

Password reset to Pwd@123456 for user admin succeeded

d. 脚本执行完成后，使用新密码重新登录Matrix页面即可。

4.2 除admin之外的其他用户输入错误的密码导致登录Matrix失败

4.2.1 故障描述

在登录Matrix页面，如果除admin之外的其他用户忘记登录密码等原因导致登录Matrix失败。

4.2.2 故障处理步骤

请根据集群情况执行对应脚本，进行重置密码的操作。

· 集群运行正常时重置密码。

a. 进入某一个Master节点的脚本存放目录，使用命令bash resetMatrixUserPassword.sh username reset_password执行该脚本，其中resetMatrixUserPassword.sh为脚本名称，username为用户名称，reset_password为新密码，例如：bash resetMatrixUserPassword.sh test Pwd@123456。

[root@node1 ~]# cd /opt/matrix/k8s

[root@name0 k8s]# bash resetMatrixUserPassword.sh test Pwd@12345

Password reset to Pwd@12345 for user test succeeded.

b. 脚本执行完成后，使用新密码重新登录Matrix页面即可。

· 集群紧急模式下重置密码。

a. 请先根据4.1 admin用户输入错误的密码导致登录Matrix失败章节重置admin用户密码并修复集群，待集群恢复正常后再根据该章节内“集群运行正常时重置密码”操作方式重置用户的密码。

5 默认路由丢失故障处理

5.1 使用ifconfig命令对网卡重启后默认路由丢失

5.1.1 故障描述

在集群中某个节点的命令行界面，使用ifconfig interface_name down和ifconfig interface_name up命令对网卡进行重启后，默认路由丢失。

5.1.2 故障处理步骤

(1) 进入故障节点操作系统的命令行界面，使用命令systemctl restart network重启network服务即可。

[root@node01 ~]# systemctl restart network

(2) 使用命令route -n查看节点默认路由是否恢复。以下返回结果为举例，不同的环境默认路由将会不同。

[root@node01 ~]# route -n

Kernel IP routing table

Destination Gateway Genmask Flags Metric Ref Use Iface

0.0.0.0 10.99.212.1 0.0.0.0 UG 0 0 0 eth0

10.99.212.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0

169.254.0.0 0.0.0.0 255.255.0.0 U 1002 0 0 eth0

192.168.122.0 0.0.0.0 255.255.255.0 U 0 0 0 virbr0

6 ETCD服务异常

6.1 ETCD服务启动失败或数据不一致

6.1.1 故障描述

出现如下任意现象，均是由于ETCD存储数据文件在节点重启后损坏或者文件丢失，导致ETCD服务启动失败或无法同步数据。可按照相应故障处理步骤进行操作。

现象一：

节点所在服务器下电后重启，ETCD服务由于数据库db文件损坏而启动失败，最终导致集群异常。查看/var/log/matrix-diag/Matrix/etcd/etcd.log日志有以下信息：

panic: freepages: failed to get all reachable pages (page 1407374894039040: out of bounds: 1264)

goroutine 116 [running]:

panic(0x55a1d6cce4a0, 0xc420202ef0)

/opt/rh/go-toolset-1.10/root/usr/lib/go-toolset-1.10-golang/src/runtime/panic.go:551 +0x3c5 fp=0xc42006bf60 sp=0xc42006bec0 pc=0x55a1d5f0ae25

github.com/coreos/bbolt.(*DB).freepages.func2(0xc42020c180)

…

现象二：

正常情况下，ETCD中/var/lib/etcd/default.etcd/member/snap日志（快照日志）文件的最大日志索引值（13d62e）大于wal日志（预写日志）文件的最小日志索引值（d4bf2）。以下图为例。

节点所在服务器下电后重启，若ETCD中wal日志文件的最小日志索引值（e6fac）大于snap日志文件的最大日志索引值（e37fd），ETCD会由于丢失必要的操作日志数据，无法恢复数据，导致文件损坏。以下图为例。

现象三：

节点所在服务器下电后重启，ETCD服务由于数据库snap日志（快照日志）文件丢失而启动失败，最终导致集群异常。查看/var/log/matrix-diag/Matrix/etcd/etcd.log日志有以下信息：

etcdserver: recovering backend from snapshot error: database snapshot file path error: snap: snapshot file doesn't exist

现象四：

ETCD服务由于数据文件损坏而启动失败，导致节点状态异常。登录ETCD服务异常的节点查看日志有以下信息：

"error":"walpb: crc mismatch"

现象五：

集群环境节点重启后ETCD服务正常启动，但是由于某一个或多个节点上的ETCD数据文件损坏导致ETCD集群数据不同步，主要有两种现象：

· 在其中一个Master节点后台执行“watch kubectl get pod -A -owide | grep -v Running”命令，发现多次回显的Pod状态不一致。

· 查看三台Master节点ETCD服务的日志（日志目录：/var/log/matrix-diag/Matrix/etcd/），发现某一个或多个节点上该日志有以下信息：“failed to publish local member to cluster through raft”。存在该日志的节点为db文件损坏、ETCD服务异常节点，故障处理时请处理该异常节点。

6.1.2 故障处理步骤

登录各节点服务器，通过命令systemctl status etcd查看各节点的ETCD服务状态，running为正常状态。如下图所示。

若为不正常状态，可根据下列步骤进行故障恢复。

· 单机环境如果ETCD服务出现上述现象，可通过6.1.2 1. 单机故障恢复章节进行故障恢复。

· 集群环境如果仅有一个节点的ETCD服务出现上述现象，请登录Matrix界面，在[部署>集群]页面单击出现问题节点右上角的按钮，选择“重建”，可对指定节点进行重建操作，重建完成后故障即可恢复。

· 集群环境如果两个节点ETCD服务出现db文件损坏情况，此时Matrix页面会进入紧急模式状态，可通过节点重建方式逐个恢复问题节点。故障描述中的现象五不会进入紧急模式，也可通过节点重建方式逐个恢复问题节点。

· 集群环境如果三个节点的ETCD服务出现上述现象，可通过6.1.2 2. 集群故障恢复章节进行故障恢复。

1. 单机故障恢复

前置条件

出现上述ETCD服务启动失败场景。

故障恢复操作

(1) 登录节点服务器，通过systemctl status etcd查看节点的ETCD服务状态，running为正常状态。若为不正常状态，可根据下列步骤进行故障恢复。

(2) 停止节点上的Matrix服务。

¡ root用户通过systemctl stop matrix命令停止节点上的Matrix服务。使用命令systemctl status matrix验证Matrix服务是否已经停止。若停止成功，则将在Active字段后显示运行信息为inactive (dead)。

[root@master1 ~]# systemctl stop matrix

¡ 非root用户通过sudo /bin/bash -c "systemctl stop matrix"命令停止节点上Matrix服务

[admin@node4 ~]$ sudo /bin/bash -c "systemctl stop matrix"

(3) 通过mv /etc/kubernetes/manifests/kube-apiserver.yaml /opt/matrix命令停止kube-apiserver服务。使用命令docker ps | grep kube-apiserver验证kube-apiserver服务是否已经停止。若无回显表示服务已停止。

[root@master1 ~]# mv /etc/kubernetes/manifests/kube-apiserver.yaml /opt/matrix

[root@master1 ~]# docker ps | grep kube-apiserver //查询是否已停止kube-apiserver

[root@master1 ~]# //无回显表示服务已停止

(4) 完全停止ETCD服务，并删除ETCD数据目录。

¡ root用户通过systemctl stop etcd命令完全停止ETCD服务，使用命令systemctl status etcd验证ETCD服务是否已经停止。若停止成功，则将在Active字段后显示运行信息为inactive (dead)。通过命令rm -rf /var/lib/etcd/default.etcd/删除ETCD数据目录，确保/var/lib/etcd下面没有数据目录。

[root@master1 ~]# systemctl stop etcd

[root@master1 ~]# rm -rf /var/lib/etcd/default.etcd/

[root@master1 ~]# ll /var/lib/etcd/

¡ 非root用户通过sudo /bin/bash -c "systemctl stop etcd"命令完全停止ETCD服务，并且通过命令sudo /bin/bash -c "rm -rf /var/lib/etcd/default.etcd/"删除ETCD数据目录，确保/var/lib/etcd下面没有数据目录

[admin@node4 ~]$ sudo /bin/bash -c "systemctl stop etcd"

[admin@node4 ~]$ sudo /bin/bash -c "rm -rf /var/lib/etcd/default.etcd/"

[admin@node4 ~]$ ll /var/lib/etcd/

(5) 查询ETCD备份目录/opt/matrix/backup/etcd_backup_snapshot/找到最新的备份数据文件，例如Etcd_Snapshot_V900R001B06D012_20210805091547.db。

[root@master1 ~]# ll /opt/matrix/backup/etcd_backup_snapshot/

(6) 进入ETCD恢复脚本目录，执行恢复操作，恢复脚本传入的Etcd_Snapshot_*_*.db为第（5）步查到的最新备份数据文件。

a. 进入ETCD恢复脚本目录。

[root@master1 ~]# cd /opt/matrix/k8s/disaster-recovery/

b. 执行恢复操作命令。

- root用户执行恢复操作命令如下

[root@master1 ~]# bash etcd_restore.sh Etcd_Snapshot_V900R001B06D012_20210805091547.db

2021-08-06 03:16:19.500144 I | mvcc: restore compact to 109069

2021-08-06 03:16:19.506086 I | etcdserver/membership: added member 91651d28c8465c86 [http://10.99.212.125:2380] to cluster db6c09f0e7b9702b

- 非root用户执行恢复操作命令如下

[admin@node4 ~]$ sudo bash etcd_restore.sh Etcd_Snapshot_V900R001B06D012_20210805091547.db

2021-08-06 03:16:19.500144 I | mvcc: restore compact to 109069

2021-08-06 03:16:19.506086 I | etcdserver/membership: added member 91651d28c8465c86 [http://10.99.212.125:2380] to cluster db6c09f0e7b9702b

(7) 重启ETCD服务。

¡ root用户通过systemctl restart etcd命令重启ETCD服务。

[root@master1 ~]# systemctl restart etcd

¡ 非root用户通过sudo /bin/bash -c "systemctl restart etcd"命令重启ETCD服务。

[admin@node4 ~]$ sudo /bin/bash -c "systemctl restart etcd"

(8) 重启Matrix服务。

¡ root用户通过systemctl restart matrix命令重启Matrix服务。

[root@master1 ~]# systemctl restart matrix

¡ 非root用户通过sudo /bin/bash -c "systemctl restart matrix"命令重启Matrix服务

[admin@node4 ~]$ sudo /bin/bash -c "systemctl restart matrix"

(9) 恢复kube-apiserver服务。

[root@master1 ~]# mv /opt/matrix/kube-apiserver.yaml /etc/kubernetes/manifests/

单机故障恢复后检查

(1) 使用北向业务虚IP登录Matrix平台的GUI界面。

(2) 点击“部署”页签，在弹出的菜单中选择“集群”，进入集群部署页面查看Master节点状态，Master节点状态正常，如下图所示。

图6-1 1个Master节点正常状态

(3) 点击“观测”页签，在弹出的菜单中选择“工作负载”，查看Pod状态，所有Pod都处于Running状态，如下图所示。

图6-2 Pod页签中所有Pod都处于Running状态

2. 集群故障恢复

前置条件

集群中三个节点都出现上述ETCD服务启动失败场景。

故障恢复操作

(1) 登录所有Master节点服务器，通过systemctl status etcd查看节点的ETCD服务状态，running为正常状态。若为不正常状态，可根据下列步骤进行故障恢复。

(2) 停止所有Master节点上的Matrix服务。

¡ root用户通过systemctl stop matrix命令停止所有Master节点上的Matrix服务

[root@master2 ~]# systemctl stop matrix

¡ 非root用户通过sudo /bin/bash -c "systemctl stop matrix"命令停止节点上Matrix服务。

[admin@node4 ~]$ sudo /bin/bash -c "systemctl stop matrix"

(3) 执行mv /etc/kubernetes/manifests/kube-apiserver.yaml /opt/matrix命令停止所有Master节点上的kube-apiserver服务。

[root@master2 ~]# mv /etc/kubernetes/manifests/kube-apiserver.yaml /opt/matrix

(4) 停止所有Master节点上的ETCD服务，并删除ETCD数据目录。

¡ root用户通过systemctl stop etcd命令完全停止所有Master节点上ETCD服务，并且通过命令rm -rf /var/lib/etcd/default.etcd/删除ETCD数据目录，确保/var/lib/etcd下面没有数据目录

[root@master2 ~]# systemctl stop etcd

[root@master2 ~]# rm -rf /var/lib/etcd/default.etcd/

[root@master2 ~]# ll /var/lib/etcd/

¡ 非root用户通过sudo /bin/bash -c "systemctl stop etcd"命令完全停止ETCD服务，并且通过sudo /bin/bash -c "rm -rf /var/lib/etcd/default.etcd/"命令删除ETCD数据目录，确保/var/lib/etcd下面没有数据目录

[admin@node4 ~]$ sudo /bin/bash -c "systemctl stop etcd"

[admin@node4 ~]$ sudo /bin/bash -c "rm -rf /var/lib/etcd/default.etcd/"

[admin@node4 ~]$ ll /var/lib/etcd/

(5) 查询ETCD备份目录/opt/matrix/backup/etcd_backup_snapshot/找到最新的备份数据文件，例如Etcd_Snapshot_V900R001B06D012_20210805091653.db。请确认所有节点存在相同的备份数据文件，如果节点没有文件，可从其他节点拷贝ETCD备份文件到节点。

[root@master1 ~]# ll /opt/matrix/backup/etcd_backup_snapshot/

(6) 进入ETCD恢复脚本目录，执行恢复操作，恢复脚本传入的Etcd_Snapshot_*_*.db为第（5）步查到的最新备份数据文件，所有节点请使用相同的备份数据文件，保持备份恢复数据一致。

a. 进入ETCD恢复脚本目录

[root@master1 ~]# cd /opt/matrix/k8s/disaster-recovery/

b. 执行恢复操作命令

- root用户执行恢复操作命令如下

[root@master2 ~]# bash etcd_restore.sh Etcd_Snapshot_V900R001B06D012_20210805091653.db

2021-08-06 06:33:14.788657 I | mvcc: restore compact to 273930

2021-08-06 06:33:14.802137 I | etcdserver/membership: added member 312131d4535cc53f [http://10.99.212.124:2380] to cluster cd6d5adc1bfd16f5

2021-08-06 06:33:14.802189 I | etcdserver/membership: added member 5fc2f82d74297956 [http://10.99.212.123:2380] to cluster cd6d5adc1bfd16f5

2021-08-06 06:33:14.802206 I | etcdserver/membership: added member ad12c65048f444bd [http://10.99.212.120:2380] to cluster cd6d5adc1bfd16f5

- 非root用户执行恢复操作命令如下

[admin@node4 ~]$ sudo bash etcd_restore.sh Etcd_Snapshot_V900R001B06D012_20210805014548.db

2021-08-06 01:22:10.876952 I | mvcc: restore compact to 12660679

2021-08-06 01:22:10.906116 I | etcdserver/membership: added member ac2cefc4cae84e25 [http://[2000::100:2000]:2380] to cluster ced7b5d5ee633b40

2021-08-06 01:22:10.906174 I | etcdserver/membership: added member b4689a44b8c1f191 [http://[2000::100:2001]:2380] to cluster ced7b5d5ee633b40

2021-08-06 01:22:10.906197 I | etcdserver/membership: added member c328a554c1ca84f4 [http://[2000::100:2002]:2380] to cluster ced7b5d5ee633b40

(7) 在上述所有操作完成后，然后在所有Master节点依次重启ETCD服务。

¡ root用户通过systemctl restart etcd命令重启ETCD服务

[root@master2 ~]# systemctl restart etcd

¡ 非root用户通过sudo /bin/bash -c "systemctl restart etcd"命令重启ETCD服务

[admin@node4 ~]$ sudo /bin/bash -c "systemctl restart etcd"

(8) 在所有Master节点依次重启Matrix服务。

¡ root用户通过systemctl restart matrix命令重启Matrix服务

[root@master2 ~]# systemctl restart matrix

¡ 非root用户通过sudo /bin/bash -c "systemctl restart matrix"命令重启Matrix服务

[admin@node4 ~]$ sudo /bin/bash -c "systemctl restart matrix"

(9) 在所有Master节点依次恢复kube-apiserver服务。

[root@master2 ~]# mv /opt/matrix/kube-apiserver.yaml /etc/kubernetes/manifests/

集群故障恢复后检查

(1) 使用北向业务虚IP登录Matrix平台的GUI界面。

(2) 点击“部署”页签，在弹出的菜单中选择“集群”，进入集群部署页面查看Master节点状态，Master节点状态正常，如下图所示。

图6-3 三个Master节点+1个Worker节点正常状态

(3) 点击“观测”页签，在弹出的菜单中选择“工作负载”，查看Pod状态，所有Pod都处于Running状态，如下图所示。

图6-4 Pod页签中所有Pod都处于Running状态

6.2 在ETCD非独立磁盘部署环境下，出现客户端请求超时或ETCD集群主备切换频繁

6.2.1 故障描述

出现如下任意现象，可能是由于ETCD非独立磁盘部署环境，磁盘IO性能差导致的故障现象。可按照相应故障处理步骤进行操作。

现象一：

ETCD客户端如K8s、Matrix等访问ETCD数据库超过800ms，分别登录各Master节点后台，在/var/log/matrix-diag/Matrix/etcd路径下查看etcd.log日志有以下信息。

[root@master2 etcd]# cat etcd.log |grep "took too long"

2020-11-15 12:36:42.013987 W | etcdserver: read-only range request "key:\"/registry/services/specs/default/kubernetes\" " with result "range_response_count:1 size:295" took too long (877.352309ms) to execute

2020-11-15 12:36:54.026221 W | etcdserver: read-only range request "key:\"/registry/pods/base-service/\" range_end:\"/registry/pods/base-service0\" " with result "range_response_count:42 size:107232" took too long (1.767232614s) to execute)

…

现象二：

ETCD集群频繁主备切换（多次执行etcdctl member list命令，若isLeader=true字段反复出现在不同节点，即为频繁主备切换），可能是由于ETCD集群因心跳超时导致。

图6-5 ETCD集群的主一直在etcd3上

6.2.2 故障处理步骤

(1) 若上述现象出现在应用安装升级、配置下发等操作过程，并导致操作失败的情况，则可以尝试再次进行安装升级、配置下发操作进行恢复（由于首次操作已完成部分数据同步，再次操作对磁盘IO影响减弱，会提高升级成功的概率）。

(2) 若上述现象出现稳态运行过程（即当前页面无用户操作），则可以通过配置定制文件/opt/matrix/config/navigator_config.json的主备切换参数"matrixLeaderLeaseDuration"（租约老化时间）和"matrixLeaderRetryPeriod"（租约检测周期）来延迟主备切换超时时间，但修改后也会影响节点故障切换时间。

(3) 如果因磁盘IO差导致无法写入或数据丢失的情况，有几种故障恢复方法：

¡ 方法一：

- 若出现Pod状态或通讯异常，可通过kubectl delete pod -n namespace podName命令删除异常Pod操作，删除后将自动创建Pod恢复ETCD数据资源。

¡ 方法二：通过6.1.2 1. 单机故障恢复和6.1.2 2. 集群故障恢复。

¡ 方法三：

- 卸载所有节点的Matrix软件包。

- 重新安装Matrix软件包。

- 登录页面，根据Matrix备份文件进行集群恢复，并进行重新安装应用再配置恢复，具体步骤请参考《统一数字底盘部署指导》的“备份恢复”章节。

7 Docker服务异常

7.1 执行Docker命令后长时间无响应

7.1.1 故障描述

执行docker ps、docker images、docker inspect、docker rmi等命令后，长时间无响应。

7.1.2 故障处理步骤

(1) 重启Docker服务。

¡ root用户执行如下命令重启Docker服务。

[root@master1 ~]# systemctl restart docker

¡ 非root用户执行如下命令重启Docker服务。

[admin@master1 ~]$ sudo /bin/bash -c "systemctl restart docker"

(2) 验证Docker服务是否已恢复正常。

¡ root用户执行docker images命令查看Docker服务。

¡ 非root用户执行sudo /bin/bash -c " docker images "命令查看Docker服务。

(3) 若回显结果中存在当前节点的镜像信息，则表示Docker恢复正常。

图7-1 docker images命令回显

7.2 页面显示Docker组件异常

7.2.1 故障描述

断电重启导致var/lib/docker系统文件损坏，Docker服务状态异常。

7.2.2 故障处理步骤

需要重新安装ISO镜像并重建节点进行恢复。

图7-2 重建节点

8 服务器下电重启或网络异常断开故障问题处理

8.1 节点所在服务器下电后重启，操作系统文件丢失

8.1.1 故障描述

Matrix正常运行或集群/应用部署过程中（如集群部署、升级、恢复、重建、应用部署和升级等），节点所在服务器下电后重启，如果出现如下任意现象，均是由节点下电导致的问题。

· /usr/lib/systemd/system目录下chronyd.service、docker.service、containerd.service文件内容丢失。

· /etc/下chrony.conf、docker、etcd、hosts、ssh配置文件内容丢失；/opt/matrix/k8s/下的deployenv.sh文件丢失。

· /var/log下的日志文件或其中的内容丢失。

8.1.2 故障处理步骤

· chronyd.service、docker.service、containerd.service的内容丢失故障处理步骤

a. 通过ls /usr/lib/systemd/system/service-name.service命令查看所有节点上的service文件是否存在或内容是否为空。

b. 若某些节点上存在该文件且内容正常，可通过scp命令将该文件拷贝到丢失该文件或文件内容为空的节点上。

c. 若所有节点上都不存在该文件，请联系技术工程师或重新安装操作系统。

· /etc/和/var/log下的文件或其中的内容丢失故障处理步骤

由于各节点的文件内容不一致，自行修改可能存在问题，请联系技术工程师处理或重新安装操作系统。

· /opt/matrix/k8s/下的deployenv.sh文件丢失故障处理步骤

集群环境从其他有deployenv.sh文件的Master节点拷贝该文件到本节点，若均不存在，尝试重建；单机环境请联系技术工程师或重装Matrix。

8.2 节点所在服务器下电后重启或网络异常断开，Matrix依赖的文件丢失

8.2.1 故障描述

Matrix正常运行或集群/应用部署过程中（如集群部署、升级、恢复、重建、应用部署和升级等），节点所在服务器下电后重启或网络异常断开，如果出现如下任意现象，均是由节点下电导致的问题。

· etcd、matrix等服务的service文件或其中的内容丢失。

· /opt/matrix/下的配置文件或其中的内容丢失。配置文件如定制化配置文件navigator_config.json。

· /opt/matrix/下的脚本文件或其中的内容丢失。脚本文件如docker.sh。

· /var/lib/docker下的Docker镜像文件损坏，如：

现象1：部分pod处于ImagePullBackOff状态，describe pod看事件日志，提示错误如下：

error creating overlay mount to /var/lib/ /overlay2/698028ac124c9d0ef831f7d2d9506acd01faddaae6ea06a0a169fb352e0eddf4/merged: too many levels of symbolic links

现象2：time="2021-05-10T18:05:50.518918884+08:00" level=error msg="Handler for GET /containers/2494c1172314e37bd8250be06a24e0636b7427f89b3b5a5398ecfad7c2fe171d/json returned error: readlink /var/lib/docker/overlay2/l: invalid argument" 。

· /opt/matrix/下的Yaml文件或文件中的内容丢失。

8.2.2 故障处理步骤

· service文件或其中的内容丢失、/opt/matrix/下的文件或其中的内容丢失故障处理步骤

a. 通过ls命令查看所有节点上的相关文件是否存在或其中的内容是否为空。

b. 若某些节点上存在该文件且内容正常，可通过scp命令将该文件拷贝到丢失该文件的节点上。

c. 若所有节点上都不存在该文件，请联系技术工程师或重新安装Matrix。

· /var/lib/docker下的Docker镜像文件损坏

¡ 请通过上传Matrix版本包的方式重建节点。

¡ 联系技术工程师处理。

8.3 节点所在服务器下电后重启，页面中节点飘红、飘黄或监控页面Pod处于CreateContainerError状态

8.3.1 故障描述

Matrix正常运行或集群/应用部署过程中（如集群部署、升级、恢复、重建、应用部署和升级等），节点所在服务器重启，出现如下现象：

· 若Matrix相关Pod异常，页面中节点可能会飘红或飘黄。

· 若产品相关Pod异常，在[观测>工作负载]页面下存在CreateContainerError状态的Pod。

登录任一Master节点后台，使用kubectl get pod -A -owide | grep CreateContainerError命令可以查看所有处于CreateContainerError状态的Pod。

[root@node1 home]# kubectl get pod -A -owide | grep CreateContainerError

NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES

kube-system calico-kube-controllers-cd96b6c89-hfz7s 0/1 CreateContainerError 0 29d 10.99.212.164 node1 <none> <none>

8.3.2 故障处理步骤

方法一：

(1) 登录异常Pod所在节点，使用docker ps | grep podname | grep -v POD | grep Up|awk '{print $1}'命令获取其处于UP状态容器ID。其中，podname为异常Pod的名称。

[root@node1 home]# docker ps |grep calico-kube-controllers-cd96b6c89-hfz7s | grep -v POD|grep Up|awk '{print $1}'

c755b7812380

(2) 执行docker stop containerid && docker rm containerid命令删除该UP状态的容器。其中，containerid为容器ID。例如，docker stop c755b7812380 && docker rm c755b7812380。

(3) 删除成功后，使用kubectl get pod -A -owide | grep CreateContainerError命令查询是否依然存在处于CreateContainerError状态的Pod，若依然存在，则需登录Matrix页面重建该节点。

(4) 方法二：

(5) 登录Matrix页面重建异常Pod所在节点。

8.4 节点所在服务器下电后重启，页面中节点飘红、飘黄或监控页面Pod处于异常状态

8.4.1 故障描述

Matrix正常运行或集群/应用部署过程中（如集群部署、升级、恢复、重建、应用部署和升级等），节点所在服务器重启，出现如下现象：

· 若Matrix相关Pod异常，页面中节点可能会飘红或飘黄。

· 若产品相关Pod异常，在[观测>工作负载]页面下存在非Running、Completed和Succeeded状态的Pod。

登录任一Master节点后台，使用kubectl get pod -A -owide | grep -Evw "Running|Completed|Succeeded"命令查看所有处于异常状态的Pod。

现象1：登录异常Pod所在节点后台，使用cat /var/log/matrix-diag/Matrix/kubelet/kubelet.log | grep "unexpected end of JSON input"命令查看该节点的kubelet日志，若出现如下报错信息，则该问题的原因为：重启节点导致Pod数据损坏，Pod无法正常启动。

Multus: failed to load netconf: unexpected end of JSON input

现象2：登录异常Pod所在节点后台，使用cat /var/log/matrix-diag/Matrix/kubelet/kubelet.log | grep "device or resource busy"命令查看该节点的kubelet日志，若出现如下报错信息，则该问题的原因为：重启节点导致Pod占用的cgroup资源无法清理，Pod无法正常删除。

msg="Failed to removecgroup" error="rmdir/sys/fs/cgroup/perf_event/kubepods.slice/kubepods-burstable.slice/kubepods-burstable-pod19477284_c12f_45ca_b1f7_e44567957829.slice/docker-39dee0c5f2b0333af7ce921b03cad9dee06b6b949c4a55a80fca31b48305d001.scope:device or resource busy"

8.4.2 故障处理步骤

方法一（当异常Pod较少时可以使用该方法）：

(1) 登录任一Master节点后台，使用kubectl get pod -A -owide | grep -Evw "Running|Completed|Succeeded"命令查看异常状态Pod的命名空间和名称。

(2) 执行kubectl delete pod -n namespace podName --grace-period=0 --force 2>/dev/null命令删除异常Pod。其中namespace为上一步查询出的异常Pod的命名空间，podName为异常Pod的名称。

说明：该命令用于删除指定节点上某个异常Pod，包括Error、CreateContainerError等异常状态，当存在多个异常Pod时，需多次执行该命令。

方法二（当异常Pod较多时可以使用该方法）：

登录任一Master节点后台，执行kubectl get pod -A -owide --no-headers=true| grep -Evw "Running|Completed|Succeeded"| awk '{print $1 " " $2}'|xargs -I {} sh -c 'kubectl delete pod -n$1 $2 --grace-period=0 --force 2>/dev/null' sh {}命令。

说明：该命令用于批量删除所有处于异常状态的Pod。

8.5 节点所在服务器下电后重启，prometheus数据文件损坏导致Pod状态异常

8.5.1 故障描述

通过kubectl get pod -n monitor -owide | grep prometheus命令查看prometheus Pod名称及状态，发现存在crashloopbackoff状态的Pod。使用kubectl logs -f -n monitor prometheus-podname prometheus-server命令查看日志，显示errorerr="opening storage failed: /data/xxx信息。

8.5.2 故障处理步骤

(1) 使用rm -rf /var/lib/ssdata/imonitor/prometheus_data/命令删除异常Pod所在节点的prometheus数据文件。

(2) 拷贝正常Pod所在节点的prometheus_data文件至异常Pod所在节点。若Pod都异常，则删除所有节点的prometheus_data文件。

(3) 重启异常Pod。

8.6 节点服务器断电重启，MACVLAN附加网络IPv6网卡不可用

8.6.1 故障描述

已部署Matrix集群，当应用所在节点的服务器下电重启后，网卡不可用，具体现象如下：

使用命令kubectl exec -it -n kube-system harbor-master1-6mvlb /bin/bash进入容器

输入ip a命令查看容器内所有网卡IP，查看MACVLAN附加网络中的IPv6网卡，网卡名称以“eth2@if3”为例，状态显示为“tentative dadfailed”状态，则表示此IPv6网卡不可用。

[root@vdhcpsrc1-6658fb96f4-j4n4f /]# ip a

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN qlen 1000

link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00

inet 127.0.0.1/8 scope host lo