tuning: NGINX 调优顾问模块

需要 GetPageSpeed NGINX Extras 订阅的专业计划（或更高版本）。

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

• RedHat Enterprise Linux 7、8、9 和 10
• CentOS 7、8、9
• AlmaLinux 8、9
• Rocky Linux 8、9
• Amazon Linux 2 和 Amazon Linux 2023

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023+CentOS/RHEL 7 和 Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-tuning

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-tuning

通过在 /etc/nginx/nginx.conf 顶部添加以下内容来启用模块：

load_module modules/ngx_http_tuning_module.so;

本文档描述了 nginx-module-tuning v1.2.0，于 2026 年 2 月 16 日发布。

---

基于数据的 NGINX 代理调优建议来自真实流量

停止猜测您的缓冲区大小。此模块观察您的实际流量模式，并准确告诉您该配置什么。

问题

每个 NGINX 代理设置指南都会告诉您调整 proxy_buffer_size、proxy_buffers 和超时。但您应该使用什么值呢？

传统的方法是对您的后端运行 curl 命令：

curl -s -w %{size_header} -o /dev/null https://backend.example.com

这给您一个单一的数据点。您的真实流量每分钟有成千上万的请求，每个请求都有不同的头部大小、主体大小和响应时间。单个 curl 命令无法告诉您造成生产环境中 upstream sent too big header 错误的第 95 个百分位数。

解决方案

此模块位于 NGINX 内部，被动观察每个代理请求，并构建实际流量的直方图。当您准备好时，查询 /tuning-advisor 端点：

{
  "sample_size": 847293,
  "uptime_seconds": 86400,
  "requests_per_second": 9.81,

  "proxy_buffer_size": {
    "observed": { "avg": "1.8k", "max": "23.4k", "p95_approx": "4.0k" },
    "recommendation": "OK",
    "suggested_value": "4k",
    "reason": "95% 的头部适合 4k"
  },

  "proxy_buffers": {
    "observed": { "avg": "12.3k", "max": "2.1m", "p95_approx": "32.0k" },
    "recommendation": "OK",
    "suggested_value": "8 4k",
    "reason": "默认的 32k (8x4k) 对 95% 的响应足够"
  },

  "nginx_config": {
    "snippet": "proxy_buffer_size 4k;\nproxy_buffers 8 4k;\nproxy_read_timeout 10s;\nclient_body_buffer_size 8k;",
    "apply_to": "http, server, or location block"
  }
}

复制代码片段，粘贴到您的配置中，重新加载。完成。

特性

指标收集

• 上游响应头部大小 → 调整 proxy_buffer_size
• 上游响应主体大小 → 调整 proxy_buffers
• 上游响应时间 → 调整 proxy_read_timeout
• 客户端请求主体大小 → 调整 client_body_buffer_size
• 连接重用比率 → 优化 keepalive 设置
• 缓存命中/未命中率 → 评估代理缓存的有效性

性能

• 无锁原子操作 — 无互斥锁，工作进程之间无争用
• 共享内存 — 所有工作进程共同贡献相同的计数器
• 基于直方图的百分位数 — 在不存储每个值的情况下近似 p95/p99
• 纳秒开销 — 每个请求约 10 次原子递增

输出格式

• JSON API，包含建议、原因和可直接使用的配置片段
• Prometheus 指标，可与 Grafana、Alertmanager 等集成
• 重置端点，用于清除计数器并开始新的观察窗口

快速开始

load_module modules/ngx_http_tuning_module.so;

http {
    # 启用所有代理请求的收集
    tuning_advisor on;

    server {
        # 暴露调优端点（限制访问！）
        location = /tuning-advisor {
            tuning_advisor_status;
            allow 127.0.0.1;
            allow 10.0.0.0/8;
            deny all;
        }

        location / {
            proxy_pass http://backend;
        }
    }
}

然后查询它：

curl http://localhost/tuning-advisor | jq .

配置参考

tuning_advisor

tuning_advisor on | off;

默认	off
上下文	http、server、location

在此上下文中启用代理请求的指标收集。

tuning_advisor_shm_size

tuning_advisor_shm_size 1m;

