Zabbix 6 配置飞书告警

2026-07-27 · monitoring · 4 次阅读

本文说明在 Zabbix 6.0（Kubernetes 部署）中，通过 UI + Webhook Media type 将告警推送到飞书群机器人，并在消息中附带主机所属的 全部 Host group，以及触发相关的 监控项当前值。

1. 前提条件

项	说明
Zabbix 版本	6.0（如 `zabbix/zabbix-server-pgsql:ubuntu-6.0-latest`）
Web 访问	可登录 Zabbix 前端，具备管理员权限
飞书	已创建群自定义机器人，拿到 Webhook 地址
出网	`zabbix-server` 能访问 `https://open.feishu.cn`
Host group	需列出主机全部所属组（内置宏只能取第一个，需配合 API）

飞书 Webhook 格式示例：

https://open.feishu.cn/open-apis/bot/v2/hook/<你的token>

2. 整体思路

创建 API Token，供 Webhook 脚本调用 host.get 查询主机全部 Host group。
创建 Media type（类型 Webhook），脚本向飞书 POST 文本消息，并追加 Host group: ...。
给用户绑定该媒介，配置 Action 在故障/恢复时发送通知。
用 Media type 的 Test 或真实触发验证。

说明：Zabbix 宏 {TRIGGER.HOSTGROUP.NAME} 在主机属于多个组时只返回按字母序的第一个组，因此要用 API 拉取全部组名。

3. 验证飞书 Webhook（可选）

在能访问外网的机器上执行（会向群内发 1 条测试消息）：

curl --max-time 10 --silent --show-error \
  --request POST 'https://open.feishu.cn/open-apis/bot/v2/hook/<你的token>' \
  --header 'Content-Type: application/json' \
  --data '{"msg_type":"text","content":{"text":"Zabbix连通性测试：飞书Webhook正常"}}'

成功响应示例：

{"StatusCode":0,"StatusMessage":"success","code":0,"data":{},"msg":"success"}

4. 创建 API Token

登录 Zabbix Web。
右上角头像 → API tokens → Create API token。
建议配置：
- Name：feishu-hostgroup
- User：具备主机只读权限的管理员（如 Admin）
- 过期时间按需设置
创建后立即复制 Token（只显示一次），后续填入 Media type，不要提交到代码仓库或公开聊天。

5. 创建 Media type：Feishu

路径：Administration → Media types → Create media type

5.1 基本信息

字段	值
Name	`Feishu`
Type	`Webhook`
Enabled	勾选
Timeout	`10s`
Process tags	可不勾选

5.2 Parameters

Name	Value	说明
`webhook_url`	飞书 Webhook 完整 URL	实际投递地址
`zabbix_url`	`http://zabbix-zabbix-web.zabbix.svc`	集群内 Web Service，供 server Pod 调 API（按实际 Service 名调整）
`api_token`	上一步创建的 API Token	查询 Host group
`hostid`	`{HOST.ID}`	当前告警主机 ID
`alert_subject`	`{ALERT.SUBJECT}`	来自 Message template / Action
`alert_message`	`{ALERT.MESSAGE}`	来自 Message template / Action

不需要增加 To / {ALERT.SENDTO}：本脚本不使用该参数；飞书目标已由 webhook_url 固定。
给用户绑定媒介时，Send to 可填占位符（如 - 或 feishu）。

若 Zabbix 不在 Kubernetes，或 server 无法解析集群 DNS，可将 zabbix_url 改为前端可达地址，例如 https://zabbix.example.com（需保证 server 能访问该地址的 /api_jsonrpc.php）。

5.3 Script

将以下脚本完整粘贴到 Script 框：

var params = JSON.parse(value),
    req = new HttpRequest(),
    response,
    data,
    groups = [],
    text,
    i,
    result = { tags: {} };

if (!params.webhook_url) {
    throw 'parameter webhook_url is missing';
}

