实战演示 Nginx 结合 vts-module 实现 Prometheus 格式的网关实时监控指标导出-Nginx-PHP中文网

vts-module 不输出 Prometheus 格式，需通过 vts-exporter 转换；编译 Nginx 必须启用 --add-module=/path/to/nginx-module-vts、--with-http_v2_module 和 --with-http_ssl_module，且需正确定义 upstream 块，否则指标缺失关键维度或全归入 default zone。

实战演示 nginx 结合 vts-module 实现 prometheus 格式的网关实时监控指标导出

直接上结论：vts-module 本身不输出 Prometheus 格式，必须通过 vts-exporter 这个中间服务做协议转换；Nginx 编译时漏掉 --with-http_v2_module 或未启用 upstream 配置，会导致指标缺失关键维度（如 upstream name、status code 分布）。

编译 Nginx 时必须启用 vts-module 和必要模块

vts-module 是第三方模块，不内置，且依赖明确的 HTTP 模块支持。缺任意一项，/status/format/json 接口要么 404，要么返回空或无 upstream 数据。

必须显式添加：--add-module=/path/to/nginx-module-vts
必须启用：--with-http_v2_module（否则 vts 的 upstream 统计不生效）
必须启用：--with-http_ssl_module（若后端 upstream 用 HTTPS，vts 才能识别 scheme 和 port）
避免使用太旧的 Nginx 版本（建议 ≥ 1.18），vts-module 对 1.21+ 兼容性更稳

验证是否生效：启动后请求 curl http://localhost/status/format/json，响应中应含 "upstreamZones" 字段，且每个 upstream name 下有 "requestCounter"、"inBytes"、"responseCodes" 等嵌套结构。

nginx.conf 中 upstream 和 vts 配置要严格对应

vts-module 的指标粒度完全取决于 Nginx 配置里是否定义了 upstream 块——它不会自动从 proxy_pass http://host:port 解析出逻辑 upstream 名。没配 upstream，所有流量就归到 default zone，无法区分后端服务。

错误写法：proxy_pass http://10.0.1.100:8080;（无 upstream，vts 只记为 "default"）

正确写法：

upstream api_backend {
    server 10.0.1.100:8080;
    server 10.0.1.101:8080;
}
server {
    location /api/ {
        proxy_pass http://api_backend;
    }
}

若用变量动态 upstream（如 proxy_pass http://$backend），vts 无法聚合，一律计入 "default" zone

注意：upstream 名称会直接成为 Prometheus label 中的 upstream 值，建议全小写+下划线，避免特殊字符。

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

vts-exporter 是唯一可行的 Prometheus 指标导出方式

Nginx + vts-module 只提供 JSON 接口，Prometheus 抓取必须是文本格式（text/plain; version=0.0.4）。没有官方 exporter，社区通用方案是 vts-exporter（Go 编写，轻量）。

下载预编译二进制：vts-exporter-0.12.0-linux-amd64（注意匹配系统架构）
启动命令示例：./vts-exporter --nginx.scrape-uri=http://localhost/status/format/json --web.listen-address=:9913
关键参数：--nginx.scrape-uri 必须指向 Nginx 的 vts JSON 接口，不能是 HTML 或 XML 格式地址
抓取间隔由 Prometheus 配置控制，vts-exporter 自身不缓存，每次请求都实时调用 Nginx 接口

验证：访问 http://localhost:9913/metrics，应看到类似 nginx_vts_upstream_requests_total{upstream="api_backend",code="200"} 的指标行，且数值与 /status/format/json 中对应字段一致。

Prometheus 配置和常见数据断点排查

即使 exporter 正常，Prometheus 也可能拉不到数据，多数因 target 状态为 DOWN 或指标无值。重点查三处：

target 页面显示 context deadline exceeded → 检查 vts-exporter 是否能通 Nginx（curl -I http://localhost/status/format/json）
target 显示 UP，但指标为空 → 检查 Nginx 日志是否有 no resolver defined（vts 在解析 upstream host 时失败，导致 zone 初始化异常）
有指标但 upstream label 全是 default → 回头确认 Nginx 配置中是否真有命名 upstream 块，且 proxy_pass 引用的是该名称
status code 分布始终为 0 → 确认 Nginx 启用了 log_format 且 access_log 开启（vts 的 responseCodes 统计依赖 access log 解析）