stub-status模块默认不启用，nginx编译时必须显式添加--with-http_stub_status_module参数；配置需在server块内定义location /stub_status并启用stub_status on指令，返回内容包含active connections、accepts、handled、requests等关键指标。
Stub-Status模块是否默认启用
不启用。Nginx编译时需显式添加 --with-http_stub_status_module，否则访问 /stub_status 会返回 404 或 403。Debian/Ubuntu 的 apt 安装包通常已内置该模块，但 CentOS Stream/RHEL 9+ 的官方 RPM 默认不启用——得自己确认：nginx -V 2>&1 | grep -o with-http_stub_status_module，无输出即未编译进内核。
如何配置并暴露 stub_status 接口
必须在 server 块（非 http 或 location 外层）中声明 location /stub_status，且需搭配 stub_status on 指令。常见错误是把它放在 location / 内部或漏写 on：
server {
listen 80;
server_name status.example.com;
location /stub_status {
stub_status on;
access_log off;
allow 127.0.0.1;
allow 10.10.0.0/16;
deny all;
}
}
注意：Nginx 1.13.10+ 支持更细粒度控制，如 stub_status basic（仅连接数）或 stub_status extended（含请求速率），但多数场景用默认 on 即可。
解析 stub_status 返回内容的关键字段
访问成功后返回纯文本，典型输出如下：
Active connections: 12 server accepts handled requests 12345 12345 67890 Reading: 0 Writing: 3 Waiting: 9
-
Active connections：当前所有 TCP 连接数（含 idle、reading、writing 状态），不是并发请求数 -
accepts：Nginx 自启动以来接受的总连接数 -
handled：成功处理的连接数（≈ accepts，若不等说明有连接被丢弃） -
requests：总 HTTP 请求次数（一个连接可承载多个 request） -
Reading：正在读取客户端请求头的连接数（通常极小） -
Writing：正向客户端发送响应的连接数（关键吞吐指标） -
Waiting：空闲 keep-alive 连接数（即 established 但无数据收发）
单位时间吞吐需自行计算：用两次采样间隔内的 requests 差值 ÷ 时间差（秒），而非直接看 Active connections。
为什么 curl 能通但 Prometheus 抓不到
常见于未正确设置 allow 规则或反向代理透传问题。Prometheus 默认用 http://localhost:80/stub_status 抓取，若 Nginx 监听在非 localhost 或被前置 LB 转发，需确保：
• allow 列表包含 Prometheus 所在 IP（不能只写 127.0.0.1）
• 若用 proxy_pass 暴露该接口，必须透传原始 Host 和路径，且后端 Nginx 的 location 需匹配真实路径
• 检查 SELinux（RHEL/CentOS）是否拦截：临时禁用测试 setenforce 0
真正容易被忽略的是：stub_status 输出无换行符保护，某些监控 Agent 对空白行敏感；建议加 add_header Content-Type text/plain; add_header Cache-Control no-cache; 避免缓存干扰。