if (params.zabbix_url && params.api_token && params.hostid) {
    req.addHeader('Content-Type: application/json-rpc');
    response = req.post(
        params.zabbix_url.replace(/\/$/, '') + '/api_jsonrpc.php',
        JSON.stringify({
            jsonrpc: '2.0',
            method: 'host.get',
            params: {
                hostids: [params.hostid],
                selectGroups: ['name'],
                output: ['hostid']
            },
            auth: params.api_token,
            id: 1
        })
    );
    data = JSON.parse(response);
    if (data.error) {
        throw 'Zabbix API error: ' + JSON.stringify(data.error);
    }
    if (data.result && data.result[0] && data.result[0].groups) {
        for (i = 0; i < data.result[0].groups.length; i++) {
            groups.push(data.result[0].groups[i].name);
        }
    }
}

text = String(params.alert_subject || '') + '\n'
    + String(params.alert_message || '') + '\n'
    + 'Host group: ' + (groups.length ? groups.join(', ') : 'N/A');

req = new HttpRequest();
req.addHeader('Content-Type: application/json');
response = req.post(params.webhook_url, JSON.stringify({
    msg_type: 'text',
    content: { text: text }
}));
data = JSON.parse(response);

if (data.StatusCode !== 0 && data.code !== 0) {
    throw 'Feishu error: ' + response;
}

return JSON.stringify(result);

说明：

Zabbix 6.0 使用 selectGroups；若升级到 6.2+ 且报错，可改为 selectHostGroups。
脚本末尾自动追加一行 Host group: 组1, 组2, ...。

5.4 Message templates

路径：同一 Media type 页签 Message templates。

Zabbix 界面中没有名为 Resolved 的类型；恢复通知对应的是 Problem recovery。

通过 {ITEM.NAME1} / {ITEM.VALUE1} 输出触发器表达式中第 1 个监控项的名称与当前值（例如 CPU 利用率数值）。多条件触发器可继续加 {ITEM.NAME2} / {ITEM.VALUE2} 等。

Problem（故障）

Subject：[故障] {TRIGGER.SEVERITY}: {HOST.NAME}
Message：

主机: {HOST.NAME}
IP: {HOST.IP}
严重性: {TRIGGER.SEVERITY}
告警: {TRIGGER.NAME}
当前值: {ITEM.NAME1} = {ITEM.VALUE1}
时间: {EVENT.DATE} {EVENT.TIME}
事件ID: {EVENT.ID}

Problem recovery（恢复）

Subject：[恢复] {TRIGGER.SEVERITY}: {HOST.NAME}
Message：

主机: {HOST.NAME}
IP: {HOST.IP}
严重性: {TRIGGER.SEVERITY}
告警: {TRIGGER.NAME}
当前值: {ITEM.NAME1} = {ITEM.VALUE1}
恢复时间: {EVENT.RECOVERY.DATE} {EVENT.RECOVERY.TIME}
事件ID: {EVENT.ID}

飞书消息示例：

[故障] Warning: 10.10.10.242
主机: 10.10.10.242
IP: 10.10.10.242
严重性: Warning
告警: Linux: High CPU utilization
当前值: CPU utilization = 92.35 %
时间: 2026.07.27 07:20:09
事件ID: 38536
Host group: Linux servers, Discovered hosts, hu_srv

Host group 由脚本追加，模板中不必再写。

常用相关宏

宏	含义
`{ITEM.NAME1}`	触发器表达式中第 1 个监控项名称
`{ITEM.VALUE1}`	该监控项当前值（告警时最有用）
`{ITEM.LASTVALUE1}`	最近一次采集值
`{ITEM.NAME2}` / `{ITEM.VALUE2}`	第 2 个监控项（多条件触发器用）
`{EVENT.OPDATA}`	触发器上配置的 Operational data；若官方模板已写好，可改用 `详情: {EVENT.OPDATA}`

基础告警只需 Problem 与 Problem recovery；Problem update、Discovery 等可按需再加。

保存 Media type（Add / Update）。注意：Media type Test 往往不会展开真实 Item 值，以真实告警为准。

6. 测试 Media type

Administration → Media types → Feishu → Test。
hostid 填真实主机 ID：在 Configuration → Hosts 打开某主机，URL 中 hostid= 后的数字。
执行测试：飞书群应收到含 Host group: ... 的消息；失败则根据报错排查（见下文）。

7. 给用户绑定媒介