默认	1m
上下文	http

用于跨工作进程指标聚合的共享内存区域大小。1MB 对于固定大小的计数器和直方图来说足够了。

tuning_advisor_status

tuning_advisor_status;

上下文	location

启用状态处理程序。响应 GET（返回指标）、POST（重置指标）和带 ?reset 的 GET（也重置）。

API 参考

GET /tuning-advisor

返回 JSON 格式的观察到的指标、建议和可直接使用的配置片段。

响应结构：

部分	描述
sample_size	观察到的总代理请求数
uptime_seconds	自收集开始（或上次重置）以来的秒数
requests_per_second	平均请求速率
proxy_buffer_size	头部大小指标和建议
proxy_buffers	主体大小指标和建议
proxy_read_timeout	响应时间指标和建议
client_body_buffer_size	请求主体指标和建议
connection_reuse	客户端和上游 keepalive 的有效性
proxy_cache	缓存命中/未命中/绕过统计
nginx_config	复制粘贴的配置片段
histograms	自定义分析的原始桶计数

GET /tuning-advisor?prometheus

返回 Prometheus 展示格式：

## HELP nginx_tuning_requests_total 观察到的总代理请求数
## TYPE nginx_tuning_requests_total counter
nginx_tuning_requests_total 847293

## HELP nginx_tuning_header_size_bucket 头部大小分布
## TYPE nginx_tuning_header_size_bucket histogram
nginx_tuning_header_size_bucket{le="1024"} 423841
nginx_tuning_header_size_bucket{le="2048"} 712453
nginx_tuning_header_size_bucket{le="4096"} 831029
nginx_tuning_header_size_bucket{le="+Inf"} 847293

配置 Prometheus 抓取：

scrape_configs:
  - job_name: nginx-tuning
    metrics_path: /tuning-advisor
    params:
      prometheus: ['1']
    static_configs:
      - targets: ['nginx:80']

POST /tuning-advisor

将所有计数器重置为零并返回确认。适用于在配置更改后开始新的观察窗口。

GET /tuning-advisor?reset

与 POST 相同 — 重置所有指标。

推荐逻辑

该模块分析百分位数并提供可操作的建议：

指标	建议	何时
proxy_buffer_size	OK	p95 头部大小 ≤ 4KB
	INCREASE	p95 > 4KB（建议 8k、16k 或 32k）
	WARNING	p95 > 16KB（调查上游）
proxy_buffers	OK	p95 主体大小 ≤ 32KB
	INCREASE	p95 > 32KB（建议更大的缓冲区）
proxy_read_timeout	CONSIDER_REDUCING	p99 响应时间 < 5s
	OK	p99 在 5s 和 30s 之间
	WARNING	p99 > 30s（后端太慢）
connection_reuse	EXCELLENT	客户端 ≥ 80% 重用，上游 ≥ 70%
	WARNING	低重用（建议调整 keepalive）
proxy_cache	EXCELLENT	命中率 ≥ 80%
	WARNING	命中率 < 20%

直方图

该模块使用指数桶直方图来近似百分位数，而无需存储每个值：

大小桶： <1k、1-2k、2-4k、4-8k、8-16k、16-32k、32-64k、>64k

时间桶： <10ms、10-50ms、50-100ms、100-500ms、500ms-1s、1-5s、5-10s、>10s

原始桶计数可在 JSON 响应的 histograms 部分中找到，以供自定义分析。

安全考虑

/tuning-advisor 端点揭示了您的流量模式的信息。始终限制访问：

location = /tuning-advisor {
    tuning_advisor_status;

    # 仅允许来自本地主机和内部网络的访问
    allow 127.0.0.1;
    allow ::1;
    allow 10.0.0.0/8;
    allow 172.16.0.0/12;
    allow 192.168.0.0/16;
    deny all;

    # 或要求身份验证
    # auth_basic "Tuning Advisor";
    # auth_basic_user_file /etc/nginx/.htpasswd;
}

相关阅读

• 在 NGINX 中调整 proxy_buffer_size — 深入了解缓冲区大小
• NGINX 超时指令解释 — 理解所有超时设置