Web 服务器与网关 / 知识点
Nginx 配置指令速查手册
反向代理
指定代理响应临时文件目录及目录层级。
proxy_temp_path
指定代理响应临时文件目录及目录层级。调整前先区分建连、发送、读取、缓冲和重试分别处在哪个阶段,避免用一个参数掩盖另一个问题。
语法
proxy_temp_path path [level1 [level2 [level3]]];上下文: http、server、location
推荐配置
proxy_temp_path /var/cache/nginx/proxy_temp 1 2;关键行为
目录必须可写且磁盘空间充足;磁盘占满会影响大响应和代理稳定性。
验证
sudo nginx -t相关指令: proxy_max_temp_file_size
控制是否拦截上游的指定错误响应并交给 error_page 处理。
proxy_intercept_errors
控制是否拦截上游的指定错误响应并交给 error_page 处理。调整前先区分建连、发送、读取、缓冲和重试分别处在哪个阶段,避免用一个参数掩盖另一个问题。
语法
proxy_intercept_errors on | off;上下文: http、server、location
推荐配置
proxy_intercept_errors on;
error_page 502 /50x.html;关键行为
开启后仅对满足错误处理条件的上游响应生效;会改变客户端看到的上游错误页面。
验证
sudo nginx -t相关指令: error_page
改写上游响应中的 Location 和 Refresh 重定向地址。
proxy_redirect
改写上游响应中的 Location 和 Refresh 重定向地址。调整前先区分建连、发送、读取、缓冲和重试分别处在哪个阶段,避免用一个参数掩盖另一个问题。
语法
proxy_redirect default | off | redirect replacement;上下文: http、server、location
推荐配置
proxy_redirect http://backend:8080/ /;关键行为
当上游返回内部地址时可重写为对外地址;使用变量形式的 proxy_pass 时不能使用 default。
验证
sudo nginx -t相关指令: proxy_pass
定义哪些上游失败条件允许当前请求切换到下一个节点。
proxy_next_upstream
后端节点失败时,需要明确哪些错误允许当前请求换节点重试时查这个指令。
语法
proxy_next_upstream condition ...;上下文: http、server、location
推荐配置
location /api/ {
proxy_connect_timeout 1s;
proxy_read_timeout 5s;
proxy_next_upstream error timeout invalid_header
http_502 http_503 http_504;
proxy_next_upstream_tries 2;
proxy_next_upstream_timeout 6s;
proxy_pass http://app_backend;
}关键行为
- 重试只能在尚未向客户端发送响应时发生。
- POST/PATCH 等非幂等请求不要为了“提高成功率”随意启用
non_idempotent,否则可能产生重复写入。 - 次数和总时间建议同时封顶,避免故障时遍历大量节点。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -i http://127.0.0.1/api/health
tail -n 20 /var/log/nginx/error.log常见问题
- 所有节点都失败:检查
$upstream_addr、$upstream_status和后端连通性。 - 接口出现重复写:检查是否错误重试了非幂等请求。
相关指令: proxy_next_upstream_tries、proxy_next_upstream_timeout
限制一次请求最多尝试多少个上游。
proxy_next_upstream_tries
限制一次请求最多尝试多少个上游。调整前先区分建连、发送、读取、缓冲和重试分别处在哪个阶段,避免用一个参数掩盖另一个问题。
语法
proxy_next_upstream_tries number;上下文: http、server、location
推荐配置
proxy_next_upstream_tries 2;关键行为
用于给失败切换次数封顶,避免故障时遍历大量节点。
验证
sudo nginx -t相关指令: proxy_next_upstream
限制一次请求在多个上游间重试的总时间窗口。
proxy_next_upstream_timeout
限制一次请求在多个上游间重试的总时间窗口。调整前先区分建连、发送、读取、缓冲和重试分别处在哪个阶段,避免用一个参数掩盖另一个问题。
语法
proxy_next_upstream_timeout time;上下文: http、server、location
推荐配置
proxy_next_upstream_timeout 6s;关键行为
与 tries 同时设置可同时限制次数和总耗时。
验证
sudo nginx -t相关指令: proxy_next_upstream_tries
选择代理响应缓存区域,或关闭继承的代理缓存。
proxy_cache
选择代理响应缓存区域,或关闭继承的代理缓存。调整前先区分建连、发送、读取、缓冲和重试分别处在哪个阶段,避免用一个参数掩盖另一个问题。
语法
proxy_cache zone | off;上下文: http、server、location
推荐配置
proxy_cache off;关键行为
需要先用 proxy_cache_path 定义缓存区域;本查询表只覆盖你当前指南中涉及的开关用途。
验证
sudo nginx -t相关指令: proxy_buffering
上游与连接复用
定义一组可被 proxy_pass 引用的上游服务器。
upstream
需要把多个后端抽象成一个命名服务组,并配置负载均衡或连接复用时查这个指令。
语法
upstream name { ... }上下文: http
推荐配置
upstream app_backend {
least_conn;
server 10.0.0.11:8080 max_fails=2 fail_timeout=10s;
server 10.0.0.12:8080 max_fails=2 fail_timeout=10s;
keepalive 32;
}
server {
listen 80;
server_name api.example.com;
location / {
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_pass http://app_backend;
}
}关键行为
- 不写算法时使用加权轮询。
keepalive是每个 worker 缓存的空闲上游连接数,不是总连接数限制。- 开源 Nginx 的常规健康处理以被动失败检测为主;不要把
max_fails当成主动健康检查。
验证
sudo nginx -t && sudo systemctl reload nginx
for i in $(seq 1 5); do curl -sS http://127.0.0.1/health; done常见问题
- 请求只到一个节点:检查算法、节点是否 down、连接失败和权重。
- 频繁 502:先逐个直连后端,再看 Nginx 重试链路。
相关指令: server(upstream 节点)、least_conn、ip_hash
在 upstream 中定义后端节点及权重、失败阈值等参数。
server(upstream 节点)
需要为某个后端节点设置地址、权重、失败阈值或备用状态时查这个指令。
语法
server address [parameters];上下文: upstream
推荐配置
upstream app_backend {
server 10.0.0.11:8080 weight=2 max_fails=2 fail_timeout=10s;
server 10.0.0.12:8080 weight=1 max_fails=2 fail_timeout=10s;
}关键行为
weight是相对请求分配权重,不是并发上限。max_fails与fail_timeout依赖真实请求触发失败统计;单节点 upstream 没有可切换节点时意义有限。
验证
sudo nginx -t
curl -sS http://10.0.0.11:8080/health
curl -sS http://10.0.0.12:8080/health常见问题
- 权重调整后延迟反而变差:检查节点实际容量,不要把权重当容量保护。
相关指令: upstream、proxy_next_upstream
把新请求优先分配给活跃连接数更少的上游节点。
least_conn
把新请求优先分配给活跃连接数更少的上游节点。参数应结合节点容量、请求耗时和连接复用情况压测,不把单一数值当作通用最优配置。
语法
least_conn;上下文: upstream
推荐配置
upstream app_backend {
least_conn;
server 10.0.0.11:8080;
server 10.0.0.12:8080;
}关键行为
适合请求耗时差异大或长连接场景;它依据连接数,不直接感知 CPU 或实际延迟。
验证
sudo nginx -t相关指令: upstream
根据客户端 IP 为请求选择相对稳定的上游节点。
ip_hash
根据客户端 IP 为请求选择相对稳定的上游节点。参数应结合节点容量、请求耗时和连接复用情况压测,不把单一数值当作通用最优配置。
语法
ip_hash;上下文: upstream
推荐配置
upstream app_backend {
ip_hash;
server 10.0.0.11:8080;
server 10.0.0.12:8080;
}关键行为
前面存在 NAT/代理且真实 IP 未恢复时可能导致流量集中;长期会话状态更适合共享存储。
验证
sudo nginx -t相关指令: set_real_ip_from、upstream
设置每个 worker 可缓存的空闲上游连接数量。
keepalive(upstream)
上游频繁建立 TCP/TLS 连接、短请求很多时查这个指令。
语法
keepalive connections;上下文: upstream
推荐配置
upstream app_backend {
server 10.0.0.11:8080;
server 10.0.0.12:8080;
keepalive 32;
}
location /api/ {
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_pass http://app_backend;
}关键行为
- 数值表示每个 worker 保存的空闲连接缓存数量,不限制活跃连接总数。
- 连接池过大仍可能压高后端空闲连接数,应结合后端连接上限和压测调整。
验证
sudo nginx -t && sudo systemctl reload nginx
ss -nt | grep ':8080' | head常见问题
- 配置了 keepalive 但仍大量新建连接:检查 HTTP 版本、Connection 头和后端是否主动关闭连接。
相关指令: proxy_http_version、keepalive_timeout
设置客户端 Keep-Alive 空闲连接保持时间。
keepalive_timeout
设置客户端 Keep-Alive 空闲连接保持时间。参数应结合节点容量、请求耗时和连接复用情况压测,不把单一数值当作通用最优配置。
语法
keepalive_timeout timeout [header_timeout];上下文: http、server、location
推荐配置
keepalive_timeout 30s;关键行为
过长会占用更多连接资源,过短会增加 TCP/TLS 重建开销。
验证
sudo nginx -t相关指令: keepalive_requests、keepalive_time
限制一个客户端 Keep-Alive 连接最多处理的请求数。
keepalive_requests
限制一个客户端 Keep-Alive 连接最多处理的请求数。参数应结合节点容量、请求耗时和连接复用情况压测,不把单一数值当作通用最优配置。
语法
keepalive_requests number;上下文: http、server、location
推荐配置
keepalive_requests 1000;关键行为
值过高会让连接相关内存长期保留;现代 HTTP/2 也使用该指令控制连接上的请求数量。
验证
sudo nginx -t相关指令: keepalive_timeout、http2
限制一个客户端 Keep-Alive 连接的最长总寿命。
keepalive_time
限制一个客户端 Keep-Alive 连接的最长总寿命。参数应结合节点容量、请求耗时和连接复用情况压测,不把单一数值当作通用最优配置。
语法
keepalive_time time;上下文: http、server、location
推荐配置
keepalive_time 1h;关键行为
达到时间后,当前请求结束时会关闭连接,可用于周期性释放连接资源。
验证
sudo nginx -t相关指令: keepalive_timeout
压缩与协议
开启或关闭响应 Gzip 压缩。
gzip
需要降低文本响应带宽时查这个指令。建议把它与最小长度、压缩级别和 MIME 类型一起配置,而不是只开一个 gzip on。
语法
gzip on | off;上下文: http、server、location、if in location
推荐配置
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_comp_level 5;
gzip_types
text/plain
text/css
application/json
application/javascript
application/xml
image/svg+xml;关键行为
- 压缩级别越高 CPU 成本通常越高,生产起点常用中等等级,再结合压测调整。
- 已经高度压缩的图片/视频通常没有必要再 gzip。
text/html由 Nginx 内建处理,不需要为了它单独重复加入 gzip_types。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -I -H 'Accept-Encoding: gzip' https://example.com/app.js常见问题
- 响应没有
Content-Encoding: gzip:检查 MIME 类型、响应长度和客户端 Accept-Encoding。
相关指令: gzip_types、gzip_comp_level
设置 Gzip 压缩级别。
gzip_comp_level
设置 Gzip 压缩级别。是否启用以及参数取值都应结合响应类型、CPU、带宽和客户端协议能力验证。
语法
gzip_comp_level level;上下文: http、server、location
推荐配置
gzip_comp_level 5;关键行为
数值越高通常压缩率越高但 CPU 开销也越大,不能简单以最高级别作为默认值。
验证
sudo nginx -t相关指令: gzip
设置启用 Gzip 的最小响应长度。
gzip_min_length
设置启用 Gzip 的最小响应长度。是否启用以及参数取值都应结合响应类型、CPU、带宽和客户端协议能力验证。
语法
gzip_min_length length;上下文: http、server、location
推荐配置
gzip_min_length 1024;关键行为
响应长度通常依据 Content-Length 判断,小响应压缩收益可能低于开销。
验证
sudo nginx -t相关指令: gzip
控制是否在压缩响应中添加 Vary: Accept-Encoding。
gzip_vary
控制是否在压缩响应中添加 Vary: Accept-Encoding。是否启用以及参数取值都应结合响应类型、CPU、带宽和客户端协议能力验证。
语法
gzip_vary on | off;上下文: http、server、location
推荐配置
gzip_vary on;关键行为
前置缓存/CDN 存在时通常应开启,让压缩与未压缩版本按客户端能力正确区分。
验证
sudo nginx -t相关指令: gzip
控制对经代理请求的响应何时允许 Gzip。
gzip_proxied
控制对经代理请求的响应何时允许 Gzip。是否启用以及参数取值都应结合响应类型、CPU、带宽和客户端协议能力验证。
语法
gzip_proxied off | expired | no-cache | no-store | private | no_last_modified | no_etag | auth | any ...;上下文: http、server、location
推荐配置
gzip_proxied expired no-cache no-store private auth;关键行为
默认行为较保守;选择条件时要考虑前置代理和缓存语义。
验证
sudo nginx -t相关指令: gzip