企业官网建设流程全解析

• 指标监控
• 可观测性
• 告警
• 运维

Zabbix 通过内置 Webhook 机制可以与 iTop（开源 IT 服务管理平台）对接，将触发器产生的告警自动转换为 iTop 工单（Ticket），并在问题恢复或更新时同步到工单的日志（Log）中，形成"监控告警 → 事件管理"的闭环。本文以仓库中 templates/media/itop/README.md 与 media_itop.yaml 为骨架，完整讲解 Webhook 的导入、参数配置、iTop 侧准备与 Zabbix 侧动作配置，并结合src/libs/zbxalerter、src/libs/zbxscripts的源码剖析 Webhook 在 Zabbix 内部的实际执行链路。读完本文，你将能独立完成 Zabbix 与 iTop 的告警工单集成，并具备排查发送失败问题的能力。

一、集成概览与前置要求

1.1 集成方案概述

该集成方案完全基于 Zabbix 的Webhook 媒体类型（Media Type）特性实现，不依赖任何外部插件或脚本服务。其工作模式为：

• Zabbix 触发告警动作（Action）时，将{ALERT.MESSAGE}、{ALERT.SUBJECT}、{EVENT.*}等宏展开后的内容作为 JSON 参数传入 Webhook 脚本；
• Webhook 脚本通过 iTop 的 REST API（webservices/rest.php，API 版本 1.3）调用core/create操作创建工单，或调用core/update操作向已存在工单的日志区（private_log/public_log）追加更新内容；
• 创建工单成功后，脚本通过结果标签（Tags）回传 iTop 工单 ID、友好名称（friendlyname）与跳转链接，使 Zabbix 前端可在问题事件菜单中直接打开对应 iTop 工单。

重要限制：恢复（Recovery）与更新（Update）操作仅支持触发器（Trigger）类型事件。这一限制不仅在 README 中声明，也在 Webhook 脚本中通过运行时校验强制执行（见下文"脚本工作原理"一节）。

1.2 版本要求

• Zabbix 版本：8.0 及以上。媒体类型导出文件 media_itop.yaml 头部声明zabbix_export: version: '8.0'，低于该版本的 Zabbix 无法正确导入。

二、Webhook 参数详解

导入 media_itop.yaml 后，媒体类型中包含两类参数：可配置参数（Configurable parameters）与内部参数（Internal parameters）。

2.1 可配置参数

可配置参数用于按实际环境调整 Webhook 行为，导入后需将占位符替换为真实值：

关于tls_verify的取值语义，可直接对照 media_itop.yaml 中脚本的CTlsConfig构造函数：脚本会将原始值trim().toLowerCase()后与['none', 'peer', 'full']比对，不在列表中的值一律回退为full；随后映射为两条底层选项——SSLVerifyPeer: (raw_value === 'peer' || raw_value === 'full')与SSLVerifyHost: (raw_value === 'full')。也就是说：

• none：不启用 TLS 校验，允许使用http://地址；
• peer：校验对端证书链及有效期，但不校验主机名；
• full：在peer基础上追加主机名校验。

同时脚本提供了checkURL()保护逻辑：当 TLS 校验启用（非none）而 URL 不是https://开头时，会直接抛出异常，提示改用 HTTPS 地址或将{$HTTP.TLS.VERIFY}设为none，避免证书校验形同虚设。

2.2 内部参数

内部参数保留给预定义宏使用，不建议修改：

从源码结构看，内部参数是脚本判断"创建 / 更新 / 恢复"分支的关键输入：脚本会检查event_source是否在 0–3 范围内，检查event_value（对 source 为 0 或 3 时）必须为 0 或 1，检查event_update_status（对 source 为 0 时）必须为 0 或 1，并强制"非触发器事件不允许恢复操作"（Recovery operations are supported only for trigger-based actions.）。

2.3 HTTP 代理支持

每个 Webhook 均支持 HTTP 代理。如需启用，在媒体类型参数中新增一个名为http_proxy的参数，将其值设为代理 URL 即可。脚本中Itop.setProxy(params.HTTPProxy)会把该值传给底层HttpRequest.setProxy()，之后所有请求都会经代理转发。

三、iTop 侧服务准备（Service setup）

在配置 Zabbix 之前，需要先在 iTop 中完成两项准备：

1. 创建 API 用户：创建具有"REST Services User"配置文件的用户（或复用现有用户），并确保该用户在目标工单模块中具备创建工单（ticket）的权限。

