Prometheus采集Nginx状态

网站访问量突然下降却不知道原因，往往是因为没有采集 Nginx 的连接数和请求数。
这篇教程会带你用 nginx-prometheus-exporter 把 Nginx 状态暴露给 Prometheus，最终在 Prometheus 里查询到活跃连接、总请求数等关键指标。

准备条件与检查清单

开始前，请确认服务器上已经运行 Nginx，并且安装了 Prometheus。
如果还没有 Prometheus，需要先完成它的安装和启动。
另外，nginx-prometheus-exporter 是一个独立小程序，它负责读取 Nginx 的 stub_status 页面，再转换成 Prometheus 能识别的格式。

检查 Nginx 是否支持 stub_status 模块：

nginx -V 2>&1 | grep -o with-http_stub_status_module

如果输出 with-http_stub_status_module，说明支持。
如果没有输出，需要重新编译 Nginx 或更换支持该模块的版本。

开启 Nginx 状态页并验证

在 Nginx 配置目录中，找到站点配置文件，通常在 /etc/nginx/conf.d/ 或 /etc/nginx/sites-enabled/ 下。
添加一个单独的状态访问路径。

server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location /stub_status {
        stub_status;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

这段配置只允许本机访问，避免状态信息暴露到公网。
保存后执行：

nginx -t && nginx -s reload

打开浏览器或使用 curl 验证：

curl http://127.0.0.1:8080/stub_status

如果看到类似下面的内容，说明状态页已生效：

Active connections: 1 
server accepts handled requests
 10 10 25 
Reading: 0 Writing: 1 Waiting: 0 

其中 Active connections 是当前活跃连接数，accepts 是已接受连接总数，handled 是已处理连接总数，requests 是客户端请求总数。

安装并运行 nginx-prometheus-exporter

nginx-prometheus-exporter 可以从 GitHub Releases 下载二进制文件，也可以使用 Docker 运行。
下面以二进制方式为例。

wget https://github.com/nginxinc/nginx-prometheus-exporter/releases/download/v1.1.0/nginx-prometheus-exporter_1.1.0_linux_amd64.tar.gz
tar -xzf nginx-prometheus-exporter_1.1.0_linux_amd64.tar.gz
sudo mv nginx-prometheus-exporter /usr/local/bin/

启动 exporter，让它去抓取刚才配置的 stub_status 地址：

nginx-prometheus-exporter -nginx.scrape-uri http://127.0.0.1:8080/stub_status

默认监听 9113 端口。
验证 exporter 是否正常：

curl http://127.0.0.1:9113/metrics | grep nginx

你应该能看到 nginx_connections_active、nginx_http_requests_total 等指标。
如果看不到，检查 exporter 进程是否在运行，以及 scrape-uri 是否填写正确。

为了让 exporter 长期运行，建议用 systemd 管理。
创建文件 /etc/systemd/system/nginx-exporter.service：

[Unit]
Description=Nginx Prometheus Exporter
After=network.target

[Service]
User=nobody
ExecStart=/usr/local/bin/nginx-prometheus-exporter -nginx.scrape-uri http://127.0.0.1:8080/stub_status
Restart=on-failure

[Install]
WantedBy=multi-user.target

然后启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable --now nginx-exporter

在 Prometheus 中配置抓取任务

打开 Prometheus 配置文件 prometheus.yml，在 scrape_configs 下新增一个 job：

scrape_configs:
  - job_name: 'nginx'
    static_configs:
      - targets: ['127.0.0.1:9113']

保存后重启 Prometheus 或发送重载信号：

curl -X POST http://127.0.0.1:9090/-/reload

进入 Prometheus 的 Web 界面，点击顶部菜单 Status -> Targets，查看 nginx 这个 job 的状态是否为 UP。
如果显示 DOWN，把鼠标悬停在错误信息上，常见原因是 exporter 未启动或防火墙拦截了 9113 端口。

常用查询与告警思路

在 Prometheus 的查询框中输入以下表达式，可以快速查看网站访问指标：

• 当前活跃连接数：nginx_connections_active
• 总请求数：nginx_http_requests_total
• 每秒请求速率：rate(nginx_http_requests_total[1m])

如果希望连接数过高时收到通知，可以基于 nginx_connections_active > 100 这样的条件创建告警规则。
注意阈值需要根据你的服务器实际承载能力调整，不要直接照搬。

避坑与排查要点

状态页无法访问：检查 Nginx 配置中 listen 的端口是否被占用，以及 allow 和 deny 规则是否误拦了本机地址。

exporter 启动失败：确认 -nginx.scrape-uri 参数指向的地址能通过 curl 正常返回数据。
如果 Nginx 状态页使用了 HTTPS，需要把 URI 改成 https:// 并确保证书有效。

Prometheus 抓取不到数据：先检查 exporter 的 /metrics 接口是否有数据，再检查 Prometheus 的 targets 页面报错信息。
如果服务器开了防火墙，需要放行 9113 端口，但只建议对内网开放。

指标不更新：Nginx 的 stub_status 数据是实时变化的，如果 Prometheus 里长时间没有新数据，查看 exporter 日志是否出现连接超时。

如何确认监控已经生效

完成以上步骤后，在 Prometheus 查询框输入 nginx_http_requests_total，点击 Execute，如果能看到数值并随时间增加，说明 Prometheus 采集 Nginx 状态已经成功。
此时你可以进一步在 Grafana 中添加面板，把连接数和请求速率可视化，方便日常巡检。

如果刚开始接触，建议先只监控活跃连接数和总请求数这两个指标，等熟悉后再添加更复杂的告警规则。