Checkmk —— 以「Agent 一次采集 + 规则集自动发现服务」为核心的高效一体化监控平台

运维监控软件手册 03-一体化监控平台 26.2 KB 原文

Checkmk —— 以「Agent 一次采集 + 规则集自动发现服务」为核心的高效一体化监控平台

分类:03 一体化监控平台 适用:中大型、批量标准化的服务器/网络/应用/云环境;从几百到数万台主机,靠分布式站点扩展 一句话:Agent 一次返回全部原始数据,服务端按「规则集」自动发现服务并套用阈值,配置少、性能好 官方:https://checkmk.com/ | https://docs.checkmk.com/ | https://github.com/Checkmk/checkmk 授权:开源版 GNU GPLv2(历史名 Raw Edition / CRE,当前官方渠道亦称 Checkmk Community);商业版(Enterprise / Managed Services / Cloud)为订阅制,功能与规模受限项见 §2.3

1. 它解决什么问题

痛点 对应能力
每台机器要手工配几十个监控项 Agent 一次采集返回全部原始数据,Service Discovery 自动列出 CPU/内存/文件系统/网卡/进程/服务
阈值要逐台改,配置量爆炸 规则集(Ruleset):一条规则作用于文件夹/标签/主机组,批量套用阈值与参数
传统 Nagios 核心单线程、规模上不去 Raw 用 Nagios 核心;商业版 CMC 多线程,同等硬件检查吞吐高数倍
多机房/多租户需要统一视图又要就地采集 原生分布式监控:中央站点 + 远程站点,配置复制 + Livestatus 汇总
Agent 部署、升级、加密注册太麻烦 商业版 Agent Bakery 自动打包分发;2.x Agent Controller 支持 TLS 注册
告警要分级、按时段、按条件分流 通知规则(Notification rules)+ 自定义通知脚本 + 计划停机

不擅长:日志全文检索与链路追踪(配 Loki/ELK、Jaeger)、原生超高频秒级时序长期分析(RRD 以趋势为主)、纯 Serverless 短生命周期对象(Prometheus 更原生);Raw 版缺自动化与高级报表,重运维效率场景需商业版。

2. 核心概念与架构

2.1 术语表

