用夜莺监控 Nginx

stub_status 够看连接和请求总量，VTS 模块能到每个 server 和 upstream 的状态码与延迟；另带 upstream_check 健康检查插件。

最后校对于 2026-10-13

Nginx 监控有三个层次。stub_status 模块自带，给出活跃连接、accepts、handled、requests 和读写等待数，够做存活与流量趋势。VTS 模块（nginx-module-vts）能按 server zone 和 upstream 细分请求数、状态码、响应时间和流量，是最推荐的方式，用 Categraf 的 prometheus 插件抓它的 /status/format/prometheus。第三个是 nginx_upstream_check 插件，读取 upstream_check 模块的健康检查结果。

模板里三张仪表盘分别对应 stub_status、upstream 健康检查和 VTS。规则覆盖 Nginx 不可达、活跃连接突增和 upstream 节点被判定为 down。

模板里有什么

• 3 张仪表盘，共 24 个面板
• 3 条告警规则，每条附处置步骤
• 7 条指标说明
• Categraf 采集配置：input.nginx、input.nginx_upstream_check

怎么接入

1. 安装 Categraf，按需启用下面的插件。每个配置放到对应的 conf/input.<插件名>/ 目录，改好地址和凭据后重启 Categraf。

   conf/input.nginx/nginx.toml

   # # collect interval
   # interval = 15
   
   [[instances]]
   ## An array of Nginx stub_status URI to gather stats.
   urls = [
   #    "http://192.168.0.216:8000/nginx_status",
   #    "https://www.baidu.com/ngx_status"
   ]
   
   ## append some labels for series
   # labels = { region="cloud", product="n9e" }
   
   ## interval = global.interval * interval_times
   # interval_times = 1
   
   ## Set response_timeout (default 5 seconds)
   response_timeout = "5s"
   
   ## Whether to follow redirects from the server (defaults to false)
   # follow_redirects = false
   
   ## Optional HTTP Basic Auth Credentials
   #username = "admin"
   #password = "admin"
   
   ## Optional headers
   # headers = ["X-From", "categraf", "X-Xyz", "abc"]
   
   ## Optional TLS Config
   # use_tls = false
   # tls_ca = "/etc/categraf/ca.pem"
   # tls_cert = "/etc/categraf/cert.pem"
   # tls_key = "/etc/categraf/key.pem"
   ## Use TLS but skip chain & host verification
   # insecure_skip_verify = false

   conf/input.nginx_upstream_check/nginx_upstream_check.toml

   # # collect interval
   # interval = 15
   
   [[instances]]
   targets = [
       # "http://127.0.0.1/status?format=json",
       # "http://10.2.3.56/status?format=json"
   ]
   
   # # append some labels for series
   # labels = { region="cloud", product="n9e" }
   
   # # interval = global.interval * interval_times
   # interval_times = 1
   
   ## Set http_proxy (categraf uses the system wide proxy settings if it's is not set)
   # http_proxy = "http://localhost:8888"
   
   ## Interface to use when dialing an address
   # interface = "eth0"
   
   ## HTTP Request Method
   # method = "GET"
   
   ## Set timeout (default 5 seconds)
   # timeout = "5s"
   
   ## Whether to follow redirects from the server (defaults to false)
   # follow_redirects = false
   
   ## Optional HTTP Basic Auth Credentials
   # username = "username"
   # password = "pa$$word"
   
   ## Optional headers
   # headers = ["X-From", "categraf", "X-Xyz", "abc"]
   
   ## Optional TLS Config
   # use_tls = false
   # tls_ca = "/etc/categraf/ca.pem"
   # tls_cert = "/etc/categraf/cert.pem"
   # tls_key = "/etc/categraf/key.pem"
   ## Use TLS but skip chain & host verification
   # insecure_skip_verify = false

2. 在夜莺「集成中心」里找到 Nginx，把仪表盘和告警规则导入到业务组。

3. 导入的告警规则默认是停用的。先确认指标已经入库，再按自己环境的阈值逐条启用。

内置仪表盘

仪表盘	面板数
Nginx Stub	6
Nginx Upstream	3
Nginx VTS	15

内置告警规则

共 3 条。每条给出触发条件（PromQL）和告警后的处置步骤，导入后可以直接改阈值。

Nginx 实例不可达

S1 紧急 · 持续 1 分钟 · 触发条件:

nginx_up == 0

处置步骤:

1. 登录主机执行 systemctl status nginx 或 ps -ef | grep nginx，确认 master 进程是否存活；
2. 进程存活则执行 curl -s http://127.0.0.1/nginx_status 手工验证 stub_status 是否被 allow/deny 或防火墙挡住；
3. 进程不在则先执行 nginx -t 校验配置再 systemctl start nginx，并查看 error_log 尾部定位退出原因；
4. 确认上游 VIP 或负载均衡已把该节点摘除，避免继续打流量。

Nginx 出现连接丢弃

S2 警告 · 持续 5 分钟 · 触发条件:

increase(nginx_accepts[5m]) - increase(nginx_handled[5m]) > 0

处置步骤:

1. 查看 error_log 是否有 worker_connections are not enough 或 too many open files；
2. 按 worker_processes × worker_connections 估算连接上限，对照 nginx_active 当前水位后调大 worker_connections；
3. 同步调大 worker_rlimit_nofile 与 systemd 的 LimitNOFILE；
4. 执行 nginx -s reload 生效后确认 accepts 与 handled 的差值不再增长。

Nginx upstream 后端节点不可用

S1 紧急 · 持续 1 分钟 · 触发条件:

nginx_upstream_check_status_code == 2

处置步骤:

1. 从告警标签取 upstream 与 name（后端地址），在 Nginx 所在主机执行 curl -sv http://<后端地址>/ 确认是否真的不通；
2. 后端不通则登录该后端主机确认应用进程与端口存活；
3. 后端正常则检查 Nginx 到后端的网络与安全组，以及 check 指令配置的探测路径是否与后端健康检查接口一致；
4. 用 curl http://<nginx>/status?format=json 确认同一 upstream 还剩几个可用节点，只剩一个时立即扩容。

指标说明

共 7 条，和仪表盘、告警规则里用到的指标一一对应。

指标	含义	单位
nginx_waiting	Nginx stub_status 当前空闲连接数 — 文档
nginx_writing	Nginx stub_status 正在回写 response 的连接数 — 文档
nginx_active	Nginx stub_status 正在处理的活动连接数 — 文档 Reading + Writing + Waiting 的总和
nginx_reading	Nginx stub_status 正在读取 request header 的连接数 — 文档
irate(nginx_accepts[3m])	Nginx stub_status 每秒 accept 的新连接数 — 文档
irate(nginx_handled[3m])	Nginx stub_status 每秒 handle 的新连接数 — 文档
irate(nginx_requests[3m])	Nginx stub_status 每秒处理的请求数 — 文档 如果有 keep-alive 连接的情况，一个连接上会处理多个请求。

相关链接

• [Nginx 模板源文件](https://github.com/ccfos/nightingale/tree/main/integrations/Nginx）：仪表盘、规则和采集配置的 JSON 原文，欢迎提 PR。
• Categraf nginx 插件文档：完整配置项和指标列表。
• Categraf nginx_upstream_check 插件文档：完整配置项和指标列表。
• 导入仪表盘和告警规则
• 核对指标是否入库
• 全部集成目录