ngx_http_stub_status_module 是 Nginx 内置轻量级状态监控模块，需显式配置 stub_status 指令启用，返回 Active connections、accepts、handled、requests 等实时连接与请求统计，适用于 Prometheus、Telegraf 等工具采集，但需限制访问且不支持细粒度分析。
要获取 Nginx 当前的实时运行状态（比如活跃连接数、请求处理量、吞吐统计等），ngx_http_stub_status_module 是最轻量、最直接的内置方案——它不依赖外部工具，无需 Lua 或第三方模块，只需几行配置就能暴露一个纯文本状态接口。
模块默认已编译，但需手动启用
该模块自 Nginx 0.7.1 起默认静态编译进主程序，但不会自动生效。你必须在 server 或 location 块中显式配置 stub_status 指令才能启用：
- 确保 Nginx 版本 ≥ 0.7.1（绝大多数现代发行版都满足）
- 检查是否真的启用：运行
nginx -V 2>&1 | grep -o with-http-stub-status-module，有输出即表示支持 - 若使用 Alpine/Debian 等精简包，极少数情况可能被裁掉；此时需重新编译并添加
--with-http-stub-status-module
基础配置：定义一个只读状态端点
推荐在独立 location 中暴露状态页，并限制访问来源，例如：
location /nginx_status {
stub_status;
allow 127.0.0.1; # 仅本地可访问
allow 10.0.0.0/8; # 或允许内网段
deny all;
}访问 http://your-domain/nginx_status 将返回类似以下纯文本内容：
Active connections: 3 server accepts handled requests 5829 5829 12345 Reading: 0 Writing: 1 Waiting: 2
- Active connections：当前全部活跃 TCP 连接数（含等待、接收、处理中）
- accepts：Nginx 自启动以来接受的总连接数
- handled：成功处理的连接数（通常等于 accepts，除非达到连接限制）
- requests：Nginx 自启动以来处理的 HTTP 请求总数
- Reading：正在读取请求头的连接数
- Writing：正在向客户端发送响应的连接数
- Waiting：处于 keep-alive 状态、等待新请求的空闲连接数（仅当启用了 keepalive）
配合监控系统采集数据
这个接口设计就是为自动化采集而生。常见用法包括：
- 用 Prometheus 的
nginx_stub_status_exporter或nginx-prometheus-exporter抓取并转为指标格式 - 用 Telegraf 的
inputs.nginx插件直连解析 - 用 shell 脚本 +
curl定时抓取，写入日志或推送到 Zabbix - 注意：接口无认证、无 JSON 格式、无时间戳，所有解析逻辑需自行实现或依赖成熟 exporter
安全与生产注意事项
虽然接口本身极简，但在生产环境仍需谨慎：
- 切勿将
/nginx_status暴露在公网；至少通过allow/deny或反向代理的 IP 白名单控制 - 避免放在根路径或易猜解路径（如
/status），建议带随机后缀或结合 auth_basic - 该模块不提供连接详情（如客户端 IP、URI）、不支持按虚拟主机拆分统计；如需更细粒度，应考虑
ngx_http_vhost_traffic_status_module或 OpenResty 生态 - 重启 Nginx 后计数器归零，不适合长期趋势分析，需配合外部存储做持续聚合
不复杂但容易忽略——一行 stub_status 就能打开 Nginx 的“生命体征”窗口，是运维可观测性的起点。