术语 含义
Site(OMD 站点) 由 omd create 建出的独立实例:独立 Linux 用户、配置、Web UI、进程与数据,位于 /omd/sites/<site>/
Host / Folder / Host tag / Label 被监控主机;文件夹是规则的作用域;标签与标签用于规则条件匹配
Agent 被管机上的 check_mk_agent(6556/TCP),一次返回 <<<section>>> 分段的原始文本;SNMP 为 agentless 路径
Check plugin 服务端 Python 插件,消费 Agent 输出的某个 section,产出若干 Service 及状态
Service / Service discovery 一个检查项(如 CPU load、Filesystem /)及其状态;-I 发现、-II 强制重发现
Rule / Ruleset Setup(旧版 WATO)里的「条件 + 值」条目;决定阈值、是否启用、联系人、Agent 参数等,按首条匹配生效
Monitoring core Raw 用 Nagios 核心;商业版默认 CMC(Checkmk Micro Core),负责调度与状态
Livestatus 核心状态查询协议(默认 6557/TCP),Web UI、分布式、外部工具都通过它读状态
WATO / Setup 1.x~2.0 称 WATO,2.0+ 改名 Setup;Web 配置界面,写入 conf.d/wato/*.mk
Agent Bakery / DCD / BI / Report 商业版能力:自动打包 Agent / 动态主机配置 / 业务智能 / SLA 报表
MKP / Exchange 扩展包格式(mkp 命令)与官方插件市场
Piggyback 把 A 主机采到的 B 主机数据(如 ESXi 上的 VM)转交给 B,用于虚拟化/云监控

2.2 Agent → Check → Service → Rule 链路

 被管机                                 Checkmk 站点
 ┌──────────────────┐   6556/TCP   ┌──────────────────────────┐
 │ check_mk_agent   │ ───────────▶ │ Fetcher / Agent receiver  │
 │ (<<<section>>>)  │  (或 8000 TLS│ 拉取 / 缓存 / piggyback   │
 │ local check /    │   注册上报)   └────────────┬─────────────┘
 │ MRPE / plugins   │                          ▼ 解析 section
 │ SNMP 设备 ───────┼── SNMP ─────▶  Check plugins(Python)    │
 └──────────────────┘                          ▼ 产出候选服务
                          Service Discovery(cm k -I) → Service
                                          ▼ 套用规则集(Setup/Rules)
                 Ruleset: 阈值 / 启用 / 联系人 / 时段 / 参数
                                          ▼ 状态计算
              Monitoring core(Nagios / CMC) → Livestatus(6557)
                                          ▼ Web UI / 通知规则 / 分布式

链路要点:

  1. Agent 采集:check_mk_agent 监听 6556(由 xinetd/systemd 或 Agent Controller 提供),输出以 <<<section>>> 分段的纯文本;本地检查走 <<<local>>>、插件放 /usr/lib/check_mk_agent/plugins/;2.1+ 可用 Agent Controller 经 8000/TCP 做 TLS 注册与推送。
  2. Check 解析:站点 fetcher 取回数据,各 Check plugin 认领自己的 section,解析成「服务名 + 指标 + 状态」的候选服务。
  3. Service 发现:cmk -I <host> 或 Setup 里的 Service discovery 把候选服务写入配置(Discovered services),并生成 Check_MK Discovery 服务监控「未发现/消失的服务」。
  4. Rule 套用:阈值与开关不写在主机上,而由规则集按 Folder / Host tag / Label / 显式主机 / 服务名匹配,首条命中生效;改规则后需 Activate changes(cmk -O 生成核心配置 + cmk -R 重载)。
  5. 状态与通知:核心计算 OK/WARN/CRIT/UNKNOWN,通知规则按条件选择插件(邮件 / 脚本 / Webhook)与接收人;Livestatus 供 Web 与分布式站点读状态。

2.3 Raw/CRE 与商业版差异

维度 Raw / CRE(Community,GPLv2) 商业版(Enterprise / Managed Services / Cloud)
监控核心 Nagios 核心(单线程),大规模受限 CMC 多线程,检查吞吐与并发显著更高
配置自动化 Setup 手动;无动态主机 DCD 动态主机配置、自动增删云/容器主机
Agent 管理 手工安装,明文 6556 Agent Bakery 自动打包/签名/更新、自动注册、TLS
分布式 支持(中央 + 远程站点) 支持,且含中央告警、许可同步、配置复制增强
报表 / SLA / BI 无 内置报表、SLA、Business Intelligence、可用性分析
通知 / 事件 基础通知规则、Event Console 增强通知、Alert handlers、事件关联与自动修复
认证 本地 / LDAP 额外 SAML、更细角色与多租户(CME)
授权与收费 免费、无节点限制、社区支持 按订阅(服务数/节点)计费,含官方支持
适用 预算有限、规模中小、愿意手工运维 大规模、强自动化、需合规报表与官方支持

命名提示:历史上开源版叫 Raw Edition / CRE(包 check-mk-raw-*、版本后缀 .cre);较新版本官方下载页与 GitHub 构建使用 Community(包 check-mk-community-*)。两者指同一开源分支,包名、站点版本后缀与下载路径以 https://checkmk.com/download 当前稳定版为准。

3. 安装与部署

当前稳定分支为 2.x(如 2.3 / 2.4 / 2.5 系列,以官方下载页最新稳定版为准)。Checkmk 按发行版提供单个 .deb/.rpm 包,不是 APT 仓库;<version>、<codename>、<tag>、<site> 均为占位符。

3.1 环境准备

项 要求
系统 官方提供 Debian/Ubuntu(.deb)与 RHEL/Rocky/SLES(.rpm)包,按发行版代号选;建议 24 核、48 GB 内存起
Web 系统 Apache(包会拉起依赖);站点自带 Apache、mod_python/WSGI、PHP 由 OMD 管理
数据库 不需要外部 DB;指标存 RRD,配置存 *.mk 文本,事件存站点内文件
端口 80/443(Web /<site>/)、6556/TCP(Agent 拉取)、8000/TCP(Agent receiver/TLS 注册)、6557/TCP(Livestatus,分布式)、161/UDP(SNMP)
时间 全节点 NTP 同步;TLS 注册证书与分布式复制依赖时钟
前置 主机 80 端口未被其他 Web 服务占用;omd 命令由安装包提供

3.2 多种安装方式

A. 官方 deb/rpm 包(推荐,Ubuntu/Debian):

CMK_VERSION=<version>                  # 如 2.4.0pX,以官方下载页最新稳定版为准
CODENAME=<codename>                    # 发行版代号,如 noble / jammy / bookworm
# 包名随版本变化(check-mk-raw-* 或 check-mk-community-*),以官方下载页实际名称为准
wget "https://download.checkmk.com/checkmk/${CMK_VERSION}/check-mk-raw-${CMK_VERSION}_0.${CODENAME}_amd64.deb"
sha256sum "check-mk-raw-${CMK_VERSION}_0.${CODENAME}_amd64.deb"   # 与下载页校验值比对
apt update && apt install -y "./check-mk-raw-${CMK_VERSION}_0.${CODENAME}_amd64.deb"
omd version                           # 输出 OMD - Open Monitoring Distribution Version <version>.cre

B. 官方 rpm 包(RHEL / Rocky / AlmaLinux / SLES):

CMK_VERSION=<version>
wget "https://download.checkmk.com/checkmk/${CMK_VERSION}/check-mk-raw-${CMK_VERSION}-<distro>.<arch>.rpm"
rpm -ivh "check-mk-raw-${CMK_VERSION}-<distro>.<arch>.rpm"   # 或 dnf install ./... 自动解决依赖
omd version
# rpm 包名中的 <distro>(如 el8/el9/sles15)与架构以官方下载页为准

C. Docker / docker compose(官方镜像,tag 用占位符):

docker run -d --name monitoring \
  -p 8080:5000 -p 8000:8000 \
  --tmpfs /opt/omd/sites/<site>/tmp:uid=1000,gid=1000 \
  -e CMK_SITE_ID=<site> \
  checkmk/check-mk-raw:<tag>
docker container logs monitoring       # 首次日志含 cmkadmin 自动生成的临时密码
# 浏览器访问 http://localhost:8080/<site>/check_mk/ ;改密码:docker exec -it monitoring su - <site> -c 'cmk-passwd cmkadmin'

官方镜像与容器内端口、环境变量以 https://checkmk.com/download 的 Docker 说明及镜像文档为准。

D. 源码构建(社区开发用,生产建议用官方包/镜像):Checkmk 源码在 https://github.com/Checkmk/checkmk ,构建需先装其声明的工具链与依赖(Bazel/Python/系统库等),流程为克隆仓库 → 按仓库构建说明执行配置与编译 → 产出 OMD 包再安装;具体 configure/make 参数以该仓库官方构建文档为准,不要照搬旧版教程。GitHub 页面确认开源版以 community 为构建产物标识、协议 GNU GPLv2。

3.3 首次启动与验证

omd create <site>                     # 1 建站点,输出含 cmkadmin 临时密码,务必保存
omd start <site>                      # 2 启动(mkeventd/rrdcached/cmc 或 nagios/apache/redis 等)
omd status <site>                     # 3 全部组件应为 running,Overall state: running
# 4 防火墙放行 80/443、6556、8000
# 5 浏览器 http://<host>/<site>/ 用 cmkadmin 登录,立即 cmk-passwd cmkadmin 改密
omd su <site>                         # 6 切到站点用户(后续 cmk 命令在此环境执行)
cmk -l | head                         # 7 列出当前配置的主机
# 8 被管机安装 Agent:Setup → Agents → 下载 check-mk-agent 包;或 wget http://<host>/<site>/check_mk/agents/
# 9 站点侧验证连通:cmk -d <host> | head ;应看到 <<<check_mk>>> 段

⚠️ 首登后立即改 cmkadmin 密码;omd create 生成的密码只显示一次。

4. 配置文件详解

路径(相对站点根 /omd/sites/<site>/) 作用
etc/check_mk/main.mk Raw 手工配置主文件(主机、分组、规则、SNMP 凭据等),Setup 生成内容不写这里
etc/check_mk/conf.d/wato/*.mk Setup/WATO 生成的配置:hosts.mk、rules.mk、groups.mk、文件夹层级等,⚠️ 不建议手改
etc/check_mk/conf.d/*.mk 用户自定义分片配置,按字母序加载
etc/check_mk/multisite.d/*.mk Web UI(Multisite)外观、视图、用户侧设置
etc/omd/site.conf OMD 站点级配置(CONFIG_* 变量,由 omd config 管理)
local/share/check_mk/ 本地扩展:checks/(check plugin)、notifications/(通知脚本)、web/plugins/(UI 插件)
var/check_mk/ 运行时数据:autochecks/(已发现服务)、cache/、RRD、日志
var/log/ web.log、cmc.log/nagios.log、apache/、Agent 相关日志

main.mk 关键项说明表:

变量 / 项 说明
all_hosts 主机名列表(可含标签与属性),Raw 版最基础的主机清单
ipaddresses / host_contactgroups / host_groups 主机名→IP 映射 / 主机联系人组 / 主机组定义
host_tags 主机标签字典,规则条件按标签匹配(如 {'web01': {'criticality':'prod'}})
extra_host_conf / extra_service_conf 按条件给主机/服务附加 Nagios 核心参数(如 notification_interval、max_check_attempts)
checkgroup_parameters 规则集参数:阈值、启用/禁用、发现参数,键为规则集名(对应 Setup 里的规则)
snmp_communities / snmp_credentials SNMP v1/v2c community 与 v3 凭据,按主机/标签匹配
datasource_programs 自定义数据源程序(替代直接连 Agent),如通过 SSH/jump 拉取
define_contactgroups / define_contacts 联系人与联系人组(通知规则依赖)
service_dependencies / servicegroups 服务依赖(抑制)/ 服务组
agent_ports / tcp_connect_timeouts 非默认 Agent 端口 / 连接超时
monitoring_core 核心选择(nagios / cmc),商业版可用 CMC

规则配置说明:Setup(旧 WATO)把每条规则写成 rules.mk 中形如 checkgroup_parameters.setdefault('<ruleset>', []).append( (<值>, <条件>, <选项>) ) 的条目;条件由 Folder、Host tag、Label、显式主机/服务名组成,按列表顺序首条命中生效(可用 Move to top 调整优先级)。查看/编辑路径:Setup → Hosts → Host monitoring rules、Setup → Services → Service monitoring rules、Setup → Agents → Agent rules;改完必须 Activate changes(生成核心配置)。⚠️ 直接手改 conf.d/wato/*.mk 会在下次 Activate 时被 Setup 覆盖。

main.mk 完整可运行最小示例:

# /omd/sites/<site>/etc/check_mk/main.mk
all_hosts = [
    'web01|prod|linux|tcp',        # 主机|criticality 标签|agent 标签|ping 方式
    'db01|prod|linux|tcp',
]
ipaddresses = {
    'web01': '<web01_ip>',
    'db01':  '<db01_ip>',
}
host_groups = [
    ('linux-servers', 'Linux 服务器', ['web01', 'db01']),
]
define_contactgroups = {
    'ops': ('运维值班', []),
}
# 规则:所有 prod 主机 CPU 负载阈值(规则集名以 Setup 对应 ruleset 为准)
checkgroup_parameters.setdefault('cpu_load', [])
checkgroup_parameters['cpu_load'].append(
    ({'levels': (5.0, 10.0)}, [], {'criticality': ['prod']}, {})
)
# 规则:文件系统 / 使用率 > 85% WARN / > 90% CRIT
checkgroup_parameters.setdefault('filesystem', [])
checkgroup_parameters['filesystem'].append(
    ({'levels': (85.0, 90.0)}, [], {'criticality': ['prod']}, {})
)
# SNMP 设备示例
snmp_communities = {
    'public': ['switch01'],
}

手工改 main.mk 后执行 cmk -O && cmk -R 生效;Raw 版也可完全用 Setup 图形化配置而不写此文件。

5. 核心使用方法

omd 命令族(站点生命周期):

omd version                                   # 1 已安装 OMD/Checkmk 版本
omd sites                                     # 2 列出所有站点及版本/状态
omd create <site>                             # 3 新建站点(含临时密码)
omd start <site>                              # 4 启动全部组件
omd stop <site>                               # 5 停止
omd restart <site>                            # 6 重启
omd status <site>                             # 7 组件状态(Overall state 应 running)
omd su <site>                                 # 8 切换到站点用户(后续 cmk 命令环境)
omd config <site> show                        # 9 查看站点配置变量
omd config <site> set LIVESTATUS_TCP on       # 10 开 TCP Livestatus(分布式用,默认端口 6557)
omd config <site> show | grep -i apache      # 11 查看站点 Apache 相关变量(TLS 建议由系统反向代理终结)
omd backup <site> /backup/<site>-$(date +%F).tar.gz    # 12 全站点备份
omd restore <site> /backup/<site>-<日期>.tar.gz        # 13 从备份恢复
omd update <site>                             # 14 将站点升级到当前安装的新版本
omd rm <site>                                 # 15 ⚠️ 删除站点(不可逆,先 backup)

cmk 命令族(监控操作,在 omd su <site> 后执行):

cmk -l                                        # 16 列出所有配置主机
cmk -D <host>                                 # 17 转储某主机的有效配置(含生效规则)
cmk -I <host>                                 # 18 服务发现(新增/移除服务)
cmk -II <host>                                # 19 强制重新发现(重算已发现参数)
cmk --discover-marked-hosts                   # 20 批量发现 Web 中标记待发现的主机
cmk -O                                        # 21 重新生成核心配置(Activate changes 的核心步骤)
cmk -R                                        # 22 重载监控核心使配置生效
cmk -d <host>                                 # 23 拉取并显示 Agent 原始输出(排障首选)
cmk -nv <host>                                # 24 详细模式检查某主机所有服务(dry-run,不写状态)
cmk -L | grep -i cpu                          # 25 列出全部 Check plugin / 规则集
cmk -V                                        # 26 Checkmk 版本
cmk-passwd cmkadmin                           # 27 修改 Web 管理员密码
lq "GET hosts\nColumns: name state\n"         # 28 经 Livestatus 查询主机状态
mkp list                                      # 29 列出已安装 MKP 扩展包
mkp install <package>.mkp                     # 30 安装扩展包
mkp package <name>                            # 31 打包本地扩展

REST API(2.x,端点以官方文档为准):

SITE=<site>; BASE="http://<host>/${SITE}/check_mk/api/1.0"
# 用 Setup → Users 生成的 Automation secret 作为 Bearer token
TOKEN='<automation_user>:<automation_secret>'
curl -sS -H "Authorization: Bearer ${TOKEN}" -H 'Accept: application/json' \
  "${BASE}/domain-types/host_config/collections/all" | jq .
curl -sS -X POST -H "Authorization: Bearer ${TOKEN}" -H 'Content-Type: application/json' \
  -d '{"host_name":"web01","folder":"/","attributes":{"ipaddress":"<ip>","tag_agent":"cmk-agent"}}' \
  "${BASE}/domain-types/host_config/collections/all" | jq .
curl -sS -X POST -H "Authorization: Bearer ${TOKEN}" "${BASE}/domain-types/activation_run/actions/activate-changes/invoke" | jq .

旧版 Web API 为 /<site>/check_mk/webapi.py?action=<action>&...(action=add_host、activate_changes 等),2.x 起推荐 REST API;参数与端点 以 https://docs.checkmk.com/ 的 REST API 文档为准。

Web UI 操作路径:Setup → Hosts → Add host(填主机名/IP、选 Checkmk agent 或 SNMP);主机页 Service configuration → Service discovery;右上角 Activate changes(含未激活变更数);Monitor → All hosts / Services / Problems;Setup → Services → Service monitoring rules(阈值规则);Setup → Agents → Agent rules / Agent Bakery;Setup → Notifications → Rules;Setup → Distributed monitoring。

6. 告警与通知

机制 说明
通知规则 Setup → Notifications → Add rule:按 Host tag / Folder / 服务状态 / 通知类型(PROBLEM/RECOVERY/ACK/FLAP/DOWNTIME)/ 时段匹配,选择插件与联系人;多规则叠加实现升级
通知插件 内置 HTML 邮件、ASCII 邮件、JIRA / Slack / PagerDuty / Cisco Webex 等(版本相关);自定义脚本放 ~/local/share/check_mk/notifications/,在 Setup 里注册为通知规则
脚本接口 通知以环境变量传入:NOTIFY_HOSTNAME、NOTIFY_SERVICEDESC、NOTIFY_HOSTSTATE/NOTIFY_SERVICESTATE、NOTIFY_NOTIFICATIONTYPE、NOTIFY_HOSTOUTPUT/NOTIFY_SERVICEOUTPUT、NOTIFY_CONTACTNAME、NOTIFY_CONTACTPAGER、NOTIFY_SHORTDATETIME 等
告警升级 用多条通知规则 + 「Match notification type / 第 N 次通知」条件,或按 Host tag criticality 分流到不同联系人组;商业版另有 Alert handlers 做自动修复
维护期 / 抑制 Monitor → 主机/服务 → Schedule downtime(固定/弹性,可 recurring 商业版)、Acknowledgements、Service dependencies、Event Console 事件关联与计数规则

自定义通知脚本(企业微信 / 钉钉 Webhook,放 ~/local/share/check_mk/notifications/notify_chat.sh):

#!/usr/bin/env bash
set -euo pipefail
STATE="${NOTIFY_SERVICESTATE:-$NOTIFY_HOSTSTATE}"
SVC="${NOTIFY_SERVICEDESC:-HOST}"
OUT="${NOTIFY_SERVICEOUTPUT:-$NOTIFY_HOSTOUTPUT}"
TEXT="[Checkmk $NOTIFY_NOTIFICATIONTYPE] $NOTIFY_HOSTNAME / $SVC = $STATE\n$OUT\n$NOTIFY_SHORTDATETIME"
KEY='<企业微信机器人 key>'                 # 地址以企业实际创建结果为准
curl -sS -X POST -H 'Content-Type: application/json' \
  --data "$(jq -n --arg c "$TEXT" '{msgtype:"text",text:{content:$c}}')" \
  "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=${KEY}"
chmod 755 ~/local/share/check_mk/notifications/notify_chat.sh
# Setup → Notifications → Add rule → Notification Method 选该脚本(先在 Setup 中登记为自定义插件)

钉钉替换为 https://oapi.dingtalk.com/robot/send?access_token=<TOKEN> + msgtype:markdown;邮件用内置 HTML mail 插件,在 Setup → Notifications 配 SMTP 与发件人。⚠️ 脚本以站点用户运行,禁止把 $NOTIFY_* 直接 eval/拼进 shell 命令(内容来自监控输出,可能含注入字符);建议用 jq -n --arg 构造 JSON。

7. 实战场景

场景一:批量纳管 100 台主机(REST API + 规则集 + 批量发现)

目标:从 CSV 批量创建主机,放到同一文件夹打 prod 标签,套用统一阈值规则,批量发现服务并激活。

SITE=<site>; BASE="http://<host>/${SITE}/check_mk/api/1.0"
TOKEN='<automation_user>:<automation_secret>'
# hosts.csv: host,ip   如 web01,10.0.1.11
while IFS=, read -r H IP; do
  [ "$H" = "host" ] && continue
  curl -sS -X POST -H "Authorization: Bearer ${TOKEN}" -H 'Content-Type: application/json' \
    -d "$(jq -n --arg h "$H" --arg ip "$IP" \
        '{host_name:$h,folder:"/linux",attributes:{ipaddress:$ip,tag_agent:"cmk-agent",tag_criticality:"prod"}}')" \
    "${BASE}/domain-types/host_config/collections/all" | jq -c '{host:$h,id:.id}'
done < hosts.csv
# 被管机批量装 Agent(Ansible 等价:分发 check-mk-agent 包并放行 6556)
# 站点侧:按文件夹/标签在 Setup → Service monitoring rules 建一条 CPU/文件系统阈值规则
su - <site> -c 'cmk --discover-marked-hosts && cmk -O && cmk -R'

验证:cmk -l | wc -l 比对数量;cmk -nv web01 看到服务;Web Activate changes 计数归零。 回滚:REST DELETE .../objects/host_config/<host> 逐台删除后 cmk -O && cmk -R;⚠️ 删除主机同时删其 RRD 历史,先 omd backup <site>。 替代:Setup → Hosts 支持 CSV 导入;商业版用 DCD 从 CMDB/云 API 自动增删主机。

场景二:自定义监控项(Local check:业务队列积压)

目标:在被管机加一个 local check,输出队列深度与阈值,站点自动发现为服务。

# 1) 被管机:/usr/lib/check_mk_agent/local/check_biz_queue.sh
cat > /usr/lib/check_mk_agent/local/check_biz_queue.sh <<'EOF'
#!/usr/bin/env bash
Q=$(cat /var/run/biz/queue.depth 2>/dev/null || echo -1)
if [ "$Q" -lt 0 ]; then echo "3 Biz_Queue - UNKNOWN - cannot read queue"; exit 0; fi
echo "P Biz_Queue queue_depth=${Q};10;20;0;1000 OK - queue=${Q} (warn 10 / crit 20)"
EOF
chmod 755 /usr/lib/check_mk_agent/local/check_biz_queue.sh
# local check 格式:状态(0/1/2/3/P) 服务名 [perfdata] 输出文本;P=由 perfdata 阈值自动判级
# 2) 验证 Agent 输出
cmk -d web01 | sed -n '/<<<local>>>/,/<<</p' | head
# 3) 站点侧发现并激活
cmk -I web01 && cmk -O && cmk -R
cmk -nv web01 | grep -i biz_queue
# 4) 可选:Setup → Services → Service monitoring rules 找 "Biz_Queue" 对应规则集统一改阈值
#    Raw 也可在 main.mk 用 checkgroup_parameters 覆盖(见 §4)

验证:Web 主机服务列表出现 Biz_Queue,写 echo 25 > /var/run/biz/queue.depth 后转 CRIT 并触发通知。 回滚:删被管机脚本 → cmk -II web01(清理 vanished 服务)→ cmk -O && cmk -R;RRD 历史按站点保留策略处理。

场景三:分布式监控(中央站点 + 异地远程站点)

目标:异地机房本地采集,中央站点统一看状态与改配置。

# 1) 远程站点与中央站点均安装同版本 Checkmk 包并 omd create
omd create <remote_site> && omd start <remote_site>
# 2) 远程站点开启 TCP Livestatus(供中央读取),端口 6557
omd config <remote_site> set LIVESTATUS_TCP on
omd restart <remote_site>
# 3) 中央站点 Setup → Distributed monitoring → Add connection
#    Site ID=<remote_site>,填远程站点 URL 与 Livestatus 地址 <remote_ip>:6557,
#    配置复制需 Setup 中生成/交换 automation user secret
# 4) 中央把主机分配到远程站点(Host 的 "Monitored by site" 属性),保存后 Activate changes
su - <central_site> -c 'cmk -O && cmk -R'
# 5) 验证
lq "GET sites\nColumns: name state\n"                       # 中央可看到远程站点状态
curl -sS -H "Authorization: Bearer <TOKEN>" "${BASE}/domain-types/activation_run/collections/all" | jq .

验证:中央 Web 的站点状态为 online,远程主机的服务出现在中央视图;断网时远程站点仍独立采集并缓存。 回滚:主机改回「Monitored by central site」→ 删除分布式连接 → 两端 cmk -O && cmk -R;⚠️ 删除连接不会删远程站点本地数据。

8. 日常运维与故障排查

omd status <site>                             # 组件健康
su - <site> -c 'cmk -O && cmk -R'            # 改配置后生成+重载
tail -f /omd/sites/<site>/var/log/web.log /omd/sites/<site>/var/log/cmc.log
grep -i 'error\|warning' /omd/sites/<site>/var/log/nagios.log | tail
cmk -d <host> | head                          # Agent 数据是否正常
lq "GET services\nColumns: host_name description state\nFilter: state = 2\n"   # 当前 CRIT 服务
现象 原因 处置
主机服务全灰 / Check_MK 服务报 Connection refused Agent 未装/未监听、防火墙 6556 未放、IP 填错 被管机装 check_mk_agent,ss -lntp|grep 6556,cmk -d <host> 验证
cmk -d 无 <<<check_mk>>> 或输出被截断 Agent 脚本报错、xinetd/systemd 配置错、超时 被管机直接跑 check_mk_agent | head,查 /var/log/syslog,调 tcp_connect_timeouts
Setup 改了规则但监控不生效 未点 Activate changes(cmk -O 未执行) 执行 cmk -O && cmk -R,或 Web 右上角 Activate changes
服务发现找不到新分区/新服务 未跑 discovery,或规则把服务禁用 cmk -II <host>,检查 Setup → Service monitoring rules 的 disabled services 规则
Check_MK Discovery 报 unmonitored/vanished 服务 硬件或应用变更,发现状态与配置不一致 跑 Service discovery 接受变更,或设「Discovery 参数」自动处理
中文服务名/输出乱码 Agent 输出编码与站点不一致 Agent 脚本输出 UTF-8,避免 locale 为 C
cmk -O 很慢 / 核心 reload 超时 主机/服务规模大、规则过多、Raw 的 Nagios 核心单线程 精简规则、合并文件夹、升级到商业版 CMC,或拆分布式站点
通知不发 通知规则条件不匹配、联系人组未关联、站点通知全局关闭、SMTP 不通 查 ~/var/log/notify.log 与通知规则,用 Setup → Notifications → Test notification
Agent Controller TLS 注册失败 8000 端口未放、站点与 Agent 版本不匹配、时钟漂移、注册凭据过期 放行 8000、对齐版本、校 NTP、用 cmk-agent-ctl register 重新注册
⚠️ 直接手改 conf.d/wato/*.mk 后配置丢失 下次 Activate 被 Setup 覆盖 自定义一律写 main.mk 或 conf.d/ 自建分片,不碰 wato 目录

9. 性能、容量与高可用

规模估算:Checkmk 的开销按「服务数 × 检查间隔」计,每秒检查数 ≈ 服务总数 / 平均间隔。Raw 版用 Nagios 核心(大体单线程),经验上数千服务需仔细调优;商业版 CMC 多线程 + 智能调度,同等硬件可高数倍。Setup → Site statistics / Check_MK 自监控服务可看 Check_MK helper usage、pending checks、check latency。

调优项 说明
商业版 CMC 多线程核心、Check_MK Helper 并发数、Smart ping 减少主机检查
分布式站点 按机房/地域拆分,中央只做配置下发与状态汇总,降低单点压力
Agent 缓存 / Piggyback 插件输出缓存避免每次全量执行;虚拟化/云用 Piggyback 一次采集多对象
SNMP bulk / 超时 网络设备用 bulk get、snmp_credentials 按分组匹配,避免逐 OID 轮询
规则精简 首条命中即停;把通用阈值放文件夹上层,减少规则数量与 -O 编译耗时
RRD / 历史 指标存 RRD,旧数据自动聚合;⚠️ 备份时用 omd backup 而非手工复制 RRD

高可用:单个 OMD 站点本身不是集群;常见做法是 keepalived + 双站点 + 配置同步(rsync/Git 的 etc/)或商业版的分布式/集群方案,⚠️ 双主会重复通知,需在备站关闭通知或用同一套通知去重。远程站点在中心断连时仍独立采集(Livestatus 断连不影响本地监控)。 自监控:每主机自带 Check_MK、Check_MK Discovery、Check_MK HW/SW Inventory 服务;站点级有 OMD <site> performance、Check_MK 站点统计;lq 查询 GET status,cmk -nv <checkmk主机> 可自检。

10. 安全加固、备份与升级

认证鉴权:首登改 cmkadmin 密码;Setup → Users & Roles 按最小权限分角色(只读/运维/管理员);接 LDAP/AD/SAML;Automation user 的 secret 专用于 API 并定期轮换;Web 强制 HTTPS(在站点 Apache 前用系统反向代理 + 证书终结 TLS,具体配置以官方文档为准);REST API 只允许内网/白名单访问。 Agent 与传输:传统 Agent 6556 为明文,建议限制 only_from/防火墙白名单;2.1+ 用 Agent Controller + 8000/TCP TLS 注册(cmk-agent-ctl register),商业版 Agent Bakery 可自动签名、加密与更新;SNMP 优先 v3;⚠️ 不要在不可信网络暴露 6556/8000。 最小权限:站点用户隔离(每站点独立系统账号);通知脚本与本地 check 用非 root;~/local/ 目录属主站点用户;禁用不必要的远程命令执行;MKP 只从可信来源安装并先审计代码。

备份与恢复:

omd stop <site>
omd backup <site> /backup/<site>-$(date +%F).tar.gz     # 含配置、RRD、事件、扩展
omd start <site>
# 恢复(⚠️ 覆盖同名站点现有数据,先在测试环境演练)
omd stop <site> && omd restore <site> /backup/<site>-<日期>.tar.gz && omd start <site>
# 仅配置备份(便于版本控制)
tar czf /backup/<site>-etc.tgz -C /omd/sites/<site> etc local

⚠️ 不要手工复制/编辑 var/ 下的 RRD 与 autochecks/;omd rm 与 omd restore 均不可逆,操作前必须 omd backup。

跨大版本升级:Checkmk 支持多版本包共存,流程为 备份 → 安装新版本包 → omd stop <site> → omd update <site>(自动迁移配置)→ omd start <site> → Web 检查并 Activate changes。⚠️ 大版本必须逐级升级(如 2.2 → 2.3 → 2.4),不可跳级;配置迁移通常不可逆,回滚只能靠「omd restore 备份 + 旧版本包/旧站点」。分布式场景先升中央站点再升远程站点,且所有站点版本需兼容。具体升级路径与兼容矩阵 以官方 upgrade 文档为准。

11. 常见坑(现象 → 原因 → 解决)

现象 原因 解决
omd create 后 Web 打不开 404 未 omd start、URL 少站点名、80 端口被占用 omd start <site>;访问 http://<host>/<site>/check_mk/;检查端口占用
忘记 cmkadmin 密码 omd create 只显示一次 su - <site> -c 'cmk-passwd cmkadmin' 重置
改了规则/主机却不生效 未 Activate changes cmk -O && cmk -R 或点右上角 Activate changes
主机服务全 UNKNOWN - Connection refused Agent 未装/6556 未放/用了 TLS 注册却仍按明文拉取 装 Agent、放行端口、对齐 tag_agent 与数据源设置
服务发现漏掉新磁盘/网卡 未重跑 discovery 或被 disabled services 规则排除 cmk -II <host>,检查规则与发现参数
Check_MK Discovery 常报警 业务频繁变更 配置「自动接受/删除服务」的发现参数,或设周期发现并抑制
手改 conf.d/wato/*.mk 被覆盖 Setup 每次 Activate 重写该目录 自定义写 main.mk 或 conf.d/ 自建 .mk,并在 Setup 中避免同名规则
checkgroup_parameters 规则不生效 规则集名写错、条件不匹配、首条命中被更靠前的规则截胡 cmk -D <host> 查看生效值;用 Setup 的「规则分析」调整顺序
通知脚本收不到变量 / 中文乱码 脚本未注册为通知插件、环境变量名拼错、非 UTF-8 在 Setup 登记插件,核对 NOTIFY_*,统一 UTF-8
升级后 Web 报配置错误 / 服务全灰 跳级升级或第三方 MKP 与新版本不兼容 逐级升级、先禁用/更新 MKP,按官方日志修配置
⚠️ 直接在生产 omd rm <site> 或 omd restore 站点数据不可恢复 先 omd backup,在测试环境演练后再执行
⚠️ 把 6556/8000 暴露到公网 Agent 输出含主机全量信息,且可能被利用执行命令 严格防火墙白名单,改用 TLS 注册与内网/VPN
⚠️ 只降级 RPM 却保留新版站点配置 版本与站点数据结构不匹配,站点起不来 回滚必须 omd restore 备份 + 对应旧版本包

12. 速查表

类别 项 值 / 命令
omd 版本 / 站点列表 omd version / omd sites
omd 建站 / 启停 / 状态 omd create <site> / omd start|stop|restart|status <site>
omd 切换站点 / 删站 omd su <site> / omd rm <site> ⚠️
omd 配置变量 / 开 Livestatus omd config <site> show|set LIVESTATUS_TCP on
omd 备份 / 恢复 / 升级 omd backup <site> <file> / omd restore <site> <file> / omd update <site>
cmk 列主机 / 转储配置 cmk -l / cmk -D <host>
cmk 发现 / 强制重发现 cmk -I <host> / cmk -II <host> / cmk --discover-marked-hosts
cmk 生成配置 / 重载核心 cmk -O / cmk -R
cmk Agent 输出 / 单主机检查 cmk -d <host> / cmk -nv <host>
cmk 列插件 / 版本 / 改密 cmk -L / cmk -V / cmk-passwd cmkadmin
查询 Livestatus / MKP lq "GET hosts\nColumns: name state\n" / mkp list|install <file>
配置 主配置 / Setup 生成 ~/etc/check_mk/main.mk / ~/etc/check_mk/conf.d/wato/*.mk(⚠️ 勿手改)
配置 本地扩展 / 通知脚本 ~/local/share/check_mk/checks/、~/local/share/check_mk/notifications/
配置 已发现服务 / 日志 ~/var/check_mk/autochecks/ / ~/var/log/web.log、cmc.log/nagios.log
端口 Web / Agent / 注册 / Livestatus 80,443 /<site>/ / 6556/TCP / 8000/TCP / 6557/TCP
Agent 输出分段 / local check <<<section>>> / P Service_Name metric=v;w;c;min;max 文本
规则 参数字典 / 生效顺序 checkgroup_parameters['<ruleset>'].append(...) / 首条命中
API REST / 旧 Web API /<site>/check_mk/api/1.0/... / /<site>/check_mk/webapi.py?action=...
Web 入口 / 激活 / 发现 http://<host>/<site>/ / 右上角 Activate changes / 主机 Service discovery
默认账号 初始 cmkadmin(密码见 omd create 输出,⚠️ 立即修改)

13. 选型建议与同类对比

维度 Checkmk Zabbix Prometheus Nagios Core
定位 规则驱动、自动发现强的一体化监控 全栈一体化监控/告警 云原生指标 + 时序 轻量状态检查框架
数据模型 Host/Service/Check + 规则集 Host/Item + 关系库历史 时序 + label Host/Service 状态
采集 Agent(6556)、SNMP、Piggyback、Agent Bakery Agent(2)/SNMP/JMX/Proxy Pull + exporter 插件 + NRPE
配置 规则集 + WATO/Setup(少写每项) 模板 + 宏 + LLD + UI/API 配置文件 + 服务发现 手写 cfg 对象文件
告警 内置通知规则 + 自定义脚本 表达式/升级/抑制/维护期 Alertmanager 外置 基础通知 + escalation
可视化 内置视图 + Grafana 集成 内置 Dashboard/Map/SLA Grafana 外置 自带 CGI(简陋)
分布式 原生中央/远程站点 原生 Proxy 缓冲 + Server HA 联邦/Thanos 需外挂
数据库 / 许可 无外部 DB(RRD)/ GPLv2(Raw)、商业订阅 强依赖 / AGPLv3(7.0+) 自带 TSDB / Apache-2.0 无 / GPLv2
学习曲线 / 规模 中低 / 中到大、批量标准化 中 / 中到超大、异构 中 / 中到大、云原生 低 / 小到中

何时选 Checkmk:主机/服务数量大且标准化程度高,希望「一次规则、批量生效」与自动服务发现,减少逐项配置;不能维护关系库(无外部 DB);需要原生分布式站点与统一视图;预算允许可上商业版换 CMC 性能、Agent Bakery、DCD、SLA 报表;已有 Nagios 插件资产可复用。 何时不选:纯 K8s/Serverless 且指标维度爆炸(Prometheus + Grafana);需要 SNMP/JMX/IPMI 全家桶与超细阈值表达式、SLA 报表在开源版就要有(Zabbix);只需几十台的简单状态检查且不愿引入 OMD 站点概念(Nagios Core);团队要求配置全部纯手写文本且不依赖 Web(Zabbix/Nagios 更直接)。Raw 版规模大时 Nagios 核心是瓶颈,需评估商业版成本。

14. 参考链接

Checkmk —— 以「Agent 一次采集 + 规则集自动发现服务」为核心的高效一体化监控平台 - 知识库 - 起航社区