当前位置：首页 > 技术 > 正文内容

NGINX Prometheus Exporter 故障排除指南

访客技术 2026年8月14日 3

常见问题诊断清单

问题类别	可能原因	快速检查方法
连接失败	NGINX stub_status 未启用	`curl http://nginx-server:8080/stub_status`
权限问题	防火墙或 SELinux 限制	`telnet exporter-host 9113`
配置错误	错误的 scrape URI	检查 `--nginx.scrape-uri` 参数
指标缺失	NGINX Plus API 未配置	验证 API 端点访问权限
认证失败	缺少 TLS 证书	检查 SSL 证书配置

监控仪表板示例

上图展示了 NGINX Prometheus Exporter 与 Grafana 集成的监控仪表板，可实时查看连接状态、请求速率等关键指标。

连接问题排查

1. NGINX stub_status 端点不可达

这是最常见的连接问题。NGINX Prometheus Exporter 需要访问 NGINX 的 stub_status 页面或 NGINX Plus 的 API 端点。

验证 NGINX 配置：
```
nginx -t
```

确认 stub_status 已启用：在 NGINX 配置文件中添加：

server {
    listen 8080;
    location /stub_status {
        stub_status;
        allow 127.0.0.1;
        deny all;
    }
}

测试端点访问：
```
curl http://localhost:8080/stub_status
```

2. 防火墙和网络问题

解决方案：

确保端口 9113（Exporter）和 8080（NGINX）在防火墙中开放
检查 SELinux 策略（如使用）
验证网络连通性

配置错误排查

1. 命令行参数错误

NGINX Prometheus Exporter 支持多种启动参数，错误的配置会导致启动失败：

# 对于 NGINX OSS
nginx-prometheus-exporter --nginx.scrape-uri=http://nginx-server:8080/stub_status

# 对于 NGINX Plus
nginx-prometheus-exporter --nginx.plus --nginx.scrape-uri=http://nginx-plus-server:8080/api

# 使用 Unix Domain Socket
nginx-prometheus-exporter --nginx.scrape-uri=unix:/var/run/nginx.sock:/stub_status

2. 环境变量配置

可以通过环境变量替代命令行参数：

export SCRAPE_URI="http://localhost:8080/stub_status"
export NGINX_PLUS="false"
export LISTEN_ADDRESS=":9113"
nginx-prometheus-exporter

安全与认证问题

1. TLS/SSL 配置问题

当 NGINX 使用 HTTPS 或需要客户端证书认证时：

nginx-prometheus-exporter \
  --nginx.scrape-uri=https://nginx-server:8443/stub_status \
  --nginx.ssl-verify \
  --nginx.ssl-ca-cert=/path/to/ca.crt \
  --nginx.ssl-client-cert=/path/to/client.crt \
  --nginx.ssl-client-key=/path/to/client.key

2. 基础认证配置

使用 web-config.yml 文件配置基本认证：

basic_auth_users:
  prometheus: $2y$10$hashed_password_here

启动命令：

nginx-prometheus-exporter --web.config.file=web-config.yml

指标显示问题

1. 指标完全缺失

如果访问 http://exporter-host:9113/metrics 没有返回任何 NGINX 指标：

检查 Exporter 日志：

journalctl -u nginx-prometheus-exporter -f

验证 scrape URI：
- 确保 URI 格式正确
- 确认使用的是正确的端口和路径
- 检查网络连通性
检查 NGINX 状态：
```
systemctl status nginx
```

2. 部分指标缺失

对于 NGINX Plus，某些指标需要额外配置：

Server Zones 指标：需要配置 status_zone 指令
Upstream 指标：需要配置 zone 指令在 upstream 块中

Docker 容器问题

1. 容器启动失败

常见错误及解决方案：

# 错误：端口绑定冲突
docker run -p 9113:9113 nginx/nginx-prometheus-exporter:latest

# 解决方案：检查端口占用
netstat -tlnp | grep 9113

2. 容器网络问题

当 Exporter 在容器中而 NGINX 在宿主机时：

# 使用主机网络模式
docker run --network=host nginx/nginx-prometheus-exporter:latest \
  --nginx.scrape-uri=http://localhost:8080/stub_status

# 或使用 Docker 网络别名
docker network create nginx-net
docker run --network=nginx-net --name=nginx nginx:latest
docker run --network=nginx-net nginx/nginx-prometheus-exporter:latest \
  --nginx.scrape-uri=http://nginx:8080/stub_status

系统服务配置

1. systemd 服务问题

使用 examples/systemd/ 中的配置模板：

常见问题：

服务权限不足
环境变量未正确设置
Socket 激活配置错误

调试命令：

# 检查服务状态
systemctl status nginx_exporter

# 查看详细日志
journalctl -u nginx_exporter -n 50 -f

# 重新加载配置
systemctl daemon-reload
systemctl restart nginx_exporter

性能优化建议

1. 调整超时设置

默认 5 秒超时可能不够，可以适当增加：

