Keep 集成 CheckmkDocker 部署、Webhook 告警接入与字段映射全解析【免费下载链接】keepThe open-source AIOps and alert management platform项目地址: https://gitcode.com/GitHub_Trending/kee/keepCheckmk 是一款面向基础设施与应用监控的开源监控平台Keep 作为开源 AIOps 与告警管理平台通过 Webhook 方式将 Checkmk 的告警统一汇入 Keep实现告警的集中管理、去重、关联与工作流自动化。本文以仓库中的 Checkmk 集成文档为主线完整还原从 Checkmk 部署、Webhook 脚本安装、通知规则配置到 Keep 侧告警解析与后续使用的全链路实战方案。集成架构Checkmk 通知如何进入 KeepKeep 与 Checkmk 的集成采用「Checkmk 自定义通知脚本 Keep Webhook API」的推模式架构核心链路如下Checkmk 的监控引擎在主机或服务状态发生变化时触发通知Checkmk 服务器上安装的webhook-keep.py通知脚本被调用将 Checkmk 注入的环境变量NOTIFY_*系列整理为结构化 JSON脚本以 HTTP POST 请求将 JSON 发送到 Keep 的告警 Webhook 端点/alerts/event/checkmk并在请求头携带 Keep API KeyKeep 侧由CheckmkProvidercheckmk_provider.py将原始负载标准化为 Keep 的统一告警模型AlertDto进入告警队列。由于走的是 Webhook 推送而非轮询拉取Checkmk Provider 无需额外的连接凭据校验其validate_config在源码中即为空实现见 checkmk_provider.py配置成本极低。第一步使用 Docker 部署 Checkmk集成的前提是先有一套可用的 Checkmk 环境。仓库中的 README.md 给出了基于官方 Docker 镜像的完整部署步骤。1. 拉取镜像docker pull checkmk/check-mk-cloud:2.3.0p19该命令拉取 Checkmk Cloud Edition 2.3.0p19 镜像。若使用 Checkmk Raw Edition开源版可按同样的方式替换为checkmk/check-mk-raw系列镜像。2. 启动容器docker container run -dit \ -p 8080:5000 \ -p 8000:8000 \ --tmpfs /opt/omd/sites/cmk/tmp:uid1000,gid1000 \ -v monitoring:/omd/sites \ --name monitoring \ -v /etc/localtime:/etc/localtime:ro \ --restart always \ checkmk/check-mk-cloud:2.3.0p19各参数的作用说明如下参数说明-p 8080:5000将容器内 Checkmk Web GUI 的 5000 端口映射到宿主机 8080用于浏览器访问-p 8000:8000将容器内用于 Agent 注册Agent Registration API的 8000 端口暴露出来--tmpfs /opt/omd/sites/cmk/tmp:uid1000,gid1000将 OMD 站点的临时目录挂载为内存文件系统以正确的 uid/gid 运行提升 IO 性能并避免写入持久层-v monitoring:/omd/sites创建名为monitoring的 Docker volume 持久化整个站点数据配置、监控数据、日志容器重建后数据不丢失-v /etc/localtime:/etc/localtime:ro以只读方式挂载宿主机时区文件保证 Checkmk 与宿主机时区一致--restart always容器异常退出或宿主机重启后自动拉起--name monitoring为容器命名后续日志查看、管理均使用该名称3. 访问 Web 界面容器启动完成后通过浏览器访问http://localhost:8080/即可进入 Checkmk Web 界面。4. 获取初始登录凭据Checkmk 首次启动会在日志中打印自动生成的站点管理员账号与密码执行以下命令查看docker container logs monitoring日志中会包含类似Created user cmkadmin with password: xxxxxxxx的信息请妥善保存该凭据用于后续登录。第二步在 Checkmk 服务器安装 Keep Webhook 脚本Keep 官方为 Checkmk 提供了一份现成的通知脚本webhook-keep.py位于 webhook-keep.py。它的职责是读取 Checkmk 通知上下文并转发给 Keep必须被部署到 Checkmk 服务器或容器上才能生效。下载脚本wget -O webhook-keep.py 仓库中 keep/providers/checkmk_provider/webhook-keep.py 的下载地址部署方式因 Checkmk 的安装形态而异Docker 容器部署将脚本复制到站点本地的 notifications 目录路径需与上文的 volume 映射对应cp webhook-keep.py /omd/sites/site_name/local/share/check_mk/notifications/webhook-keep.py cd /omd/sites/site_name/local/share/check_mk/notifications直接安装在服务器上cp webhook-keep.py ~/local/share/check_mk/notifications/webhook-keep.py cd ~/local/share/check_mk/notifications赋予执行权限Checkmk 的通知插件以外部命令方式调用必须具有可执行权限chmod x webhook-keep.py完成以上步骤后Checkmk 便能识别名为webhook-keep的通知方法。第三步在 Checkmk WebUI 配置通知规则登录 Checkmk Web 界面后按以下路径创建将告警转发给 Keep 的通知规则。1. 进入 Setup 配置区在主界面左侧导航栏找到并点击Setup进入 Checkmk 的集中配置区。2. 打开 Notifications 通知配置在 Setup 左侧菜单中展开Events分类并点击Notifications进入通知规则管理页面。3. 新建通知规则在 Notification configuration 页面点击Add rule创建一个新的通知规则。4. 选择通知方法与填写参数在新建规则的Notification method区域下拉框中选择Webhook - KeepHQ并选择 Call with the following parameters: 方式传入参数随后配置以下两个参数第一个参数Keep Webhook URLKeep 的告警 Webhook 地址指向 Keep 的 Checkmk 事件端点。使用 Keep Cloud 时为https://api.keephq.dev/alerts/event/checkmk自托管部署时替换为你自己的 Keep API 地址例如http://keep-host:port/alerts/event/checkmk。该值会作为环境变量NOTIFY_PARAMETER_1注入通知脚本。第二个参数Keep API Key在 Keep 的设置页面Settings → Users → API Keys中生成的 API Key用于认证请求会作为环境变量NOTIFY_PARAMETER_2注入通知脚本。5. 配置规则属性并保存根据实际告警策略配置Rule properties规则名称、匹配范围、Contact selections哪些联系人触发该通知与Conditions如主机/服务过滤条件、状态阈值等。完成后点击Save保存。之后只要被监控的主机或服务满足规则条件Checkmk 便会调用webhook-keep.py将告警推送到 Keep。第四步深入 webhook-keep.py 的实现细节要理解告警负载的内容与行为需要读懂 webhook-keep.py 的三个关键环节。1. 从环境变量读取插件参数Checkmk 通知插件的自定义参数通过环境变量注入。脚本通过GetPluginParams()读取WebHookURL str(env_vars.get(NOTIFY_PARAMETER_1)) API_KEY str(env_vars.get(NOTIFY_PARAMETER_2))若两者缺失值为字符串None脚本会打印keep-plugin: Missing Webhook URL or API Key并返回退出码2Checkmk 文档约定的失败返回码确保通知可被追溯。2. 收集 Checkmk 通知上下文Checkmk 将本次通知的完整上下文注入到NOTIFY_*环境变量中脚本通过GetNotificationDetails()逐项读取主要分组如下通用信息OMD_SITE站点名、NOTIFY_WHATHOST / SERVICE、NOTIFY_NOTIFICATIONTYPE通知类型、NOTIFY_CONTACTNAME/NOTIFY_CONTACTEMAIL/NOTIFY_CONTACTPAGER联系人、NOTIFY_DATE/NOTIFY_LONGDATETIME/NOTIFY_SHORTDATETIME/NOTIFY_MICROTIME时间戳支持微秒精度主机相关NOTIFY_HOSTNAME、NOTIFY_HOSTALIAS、NOTIFY_HOSTADDRESS、NOTIFY_HOSTPROBLEMID、NOTIFY_HOSTOUTPUT、NOTIFY_HOSTSTATE、NOTIFY_LONGHOSTOUTPUT、NOTIFY_HOSTURL、NOTIFY_HOSTCHECKCOMMAND、NOTIFY_LASTHOSTSHORTSTATE服务相关NOTIFY_SERVICEDESC、NOTIFY_SERVICEPROBLEMID、NOTIFY_SERVICEOUTPUT、NOTIFY_LONGSERVICEOUTPUT、NOTIFY_SERVICEURL、NOTIFY_SERVICECHECKCOMMAND、NOTIFY_SERVICEPERFDATA性能数据、NOTIFY_SERVICESTATE、NOTIFY_LASTSERVICESTATE。脚本将这些变量分别组装为host_notify与service_notify两个结构summary字段由模板拼装例如主机告警为CheckMK {HOSTNAME} - {旧状态} - {新状态}服务告警为CheckMK {HOSTNAME}/{SERVICE} {旧状态} - {新状态}。3. 通知类型到状态语义的映射脚本根据NOTIFY_NOTIFICATIONTYPE将通知映射为 Keep 可识别的状态值NOTIFICATIONTYPE映射 status语义RECOVERYUP告警恢复PROBLEMDOWN产生问题ACKNOWLEDGEMENTACKNOWLEDGED人工确认其他FLAPPINGSTART、DOWNTIMESTART 等DOWN默认按问题处理4. 发送到 KeepStartKeepWorkflow()使用requests以 JSON 格式 POST 到 Webhook URL并在请求头携带认证信息headers { Content-Type: application/json, Accept: application/json, X-API-KEY: API_KEY, } response requests.post(WebHookURL, headersheaders, jsondata)返回 200 表示 Keep 成功接收其他状态码或网络异常时返回码为2Checkmk 端可据此追溯失败的通知。第五步Keep 侧 CheckmkProvider 的告警解析告警到达 Keep 后由 checkmk_provider.py 中的_format_alert完成从原始 JSON 到AlertDto的标准化转换。该 Provider 继承了BaseProvider见 base_provider.py的format_alert处理链负责 Webhook 负载的解析、指纹计算与自定义去重规则的应用。严重度与状态映射源码中定义了两张映射表SEVERITIES_MAP { OK: AlertSeverity.INFO, WARN: AlertSeverity.WARNING, CRIT: AlertSeverity.CRITICAL, UNKNOWN: AlertSeverity.INFO, } STATUS_MAP { UP: AlertStatus.RESOLVED, DOWN: AlertStatus.FIRING, ACKNOWLEDGED: AlertStatus.ACKNOWLEDGED, UNREACH: AlertStatus.FIRING, }即 Checkmk 的CRIT对应 Keep 的CRITICAL、WARN对应WARNING、OK/UNKNOWN归为INFO主机状态UP视为已恢复RESOLVEDDOWN/UNREACH视为触发中FIRING。主机告警与服务告警的差异化处理由于主机告警与服务告警的字段集不同_format_alert内部做了区分服务告警没有独立的 status 字段因此_set_severity会依据状态推导严重度——DOWN与UNREACH直接映射为CRITICALUP映射为INFO。时间戳的兼容性处理Checkmk 的通知时间可能存在多种格式Provider 提供了两层解析优先使用micro_time微秒时间戳除以 1000000 转为秒后由datetime.fromtimestamp转换无micro_time时调用convert_to_utc_isoformat见 checkmk_provider.py依次尝试三种strptime格式涵盖带时区名称如CEST、带时区偏移如0700以及偏移被空格拆开如07 00的场景并统一转换为 UTC 的 ISO 8601 格式全部失败则回退到short_date_time。字段映射清单转换后的AlertDto完整保留 Checkmk 的原始语义关键字段映射如下AlertDto 字段来源webhook JSON 字段含义ididHOST/SERVICEPROBLEMID告警唯一标识同时用作指纹字段namecheck_command触发告警的检查命令descriptionsummary告警摘要host/alias/addresshost/alias/address主机名、别名、IPserviceservice服务描述服务告警severity/statusseverity/status经映射表转换output/long_outputoutput/long_output检查输出与详细输出perf_dataperf_data服务性能数据path_urlurlCheckmk 中的详情页链接source固定[checkmk]来源标记lastReceivedmicro_time或long_date_time标准化后的接收时间仓库中的 alerts_mock.py 提供了一份真实格式的示例负载主机server1从DOWN - UP的恢复通知可作为调试与理解字段结构的参考。告警进入 Keep 之后去重、关联与工作流Checkmk 告警被标准化为AlertDto后即可复用 Keep 的完整告警治理能力。指纹与去重CheckmkProvider声明FINGERPRINT_FIELDS [id]即以 Checkmk 的 Problem ID 作为告警指纹重复推送的同一问题会自动去重合并同时可在 Keep 中配置自定义去重规则覆盖该默认行为去重规则的实现入口见 base_provider.py。告警关联Checkmk 告警带有source checkmk标记可直接用于关联规则。仓库测试 test_incidents.py 即演示了通过definition_celsource checkmk将所有 Checkmk 告警归入同一关联规则进而自动聚合为事件的场景。工作流编排需要注意的是按 checkmk-snippet-autogenerated.mdx 的说明该 Provider 当前仅作为告警入口使用不能作为工作流中的 step/action 被调用但所有进入 Keep 的 Checkmk 告警都可以作为触发器驱动工作流例如路由通知、创建工单、执行自动化处置等。自托管部署时的适配要点若使用自托管 Keep请将通知规则中的第一个参数替换为自身 API 地址/alerts/event/checkmk并确认网络可达检查 Keep 的 API Key 权限与有效期Key 失效后 Checkmk 侧会收到非 200 响应脚本会打印状态码与响应体便于排查在 Checkmk 侧可通过通知历史记录与脚本输出的keep-plugin:前缀日志定位问题缺少参数、网络错误、非 200 响应均有明确的错误信息与退出码2。完整的官方配置说明可进一步参考 checkmk-provider.mdxProvider 实现细节则以 checkmk_provider.py 与 webhook-keep.py 为准。按上述步骤完成部署与配置后Checkmk 的每一次主机/服务状态变化都会实时、结构化地进入 Keep与其余监控源的告警统一治理。【免费下载链接】keepThe open-source AIOps and alert management platform项目地址: https://gitcode.com/GitHub_Trending/kee/keep创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考