实战 Nginx 结合 VTS 模块实现基于虚拟主机维度的实时流量与错误率看板-Nginx-PHP中文网

vhost_traffic_status需正确配置server_name、location /status位置、Nginx版本与VTS分支匹配、vhost_traffic_status_zone指令及模块加载，否则流量统计和错误率为空。

实战 nginx 结合 vts 模块实现基于虚拟主机维度的实时流量与错误率看板

直接用 vhost_traffic_status 就能按 server_name 实时分组统计流量和错误率，但 90% 的人配完看不到数据，问题不在模块没装好，而在 server_name 没生效、location /status 放错位置，或 Nginx 版本不兼容。

确认 Nginx 版本与 VTS 模块是否真正兼容

VTS 模块对 Nginx 主版本极其敏感：它不支持 1.25+，1.24.x 需用 vts-0.1.18 分支，1.22.x 推荐用 vts-1.22 分支。拉错分支或硬套 master 会导致编译通过但运行时指标全为 0 或崩溃。

执行 nginx -v 查版本，再查对应 GitHub release 页面（如 vozlt/nginx-module-vts）找匹配分支
./configure 必须显式带 --add-module=/path/to/nginx-module-vts，路径不能是软链接，否则报 no such file or directory
编译后验证：nginx -V 2>&1 | grep vts 有输出才说明加载成功；若无，检查 objs/Makefile 是否含该模块编译项

location /status 必须放在 server 块内，且 URI 严格匹配

/status 返回空白页或 404，大概率是配置位置错了——vhost_traffic_status_display 指令必须在 server 块里，不能写在 http 块顶层；否则 VTS 拿不到虚拟主机上下文，所有流量都归到 default 或丢弃。

正确写法：

server {
  listen 80;
  server_name api.example.com;
  location /status {
    vhost_traffic_status_display;
    vhost_traffic_status_display_format html;
  }
}

URI 必须完全一致：/status 可以，/status/、/status/index.html 或加 rewrite 都会 404
HTTPS 场景下，若前端有 TLS 终止代理（如 ALB、Cloudflare），需确保其不 strip User-Agent 或自定义 header，否则部分 VTS 内部请求可能被拦截

server_name 是唯一标识，空值或重复会导致数据混杂

VTS 默认用 server_name 作为 serverZones 的 key。如果某个 server 块没写 server_name，或多个 server 共用同一个 server_name，数据就会堆在 127.0.0.1 或随机合并条目里，根本分不清哪个域名出了 5xx 错误。

Nginx Hosting

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

下载

每个 server 块必须有明确、唯一、非通配的 server_name，例如 app.example.com、admin.example.com
通配符 *.example.com 在 VTS 中不会自动展开为具体域名，只会生成一个叫 *.example.com 的条目，无法区分子域
测试是否生效：访问 /status/format/json，检查返回 JSON 中 serverZones 对象的 key 是否与你配置的 server_name 完全一致

错误率看板依赖状态码字段，别漏掉 vhost_traffic_status_zone

错误率（比如 4xx/5xx 占比）需要 VTS 在共享内存中维护各状态码计数器，而这个能力由 vhost_traffic_status_zone 指令启用。没配这行，JSON 里 responses 下的 4xx、5xx 字段永远是 0。

必须在 http 块顶部加：vhost_traffic_status_zone shared:vts_zone:10m;（10m 是最小推荐值，每万 QPS 留 1MB）
该指令只写一次，不要在每个 server 块里重复写，否则 Nginx 启动失败
HTML 页面里“Server Zones”标签页中的 4xx、5xx 列，就是从这里来的；若为空，先查这个 zone 是否存在、大小是否够用

最易忽略的是：VTS 的 HTML 页面本身不缓存、不压缩、不做分页，一旦虚拟主机超过 50 个，/status 加载就卡死，而 JSON 接口又默认不限流——监控脚本高频轮询会直接拖垮 Nginx 进程。真要长期用，得关 HTML、用 /status/format/json + Prometheus 抓取，别信“开箱即用”的页面。