nginx-prometheus-exporter --nginx.timeout=30s

2. 使用多个 scrape URI

对于多个 NGINX 实例：

nginx-prometheus-exporter \
  --nginx.scrape-uri=http://nginx1:8080/stub_status \
  --nginx.scrape-uri=http://nginx2:8080/stub_status \
  --nginx.scrape-uri=http://nginx3:8080/stub_status

高级调试技巧

1. 启用详细日志

# 设置日志级别为 debug
nginx-prometheus-exporter --log.level=debug

# 或通过环境变量
export LOG_LEVEL=debug
nginx-prometheus-exporter

2. 使用 Prometheus 调试工具

# 直接测试指标端点
curl -v http://localhost:9113/metrics

# 检查 Prometheus 目标状态
# 在 Prometheus Web UI 中查看 /targets 页面

3. 监控 Exporter 自身指标

NGINX Prometheus Exporter 也暴露自身的监控指标：

nginx_exporter_build_info - Exporter 构建信息
promhttp_metric_handler_requests_total - 请求统计
go_* - Go 运行时指标

实用工具和命令

快速诊断脚本

#!/bin/bash
echo "=== NGINX Prometheus Exporter 诊断工具 ==="
echo "1. 检查 Exporter 进程..."
ps aux | grep nginx-prometheus-exporter

echo "2. 测试指标端点..."
curl -s http://localhost:9113/metrics | head -20

echo "3. 检查 NGINX stub_status..."
curl -s http://localhost:8080/stub_status

echo "4. 验证端口监听..."
netstat -tlnp | grep -E '9113|8080'

echo "5. 检查系统日志..."
journalctl -u nginx-prometheus-exporter --since "1 hour ago" | tail -20

总结

通过本指南，您应该能够解决 NGINX Prometheus Exporter 的大多数常见问题。记住故障排除的关键步骤：

验证基础连接 - 确保网络和端口可达
检查配置参数 - 确认 scrape URI 和启动参数正确
查看日志信息 - 日志通常包含详细的错误信息
逐步测试 - 从简单到复杂，逐步验证每个环节

如果问题仍然存在，可以参考项目的 ISSUE_LIFECYCLE.md 文件了解如何提交问题报告，或在社区中寻求帮助。祝您监控顺利！

标签: Nginx

返回列表

上一篇：基于STM32F429与LAN8720A的嵌入式以太网开发实战

下一篇：Django 模型外键反向关联名称配置解析

Linux crontab 详解

1) crontab 是什么cron 是 Linux 的定时任务守护进程；crontab 是用来编辑/查看“按时间周期执行命令”的表（cron table）。常见两类：用户 crontab：每个用户一份（crontab -e 编辑）系统级 crontab / cron.d：可指定执行用户（/etc/crontab、/etc/cron.d/*）2) crontab 时间...

富文本里可以允许的 HTML 属性

一、所有标签默认允许的安全属性（极少）class （可选）id （通常建议禁用）title️ 注意：id 容易被滥用做锚点注入，很多系统直接禁用class 允许的话最好只允许固定前缀（如 editor-*）二、a 标签允许属性<a href="" t...

方法一：通过官网安装包（最简单，适合初学者）如果你只是想快速安装并开始使用，这是最直接的方法。访问 Node.js 官网。页面会显示两个版本：LTS (Recommended For Most Users)：长期支持版，最稳定。建议选这个。Current：最新特性版，包含最新功能但可能不够稳定。下载 .pkg 安装包并运行。按照安装向导点击“下一步”即可完成。方法二：使用 Homebrew 安装（...

Dom\HTML_NO_DEFAULT_NS 的副作用：自动加闭合标签

在使用Dom\HTMLDocument时，Dom\HTML_NO_DEFAULT_NS 将禁止在解析过程中设置元素的命名空间, 此设置是为了与DOMDocument向后兼容而存在的。当使用它时，已知的一个副作用就是：自动加闭合标签例如 </img> 为什么会这样？当你使用：Dom\HTML_NO_DEFAULT_NS文档会变成无命名空间模式，此时内部更接近 XML...

Laravel 事件和监听器创建

在 Laravel 中，使用 Artisan 命令创建 Events（事件）和 Listeners（监听器）是非常高效的。你可以通过以下几种方式来实现：1. 手动创建单个 Event如果你只想创建一个事件类，可以使用 make:event 命令：Bashphp artisan make:event UserRegistered执行后，文件将生成在 app/Even...

自定义域名解析神器 dnsmasq

什么是 dnsmasq？dnsmasq 是一个轻量级、功能强大的网络服务工具，专为小型和中等规模网络设计。它是一个综合的网络基础设施解决方案[1]。dnsmasq 能做什么？功能说明应用场景DNS 转发与缓存将 DNS 查询转发到上游服务器（ISP、Google DNS 等），并在本地缓存结果加快 DNS 查询速度，减少外部 DNS 流量本地 DNS解析本地网络设备的主机名，无需编辑&n...

老程序员博客