r-t-chan/keycloak-zabbix-monitoring

# 通过 Prometheus/OpenMetrics 使用 Zabbix 监控 Keycloak Zabbix 模板和告警路由，用于通过 Prometheus/OpenMetrics 端点监控 Keycloak 部署 —— 涵盖 container/JVM 健康、身份验证失败和服务间错误，并将告警发送至 Google Chat。 ## 为什么选择 Zabbix 来处理 Prometheus 指标？ 我们已经使用 Zabbix 进行基础设施监控。与其仅仅为了 Keycloak 单独搭建一套 Prometheus + Alertmanager 技术栈，不如利用 Zabbix 原生的 **Prometheus check** 预处理功能，让一个 HTTP item 抓取指标端点并为 dependent item 提供数据 —— 从而将身份监控与其他所有监控保留在同一位置，并使用相同的告警路由。 ## 工作原理 ``` flowchart LR kc["Keycloak\n/metrics endpoint"] master["Zabbix HTTP agent item\n(master — scrapes every 1m)"] dep["Dependent items\nPrometheus pattern preprocessing"] trig["Triggers\n(failed logins, error rates,\nendpoint availability)"] gchat["Google Chat space\n(webhook media type)"] kc --> master --> dep --> trig --> gchat ``` 1. 一个 **HTTP agent master item** 每分钟抓取一次完整的指标输出。 2. **Dependent item** 使用 Zabbix 的 Prometheus pattern 预处理提取各个序列 —— 无需对 Keycloak 发起额外请求。 3. **Triggers** 会在真正关键的情况发生时触发：登录失败激增、服务间错误率上升以及指标端点失效。 4. 一个 **webhook media type** 将告警发布到 Google Chat 空间中。 ## 告警内容 | 信号 | 重要性 | |--------|----------------| | 登录失败激增（按 realm） | 凭证填充 / 暴力破解尝试会首先在这里体现出来 | | 服务间身份验证错误 | 客户端密钥轮换或配置错误会悄无声息地破坏机器身份验证 —— 用户不会报告此问题 | | 认证端点上的 HTTP 5xx 比率 | Keycloak 性能下降会导致每个下游服务的登录功能随之一同失效 | | 指标端点无法访问 | 监控系统本身也是一个值得监控的依赖项 | JVM 堆作为原始字节数据收集，用于容量趋势分析；百分比阈值 trigger 需要 max-heap 序列，该序列因 Keycloak 版本而异，因此请添加一个以匹配您的部署环境。 ## 文件 - [`zabbix/template_keycloak_metrics.yaml`](zabbix/template_keycloak_metrics.yaml) — 可导入模板：master 抓取 item、dependent item、triggers - [`zabbix/media_google_chat_webhook.js`](zabbix/media_google_chat_webhook.js) — 用于 Google Chat 的 webhook media type 脚本 ## 适配您的 Keycloak 版本 - **Keycloak (Quarkus，现代版本)**：使用 `KC_METRICS_ENABLED=true` 启用指标；您将获得 `http_server_requests_seconds_*`、JVM 指标以及（在较新版本中）用户事件指标。 - **带有 aerogear metrics SPI 的旧版 Keycloak (WildFly)**：公开带有 realm/provider 标签的 `keycloak_failed_login_attempts`、`keycloak_logins`、`keycloak_response_errors` —— 模板中的示例 item 使用了这些名称。 无论哪种方式，模式都是相同的：调整 dependent item 中的 Prometheus patterns，以匹配您的部署所公开的序列。运行 `curl -s https:///metrics | grep -i login` 以查看您拥有的指标。 ## 设置 1. 将模板 YAML 导入 Zabbix (6.0+)。 2. 将其链接到运行 Keycloak 的主机；设置 `{$KEYCLOAK.METRICS.URL}` 宏。 3. 创建一个 Google Chat 空间 webhook，并添加带有该 webhook URL 的 media type 脚本。 4. 根据您的基准调整 trigger 阈值 —— 默认值是刻意设置的保守起始点。

标签：Google Chat, Keycloak, Zabbix, 告警通知, 数据可视化, 自定义脚本, 运维监控