2. 获取组织 ID：进入数据管理（Data administration）> 目录（Catalog）> 组织（Organizations），打开目标组织的资料页，从浏览器地址栏 URL 中获取组织 ID。典型 URL 形如：

   <itop_url>/pages/UI.php?operation=details&class=Organization&id=1&c[menu]=Organization

   其中id=1即组织 ID，将其填入媒体类型的itop_organization_id参数。

四、Zabbix 配置步骤

4.1 导入媒体类型并填写参数

1. 进入管理（Administration）> 媒体类型（Media types），导入仓库中的 media_itop.yaml。
2. 打开新建的iTop媒体类型，将所有<PLACEHOLDERS>替换为实际值。以下参数为必填：
   • itop_url— iTop 实例的实际 URL；
   • itop_user— iTop 用户登录名；
   • itop_password— 用户密码；
   • itop_organization_id— 组织的 ID；
   • itop_class— 从 Zabbix 通知创建工单时使用的类名，例如UserRequest或Problem；
   • itop_log— 工单中用于记录 Zabbix 问题更新的日志区类型，必须为Private（private_log）或Public（public_log）；
   • itop_comment— 写入工单历史的注释。

导入后的媒体类型默认状态为DISABLED（已禁用）（见 media_itop.yaml 中status: DISABLED），完成参数配置后需记得启用。

4.2 创建 Zabbix 用户并添加媒体

创建（或复用）一个Zabbix 用户，在其媒体（Media）中添加iTop媒体类型。注意：

• 虽然 iTop Webhook 不使用"发送到（Send to）"字段，但该字段不能为空；为满足前端校验要求，可填入任意字符。
• 确保该用户对所有需要将问题通知转换为 iTop 工单的主机都具有访问权限（否则这些主机产生的告警不会触发发送）。

4.3 创建动作（Action）

在告警动作（Actions）中配置触发器动作，将 iTop 媒体类型加入通知收件人（即 4.2 创建的用户）。动作的"默认主题"与"默认消息"会分别映射为{ALERT.SUBJECT}与{ALERT.MESSAGE}，作为工单的标题（title）与描述（description）内容。

媒体类型自带针对各类事件源的消息模板（见 media_itop.yaml 的message_templates段），覆盖：触发器的问题/恢复/更新、发现（Discovery）、自动注册（Autoregistration）、内部事件（Internal）以及服务（Service）事件，导入后即可作为动作消息的默认内容使用。

五、Webhook 在 Zabbix 内部的执行链路（源码级解析）

5.1 从动作到脚本执行

Webhook 媒体类型在 Zabbix 内部被当作一种"脚本型"告警处理。从 src/libs/zbxalerter/alerter.c 的alerter_process_webhook()可以看出完整链路：

1. 告警数据经 IPC 消息传给 alerter 进程（对应zbx_alerter_deserialize_webhook()，序列化/反序列化实现在 src/libs/zbxalerter/alerter_protocol.c）；
2. 初始化嵌入式脚本引擎（zbx_es_init），并注入代理/来源 IP 等环境信息（zbx_es_init_env）；
3. 设置脚本执行超时（zbx_es_set_timeout），开启调试模式（可选）；
4. 调用zbx_es_execute()执行媒体类型携带的脚本，传入脚本二进制与 JSON 参数；
5. 执行结果（含调试信息）通过alerter_send_result()回传给告警处理流程。

可见 Webhook 脚本由 Zabbix 内置的嵌入式脚本引擎执行，而非系统 Shell。

5.2 参数打包：宏展开后如何传给脚本

媒体类型的参数在发送前会被收集并打包为 JSON 字符串。核心实现在 src/libs/zbxscripts/scripts.c 的zbx_webhook_params_pack_json()：该函数遍历"参数名-值"对，逐一写入 JSON 对象（zbx_json_addstring）。也就是说，动作配置中的{ALERT.MESSAGE}、{ALERT.SUBJECT}、{EVENT.SOURCE}等宏会先被展开为实际文本，再与媒体类型参数一起组成 JSON，作为脚本入口value传入。

脚本入口部分（media_itop.yaml 的script段）正是JSON.parse(value)取出全部参数：凡是键以itop_开头的参数会被剥离前缀后归入itop_params（供请求构造使用）；alert_subject、summary、event_recovery_value、event_source、event_value、action_name等关键参数若为空则直接抛出Parameter "..." can't be empty.。

5.3 脚本分支逻辑：创建 / 恢复 / 更新

脚本主体定义了一个Itop对象，其核心行为可归纳为三条分支（对应 iTop 工单生命周期）：

