stub status 是 nginx 内置轻量级状态监控模块，用于实时监测连接水位与请求处理节奏，需验证编译支持、正确嵌套于 server 块、安全暴露端点并解读 active/reading/writing/waiting 字段含义。
Stub Status 是 Nginx 内置的轻量级状态监控模块，不依赖外部组件，能实时反映连接水位和请求处理节奏。它不是“高阶监控方案”，而是排查连接耗尽、响应延迟、长连接堆积等问题的第一现场数据源。
确认模块是否可用并完成基础启用
多数发行版预编译 Nginx（如 Ubuntu 的 nginx-full、CentOS 的 nginx）已包含该模块，但需主动验证：
- 运行 nginx -V 2>&1 | grep with-http_stub_status_module，有输出即支持；无输出则需重编译并添加 --with-http_stub_status_module
- 模块仅在 HTTP 上下文生效，不能写在 http 块顶层或 stream 块中，必须嵌套在某个 server 块内
- 若配置后 reload 报错 unknown directive "stub_status"，说明模块未编译，而非配置语法问题
安全暴露监控端点（关键实操细节）
暴露路径本身极简，但安全控制缺一不可。推荐采用独立本地 server 块方式，避免与业务配置耦合：
- 监听 127.0.0.1:8081（不复用 80/443），路径设为 /_nxs（避开 /status 等易被扫描的通用名）
- 必须写 access_log off，否则每秒访问都会刷一条日志，I/O 和磁盘压力陡增
- 访问控制严格按顺序：先 allow 127.0.0.1 和 allow ::1，再 deny all；顺序颠倒会导致全拒
- 示例配置：
server {
listen 127.0.0.1:8081;
server_name _;
location /_nxs {
stub_status on;
access_log off;
allow 127.0.0.1;
allow ::1;
deny all;
}
}
读懂返回字段的真实含义
访问 http://127.0.0.1:8081/_nxs 返回三行纯文本，重点不在数值大小，而在状态分布逻辑：
- Active connections：当前所有 TCP 连接总数（含 Reading/Writing/Waiting），是判断是否逼近 worker_connections 上限的直接依据
- Reading：正在读请求头的连接数——通常为 0 或个位数；持续 >3 可能存在大 Body 上传或慢客户端
- Writing：正发响应的连接数——值高且持续增长，大概率指向后端响应慢或网络吞吐瓶颈
- Waiting：空闲 keep-alive 连接数 = Active − Reading − Writing；健康状态下应占 Active 的 70% 以上，过低说明连接复用不足或请求处理过快
对接监控系统与日常观测技巧
Stub Status 是瞬时快照，需采集+计算才有趋势价值：
- 抓取 Active connections：curl -s http://127.0.0.1:8081/_nxs | awk '/^Active/ {print $3}'
- 估算 QPS：(当前 requests 值 − 上次值) ÷ 采样间隔，需脚本维护历史值或接入 Prometheus
- Prometheus 推荐用 node_exporter textfile collector 中转：脚本每 10 秒提取指标，写成 nginx_stub_active_connections 142 格式到指定文件
- 人工临时查看务必走反向代理层加固：加 Basic Auth、限制内网 IP、隐藏 Connection 头，不直曝原始端点
