Nginx 通过 ngx_http_stub_status_module 提供轻量级状态接口，需在 server 块内配置受控 location，返回纯文本统计；必须启用模块、限制访问、解析指标用于监控或告警。
确认模块已编译启用
该模块多数发行版（如 Ubuntu/Debian 的 nginx-full、CentOS 官方包）默认包含，但需验证是否实际启用：
- 执行
nginx -V 2>&1 | grep -o with-http_stub_status-module，有输出即支持 - 若无输出，需重新编译 Nginx 并添加
--with-http_stub_status_module参数 - OpenResty 或 Alpine 精简镜像可能默认未启用，需检查基础镜像构建参数
在 server 块中配置 stub_status location
必须将配置写在某个 server{...} 块内部，不能放在 http 或顶层；推荐单独建一个仅监听本地或内网的 server：
- 示例配置（监听
127.0.0.1:8080）：
server {
listen 127.0.0.1:8080;
server_name localhost;
location /nginx-status {
stub_status on;
access_log off;
allow 127.0.0.1;
deny all;
}
}
-
stub_status on必须写在location内，且不可省略on -
access_log off避免状态页频繁访问刷爆日志 -
allow/deny是硬性要求，禁止公网暴露；可允许多个内网段，如allow 10.0.0.0/8;
理解返回内容与关键指标
访问 http://127.0.0.1:8080/nginx-status 得到类似响应：
Active connections: 24 server accepts handled requests 12456 12456 34567 Reading: 0 Writing: 3 Waiting: 21
- Active connections：当前所有活跃连接总数（含 Reading/Writing/Waiting）
- accepts / handled / requests：三个累加值，分别表示接受连接数、成功处理连接数、总 HTTP 请求次数
- Reading：正在读取客户端请求头的连接数（过高可能说明请求体大或客户端慢）
- Writing：正向客户端发送响应的连接数（过高可能后端延迟或网络瓶颈）
- Waiting：keep-alive 空闲等待新请求的连接数（通常应占 Active 大部分，属正常现象）
对接监控与自动化采集
该接口输出为固定格式纯文本，适合脚本解析或作为基础探活依据：
- 用
curl+ 正则提取活跃连接数：curl -s http://127.0.0.1:8080/nginx-status | grep "Active connections" | sed 's/[^0-9]//g' - Prometheus 场景下，不建议直接抓取 stub_status，应使用
nginx-prometheus-exporter或nginx-lua-prometheus转换为标准 metrics 格式 - 用于健康检查时，可结合 HTTP 状态码（200）和
Active connections是否异常飙升做简单告警