1. 创建工单（core/create）：发生在两类场景——非触发器事件首次上报，或触发器问题事件且尚无关联工单（itop_id仍为未替换的{EVENT.TAGS.__zbx_itop_id}字面值）时。setCreatePayload()会将alert_subject作为工单标题（title）、alert_message作为描述（description），并对描述做 HTML 转义（<→<、>→>）及换行转换（\r\n|\r|\n→<br>）。创建成功后，脚本通过result.tags.__zbx_itop_id、result.tags.__zbx_itop_key、result.tags.__zbx_itop_link三个标签回传工单 ID、友好名称与详情页链接。
2. 更新工单（core/update）：当问题已关联工单（itop_id已替换为真实 ID）时，setUpdatePayload()使用add_item向private_log或public_log日志区追加一条文本消息（内容为主题 + 换行 + 消息体），实现"问题更新同步到工单日志"。
3. 恢复（Recovery）：恢复事件时同样走core/update分支，向工单日志追加恢复信息。

5.4 请求构造与错误处理

• 认证：脚本使用 HTTP Basic 认证，Authorization: Basic <base64(user:password)>，并设置Content-Type: multipart/form-data；
• URL 拼接：itop_url末尾若不以/结尾则自动补全，随后追加webservices/rest.php?version=<api_version>，最终请求为POST <url>&json_data=<JSON 载荷>；
• 响应校验：脚本解析 iTop 返回的 JSON，依次检查：HTTP 状态码必须落在 200–299；iTop 业务码code必须为 0；否则抛出带状态码 / iTop code / message 的错误，并提示查阅调试日志（Zabbix.log(4, ...)记录请求与响应全文）；
• 调试：媒体类型开启"调试（debug）"模式时，请求 URL 与响应内容会以日志级别 4 记录（脚本中以[ iTop Webhook ]为前缀），错误信息以级别 3 记录，这是排查工单创建失败最直接的线索。

5.5 事件菜单与工单跳转

媒体类型还启用了两项与问题事件菜单相关的能力（见 media_itop.yaml 尾部）：

• process_tags: 'YES'：允许脚本向事件写入标签（__zbx_itop_id、__zbx_itop_key、__zbx_itop_link）；
• show_event_menu: 'YES'+event_menu_url/event_menu_name：在 Zabbix 前端的告警事件菜单中增加一条"iTop: {EVENT.TAGS.__zbx_itop_key}"菜单项，点击即可跳转到对应的 iTop 工单详情页。

从源码结构可以推断，创建工单时写入的__zbx_itop_id标签会持久化到事件上，后续更新/恢复事件即可通过{EVENT.TAGS.__zbx_itop_id}定位到同一工单，形成闭环。

六、常见问题与排错建议

• 工单创建失败，报"Request failed with iTop code ..."：多为认证信息错误（itop_user/itop_password）、组织 ID 不正确或 API 用户权限不足，可在媒体类型上开启调试后查看[ iTop Webhook ]前缀的日志。
• 报"Failed to parse response received from iTop"：iTop 返回了非 JSON 内容，通常是 URL 配置错误（如缺少webservices路径前缀）或代理干预。
• 报"TLS certificate verification is enabled ... but the URL uses plain HTTP"：tls_verify未设为none而itop_url使用了http://，按脚本的checkURL()逻辑会直接拒绝执行。
• 报"Recovery operations are supported only for trigger-based actions"：恢复操作只支持触发器动作，请勿为发现/自动注册/内部/服务事件配置恢复动作。
• 报"Incorrect iTop ticket ID given"：itop_id未替换为有效工单 ID（仍为宏字面值或为空），即事件标签中不存在__zbx_itop_id，无法执行更新/恢复。
• 告警未发出：请检查媒体类型是否已启用（导入后默认为 DISABLED）、动作收件用户是否对相关主机有访问权限，以及用户媒体中的"发送到"字段是否非空。

七、延伸阅读

• Webhook 执行引擎与告警处理：src/libs/zbxalerter/alerter.c
• Webhook 参数打包为 JSON：src/libs/zbxscripts/scripts.c
• Webhook IPC 序列化协议：src/libs/zbxalerter/alerter_protocol.c
• 完整媒体类型定义（含脚本源码与全部消息模板）：templates/media/itop/media_itop.yaml

若在使用该媒体类型时发现问题，可向 Zabbix 官方支持系统提交工单，或在 Zabbix 官方论坛的 Suggestions and Feedback 版块反馈讨论。

• 指标监控
• 可观测性
• 告警
• 运维