/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后,紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}
一、先说结论:巡检不是“看一眼”,是“每次都看同样的 9 项”
上一篇《大模型API成本实战:Token怎么计费、缓存与模型分级怎么省钱》(https://blog.csdn.net/guiren88/article/details/170971078 )算的是调用 API 的账。这一篇回到自家三节点 K8s 集群,解决一个更日常的问题:每天打开集群,第一件事是确认它健不健康。
手动巡检的问题不是不会查,而是每次查的项目不一样、凭心情:今天看了节点忘了看 PVC,明天看了 Pod 忘了看证书。漏掉的那一项,往往就是出事的那一项。所以正确的做法是把巡检写成脚本:固定的检查清单、固定的判断标准、固定的退出码,跑一次就知道结论。
这篇的脚本就是这么来的:9 项检查,只读不改集群,跑完给一个退出码——0 健康、1 有警告、2 有故障。脚本先在模拟数据上验证了健康与故障两种场景,再对真实集群实测。实测还真抓到一个故障:一个 Deployment 3 个副本 0 个可用,根因是 PodSecurity 准入策略把它拦下了。下面是完整过程。
二、脚本要查哪 9 项
设计之前先定三条原则:
9 项检查清单:
| 0 | 前置:kubectl 与 API 连通性 | kubectl 不可用 / 连不上 API | — |
| 1 | 节点状态 | 有节点未 Ready | — |
| 2 | 控制面 Pod(kube-system) | 有 Pod 非 Running | — |
| 3 | 全集群异常 Pod | 有 Pod 非 Running/Completed | 单个 Pod 重启 ≥10 次 |
| 4 | Deployment 副本数 | 可用副本数不足 | — |
| 5 | PVC | — | 有 PVC 未 Bound |
| 6 | 集群证书有效期 | — | 有证书 30 天内过期 |
| 7 | 节点资源用量(kubectl top) | — | CPU 或内存使用率 ≥80% |
| 8 | 最近 Warning 事件 | — | 存在 Warning 事件 |
阈值用环境变量可调:WARN_RESTARTS(默认 10)、WARN_CPU_PCT(默认 80)、WARN_MEM_PCT(默认 80)。
三、完整脚本
#!/usr/bin/env bash
# k8s-health-check.sh — 三节点 Kubernetes 集群一键巡检(只读)
#
# 用法:
# ./k8s-health-check.sh # 彩色输出(终端)
# ./k8s-health-check.sh –no-color # 纯文本输出(写日志 / 发告警时用)
#
# 退出码:0 全部正常;1 有警告;2 有故障
# 只调用 kubectl 只读命令,不改集群任何东西;不打印节点 IP、域名等信息。
# 依赖:kubectl(已配置好指向集群的 kubeconfig)、bash 4+、awk
#
# 阈值可调(环境变量):
# WARN_RESTARTS=10 # 单个 Pod 重启次数达到该值即警告
# WARN_CPU_PCT=80 # 节点 CPU 使用率达到该百分比即警告
# WARN_MEM_PCT=80 # 节点内存使用率达到该百分比即警告
set -u
# ———- 颜色 ———-
if [[ "${1:-}" == "–no-color" ]] || [[ -n "${NO_COLOR:-}" ]] || [[ ! -t 1 ]]; then
RED=""; GREEN=""; YELLOW=""; BLUE=""; BOLD=""; RESET=""
else
RED=$'\\033[31m'; GREEN=$'\\033[32m'; YELLOW=$'\\033[33m'
BLUE=$'\\033[34m'; BOLD=$'\\033[1m'; RESET=$'\\033[0m'
fi
WARN_RESTARTS="${WARN_RESTARTS:-10}"
WARN_CPU_PCT="${WARN_CPU_PCT:-80}"
WARN_MEM_PCT="${WARN_MEM_PCT:-80}"
OK_COUNT=0
WARN_COUNT=0
FAIL_COUNT=0
SKIP_COUNT=0
FAIL_ITEMS=()
WARN_ITEMS=()
section() { echo; echo "${BOLD}== $1 ==${RESET}"; }
ok() { echo "${GREEN}[OK]${RESET} $1"; OK_COUNT=$((OK_COUNT + 1)); }
warn() { echo "${YELLOW}[WARN]${RESET} $1"; WARN_COUNT=$((WARN_COUNT + 1)); WARN_ITEMS+=("$1"); }
fail() { echo "${RED}[FAIL]${RESET} $1"; FAIL_COUNT=$((FAIL_COUNT + 1)); FAIL_ITEMS+=("$1"); }
skip() { echo "${BLUE}[SKIP]${RESET} $1"; SKIP_COUNT=$((SKIP_COUNT + 1)); }
echo "${BOLD}Kubernetes 集群巡检 $(date '+%Y-%m-%d %H:%M:%S')${RESET}"
# ———- 0. 前置:kubectl 与 API 连通性 ———-
section "0. 前置检查"
if ! command -v kubectl >/dev/null 2>&1; then
fail "未找到 kubectl,请先安装并配置 kubeconfig"
echo; echo "${RED}巡检中止:kubectl 不可用${RESET}"
exit 2
fi
if ! kubectl cluster-info >/dev/null 2>&1; then
fail "kubectl 无法连通 API Server(kubeconfig 或网络有问题)"
echo; echo "${RED}巡检中止:集群不可达${RESET}"
exit 2
fi
SERVER_VER="$(kubectl version -o json 2>/dev/null | grep -A3 '"serverVersion"' | grep '"gitVersion"' | head -1 | cut -d'"' -f4)"
ok "kubectl 可用,API Server 连通(版本:${SERVER_VER})"
# ———- 1. 节点状态 ———-
section "1. 节点状态"
NODES_OUT="$(kubectl get nodes –no-headers 2>&1)" || { fail "kubectl get nodes 执行失败:$NODES_OUT"; NODES_OUT=""; }
TOTAL_NODES="$(echo "$NODES_OUT" | grep -c . || true)"
NOT_READY="$(echo "$NODES_OUT" | awk '$2 != "Ready"' | wc -l)"
echo "$NODES_OUT" | awk '{printf " %-12s %-10s %s\\n", $1, $2, $4}'
if [[ "$TOTAL_NODES" -eq 0 ]]; then
fail "一个节点都没取到"
elif [[ "$NOT_READY" -gt 0 ]]; then
fail "$NOT_READY/$TOTAL_NODES 个节点未 Ready"
echo "$NODES_OUT" | awk '$2 != "Ready" {print " 未 Ready 节点:" $1 " 状态:" $2}'
else
ok "$TOTAL_NODES 个节点全部 Ready"
fi
# ———- 2. 控制面 Pod ———-
section "2. 控制面 Pod(kube-system)"
SYS_PODS="$(kubectl get pods -n kube-system –no-headers 2>&1)" || { fail "kubectl get pods -n kube-system 执行失败"; SYS_PODS=""; }
# 注意:-n 指定命名空间时输出没有 NAMESPACE 列,各列为 NAME READY STATUS RESTARTS AGE
SYS_BAD="$(echo "$SYS_PODS" | awk '$3 != "Running" && $3 != "Completed"')"
SYS_BAD_N="$(echo "$SYS_BAD" | grep -c . || true)"
if [[ "$SYS_BAD_N" -gt 0 ]]; then
fail "kube-system 有 $SYS_BAD_N 个 Pod 非 Running"
echo "$SYS_BAD" | awk '{printf " %s 状态:%s 重启:%s\\n", $1, $3, $4}'
else
SYS_TOTAL="$(echo "$SYS_PODS" | grep -c . || true)"
ok "kube-system $SYS_TOTAL 个 Pod 全部 Running"
fi
# ———- 3. 全集群异常 Pod ———-
section "3. 全集群异常 Pod"
ALL_PODS="$(kubectl get pods -A –no-headers 2>&1)" || { fail "kubectl get pods -A 执行失败"; ALL_PODS=""; }
BAD_PODS="$(echo "$ALL_PODS" | awk '$4 != "Running" && $4 != "Completed"')"
BAD_N="$(echo "$BAD_PODS" | grep -c . || true)"
TOTAL_PODS="$(echo "$ALL_PODS" | grep -c . || true)"
if [[ "$BAD_N" -gt 0 ]]; then
fail "全集群 $BAD_N/$TOTAL_PODS 个 Pod 异常"
echo "$BAD_PODS" | awk '{printf " %s/%s 状态:%s 重启:%s\\n", $1, $2, $4, $5}'
else
ok "全集群 $TOTAL_PODS 个 Pod 全部 Running/Completed,无异常"
fi
# 重启次数过高的 Pod
HIGH_RESTART="$(echo "$ALL_PODS" | awk -v t="$WARN_RESTARTS" '$5+0 >= t')"
HIGH_RESTART_N="$(echo "$HIGH_RESTART" | grep -c . || true)"
if [[ "$HIGH_RESTART_N" -gt 0 ]]; then
warn "$HIGH_RESTART_N 个 Pod 重启次数 >= $WARN_RESTARTS 次"
echo "$HIGH_RESTART" | awk '{printf " %s/%s 状态:%s 重启:%s\\n", $1, $2, $4, $5}'
fi
# ———- 4. Deployment 副本 ———-
section "4. Deployment 副本数"
DEPS="$(kubectl get deployments -A –no-headers 2>&1)" || { fail "kubectl get deployments -A 执行失败"; DEPS=""; }
DEP_BAD="$(echo "$DEPS" | awk '{split($3, a, "/"); if (a[1] != a[2]) print}')"
DEP_BAD_N="$(echo "$DEP_BAD" | grep -c . || true)"
if [[ "$DEP_BAD_N" -gt 0 ]]; then
fail "$DEP_BAD_N 个 Deployment 可用副本数不足"
echo "$DEP_BAD" | awk '{printf " %s/%s 就绪:%s\\n", $1, $2, $3}'
else
DEP_TOTAL="$(echo "$DEPS" | grep -c . || true)"
ok "$DEP_TOTAL 个 Deployment 副本全部就绪"
fi
# ———- 5. PVC ———-
section "5. 持久卷声明(PVC)"
PVCS="$(kubectl get pvc -A –no-headers 2>&1)" || { fail "kubectl get pvc -A 执行失败"; PVCS=""; }
PVC_BAD="$(echo "$PVCS" | awk '$3 != "Bound"')"
PVC_BAD_N="$(echo "$PVC_BAD" | grep -c . || true)"
if [[ -z "$(echo "$PVCS" | grep .)" ]]; then
ok "集群中没有 PVC"
elif [[ "$PVC_BAD_N" -gt 0 ]]; then
warn "$PVC_BAD_N 个 PVC 未 Bound"
echo "$PVC_BAD" | awk '{printf " %s/%s 状态:%s\\n", $1, $2, $3}'
else
PVC_TOTAL="$(echo "$PVCS" | grep -c . || true)"
ok "$PVC_TOTAL 个 PVC 全部 Bound"
fi
# ———- 6. 证书有效期 ———-
section "6. 集群证书有效期"
if CERT_OUT="$(kubeadm certs check-expiration 2>&1)"; then
EXPIRING="$(echo "$CERT_OUT" | awk 'NR > 1 && $0 ~ /[0-9]+d/ {print}' | awk '{for (i=1;i<=NF;i++) if ($i ~ /^[0-9]+d$/) {gsub("d","",$i); if ($i+0 < 30) print}}' | wc -l)"
if [[ "$EXPIRING" -gt 0 ]]; then
warn "有 $EXPIRING 张证书 30 天内过期,请安排续期"
echo "$CERT_OUT" | grep -E "days|CERTIFICATE" | head -20
else
ok "全部证书有效期大于 30 天"
fi
else
skip "kubeadm 证书检查未执行(需要控制面本机权限),请在 master 上以 root 运行 kubeadm certs check-expiration"
fi
# ———- 7. 节点资源用量 ———-
section "7. 节点资源用量(kubectl top)"
if TOP_OUT="$(kubectl top nodes –no-headers 2>&1)"; then
echo "$TOP_OUT" | awk '{printf " %-12s CPU:%s 内存:%s\\n", $1, $3, $5}'
HIGH_CPU="$(echo "$TOP_OUT" | awk -v t="$WARN_CPU_PCT" '{gsub("%","",$3); if ($3+0 >= t) print $1 " CPU " $3 "%"}')"
HIGH_MEM="$(echo "$TOP_OUT" | awk -v t="$WARN_MEM_PCT" '{gsub("%","",$5); if ($5+0 >= t) print $1 " 内存 " $5 "%"}')"
if [[ -n "$HIGH_CPU" || -n "$HIGH_MEM" ]]; then
warn "节点资源用量超过阈值(CPU>${WARN_CPU_PCT}% 或内存>${WARN_MEM_PCT}%):$HIGH_CPU $HIGH_MEM"
else
ok "各节点 CPU/内存用量均低于阈值"
fi
else
skip "kubectl top 不可用(metrics-server 未安装或未就绪),资源用量项跳过"
fi
# ———- 8. 最近 Warning 事件 ———-
section "8. 最近 Warning 事件"
EVENTS="$(kubectl get events -A –field-selector type=Warning –sort-by=.lastTimestamp –no-headers 2>&1 | tail -5)"
if [[ -z "$EVENTS" ]]; then
ok "最近无 Warning 事件"
else
warn "最近有 Warning 事件(最新 5 条):"
echo "$EVENTS" | awk '{printf " %s %s %s\\n", $2, $3, $4}' | sed 's/ */ /g'
fi
# ———- 汇总 ———-
echo
echo "${BOLD}== 巡检汇总 ==${RESET}"
echo " OK:$OK_COUNT WARN:$WARN_COUNT FAIL:$FAIL_COUNT SKIP:$SKIP_COUNT"
if [[ "$FAIL_COUNT" -gt 0 ]]; then
echo "${RED}结果:发现故障,请处理:${RESET}"
printf ' – %s\\n' "${FAIL_ITEMS[@]}"
exit 2
elif [[ "$WARN_COUNT" -gt 0 ]]; then
echo "${YELLOW}结果:有警告项,建议关注:${RESET}"
printf ' – %s\\n' "${WARN_ITEMS[@]}"
exit 1
else
echo "${GREEN}结果:集群健康,无警告、无故障。${RESET}"
exit 0
fi
四、实测第一步:先用模拟数据验证脚本本身
直接拿真实集群测脚本有个问题:如果脚本有 bug,输出可能是错的,自己还不知道。所以先做了两组模拟测试:用一个假的 kubectl(按参数返回写好的样例输出)喂给脚本,验证两种场景。
- 健康场景:3 节点 Ready、Pod 全 Running、Deployment 副本齐全、PVC 已 Bound、资源用量正常、无 Warning 事件。结果:OK:8 WARN:0 FAIL:0 SKIP:1,退出码 0,结论“集群健康”。其中 1 个 SKIP 是证书检查——模拟环境里没有 kubeadm,属于预期内的跳过。
- 故障场景:1 个节点 NotReady、1 个 Pod CrashLoopBackOff 且重启 15 次、1 个 Deployment 0/1、1 个 PVC Pending、kubectl top 不可用、1 条 Warning 事件。结果:OK:2 WARN:3 FAIL:3 SKIP:2,退出码 2,汇总里三条 FAIL 全部列出。
模拟测试还真抓出一个 bug:kubectl get pods -n kube-system 的输出没有 NAMESPACE 列(各列是 NAME READY STATUS RESTARTS AGE),而 kubectl get pods -A 的输出有 NAMESPACE 列。第 2 节一开始按 -A 的列号取状态,把 READY 列(1/1)当成了状态,结果健康场景也被判成 FAIL。修掉列号后,两组模拟全部通过。这个 bug 如果直接上真实集群测,很可能被误读成“控制面全挂了”——先模拟再实测,就是为了避开这种坑。
五、实测第二步:对真实集群只读运行
模拟通过后,2026-11-18 中午对自家三节点集群(kubelet v1.30.14)只读运行了一次,真实输出如下(已脱敏,无 IP 与域名):
Kubernetes 集群巡检 2026-11-18 12:09:04
== 0. 前置检查 ==
[OK] kubectl 可用,API Server 连通(版本:v1.30.0)
== 1. 节点状态 ==
k8s-master Ready 97d
k8s-node1 Ready 97d
k8s-node2 Ready 69d
[OK] 3 个节点全部 Ready
== 2. 控制面 Pod(kube-system) ==
[OK] kube-system 14 个 Pod 全部 Running
== 3. 全集群异常 Pod ==
[OK] 全集群 39 个 Pod 全部 Running/Completed,无异常
[WARN] 9 个 Pod 重启次数 >= 10 次
kube-system/calico-node-7czk8 状态:Running 重启:10
kube-system/etcd-k8s-master 状态:Running 重启:15
kube-system/kube-apiserver-k8s-master 状态:Running 重启:24
kube-system/kube-controller-manager-k8s-master 状态:Running 重启:43
kube-system/kube-proxy-mwgf2 状态:Running 重启:15
kube-system/kube-proxy-ssw6v 状态:Running 重启:12
kube-system/kube-scheduler-k8s-master 状态:Running 重启:43
kuboard/kuboard-etcd-675cb 状态:Running 重启:23
team-a/psa-good-cc5bdd8df-rxrmc 状态:Running 重启:34
== 4. Deployment 副本数 ==
[FAIL] 1 个 Deployment 可用副本数不足
team-a/app-a 就绪:0/3
== 5. 持久卷声明(PVC) ==
[OK] 5 个 PVC 全部 Bound
== 6. 集群证书有效期 ==
[SKIP] kubeadm 证书检查未执行(需要控制面本机权限),请在 master 上以 root 运行 kubeadm certs check-expiration
== 7. 节点资源用量(kubectl top) ==
k8s-master CPU:8% 内存:45%
k8s-node1 CPU:44% 内存:39%
k8s-node2 CPU:1% 内存:40%
[OK] 各节点 CPU/内存用量均低于阈值
== 8. 最近 Warning 事件 ==
[WARN] 最近有 Warning 事件(最新 5 条):
17m Warning FailedCreate
2m14s Warning DNSConfigForming
2m1s Warning DNSConfigForming
67s Warning DNSConfigForming
51s Warning FailedCreate
== 巡检汇总 ==
OK:6 WARN:2 FAIL:1 SKIP:1
结果:发现故障,请处理:
– 1 个 Deployment 可用副本数不足
整体结论:节点、控制面、存储、资源用量都没问题,但脚本退出码是 2——有一个真实故障。
六、实测抓到的故障:app-a 3 个副本 0 个可用
第 4 项报出的 team-a/app-a 就绪 0/3,是一个 60 天前创建的学习用 Deployment。顺手查了它的事件,根因很明确:
Warning FailedCreate replicaset/app-a-59f54959cc
Error creating: pods "app-a-…" is forbidden:
violates PodSecurity "restricted:latest":
allowPrivilegeEscalation != false
(container "nginx" must set securityContext.allowPrivilegeEscalation=false),
unrestricted capabilities
(container "nginx" must set securityContext.capabilities.drop=["ALL"]),
runAsNonRoot != true
(pod or container "nginx" must set securityContext.runAsNonRoot=true),
seccompProfile
(pod or container "nginx" must set securityContext.seccompProfile.type
to "RuntimeDefault" or "Localhost")
也就是说:这个命名空间启用了 Pod Security Standards 的 restricted 级别,而 app-a 的 Pod 模板没有写 securityContext,创建 Pod 的请求直接被准入控制器拒绝,副本数永远是 0。Pod 都没创建出来,所以第 3 项“全集群异常 Pod”反而是 OK 的——这是只看 Pod 状态会漏掉的一类问题,也是第 4 项“查 Deployment 副本数”存在的意义。
修复方向是在 Deployment 的 Pod 模板里补上四项 securityContext:
spec:
template:
spec:
securityContext:
runAsNonRoot: true
seccompProfile:
type: RuntimeDefault
containers:
– name: nginx
securityContext:
allowPrivilegeEscalation: false
runAsNonRoot: true
capabilities:
drop: ["ALL"]
这是一个真实存在的遗留问题,本文只记录、不顺手改——改命名空间的 Deployment 属于变更操作,不在一键巡检的职责里。
七、另外两个值得关注的信号
1. 控制面 Pod 的累计重启次数偏高。 etcd 15 次、apiserver 24 次、controller-manager 与 scheduler 各 43 次。这些是静态 Pod,重启计数是累计值,集群 97 天里经历过主机升级、重启等操作,数字会自然累积;当前状态全部 Running,不算故障。但 43 次这个量级值得记下来:如果某天发现某个控制面 Pod 的重启数在短时间内快速上涨,那就是当天要处理的问题。脚本把阈值定在 10 次,正是为了让这类“慢慢变大”的数字早点进入视野。
2. DNSConfigForming 事件反复出现。 最近 5 条 Warning 事件里有 3 条是 DNSConfigForming,原因是 Pod 的 DNS 配置里 nameserver 数量超过上限(通常是宿主机 /etc/resolv.conf 里 nameserver 太多,Kubernetes 只取前 3 个)。它不影响 Pod 运行,只是个提示;彻底修要改宿主机的 DNS 配置,本文不展开。
八、怎么把巡检变成日常习惯
脚本本身只解决“查一次”,要变成习惯还需要两步:
1. 放进定时任务,每天自动跑。 例如每天早上 8 点跑一次,把输出追加到日志:
0 8 * * * /path/to/k8s-health-check.sh –no-color >> /var/log/k8s-health-check.log 2>&1
2. 用退出码接告警。 退出码 2(有故障)就发通知,退出码 1(有警告)只记日志。巡检脚本不负责发通知——它只负责给出可信的结论,通知交给现成的告警通道(比如之前文章里提到的 Prometheus + Alertmanager,或一个简单的 cron 邮件)。
两个小提醒:
- kubectl top 依赖 metrics-server,没装它第 7 项会 SKIP,属于正常,不是故障。
- 证书检查那一项需要在 master 本机以 root 运行 kubeadm certs check-expiration,普通账号跑巡检时会 SKIP。如果你的巡检账号就是 root,这一节就能正常出结果。
验证范围说明:本文的模拟测试用的是手写的样例 kubectl 输出,验证的是脚本的判断逻辑与退出码;真实集群实测于 2026-11-18 在自家三节点集群上只读运行,集群规模是 3 节点、39 个 Pod、5 个 PVC,数字以实测输出为准。证书有效期一项因权限原因未在本次实测中覆盖(SKIP),需在 master 上以 root 身份单独验证。
九、下一步
巡检脚本回答的是“集群现在健不健康”。下一个问题是“某个 Pod 为什么异常”——只看状态列不够,还得看它的事件、日志与重启历史。下一篇用 Python + kubernetes-client 写一个 Pod 异常巡检工具,把“发现异常 Pod → 自动定位原因”这一步也自动化,敬请期待。
网硕互联帮助中心





评论前必须登录!
注册