如何利用 stub_status 监控反向代理层的活跃连接数与处理效率-Nginx-PHP中文网

nginx stub_status模块是轻量级监控反向代理连接状态的核心工具，实时暴露活跃连接、接受/处理请求数等指标，需在server或location块中启用并限制访问权限，配合prometheus可实现自动化采集与告警。

如何利用 stub_status 监控反向代理层的活跃连接数与处理效率

Nginx 的 stub_status 模块是轻量级监控反向代理层连接状态的核心工具，它不依赖外部服务，能实时暴露活跃连接数、已接受/处理请求数等关键指标，特别适合快速定位连接堆积、请求积压或后端响应慢等问题。

启用 stub_status 并限制访问权限

该模块默认编译进大多数 Nginx 官方发行版（可通过 nginx -V 2>&1 | grep -o with-http_stub_status_module 确认）。需在 server 或 location 块中显式开启，并严格限制访问来源，避免信息泄露：

在配置中添加如下内容（建议放在专用于监控的 server 块中）：

location /nginx-status {
    stub_status on;
    access_log off;
    allow 127.0.0.1;     # 仅允许本机采集
    allow 10.10.0.5;     # 或指定监控服务器 IP
    deny all;
}

重启 Nginx 后，通过 curl http://127.0.0.1/nginx-status 可看到类似输出：

Active connections: 24 
server accepts handled request
 123456 123456 234567 
Reading: 2 Writing: 8 Waiting: 14

解读关键字段含义与监控重点

Active connections：当前所有处于活跃状态的 TCP 连接数（包括建立但未关闭的 keepalive 连接），反映瞬时负载压力；

accepts：Nginx 启动以来接受的总连接数；

handled：成功处理的连接数（通常与 accepts 相等，若不等说明有连接被丢弃，可能因资源不足或 limit_conn 触发）；

requests：已处理的 HTTP 请求数（一个连接可承载多个请求，尤其启用了 keepalive）；

Reading/Writing/Waiting：分别表示当前正在读取请求头、向客户端发送响应、等待请求体或客户端保持空闲连接（keepalive）的连接数。其中 Waiting 高而 Writing 低，常意味着后端响应慢或客户端接收慢；Writing 持续高位则可能后端返回大响应体或网络拥塞。

结合 Prometheus 实现自动化采集与告警

使用 nginx-prometheus-exporter 可将 stub_status 数据自动转换为 Prometheus 格式指标，无需修改 Nginx 配置：

启动 exporter 时指定 stub_status 地址：./nginx-prometheus-exporter -nginx.scrape-uri http://127.0.0.1/nginx-status
Prometheus 抓取 http://exporter-host:9113/metrics，即可获得如 nginx_connections_active、nginx_http_requests_total 等指标
设置告警规则示例（当活跃连接持续超过 1000 且 Waiting 连接占比超 80%）：

- alert: HighNginxWaitingConnections
  expr: 100 * nginx_connections_waiting / nginx_connections_active > 80
  for: 2m
  labels:
    severity: warning
  annotations:
    summary: "High waiting connections on nginx"

关联分析：连接数异常时的排查路径

发现 Active connections 异常升高时，不要只看单一数值，应联动其他维度判断根因：

检查 Waiting 是否同步飙升 → 可能是客户端慢速读取、后端响应延迟、或 upstream 超时设置过长
对比 accepts 与 handled 差值是否持续扩大 → 查看 error.log 中是否有 accept() failed (24: Too many open files) 或 connection refused，确认 ulimit 和 worker_connections 设置是否合理
观察 requests / accepts 比值是否明显下降 → 若显著低于 1.0，说明大量连接未发出请求即断开（如健康检查失败、客户端主动中断）
配合 upstream response time 日志变量（如 $upstream_response_time）分析后端耗时分布，验证是否为上游瓶颈