Web 服务器与网关 / 知识点
Nginx 配置指令速查手册
站点与路由
按正则重写 URI 或发起重定向。
rewrite
只有在 URI 需要正则捕获和改写、return 或 try_files 无法清晰完成时再查这个指令。
语法
rewrite regex replacement [flag];上下文: server、location、if
推荐配置
location /old/ {
rewrite ^/old/(.*)$ /new/$1 permanent;
}关键行为
- 规则按配置顺序执行;
last会重新进行 location 匹配,break则停止当前 rewrite 阶段。 - 复杂 rewrite 很容易产生二次匹配和循环;简单跳转优先
return。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -I http://127.0.0.1/old/demo常见问题
- 循环重定向:检查替换后的 URI 是否再次匹配同一规则。
- 反向代理 location 内 rewrite 后再 proxy_pass 时,要同时核对转发 URI。
相关指令: return、location
根据源值映射生成一个新变量。
map
当一个变量需要根据另一个变量的值做映射时查 map。适合 WebSocket、CORS、日志标签和条件配置,通常比在 location 中堆多个 if 更清晰。
语法
map string $variable { ... }上下文: http
推荐配置
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name ws.example.com;
location /ws/ {
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_pass http://127.0.0.1:8080;
}
}关键行为
map只能定义在http上下文。- 映射变量按需计算,不会因为定义了很多 map 就自动对每个请求做昂贵处理。
验证
sudo nginx -t
sudo nginx -T 2>/dev/null | grep -n 'map $http_upgrade'常见问题
- 配置在 server/location 内会报上下文错误。
- WebSocket 仍失败时继续检查上游协议和 Upgrade/Connection 头。
相关指令: proxy_set_header
设置 Expires,并联动生成 Cache-Control 的缓存时间。
expires
设置 Expires,并联动生成 Cache-Control 的缓存时间。排查路由问题时,重点确认请求实际命中的 server / location,不要只看文件里“写了什么”。
语法
expires [modified] time | epoch | max | off;上下文: http、server、location、if in location
推荐配置
location /assets/ {
expires 30d;
}关键行为
适合静态资源缓存;带内容哈希的资源可使用更长缓存,HTML 通常应更谨慎。
验证
sudo nginx -t相关指令: add_header
向响应添加指定 HTTP 头。
add_header
需要给响应补安全头、缓存头或调试标记时查这个指令。重点是状态码覆盖范围和继承规则。
语法
add_header name value [always];上下文: http、server、location、if in location
推荐配置
server {
listen 443 ssl;
server_name example.com;
add_header X-Content-Type-Options nosniff always;
add_header Referrer-Policy strict-origin-when-cross-origin always;
location / {
try_files $uri =404;
}
}关键行为
always可让响应头覆盖更多状态码,安全头通常建议显式使用。- 子层一旦重新声明
add_header,继承行为可能与直觉不同;排障时查看最终nginx -T。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -I https://example.com/常见问题
- 头只在 200 有、错误页没有:检查是否缺少
always。 - 同名头重复:检查 CDN、应用和 Nginx 是否同时添加。
相关指令: expires
客户端请求
限制客户端请求体最大大小,超出通常返回 413。
client_max_body_size
上传文件或大请求体出现 413 时查这个指令。它只控制 Nginx 入口的请求体上限,不会自动修改 CDN、Ingress 或应用服务器的限制。
语法
client_max_body_size size;上下文: http、server、location
推荐配置
server {
listen 443 ssl;
server_name upload.example.com;
client_max_body_size 20m;
location /upload/ {
proxy_pass http://127.0.0.1:8080;
proxy_read_timeout 60s;
}
}关键行为
- 超出上限通常返回 413。
- 不要把值无上限放大;应按真实业务文件大小和前后链路限制确定。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -i -F 'file=@<PATH>' https://upload.example.com/upload/常见问题
- Nginx 已改仍 413:继续检查前置代理和后端框架。
- 超大上传还应结合
proxy_request_buffering、临时目录空间和超时。
相关指令: proxy_request_buffering
设置读取客户端请求体两次读操作之间的超时时间。
client_body_timeout
设置读取客户端请求体两次读操作之间的超时时间。参数应依据真实请求大小、上传耗时和客户端行为设定,不建议为了消除报错直接无限放大。
语法
client_body_timeout time;上下文: http、server、location
推荐配置
client_body_timeout 30s;关键行为
它不是整个上传过程的总时长;客户端在指定间隔内没有继续发送数据时连接会被关闭。
验证
sudo nginx -t相关指令: client_max_body_size
设置普通请求头的初始缓冲区大小。
client_header_buffer_size
设置普通请求头的初始缓冲区大小。参数应依据真实请求大小、上传耗时和客户端行为设定,不建议为了消除报错直接无限放大。
语法
client_header_buffer_size size;上下文: http、server
推荐配置
client_header_buffer_size 2k;关键行为
头部超过该缓冲区时会尝试 large_client_header_buffers;不要为了绕过异常 Cookie 无限放大。
验证
sudo nginx -t相关指令: large_client_header_buffers
设置处理超大请求行或请求头字段的缓冲区数量和大小。
large_client_header_buffers
设置处理超大请求行或请求头字段的缓冲区数量和大小。参数应依据真实请求大小、上传耗时和客户端行为设定,不建议为了消除报错直接无限放大。
语法
large_client_header_buffers number size;上下文: http、server
推荐配置
large_client_header_buffers 4 16k;关键行为
单个请求行或单个头字段必须能放入一个大缓冲区;过大配置会增加并发内存消耗。
验证
sudo nginx -t相关指令: client_header_buffer_size
反向代理
把请求转发给 HTTP 上游,并决定 URI 如何传递。
proxy_pass
把请求转发给 HTTP/HTTPS 后端时查这个指令。最关键的是上游地址和 URI 映射,尤其要弄清 URL 是否带 URI/尾斜杠。
语法
proxy_pass URL;上下文: location、if in location、limit_except
推荐配置
upstream app_backend {
server 127.0.0.1:8080;
keepalive 32;
}
server {
listen 80;
server_name api.example.com;
location /api/ {
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 3s;
proxy_read_timeout 30s;
proxy_pass http://app_backend/;
}
}关键行为
location /api/+proxy_pass http://app_backend/;会用/替换匹配到的/api/,因此/api/users通常转成/users。proxy_pass http://app_backend;不带 URI 时通常保留原请求 URI,例如/api/users。- 正则 location、命名 location 或某些 rewrite 场景无法可靠确定待替换 URI,应按官方规则使用不带 URI 的 proxy_pass。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -i -H 'Host: api.example.com' http://127.0.0.1/api/health常见问题
- 404:优先检查 URI/尾斜杠映射。
- 502:优先检查后端地址、端口、DNS 和服务监听。
- 后端拿不到真实协议/IP:检查
proxy_set_header与可信代理链。
相关指令: proxy_set_header、upstream
覆盖或补充发送给上游的请求头。
proxy_set_header
需要控制发送给上游的 Host、客户端 IP、原始协议或 WebSocket 头时查这个指令。
语法
proxy_set_header field value;上下文: http、server、location
推荐配置
location /api/ {
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://127.0.0.1:8080;
}关键行为
$proxy_add_x_forwarded_for会在已有 X-Forwarded-For 后追加当前客户端地址,适合标准代理链。- 不要直接信任客户端自带的 X-Forwarded-For 做鉴权;真正恢复客户端 IP 应配合 Real IP 模块和可信代理网段。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -i -H 'Host: api.example.com' http://127.0.0.1/api/headers常见问题
- 应用看到错误 Host:确认是否应该传
$host、$http_host或上游固定域名。 - 客户端 IP 始终是代理地址:继续配置
set_real_ip_from/real_ip_header。
相关指令: set_real_ip_from、real_ip_header
指定 Nginx 与 HTTP 上游通信使用的协议版本。
proxy_http_version
上游连接需要 Keep-Alive、WebSocket 或明确协议行为时查这个指令。生产配置建议显式声明需要的版本,而不是依赖不同 Nginx 版本的默认值。
语法
proxy_http_version 1.0 | 1.1;上下文: http、server、location
推荐配置
location /api/ {
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_pass http://app_backend;
}关键行为
- HTTP/1.1 是上游连接复用和 WebSocket 的常见前提。
- 普通 keepalive 代理可清空
Connection头;WebSocket 则需要显式传Upgrade与合适的Connection。
验证
sudo nginx -t
sudo nginx -T 2>/dev/null | grep -n 'proxy_http_version'常见问题
- WebSocket 101 失败:同时检查 Upgrade/Connection 头和上游应用。
相关指令: proxy_set_header、keepalive
设置与上游建立连接的超时时间。
proxy_connect_timeout
502/504 发生在连接后端阶段,或需要给后端建连设置明确预算时查这个指令。
语法
proxy_connect_timeout time;上下文: http、server、location
推荐配置
location /api/ {
proxy_connect_timeout 3s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;
proxy_pass http://app_backend;
}关键行为
- 只控制与上游建立连接的阶段,不等于整个请求总超时。
- 值过长会让故障节点拖慢请求;值过短会把正常网络抖动误判为故障。
验证
sudo nginx -t
curl -i http://127.0.0.1/api/health常见问题
- 连接被拒绝通常立即失败,不会等待完整 connect timeout。
- 超时问题要区分 connect/send/read 三个阶段。
相关指令: proxy_read_timeout、proxy_send_timeout
设置向上游发送请求时两次写操作之间的超时。
proxy_send_timeout
设置向上游发送请求时两次写操作之间的超时。调整前先区分建连、发送、读取、缓冲和重试分别处在哪个阶段,避免用一个参数掩盖另一个问题。
语法
proxy_send_timeout time;上下文: http、server、location
推荐配置
proxy_send_timeout 30s;关键行为
不是整个请求上传到上游的总时长。
验证
sudo nginx -t相关指令: proxy_connect_timeout、proxy_read_timeout
设置从上游读取响应时两次读操作之间的超时。
proxy_read_timeout
上游处理时间较长、长轮询或 WebSocket 空闲断开时查这个指令。
语法
proxy_read_timeout time;上下文: http、server、location
推荐配置
location /api/ {
proxy_connect_timeout 3s;
proxy_read_timeout 60s;
proxy_pass http://app_backend;
}关键行为
- 它控制两次从上游读取数据之间允许的最大间隔,不是整个响应的总时长。
- 长轮询和 WebSocket 应按业务心跳周期设置,不能简单无限放大。
验证
sudo nginx -t
curl -i http://127.0.0.1/api/slow常见问题
- 504:结合 error.log 区分
upstream timed out与其他网关错误。
相关指令: proxy_connect_timeout、proxy_send_timeout
控制是否先完整读取客户端请求体,再把请求发送给上游。
proxy_request_buffering
大文件上传、流式请求或希望后端尽早收到请求体时查这个指令。
语法
proxy_request_buffering on | off;上下文: http、server、location
推荐配置
location /upload/ {
client_max_body_size 100m;
proxy_request_buffering off;
proxy_http_version 1.1;
proxy_pass http://upload_backend;
}关键行为
- 关闭后请求体会更直接地流向上游,可减少 Nginx 临时文件压力。
- 请求体一旦发送给上游,失败后切换其他上游的能力会受到限制。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -F 'file=@<PATH>' http://127.0.0.1/upload/常见问题
- 上传仍落盘:检查是否还有其他层做缓冲。
- 重试行为异常:确认是否依赖
proxy_next_upstream。
相关指令: client_max_body_size、proxy_next_upstream
控制是否缓冲上游响应。
proxy_buffering
SSE、流式接口需要低延迟透传,或普通接口需要隔离慢客户端时查这个指令。
语法
proxy_buffering on | off;上下文: http、server、location
推荐配置
location /events/ {
proxy_http_version 1.1;
proxy_buffering off;
proxy_read_timeout 1h;
proxy_pass http://event_backend;
}关键行为
- 普通 API 一般保留缓冲更稳妥;关闭更适合 SSE/流式响应。
- 关闭缓冲后,上游发送速度更直接受客户端读取速度影响。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -N http://127.0.0.1/events/常见问题
- SSE 成批到达而不是实时:检查 Nginx 与上游是否仍在缓冲。
相关指令: proxy_buffers、proxy_buffer_size
设置读取上游响应首部所用缓冲区大小。
proxy_buffer_size
设置读取上游响应首部所用缓冲区大小。调整前先区分建连、发送、读取、缓冲和重试分别处在哪个阶段,避免用一个参数掩盖另一个问题。
语法
proxy_buffer_size size;上下文: http、server、location
推荐配置
proxy_buffer_size 16k;关键行为
上游响应头过大时可出现 upstream sent too big header;应先检查异常 Cookie/头字段再调整。
验证
sudo nginx -t相关指令: proxy_buffers
设置读取上游响应正文时使用的缓冲区数量和大小。
proxy_buffers
设置读取上游响应正文时使用的缓冲区数量和大小。调整前先区分建连、发送、读取、缓冲和重试分别处在哪个阶段,避免用一个参数掩盖另一个问题。
语法
proxy_buffers number size;上下文: http、server、location
推荐配置
proxy_buffers 8 16k;关键行为
缓冲区过大会提高每个活跃请求的潜在内存占用。
验证
sudo nginx -t相关指令: proxy_buffering、proxy_busy_buffers_size
限制向客户端发送响应时可处于 busy 状态的代理缓冲区总大小。
proxy_busy_buffers_size
限制向客户端发送响应时可处于 busy 状态的代理缓冲区总大小。调整前先区分建连、发送、读取、缓冲和重试分别处在哪个阶段,避免用一个参数掩盖另一个问题。
语法
proxy_busy_buffers_size size;上下文: http、server、location
推荐配置
proxy_busy_buffers_size 32k;关键行为
需要与 proxy_buffer_size/proxy_buffers 协同设置,不适合脱离实际流量单独调大。
验证
sudo nginx -t相关指令: proxy_buffers
限制缓冲代理响应时写入单个临时文件的最大大小。
proxy_max_temp_file_size
限制缓冲代理响应时写入单个临时文件的最大大小。调整前先区分建连、发送、读取、缓冲和重试分别处在哪个阶段,避免用一个参数掩盖另一个问题。
语法
proxy_max_temp_file_size size;上下文: http、server、location
推荐配置
proxy_max_temp_file_size 0;关键行为
设置为 0 可禁止代理响应写临时文件;可能增加内存压力或影响大响应处理。
验证
sudo nginx -t相关指令: proxy_temp_path、proxy_buffering