「史上最全」ngx_http_status_module 深度实战指南-CSDN博客

本文链接：https://blog.csdn.net/weixin_43114209/article/details/148177399

1、快速启用 & 最小权限

# ① 定义共享区收集虚拟主机指标
server {
    listen 80;
    server_name app.example.com;

    # 每个 server 只能绑定一个 zone，多个 server 可复用同名 zone
    status_zone app_server;
    location / {
        proxy_pass http://app_upstream;
    }
}

# ② 管理端口，仅内网可访问
server {
    listen 127.0.0.1:8080;

    # JSON 输出
    location /status { status; }
    # 简易可视化 HTML（官方附带）
    location = /status.html { root /usr/share/nginx/html; }
}

线上务必加 allow 127.0.0.1; deny all; 或 WAF/IP 白名单。

2、输出结构总览 (v8)

{
  "version": 8,
  "nginx_version": "1.13.10",
  "timestamp": 1716458256437,
  "connections": { "accepted": 17302, "active": 13, "idle": 3 },
  "requests":     { "total": 92311, "current": 7 },

  "server_zones": {
    "app_server": {
      "processing": 3,
      "requests":   88100,
      "responses":  { "1xx":0, "2xx":86391, "3xx":0, "4xx":122, "5xx":587 },
      "sent":  "4.2g",
      "received":"1.1g"
    }
  },

  "caches": {
    "cache_backend": {
      "size": "8.3g", "max_size": "10g", "cold": false,
      "hit": { "responses": 45500, "bytes":"3.2g" },
      "miss":{ "responses": 8200,  "bytes":"650m" },
      "revalidated":{ "responses":2300 }, ...
    }
  },

  "upstreams": {
    "backend": {
      "zone": "http_backend",
      "peers": [
        {
          "id": 1,
          "server": "10.0.0.11:80",
          "weight": 5,
          "state": "up",
          "active": 2,
          "requests": 55000,
          "responses": { "2xx":54000, "5xx":1000 },
          "fails": 4,
          "unavail": 1,
          "header_time": 23,
          "response_time": 45,
          "selected": 1716458233210
        },
        ...
      ],
      "queue": { "size": 0, "max_size": 100, "overflows": 5 }
    }
  },

  "slabs": {
    "cache_backend": {
      "pages": { "used": 1030, "free": 18 },
      "slots": { "64": { "used":1234,"free":33,"reqs":1.2e6,"fails":0 }, ... }
    }
  }
}

3 、指令全解

指令	级别	作用	常见值	重点提示
`status;`	`location`	启动状态接口	–	最好配合内网监听、Basic Auth
`status_format`	`http/server/location`	JSON / JSONP	`json` (默认) `jsonp myCallback`	JSONP 可用变量：`jsonp $arg_cb`
`status_zone`★	`server`	把当前虚拟主机或 TCP 服务的指标写入共享内存	`status_zone app_server;`	名字随意；多个 server 同名 → 合并

4、核心监控指标一览

类别	必看字段	运维含义
全局	`connections.accepted/dropped`	战线长短、SYN flood？
	`requests.total/current`	QPS、突刺监测
server_zones	`processing`	当前活动请求（> 线程 = 拥堵）
	`responses.5xx`	应用错误率
upstreams.peers	`state`	`up/down/unavail/checking/unhealthy/draining`
	`fails / unavail`	后端故障次数、熔断触发
	`header_time / response_time`	后端平均延迟 (ms)
caches	`hit/miss/stale/revalidated`	缓存命中率
	`size / max_size / cold`	Loader 状态、磁盘占用
slabs	`fails`	共享内存OOM，须调大 zone
stream	`sessions.4xx/5xx`	L4 直连错误

5、分布式采集与可视化

Prometheus
- 用 telegraf / vector 拉取 /status → 转换为 metrics。
- 或开源 nginxstatus-exporter（自带 JSON→Prom）。
Grafana 示例 Dashboard
- 官方 ID 10229（Upstreams & Caches）
- 修改 JSON 数据源字段映射即可。
原生 HTML 面板
- /status.html + /status，快速瞄数值。

6、性能与资源考量

维度	开销来源	建议
CPU	计算 JSON / 字符串格式化	千级 QPS 影响可忽略
内存	`status_zone` 共享内存 `upstream zone` / `cache zone` 已有	`status_zone` 几 KB~MB 级；按 upstream * peers 数量预估
磁盘	N/A	仅 HTML 静态文件几 KB

7、升级迁移指北

旧版 status	新版 API (≥1.13.3) 对应路径
`/status` 全局	`/api`
`/status/server_zones`	`/api/http/server_zones`
`/status/upstreams`	`/api/http/upstreams`
`/status/caches`	`/api/http/caches`
`/status/stream`	`/api/stream/…`

脚本兼容方案：在 127.0.0.1 上用 rewrite ^/status/(.*)$ /api/$1 last; 过渡。

8、常见陷阱与排错

症状	可能原因	解决
404 /status	location 未配置 or 被 `deny all;`	检查 server 块优先级
`state":"draining"` 长期存在	上游被从配置移除但仍有连接	正常，待请求结束后消失
`slabs ... fails` 激增	共享内存耗尽	增大 `zone` 中 bytes
`upstreams.peers.*.response_time = 0`	无 `least_time` or old 1.6.x	升级 1.7.10+ 或换均衡算法
Cache `cold=true` 持续	cache loader 没跑完 or 权限	检查 `ps aux	grep cache_loader`

9、生产模板清单

9.1 单节点监控服务

server {
    listen 127.0.0.1:8080;
    location /status      { status; allow 127.0.0.1; deny all; }
    location = /status.js { status_format jsonp callback=$arg_cb; }
    location = /status.html {
        root /etc/nginx/html;  # 复制官方 status.html
    }
}

9.2 Prometheus Export

# 本地拉取
bash$ curl -s http://127.0.0.1/status \
 | jq -r '.server_zones | to_entries[]| "nginx_requests_total{zone=\""+.key+"\"} "+(.value.requests|tostring)'

用 cron/sidecar 5s PushGateway。

9.3 高可用 Upstream 灰度

upstream api {
    zone api_zone 128k;  # <<— 统计需 zone
    server v1 weight=9;
    server v2 weight=1 service=gray;
}
server {
    status_zone api_front;   # <<— 对外 server Zone
}

监控 /status/upstreams/api/peers/.../requests 实时对比灰度流量。

结语

虽已被更现代的 ngx_http_api_module 取代，ngx_http_status_module 依旧在大量旧版 Nginx 与商业发行版中承担核心监控职责。熟悉其数据结构、指令和监控指标，可以让你在 无第三方二进制、零外部插件 的前提下，实现细粒度 Upstream/缓存/连接健康度可观测。

如果你准备升级：