先说结论Zabbix 监控 Nginx最关键的环节不在 Server 端怎么写监控项而在 Agent 端怎么把 Nginx 的实时状态稳定采集上来。很多人装了一堆组件最后发现数据过不来问题大多出在 Nginx 状态页没开、Agent 配置文件没改对、自定义监控项写错这三个地方。这篇文章适合两类人。一类是刚开始接触 Zabbix想用 Agent 方式给 Nginx 加监控的新手另一类是已经把 Zabbix Server 跑起来但搞不清客户端、状态页、自定义 key 之间关系的人。看完之后你能按顺序搭出一条完整链路Nginx 暴露状态页Agent 执行采集命令Zabbix Server 通过 key 拿到数据最终在 Web 界面看到指标曲线和告警。下面按实际落地顺序拆一遍。1. 先把Zabbix监控Nginx的数据链路拆清楚1.1 Agent在监控链路里到底干什么Zabbix 监控 Nginx 可以有多种方式比如直接用 SNMP、用 Zabbix Agent、或者让 Zabbix Server 主动去请求 HTTP 接口。最常见、也最适合多数企业内部场景的就是Zabbix Agent方式。Agent 本质上是一个安装在被监控机器上的小服务。它负责做三件事接收 Zabbix Server 或 Zabbix Proxy 发来的数据请求执行本地的采集命令、脚本或从状态页读取数据把结果返回给 Server 端。所以Agent 不是直接“连”上 Nginx而是起到了一个翻译和采集的作用。Nginx 本身不会主动告诉 Zabbix “我的并发连接是多少”Agent 需要自己去读 Nginx 暴露出来的状态信息然后转换成 Zabbix 能识别的数值。理解这条链路非常重要。很多人直接照着网上配置往配置文件里写了几行UserParameter发现没数据就以为是 Zabbix 的问题。实际上往往是 Nginx 状态页本身打不开或者 Agent 所在用户没有权限执行 curl又或者 key 名称写错了导致 Server 端拿不到结果。1.2 基础监控项可以直接用高级指标要靠状态页或脚本如果你只是监控“进程在不在”那 Zabbix 自带的模板和内置 key 就够了。比如用proc.num[nginx]或proc.num[nginx.exe]判断 Nginx 进程数量用system.cpu.load看 CPU 负载用net.if.in、net.if.out看网卡流量。这些不需要改动 Nginx 配置Agent 装上之后就能用。但如果你想监控 Nginx 的业务指标比如当前活跃连接数总连接数总请求数每秒请求数Reading、Writing、Waiting 的数量那一定要开启 Nginx 的stub_status模块并配置一个状态页。然后通过 Agent 的UserParameter去读取解析。这里有一个常见误解以为 Zabbix 官方模板会自动采集这些数据。实际上官方模板里包含这些监控项但前提是 Agent 端已经装好了 Nginx 状态页采集脚本或自定义 key。模板只是“装了 CPU 插座”还得你自己把“电源线”接上。1.3 环境准备和判断标准准备环境时先确认以下条件Zabbix Server 已经安装并运行Web 界面可以打开被监控的 Nginx 服务器能访问 Zabbix Server/Serve 端也能访问 Agent 的监听端口Agent 版本尽量和 Server 主版本接近避免低版本 agent 不支持某些 keyNginx 编译时带上了--with-http_stub_status_module或者本身就是发行版默认编译好的版本如果是 Docker 部署的 Nginx也要确认容器内是否有 curl、grep、awk 这些基础命令后面脚本采集时会用到。其中“Agent 版本和 Server 版本尽量一致”这条很多人会忽略。虽然 Zabbix Agent 大体上向后兼容但高版本 Server 搭配特别老的 Agent可能出现监控项显示“不支持”的情况。建议落地前先统一版本。如果只是学习测试单机部署一台 VM 就够如果要进生产建议把 Zabbix Server 和 Agent 分别部署在不同机器上避免性能干扰。2. Agent端安装和基础配置决定后面少踩一半坑2.1 安装方式选择Zabbix Agent 的安装方式取决于操作系统。常见的有使用发行版官方仓库或 Zabbix 官方仓库安装下载源码编译安装使用 Docker 容器运行 agent如果是 Windows Nginx还需要安装 Windows 版本的 agent。安装时最好不要用“从网上随手找个包”的方式因为 Zabbix 官方仓库会根据你使用的系统版本提供对应的 agent 包依赖也能自动处理。具体安装命令这里不给死版本因为不同系统和 Zabbix 版本的仓库地址差异很大。建议参考官方安装文档或者直接看仓库安装提示按照“添加官方仓库 - 刷新包列表 - 安装 zabbix-agent”的顺序走。安装完成后先不着急改配置确认 agent 二进制文件已经存在。which zabbix_agentd或者zabbix_agentd --version如果命令能打印出版本信息说明安装成功。这一步能提前发现“安装到一半缺依赖”“架构不对”等问题。2.2 修改Agent配置文件Agent 的主配置文件一般叫zabbix_agentd.conf在 Linux 上常见路径有/etc/zabbix/zabbix_agentd.conf、/usr/local/etc/zabbix_agentd.conf。Windows 上通常安装在 agent 安装目录下。需要重点关注这几个参数参数作用填写建议Server允许向本 Agent 请求数据的 Zabbix Server 或 Proxy IP写 Server 的实际 IP不要写 0.0.0.0ServerActiveAgent 主动连接 Server 的地址用于主动模式同样写 Server IP 和端口HostnameAgent 在 Server 端注册或显示的主机名必须和 Web 界面创建的主机名一致UnsafeUserParameters是否允许自定义 key 包含特殊字符或带参数如果自定义命令很简单可以设为 0如果带参数、管道最好设为 1UserParameter自定义监控项 key 和采集命令可以写在单独文件里引用一个常见的问题是同时配置了Server和ServerActive但 Hostname 写错了。结果就是 Zabbix Server 能看到主机但数据全断断续续。原因是被动模式下 Server 根据 IP 来找 Agent主动模式下 Agent 要上报自己的 Hostname两套机制的校验方式不一样。我给你一个比较稳妥的配置习惯先只配置被动模式也就是Server和Hostname确认 zabbix_get 能取到数据后再按需开启主动模式不要一上来就同时开两个模式排查起来不方便。2.3 启动与连通性验证配置文件改完后重启 Agent 服务。systemctl restart zabbix-agent确认进程状态systemctl status zabbix-agent然后看 Agent 日志确认没有报错。日志位置通常在/var/log/zabbix/zabbix_agentd.log。如果 Agent 和服务在同一台机器可以用zabbix_get命令模拟 Server 拉取数据。zabbix_get -s 127.0.0.1 -k agent.ping返回1代表 Agent 活着。返回超时或cannot connect就要检查端口监听和防火墙。接下来用同样方式测试 Nginx 相关的内置 key比如zabbix_get -s 127.0.0.1 -k proc.num[nginx]如果返回数字说明 Agent 部署正常已经能获取系统数据。到这里基础的 Agent 链路算通了。3. Nginx状态页开启核心指标都从这里来3.1 检查Nginx是否带stub_status模块Nginx 的stub_status是官方自带的一个模块但很多源码编译的 Nginx 默认并没有把它带上。所以第一步是先确认。看已安装 Nginx 是否包含该模块nginx -V 21 | grep stub_status如果有输出说明模块已经编译进去了。如果没有输出有两种处理方式重新编译 Nginx在 configure 参数中加上--with-http_stub_status_module如果用的是发行版默认 Nginx可以检查是否已经默认带了这个模块。比如某些 Linux 发行版的 nginx 包会默认包含。重新编译相对麻烦尤其会影响现有 Nginx 的平滑升级。建议先在测试环境验证不要直接在线上操作。如果线上 Nginx 是别人装的你也不清楚编译参数那就先跑nginx -V看看结果。3.2 配置location /nginx_status在 Nginx 配置中增加一个状态页 location。常见做法是新增一个独立配置文件或者在server块中新增 location。location /nginx_status { stub_status on; access_log off; allow 127.0.0.1; deny all; }这里最重要的不是stub_status on;而是allow和deny的访问控制。默认情况下这个页面会暴露 Nginx 当前所有连接和请求状态。如果不做限制外网可以随便访问等于泄露了服务运行基础信息。所以一般只允许本机或内网监控网段访问。如果 Agent 和 Nginx 在同一台机器allow 127.0.0.1就够了。如果 Agent 要从另一台机器抓取就把allow换成监控网段但这样会对 Nginx 暴露一个 HTTP 端点必须在防火墙层面做好限制。有些朋友会问不是 Agent 本机采集吗为什么还要允许局域网因为如果你的采集脚本是跑在 Agent 本机通过http://127.0.0.1/nginx_status访问那确实只需要允许本机。但如果你尝试从 Zabbix Server 直接用 HTTP agent 监控 Nginx那就必须允许 Server IP。本文统一采用 Agent 本机采集的方式所以只允许 127.0.0.1 最稳。配置完成后重载 Nginx。nginx -t nginx -s reload3.3 本地curl验证输出格式在 Agent 本机执行curl http://127.0.0.1/nginx_status正常情况下会看到类似这样的输出Active connections: 12 server accepts handled requests 100 100 200 Reading: 0 Writing: 1 Waiting: 11四行数据的含义第一行当前活跃连接数第二行三个计数器的标题第三行总接受连接数、总握手连接数、总请求数第四行正在读取请求头的连接数、正在写入响应的连接数、空闲等待请求的连接数。如果 curl 返回空或者 403、404先查 Nginx 配置是否真正生效再查防火墙。403 通常是 allow/deny 规则问题404 通常是 location 路径或配置文件没加载。4. 自定义监控项把status页转换成Zabbix能识别的数据4.1 用UserParameter定义KeyAgent 拿到 Nginx 状态页内容之后还需要把它解析成独立指标。Zabbix 是通过自定义 key 来实现的。在/etc/zabbix/zabbix_agentd.d/目录下新建一个配置文件比如userparameter_nginx.conf写入UserParameternginx.active,curl -s http://127.0.0.1/nginx_status | grep Active | awk {print $NF} UserParameternginx.requests,curl -s http://127.0.0.1/nginx_status | sed -n 3p | awk {print $3} UserParameternginx.reading,curl -s http://127.0.0.1/nginx_status | grep Reading | awk {print $2} UserParameternginx.writing,curl -s http://127.0.0.1/nginx_status | grep Writing | awk {print $4} UserParameternginx.waiting,curl -s http://127.0.0.1/nginx_status | grep Waiting | awk {print $6}注意这里的命令里用到了管道和grep所以UnsafeUserParameters需要设为1否则 Agent 可能拒绝执行这类带特殊字符的命令。配置完重启 Agentsystemctl restart zabbix-agent用zabbix_get测试zabbix_get -s 127.0.0.1 -k nginx.active如果返回数字说明自定义 key 已经生效。4.2 用脚本代替多条命令上面的写法虽然简单但每条 key 都执行一次 curl而且解析逻辑各不相同。如果有 5 个指标每次采集都要重复请求 5 次状态页。虽然对单机来说影响不大但会让监控数据点的时间不完全一致尤其是 active、connections、requests 三个值是不同时间快照画图时可能看到轻微波动。更好的方式是写一个采集脚本一次请求拿到所有值再按需输出。#!/bin/bash STATUS$(curl -s http://127.0.0.1/nginx_status) case $1 in active) echo $STATUS | grep Active | awk {print $NF} ;; requests) echo $STATUS | sed -n 3p | awk {print $3} ;; reading) echo $STATUS | grep Reading | awk {print $2} ;; writing) echo $STATUS | grep Writing | awk {print $4} ;; waiting) echo $STATUS | grep Waiting | awk {print $6} ;; *) echo UNKNOWN ;; esac把这个脚本放到/usr/local/bin/nginx_status.sh并加执行权限chmod x /usr/local/bin/nginx_status.sh然后配置 userparameterUserParameternginx.status[*],/usr/local/bin/nginx_status.sh $1这样在 Zabbix Server 端可以用nginx.status[active]、nginx.status[waiting]读取不同指标每次采集只请求一次 Nginx 状态页。这类脚本方案适合指标多、采集频率高的场景。缺点是脚本出了问题排查难度更大所以脚本里尽量减少对系统命令路径的依赖。4.3 主动模式和被动模式对自定义key的影响自定义 key 本身不区分主动还是被动两种模式都支持。区别在于被动模式Zabbix Server 发起 TCP 连接向 Agent 请求 keyAgent 执行命令返回结果。适合监控项不多、Server 并发压力不大的场景。主动模式Agent 每隔一段时间主动去向 Server 获取监控项列表然后执行并上报结果。适合监控项很多、网络分区复杂的场景。如果你使用主动模式ServerActive必须配置正确并且 Agent 能访问 Server 的 10051 端口。同时 Hostname 必须和 Web 界面创建的主机名完全一致否则 Agent 上报的数据找不到归属主机。在测试阶段建议先使用被动模式因为zabbix_get就是模拟被动模式的请求排错更直观。5. Server端把主机和监控项绑定起来5.1 在Web界面添加主机Zabbix Server 装好并配置好 Agent 后登录 Web 界面在“数据采集 - 主机”里创建新主机。需要填写的内容主机名称必须与 Agent 配置里的Hostname一致可见名称可以自定义显示在页面上模板可以先选择自带模板测试连接性群组选一个已有主机组或者新建一个 Nginx 组Interface选择 Agent填写被监控机器 IP 地址端口默认 10050。创建时如果勾选了“添加后启用”保存后主机应该会出现在可用主机列表里。很多人第一次配置时会把“主机名称”和“可见名称”混在一起。实际上主机名称是 Zabbix 内部用于匹配 Agent 上报的标识必须严格对应可见名称可以随便写。如果主机名称填错主动模式下数据绝对不来被动模式下有时还能通过 IP 匹配所以这个坑要记住。5.2 关联模板或手动添加监控项Zabbix 官方提供了 Nginx by Zabbix agent 模板里面已经定义好了监控项和触发器。如果你的 Agent 端已经配好了对应的自定义 key直接关联模板就能看到数据。关联模板之后建议先看“最新数据”。如果监控项显示“不支持”说明模板里引用的 key 在 Agent 端并没有定义要么是自定义配置文件没生效要么是 key 名称不匹配。不使用模板的情况下也可以手动创建监控项字段示例名称Nginx 活跃连接数类型Zabbix agent键值nginx.status[active]信息类型数字无正负更新时间30s手动创建的好处是灵活坏处是每台主机都要配一遍效率低。建议至少从模板开始再按需修改。5.3 最新数据验证添加监控项后等一两个更新周期再到“监测 - 最新数据”里查看。判断标准有数值且持续更新链路完全通显示不支持Agent 执行命令失败或 key 名称不对显示“不支持”但 zabbix_get 正常检查 Server 端 Agent 配置的 IP 和端口有数据但一直不变检查脚本是否用了缓存或者 Nginx 状态页是否更新异常。有时候 Agent 端刚改了自定义配置需要等 Agent 重启后才会重新加载。如果发现改了配置但没生效先确认是否重启了 zabbix-agent。我用 zabbix_get 排查时会习惯在前面加一个timeouttimeout 5 zabbix_get -s 192.168.1.10 -k nginx.status[active]加上 timeout 可以避免命令长时间卡住尤其当脚本内部频繁请求外部地址时。生产上不建议让监控采集命令永久阻塞Zabbix Agent 本身有 timeout 限制但脚本内部如果卡在某个命令上也会拖慢采集。6. 数据没到、不支持、为0时按这个顺序排查6.1 Agent状态不可达现象Zabbix Server 页面显示主机离线zabbix_get -s 目标IP -k agent.ping超时或 cannot connect。排查顺序先确认目标 IP 是否通ping 目标IP确认 Agent 端口监听是否正常ss -lntp | grep 10050确认防火墙是否放行端口Linux 检查firewalld或iptables确认 Zabbix Server 能否连接到该端口用telnet 目标IP 10050或nc -vz 目标IP 10050如果前面都正常看 Agent 日志可能有配置错误或启动失败。大多数“不可达”不是 Zabbix Server 的问题而是防火墙或者 Agent 没启动。6.2 监控项显示不支持现象agent.ping正常但 Nginx 相关监控项显示“不支持”。在 Agent 本机执行zabbix_get -s 127.0.0.1 -k nginx.status[active]如果返回非数字或报错继续看key 名称是否和 Server 端完全一致自定义配置文件是否生效脚本是否有执行权限脚本里的 curl 是否能访问 Nginx 状态页Agent 日志里是否有cannot run command之类的记录。这一层最常见的问题有两个一个是UnsafeUserParameters0导致带管道或参数字符的命令被拦截另一个是脚本权限不对Agent 执行脚本时没有执行权限返回空值。6.3 数据为0或长时间不变如果 zabbix_get 能返回数字但 Web 界面数据为 0 或不变可能的原因监控项类型设置错误比如把整数项配置成字符型更新周期太长短时间内看不到变化Agent 端脚本使用了缓存文件但缓存文件没有及时更新Nginx 状态页的数值确实没变化尤其是 Reading/Writing/Waiting请求量低的时候波动很小。遇到这种问题先把监控项改成 10s 更新间隔观察同时把采集脚本手动执行几次对比结果。如果手动执行有变化而 Zabbix 一直取旧值多半是 Agent 端缓存或 Server 端历史数据存储延迟。6.4 检查权限和SELinux这个坑在 Linux 生产环境中非常普遍。如果 Agent 和 Nginx 都在同一台机器Agent 执行 curl 访问http://127.0.0.1/nginx_status一般没问题。但如果 SELinux 开启可能会有连接被拒的情况。排查时先看/var/log/audit/audit.log有没有 denied 记录。有的话可以采用两种方式放通相关端口或者把 SELinux 临时转为 permissive 测试。不要一上来就永久关闭 SELinux先确认是不是它的原因。Zabbix Agent 默认以zabbix用户运行这个用户对 Nginx 状态页的访问是走 HTTP 协议的不涉及文件系统权限但要在操作系统层面允许它建立本地网络连接。如果连本机回环都被限制curl 会返回空。7. 从单台试跑到批量部署还要补三件事7.1 批量部署Agent单机跑通后批量监控也别急着手工逐台配置。建议提前准备好 Agent 配置文件模板和安装脚本利用自动化运维工具分发安装。批量部署时每台机器需要变化的内容主要有两个Hostname和Server。Server通常都指向同一个 Zabbix ServerHostname则建议用机器名或业务名方便识别。如果没有自动化工具可以写一个简单的 Shell 脚本在一批机器上执行安装、写入配置、启动服务。关键点在于脚本要幂等重复执行不会产生重复监控项或配置冲突。7.2 模板复用和指标命名规范批量部署前先定义一套统一的监控项命名规范。比如nginx.active nginx.requests nginx.reading nginx.writing nginx.waiting不要每台机器都用不同的 key 名。否则后面加图形、加聚合、加告警时工作量会翻好几倍。在 Zabbix 里一套完整的 Nginx 监控模板应该包含监控项连接数、请求数、Reading、Writing、Waiting触发器活跃连接数过高、请求数异常下降、Nginx 进程数小于 1图形连接数和请求数趋势图聚合原型如果需要按集群视图查看可以配置聚合监控项。模板设计好之后所有新主机直接关联模板避免人工逐条添加监控项。7.3 监控频率与告警阈值的取舍Nginx 的指标采集频率不建议太高。默认 30 秒到 1 分钟已经足够尤其是请求数、活跃连接数这类指标本身就是瞬时快照采集频率高并不能提高准确性反而会增加 Agent 和 Server 的负担。告警阈值要根据实际业务来定。比如活跃连接数超过某个值就告警但不同服务器的性能差异很大最好先采集一周数据再看基线请求数突然掉到接近 0可能是 Nginx 挂了也可能是业务本身陷入了低谷Reading、Writing 长期偏高说明可能有大文件传输或慢客户端不一定是故障。我在实际项目中用过的最不后悔的一个习惯是刚开始只采集不告警。先积累一两周数据再根据真实基线设定阈值否则很容易被误报刷屏。7.4 日志和备份最后补一个容易被忽略的点Agent 端自定义配置和脚本要纳入版本管理不能只留在机器上。否则重装机器后监控配置就很难原样恢复了。Zabbix 本身的模板、主机、监控项配置也要定期导出备份。监控系统一旦配置多了重新手搭非常痛苦。备份不只是保护数据也是在保护自己的运维效率。如果只是学习按默认配置跑通就可以了如果要长期维护那就把日志、输出目录、模板备份和权限控制都提前整理好后面真的会省很多事。踩过几次之后我发现Zabbix 监控 Nginx 的坑很少在“功能不够”上多半是前置环境不一致、状态页访问受限、自定义 key 书写习惯不统一。把这几条理顺整个监控链路就稳了。