Checkmk —— 以「Agent 一次采集 + 规则集自动发现服务」为核心的高效一体化监控平台
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 / 通知规则 / 分布式
链路要点:
- Agent 采集:
check_mk_agent监听 6556(由 xinetd/systemd 或 Agent Controller 提供),输出以<<<section>>>分段的纯文本;本地检查走<<<local>>>、插件放/usr/lib/check_mk_agent/plugins/;2.1+ 可用 Agent Controller 经 8000/TCP 做 TLS 注册与推送。 - Check 解析:站点 fetcher 取回数据,各 Check plugin 认领自己的 section,解析成「服务名 + 指标 + 状态」的候选服务。
- Service 发现:
cmk -I <host>或 Setup 里的 Service discovery 把候选服务写入配置(Discovered services),并生成Check_MK Discovery服务监控「未发现/消失的服务」。 - Rule 套用:阈值与开关不写在主机上,而由规则集按 Folder / Host tag / Label / 显式主机 / 服务名匹配,首条命中生效;改规则后需 Activate changes(
cmk -O生成核心配置 +cmk -R重载)。 - 状态与通知:核心计算 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)包,按发行版代号选;建议 2 |
| 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 官网:https://checkmk.com/
- 官方下载(按版本/发行版选包):https://checkmk.com/download
- 官方在线文档(含 REST API 与升级指南):https://docs.checkmk.com/
- GitHub 仓库(Community,GPLv2):https://github.com/Checkmk/checkmk
- 官方包下载站:https://download.checkmk.com/
- Checkmk Exchange(插件/MKP 市场):https://exchange.checkmk.com/