Administration → Users → 选择接收告警的用户（或专用告警账号）。
Media → Add：
- Type：Feishu
- Send to：填 - 或 feishu（占位即可）
- When active：按需（如 1-7,00:00-24:00）
- Use if severity：勾选需要的级别
- Enabled：勾选
保存用户。

8. 配置 Action

路径：Configuration → Actions → Trigger actions → Create action（或改现有动作）。

建议要点：

Conditions：按环境限制（主机群组、标签、严重性等），避免全量风暴。
Operations（故障时）：
- Send to users / groups：选已绑定 Feishu 的用户
- Only to：Feishu（或 Default 且用户仅有 Feishu）
Recovery operations：同样发送到 Feishu，以便恢复通知进群。
启用 Action 并保存。

若已有通用告警 Action，只需确保其 Operations 会发到绑定了 Feishu 的用户即可。

9. 常见问题

现象	可能原因	处理
Test 失败：Feishu error	Webhook 错误、机器人被移出群、网络不通	用第 3 节 curl 从 zabbix-server Pod 再测
Zabbix API error	Token 无效/过期、权限不足、`zabbix_url` 不可达	检查 Token；从 server 容器访问 `{zabbix_url}/api_jsonrpc.php`
`Host group: N/A`	Parameters 缺少 `api_token` / `zabbix_url` / `hostid`（缺任一则跳过 API）；或 Token/`zabbix_url` 不可用	核对三参数；用本机 `curl` 调 `{zabbix_url}/api_jsonrpc.php` 的 `host.get`（`selectGroups`）验证
只有一个组	误用 `{TRIGGER.HOSTGROUP.NAME}` 且未跑 API 逻辑	确认脚本与 `api_token`/`zabbix_url`/`hostid` 参数完整
告警无当前值	Message template 未加 `{ITEM.VALUE1}`；或 Test 未展开宏	按 5.4 更新模板；用真实触发验证
有告警无飞书	用户未绑媒介、Action 未含该用户、严重性未勾选	查 Reports → Action log / Administration → Queue

说明：官方 zabbix-server 镜像通常不含 curl，连通性建议在 节点本机 或能访问 ClusterIP/Ingress 的机器上测。

本机验证 API / Host group 示例（将 Token、Service IP、主机名按实际替换）：

TOKEN='<你的API_Token>' && curl --max-time 10 --silent --show-error \
  --request POST 'http://<zabbix-web-ClusterIP>/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data "{\"jsonrpc\":\"2.0\",\"method\":\"host.get\",\"params\":{\"output\":[\"hostid\",\"name\"],\"selectGroups\":[\"name\"],\"filter\":{\"host\":[\"10.80.238.242\"]}},\"auth\":\"${TOKEN}\",\"id\":1}"

本机验证飞书 Webhook：

curl --max-time 10 --silent --show-error \
  --request POST 'https://open.feishu.cn/open-apis/bot/v2/hook/<你的token>' \
  --header 'Content-Type: application/json' \
  --data '{"msg_type":"text","content":{"text":"从节点测试飞书"}}'

10. 安全建议

Webhook URL、API Token 视为密钥，勿写入公开仓库。
API Token 使用最小权限账号，定期轮换。
飞书机器人仅拉进必要群；泄露后立即在飞书侧重置 Webhook。
生产建议对 Action 加条件，避免测试告警刷屏。

11. 配置检查清单

飞书 Webhook curl 返回 success
已创建 API Token 并写入 Media type
Media type Feishu 已启用，Timeout ≤ 10s
Parameters 含 webhook_url / zabbix_url / api_token / hostid / alert_subject / alert_message
Message templates 已配置 Problem 与 Problem recovery（含 {ITEM.NAME1} / {ITEM.VALUE1}）
Media type Test 成功且消息含全部 Host group
真实告警中可见 当前值: ... = ...
用户已绑定 Feishu 媒介
Trigger Action 的 Operations / Recovery operations 已指向该用户

文档对应环境示例：Zabbix 6.0 on Kubernetes，前端 Ingress 形如 https://zabbix.example.com/，命名空间 zabbix，Web Service 名 zabbix-zabbix-web。按实际名称替换即可。

igozhang