Nginx stub_status 指南从启用到监控落地的全流程详解-EW帮帮网

1、模块定位

轻量：核心指标只有 6 行文本，单次响应 < 200 B。
零依赖：无需共享内存、无需 JS，可在任何 shell 中 curl。
快速：读取全局原子计数，不会遍历连接池，毫秒级返回。
遗留兼容：很多老运维脚本（zabbix、cacti、nagios）默认解析它。
如果需要 Upstream / 缓存 / 连接池维度，请考虑 ngx_http_api_module (≥ 1.13.3) 或商业版 status。

2、最小可用配置

server {
    listen 127.0.0.1:8080;          # 仅本机

    location /basic_status {
        stub_status;                # 1.7.5+ 不再需要“on”
        allow 127.0.0.1;            # ★强烈建议加 ACL
        deny  all;
    }
}

访问：

$ curl http://127.0.0.1:8080/basic_status
Active connections: 34
server accepts handled requests
 1946572 1946572 3558741
Reading: 3 Writing: 12 Waiting: 19

3、输出字段逐一解读

行	字段	公式 / 含义	运维关注点
1	`Active connections`	当前活跃 TCP 连接数 = Reading + Writing + Waiting	突升→长连接激增/攻击
2-3	(表头 + 三列)	`accepts`：⽣成的 TCP 连接总计 `handled`：成功建链数（资源不足可 < accepts） `requests`：HTTP 请求数（包括 keep-alive 内第二、三…次）	请求 / 连接比评估：`requests / accepts ≈ keep-alive 平均复用次数`
4	`Reading`	正在读请求头	IO 阻塞、慢客户端
	`Writing`	正在回包	上游慢 / 网速慢
	`Waiting`	已握手、空闲 Keep-alive 数	太低→排队；太高→闲连浪费

4、内嵌变量（1.3.14+）

可在 log_format、map、set、lua 等处使用。

变量	等价字段	场景示例
`$connections_active`	Active connections	shell_exporter 推送自定义 metrics
`$connections_reading`	Reading	将 header 注入 PromTail：`add_header X-Reading $connections_reading`;
`$connections_writing`	Writing	Lua 限流：`if tonumber(ngx.var.connections_writing) > 100 then ... end`
`$connections_waiting`	Waiting	分流高并发到只读节点

5、典型部署 & 安全加固

5.1 本地 + sidecar 采集（推荐）

Nginx ↔ 127.0.0.1:8080/basic_status ← sidecar exporter → Prometheus

生产端口不上公网；
Sidecar 负责转 Prometheus 指标格式（文本或 PushGateway）。

5.2 多实例统一入口

map $hostname $stub_up {
    default 127.0.0.1:8080;
    web-2   127.0.0.2:8080;
}
server {
    listen 9000 ssl; auth_basic ...;
    location /status {
        proxy_pass http://$stub_up/basic_status;
    }
}

运维只暴露 1 个 HTTPS；
通过 $hostname 把多台 Nginx 的 stub_status 聚合。

6、Prometheus / Grafana 实战

6.1 telegraf 示例

[[inputs.exec]]
  commands = ["curl -s http://127.0.0.1:8080/basic_status"]
  data_format = "nginx"
  name_override = "nginx_stub"

data_format="nginx" 内置解析 stub_status，自动产出 8 个字段。

6.2 grafana.com Dashboard IDs

ID	说明
10000	官方轻量仪表，仅连接/请求
2949	community，包含 Reading/Writing/Waiting 趋势

7、模块对比

功能	stub_status	status (商业)	api
连接级	✅	✅	✅
Upstream 细节	❌	✅	✅
Cache 统计	❌	✅	✅
Stream(L4)	❌	✅	✅
JSON	❌	✅	✅
轻量/易启	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐

8、性能与常见误区

误区 / 问题	说明	正解
“开了 stub_status QPS 就掉”	可能被外网频繁轮询，导致长 keep-alive 占用	内网监听或 rate-limit (`limit_req zone=monitor 1r/s`)
`handled < accepts`	worker_connections 用尽或系统 FD 限制	查看 `error.log` 中 “worker_connections are not enough”
`Waiting` 长期 0	关闭 keep-alive（或代理通道关闭）	`keepalive_timeout 75` 建议开启
`Active connections` 高但 QPS 低	浏览器长轮询 / websocket	评估升级 `worker_connections`

9、FAQ

Q1. 是否能出 JSON？
A. 原生不行，需 awk/lua 或升级 api 模块。

Q2. stub_status 会拖慢 Nginx 吗？
A. 读取共享原子计数 ≈ ++int; 单次响应 100–200 B，可忽略。

Q3. Windows Nginx 支持吗？
A. 只要编译打开即可，行为一致。

Q4. 如何同时监控多 worker？
A. 这些全局计数是跨 worker 汇总的，不需额外汇聚。

结语

如果你只想在“1 分钟”内拿到在线连接数、累计请求量、读写等待指标——stub_status 依然是最简单、最轻量、最兼容的方案。

对于需要更丰富度量的现代集群，请逐步迁移到 ngx_http_api_module 或官方商业 API；但在迁移完成前，掌握 stub_status 的安全暴露、采集脚本与指标含义，依旧是 Nginx 运维的基本功。祝你监控顺畅，问题秒定位！

Nginx stub_status 指南从启用到监控落地的全流程详解