1. 先说清楚hualinxu ext zbx 1.4 到底解决什么问题监控系统里Zabbix 的配置流程始终是让新人最头疼的部分。hualinxu ext zbx 1.4 是一套我在实际监控工作中维护的 Zabbix 扩展包它把常用的监控模板、外部检查脚本、自动发现规则和告警收敛策略打包到了一起省掉了大量重复劳动。但这套东西能不能真正跑起来关键不在脚本本身而在配置流程是否规范。这篇文章就把我从零开始配置这套扩展的完整流程讲清楚包括每一步为什么要这么做的理由以及文档里通常不会写的那些坑。如果你手头的工作是给一套已有或新建的 Zabbix 环境做监控上线或者你刚接手一个团队留下的 Zabbix正看着一堆模板和脚本不知道怎么串起来那这篇内容正好对口。我尽量按实际操作顺序来写而不是按功能模块堆文档这样你跟着走一遍基本就能把环境理顺。1.1 这个扩展包在监控链路里的位置在讲配置流程之前先得搞清楚 hualinxu ext zbx 1.4 在 Zabbix 体系里到底属于哪一层。Zabbix 的数据链路大致是Agent 或外部脚本采集数据通过主动或被动方式送到 ServerServer 写入数据库前端从数据库读出来展示同时触发器引擎判断指标是否异常异常则通过动作发告警。这套扩展包做的事是把链路中间采集什么样的数据、怎么判断异常、怎么收敛告警这部分预先写好做成可以直接复用的模板和脚本。具体来说我维护的这个版本里主要包含四类东西预置模板覆盖常见服务的基础监控项比如 MySQL 的连接数、慢查询、主从状态Nginx 的活跃连接数Redis 的内存和命中率以及操作系统层面的 CPU、内存、磁盘、网卡流量。外部检查脚本有些指标没法靠 Agent 内置 key 拿到必须通过自定义脚本去采集比如某个业务接口的响应耗时、证书剩余有效期、特定日志关键词计数。低层自动发现规则网卡列表、磁盘挂载点、进程实例这类会变化的资源用自动发现规则来生成动态监控项避免配死路径。告警策略预置包括触发器表达式、告警收敛时长、恢复表达式减少从零写表达式的工作量。这几类东西并不是装上就完事。模板导入只是第一步后续的主机分组、宏赋值、动作绑定、脚本权限任何一环断了监控数据或告警链路就会以各种奇怪的方式失效。标题里标注重要其实是因为我踩过的绝大多数问题都出在配置流程的衔接环节而不是扩展包本身。1.2 为什么配置流程比功能本身更需要重视我见过不少团队把模板文件导入之后界面上一看主机有了、图表有了就觉得监控上线了。过几天告警没收到才回头看发现动作没启用或者用户没配媒介又或者宏没有赋值导致模板里的监控项全部报不支持。这些问题基本都不是功能缺陷而是配置流程缺了环节。配置流程的意义在于把导入模板和告警真正到达责任人之间的断点全部补齐。扩展包提供的是素材流程保证的是素材被正确装配进运行环境。比如外部检查脚本模板里写的是my.ext.check这类自定义 key如果脚本没有放到 Server 的 ExternalScripts 目录或者没有可执行权限监控项会一直显示不支持但界面上并不会有显眼的错误提示你只能去日志里翻。再比如告警收敛模板里预置了收敛时长但如果你在主机级别把相关宏覆盖成了空值收敛逻辑就失效了。所以这篇文章的核心思路是按照真实操作顺序把从 Server 配置、Agent 部署、资源导入到告警联调的完整链路串一遍每个环节都交代清楚判断标准。下面正式开始。2. 配置前的准备版本、数据库、网络一次想清楚很多人配置 Zabbix 喜欢拿到安装包直接装装完再想数据库和端口的事。我的建议是反过来先把版本矩阵、数据库方案、网络端口这三件事定下来后面会少很多返工。2.1 版本兼容矩阵与安装方式hualinxu ext zbx 1.4 我主要在 Zabbix 6.0 LTS 和 7.0 两条线上做验证前端用 Nginx 加 PHP-FPM数据库用 MySQL 8.0 或 PostgreSQL 都可以。不同版本之间模板格式、item key 语法、宏用法有一定差异所以配置前先确认你手上的 Zabbix 版本避免拿旧版本的模板往新版本里导出现兼容性警告。组件推荐版本说明Zabbix Server6.0 LTS / 7.0 LTS长期支持版模板和 API 行为稳定Zabbix Agent与 Server 同大版本主被动模式都支持Agent 2 更省资源数据库MySQL 8.0 / PostgreSQL 14字符集要建对否则中文告警消息乱码前端Nginx PHP-FPMPHP 版本需满足官方要求hualinxu ext zbx1.4兼容性说明记录在扩展包的 docs/compat 目录安装方式我推荐用官方仓库的 RPM/DEB 包或者容器化部署不要自己源码编译。不是编译有什么问题而是后续升级、排障、查依赖太费劲尤其是 PHP 扩展和 agent 的二进制版本管理包管理器能省掉大量手忙脚乱的时间。容器化部署的话注意数据卷和时区挂载后面会提到。2.2 数据库初始化与前端部署数据库是 Zabbix 最容易在初期埋坑的地方。MySQL 建库时字符集最好明确指定否则模板里的中文描述和脚本返回的中文文本在入库后可能出现编码问题。CREATE DATABASE zabbix CHARACTER SET utf8mb4 COLLATE utf8mb4_bin; CREATE USER zabbixlocalhost IDENTIFIED BY YourStrongPassword; GRANT ALL PRIVILEGES ON zabbix.* TO zabbixlocalhost;导入初始 schema 的顺序要按官方文档来先 schema.sql再 data.sql最后 images.sql。很多人只导了 schema.sql 就开始配前端打开后一堆小图标不显示就是 images 数据缺失角色和用户界面报错多半是 data.sql 没导。我的做法是建完库之后把这三个文件一次性按顺序导入再顺手执行一遍SELECT * FROM users;之类的基础查询确认表结构和基础数据都正常再进入前端安装向导。前端部署时 PHP-FPM 的时区设置很关键php.ini里的date.timezone必须和服务器保持一致否则告警时间、图表时间全部偏移排查时非常容易误判是不是触发有问题。另外前端的安装向导会在最后一步写配置文件zabbix.conf.php如果之前目录权限不对向导会卡住。我的习惯是提前把 web 目录设为可写确认 PHP 模块齐全后再跑向导。2.3 网络端口与防火墙清单端口问题看起来简单但主被动模式混用时经常被忽略。Zabbix 依赖的端口不多但方向不能搞反。端口协议方向用途10051TCPAgent/Proxy 到 Server主动模式数据上报、Proxy 上报10050TCPServer 到 Agent被动模式拉取数据10051TCP前端到 Server前端通过 HTTP 走 Server API不直连 1005180/443TCP浏览器到前端Web 界面实践中有个常见误解配了主动模式以为只需要放行 Agent 所在机器的出站结果把 Server 的入站 10051 忘了放行数据到了 Server 端口却被防火墙丢掉agent 日志显示连接成功但 Server 端什么都收不到。如果你有 Zabbix Proxy 或多级架构相应的 10051 也需要在 Proxy 和 Server 之间放行。建议在配置前先把这些端口在防火墙和安全组里一次性列清楚再进入配置环节。3. 核心配置流程从 Server 到 Agent 再到告警通知准备做完下面进入正题。我按一条实际履行的顺序来讲先 Server 端再 Agent 端然后导入 hualinxu ext zbx 1.4 的资源并挂到主机上最后配告警媒介和动作。每一步我都尽量给出判断标准方便你确认自己走到哪一步了。3.1 Server 端初始化配置zabbix_server.conf是整套系统的中枢配置。安装完成后先别急着开 web 界面把关键参数过一遍。数据库参数是最基本的DBHostlocalhost DBNamezabbix DBUserzabbix DBPasswordYourStrongPassword ListenPort10051接下来是几个直接影响容量的参数。默认值在小规模环境够用但如果你导入 hualinxu ext zbx 1.4 的自动发现规则后监控项数量一下子涨到几万默认的缓存可能不够。日志里出现 history cache is 75% full 或 history cache is 90% full 时不要慌这不是错误是提示你HistoryCacheSize需要调大。我会结合监控项数量看情况调整StartPollers5 StartTrappers5 StartDiscoverers3 HistoryCacheSize128M TrendCacheSize64M ValueCacheSize8M CacheSize32MExternalScripts参数对这套扩展是必须的外部检查脚本默认放在这个目录下ExternalScripts/usr/lib/zabbix/externalscripts改完配置要重启zabbix-server然后用日志确认它真的起来了tail -f /var/log/zabbix/zabbix_server.log。日志里出现 using configuration file 和监听端口信息再继续往下。这里有个经验配置 Server 时顺便把日志级别调到 3 左右排查问题时方便追溯平时可以调回 2 或者更高避免日志刷得太快。3.2 Agent 端安装与主被动模式选择Agent 端的核心配置在zabbix_agent2.conf如果你用 Agent 2或zabbix_agentd.conf。无论是哪种关键参数都是这几个Server监控服务器IP ServerActive监控服务器IP Hostname唯一主机名 ListenPort10050Server和ServerActive的区别很多人分不清。Server用于被动模式标识允许哪些 Server 来拉取数据ServerActive用于主动模式告诉 Agent 主动把数据推给谁。两个参数可以同时配意味着主被动并存。主动模式和被动模式怎么选我的建议能主动尽量主动。原因很实际主动模式下 Agent 主动向外连 Server 的 10051不需要 Server 反向连回来对 NAT、云主机、安全组都很友好。被动模式要求 Server 能直接访问 Agent 的 10050网络限制多的环境特别容易出问题。而且主动模式的监控项由 Server 下发后续调整模板更新监控项时生效更快。配完 Agent 后重启 agent 服务然后立刻用zabbix_get验证被动模式zabbix_get -s 10.0.0.20 -k agent.ping如果返回1说明被动链路通了。主动链路不好直接用zabbix_get验证要在前端看最新数据是否有上报或者看 Server 日志。这一条后面在验证清单里还会细说。3.3 导入扩展资源与主机挂载Agent 通了之后才轮到 hualinxu ext zbx 1.4 的核心步骤。先把扩展包里的模板和媒体类型导入进来。在 Zabbix 前端的数据管理模块里选择导入格式用 yaml 或 XML 都可以导入时建议勾选更新现有选项方便以后升级 1.4 版本时覆盖旧数据。媒体类型一般在告警媒介里导入扩展包自带一个通用的 webhook 脚本模板用来往即时通信机器人的 webhook 地址发告警你只需在导入后填上机器人地址和密钥即可。导入完成后的操作顺序是先建主机再挂模板再按主机实际情况填宏。创建主机时主机组、Agent 接口这两项一定要对上。Agent 接口的 IP/DNS 和端口要填 Agent 实际监听的地址而不是随便填。主机名要尽量和 Agent 配置里的Hostname保持一致主动模式下这是匹配的唯一标识。挂模板时按需勾选扩展包里的模板。比如这台机器上有 MySQL就挂 MySQL 模板没有 Redis 就不挂。挂完后进宏配置页签把模板里要求填的宏逐个赋值。常见的有这些{$MYSQL_USER} zabbix_mon {$MYSQL_PASSWORD} 专用密码 {$NGINX_STATUS_URL} http://127.0.0.1/nginx_status {$ALERT_SCRAPE_TIMEOUT} 5宏不赋值会怎样模板里的监控项不会报错但采集脚本会因为拿不到用户密码或 URL 直接失败监控项显示不支持。这类问题在界面上不显眼排查成本最高。所以我每次配完主机都会逐个模板看监控项 → 最新数据专挑不支持的项处理。外部检查脚本的部署也别忘。把 hualinxu ext zbx 1.4 的scripts/目录复制到 Server 的ExternalScripts路径下然后确认执行权限和属主chown -R zabbix:zabbix /usr/lib/zabbix/externalscripts chmod -R 755 /usr/lib/zabbix/externalscripts这里有个容易踩的细节脚本要能被zabbix用户执行而不是 root。如果脚本依赖某个密码文件或配置文件也要确保zabbix用户可读。手动用 root 执行脚本一切正常一到 Zabbix 采集就失败十有八九就是属主和权限问题。3.4 告警媒介与动作的配置监控项有了数据上了接下来是把告警真正发出去。这一步的配置入口在告警媒介和配置 → 动作。先创建用户或复用现有用户然后在用户属性里添加媒介选择扩展包导入的 webhook 模板填上接收地址。注意媒介不是配了就有用得在用户属性里把它启用并且把启用时间设置正确否则告警发不出去。然后是动作。动作决定了什么条件下、给谁发、发什么。我通常会建一个名为全量告警通知的触发器动作条件设置成触发器严重性在一般及以上操作第一步给运维用户组发告警消息。配置页面里这几项要特别注意动作必须启用状态是已启用操作里要选择发送消息并勾选正确的用户组如果要做告警升级把后续步骤的步骤持续时间设置好比如 5 分钟无响应就升级恢复操作里也要配发送消息否则恢复时大家看不到故障已恢复的通知。还需要检查一下模板里预置的触发器是否按预期工作。hualinxu ext zbx 1.4 的模板里已经写好了常用的触发器表达式但触发器的严重性、事件标签这些属性你可能需要按自己的告警策略调整。比如磁盘使用率模板默认是警告但生产环境的根分区你可能想改成严重这个直接在模板里改改完所有挂载该模板的主机一起生效。4. 配置过程中最值得注意的五个坑前面讲的是流程这一节专门讲坑。以下五类问题是我配置这套扩展时反复遇到的也是后台私信里问得最多的放在一起集中说。4.1 时区与日志定位问题告警时间偏移是最容易被误判成系统坏了的问题。表现是数据明明正常但告警消息里的事件时间比实际时间早几个小时或晚几个小时。原因通常是三个环节的时间设置不一致系统时间、PHP 的date.timezone、数据库时区。排查时先date看系统时间再对比前端页面的时间最后看zabbix_server.log的时间戳。日志定位本身也有技巧。前端显示主机不可达或监控项不支持时多去翻 Server 日志而不是 Agent 日志因为大多数链路问题发生在 Server 解析数据或执行脚本的阶段。把DebugLevel临时调高到 4 或 5复现问题后看具体报错再调回来。我曾经遇到一个外部检查脚本在 Server 端执行报错前端不显示任何细节就是靠调高日志级别看到 stderr 输出才定位到脚本里一个路径写死了。4.2 模板继承与宏覆盖逻辑Zabbix 的宏和作用域遵循从上到下逐级覆盖的规则全局宏 → 模板级宏 → 主机级宏 → 监控项级宏。hualinxu ext zbx 1.4 的模板里预置了许多{$...}宏这些宏的默认值在模板上定义。如果你在主机上填了同名宏主机级的值会覆盖模板里的默认值如果你在监控项级别单独设置监控项级又会覆盖主机级。这个机制灵活但容易出错。最常见的错误是在主机上一口气填了几十个宏后来在模板里改了默认值主机上的旧值却不更新了排查问题时发现为什么我改了模板没生效——因为主机级的宏一直在起作用。我的习惯是能不改就不在主机级动宏必须个性化的时候每次改动在主机备注里记一笔避免维护时靠猜。4.3 主动模式下的网络连通性陷阱主动模式的数据链路是 Agent 主动连 Server 的 10051对防火墙友好但它有一个被动模式没有的大坑Hostname 严格匹配。Agent 的Hostname参数必须和前端主机配置里的名称完全一致注意大小写和空格。不一致时前端这台主机就会一直显示不可达但 Agent 日志里可能显示连接正常因为 TCP 连接是建立了的只是 Server 找不到对应的 host 配置把数据丢掉了。另一个主动模式的坑是ServerActive配置了域名而 DNS 解析不稳定或者写了多个 Server 地址用逗号分隔但格式不对。建议 ServerActive 直接填 Server 的固定 IP避免 DNS 抖动导致 Agent 报 cannot connect 然后又重试的循环。另外如果 Server 前面有负载均衡要保持长连接相关参数一致避免 10051 连接被中间设备重置。4.4 触发器表达式里的恢复表达式在很多 Zabbix 版本里触发器可以分别配置问题表达式和恢复表达式。如果恢复表达式没配好会出两种状况一是故障恢复了但告警一直停留在问题状态二是恢复表达式写得太松数据抖动导致频繁报警。hualinxu ext zbx 1.4 模板里的触发器原则上都带恢复表达式但你新加触发器时要自己写。几个常用表达式的写法last(/主机/key)表示最新值avg(/主机/key,5m)表示最近 5 分钟平均值nodata(/主机/key,5m)1表示 5 分钟没有数据。做进程监控时我常用last()0加恢复表达式last()0。写完后建议用界面上的测试功能先验一下表达式语法再等真实事件发生。否则表达式写错导致的误报比不报警还要让人头疼。4.5 权限与用户组配置顺序告警都发到用户了结果用户登录后看不到主机、看不到数据这类问题属于权限配置顺序不对。Zabbix 的权限模型是用户属于用户组用户组被赋予主机组或数据集的权限权限又有无权限、只读、读写等级之分。配置顺序应该是先建主机组再建用户组给用户组分配主机组权限最后把用户加进用户组。顺序反了或者权限只给了用户而不是用户组前端就会出现全部主机都不可见的情况。另外如果用了不同角色比如用户和管理员角色限制也会影响界面可见性和操作权。排障时先确认角色再确认用户组权限最后看主机组的继承关系。这套规则不复杂但它贯穿整个前端体验很多看不到数据的问题毛病出在这里。建议配完权限后用一个只读测试账号登录验证而不是一直拿管理员账号看。5. 配置完成后的验证清单配置流走到这里系统已经上线。但上线了和真好用之间还差一轮系统验证。我会按两条链路来检验一条是数据链路一条是告警链路。5.1 数据链路验证数据链路验证的目标是确认从 Agent 采集到前端展示全程无断点。被动模式用zabbix_get直接测zabbix_get -s 10.0.0.20 -k system.cpu.load[all,avg1] # 返回数值说明被动链路正常主动模式没有对应的命令行工具最简单的方法是在前端最新数据里看对应主机最近有没有数据。如果等了 5 分钟还是空的去 Server 日志搜主机名重点看有没有 no data 或 cannot send 的记录。外部检查脚本的验证更直接切到zabbix用户手动执行一次脚本看输出是否符合预期sudo -u zabbix /usr/lib/zabbix/externalscripts/myscript.sh如果能执行但前端显示不支持检查脚本输出格式是不是模板里定义的类型文本还是数值以及是否输出额外字符破坏了格式。我写过不少采集脚本最常踩的就是把调试信息和正式输出混在一起Zabbix 把整段内容当成了监控值导致数值型监控项解析失败。5.2 告警链路验证告警链路的验证要模拟真实故障而不是只看配置。我会挑一台测试机器临时停掉 Agent 服务看触发器是否能通过nodata()识别到数据缺失然后在动作日志里确认告警消息被生成并发送。这个测试动作要专门做一次不要等到生产真的出故障时才发现媒介没配或动作没启用。恢复链路的验证同样重要。把 Agent 服务重新拉起观察触发器是否从问题恢复到已解决恢复消息是否推送到责任人。确认无误后把测试动作停用或删除避免影响线上告警统计。整套流程走完我会再备份一份配置包括导入的模板文件、zabbix_server.conf、脚本目录放进配置仓库统一管理。后续升级 hualinxu ext zbx 到更高版本时这份备份就是快速回滚的底气。最后再说一个我个人的习惯每次新环境配置完这套扩展我都会在前端报表 → 动作日志里把这一周的动作日志扫一遍重点看有没有已发送失败的记录。告警通道是监控系统最末端的一环也是最容易被忽略的一环数据再全告警没送达责任人监控的价值就打了一半折扣。把这一步养成习惯Zabbix 用起来会顺手很多。
