在帮助遇到问题的NGINX用户时,我们经常会看到一些屡见不鲜的配置错误,有时甚至连NGINX工程师编写的配置也会出现这些错误!本文将介绍其中10种最常见的错误,说明问题所在及其修复方法。
- 每个工作进程的文件描述符不足
- The
error_logoff指令 - 未启用与上游服务器的 keepalive 连接
- 忘记指令继承的工作原理
- 将
proxy_buffering设置为off的指令 - 不当使用
if指令 - 运行状况检查过于频繁
- 对指标的不安全访问
- 当所有流量均来自同一个/24 CIDR块时使用
ip_hashwhen all traffic comes from the same /24 CIDR block - 未充分利用上游组
错误 1:每个工作进程的文件描述符数量不足
The worker_connections指令用于设置每个NGINX工作进程可同时打开的最大连接数(默认值为512)。所有类型的连接(例如与代理服务器的连接)都会计入此上限,而不仅仅是客户端连接。但需要注意,每个工作进程的并发连接数最终还会受到另一项限制:操作系统为每个进程分配的文件描述符(FD)数量上限。在现代UNIX发行版中,默认上限为1024。
除规模最小的NGINX部署外,每个工作进程最多512个连接的限制可能都过低。事实上,我们随NGINX Open Source二进制文件和NGINX Plus分发的默认nginx.conf文件已将此限制提高到1024。
常见的配置错误是未将文件描述符(FD)上限提高到至少为worker_connections值的两倍。解决方法是在主配置上下文中使用worker_rlimit_nofile指令设置该值。
之所以需要更多FD,是因为从NGINX工作进程到客户端或上游服务器的每个连接都会占用一个FD。当NGINX充当Web服务器时,客户端连接会占用一个FD,提供的每个文件也会占用一个FD,因此每个客户端至少需要两个FD(但大多数网页由多个文件构成)。当NGINX充当代理服务器时,与客户端和上游服务器的连接各占用一个FD,用于临时存储服务器响应的文件还可能占用第三个FD。当NGINX充当缓存服务器时,对于缓存的响应,其行为类似Web服务器;如果缓存为空或已过期,其行为则类似代理服务器。
NGINX还会为每个日志文件使用一个FD,并使用几个FD与主进程通信,但与连接和文件所使用的FD数量相比,这些FD通常很少。
UNIX提供了多种方法来设置每个进程的文件描述符(FD)数量:
- 如果从shell启动NGINX,可使用
ulimit命令 - 如果将NGINX作为服务启动,则使用
init脚本或systemd服务清单变量 - The /etc/security/limits.conf 文件
不过,具体使用哪种方法取决于NGINX的启动方式,而worker_rlimit_nofile无论NGINX以何种方式启动都有效。
系统还会限制整个系统可使用的文件描述符(FD)数量,可通过操作系统的sysctl fs.file-max命令进行设置。该限制通常足够大,但仍应确认所有NGINX工作进程可能使用的文件描述符数量上限(worker_rlimit_nofile * worker_processes)远低于fs.file‑max。如果NGINX因某种原因用尽所有可用的FD(例如遭受DoS攻击时),甚至将无法登录该计算机来解决问题。
错误 2:error_log off 指令
常见的误解是认为error_log off指令会禁用日志记录。事实上,与access_log指令不同,error_log不接受off参数。如果在配置中加入error_log off指令,NGINX会在NGINX配置文件的默认目录(通常为/etc/nginx)中创建一个名为off的错误日志文件。
不建议禁用错误日志,因为在调试NGINX的任何问题时,错误日志都是重要的信息来源。但是,如果存储空间非常有限,记录的数据可能会耗尽可用磁盘空间,则可以考虑禁用错误日志。请在主配置上下文中添加以下指令:
error_log /dev/null emerg;请注意,此指令要等到NGINX读取并验证配置后才会生效。因此,每次NGINX启动或重新加载配置时,在配置通过验证之前,日志可能会写入默认的错误日志位置(通常为/var/log/nginx/error.log)。要更改日志目录,请在-e <error_log_location>命令行参数中指定位置,并将其添加到nginx命令中。
错误3:未启用与上游服务器的长连接
默认情况下,NGINX会针对每个新收到的请求,与上游(后端)服务器建立一个新连接。这种方式安全但效率较低,因为NGINX与服务器必须交换3个数据包才能建立连接,并交换3或4个数据包才能终止连接。
在流量较大时,为每个请求新建连接可能会耗尽系统资源,导致完全无法建立连接。原因如下:每个连接的四元组(源地址、源端口、目标地址和目标端口)必须唯一。对于从NGINX到上游服务器的连接,其中3个元素(第1个、第3个和第4个)是固定的,只有源端口是变量。连接关闭后,Linux套接字会处于TIME‑WAIT状态2分钟。在流量较大时,这会增加可用源端口池耗尽的可能性。一旦发生这种情况,NGINX将无法与上游服务器建立新连接。
解决方法是在NGINX与上游服务器之间启用keepalive连接。请求完成后,连接不会关闭,而是保持打开状态,以供后续请求复用。这样既能降低源端口耗尽的可能性,又能提升性能。
要启用keepalive连接:
- 在每个
keepalive指令添加到upstream{}块中,用于设置每个工作进程的缓存中保留的、与上游服务器之间的空闲keepalive连接数。请注意,keepalive指令不会限制NGINX工作进程可与上游服务器建立的连接总数,这一点经常被误解。因此,keepalive的参数值不必像您可能认为的那样大。建议将该参数设置为upstream{}块中所列服务器数量的2倍。该值足以让NGINX与所有服务器保持keepalive连接,同时又不会过大,确保上游服务器也能处理新传入的连接。另请注意,在upstream{}块中使用hash、ip_hash、least_conn、least_time或random指令指定负载均衡算法时,该指令必须位于keepalive指令之前。这是NGINX配置中指令顺序通常无关紧要这一通用规则的少数例外之一。 - 在将请求转发到上游组的
location{}块中,除proxy_pass指令外,还应包含以下指令:
proxy_http_version 1.1;
proxy_set_header "Connection" "";- 默认情况下,NGINX使用HTTP/1.0连接上游服务器,因此会在转发给服务器的请求中添加
Connection:close标头。这样一来,即使upstream{}块中存在keepalive指令,每个连接仍会在请求完成时关闭。proxy_http_version指令让NGINX改用HTTP/1.1,而proxy_set_header指令会从Connection标头中移除close值。
错误 4:忽略指令继承的工作原理
NGINX指令采用向下继承,即“由外向内”:嵌套在另一个上下文(其子上下文)中的父上下文会继承父级中所含指令的设置。例如,server{}和location{}上下文中的所有http{}块都会继承http级别所含指令的值,而server{}块中的指令会由其中的所有子location{}块继承。但是,如果父上下文及其子上下文中包含同一指令,这些值不会相加;子上下文中的值会覆盖父上下文中的值。
常见错误是忘记此“覆盖规则”同样适用于数组指令。这类指令不仅可以包含在多个上下文中,还可以在同一上下文中多次包含。例如,proxy_set_header和add_header都属于此类指令;后者的名称中含有“add”,因此尤其容易让人忽略覆盖规则。
以下以add_header为例说明继承的工作原理:
http {
add_header X-HTTP-LEVEL-HEADER 1;
add_header X-ANOTHER-HTTP-LEVEL-HEADER 1;
server {
listen 8080;
location / {
return 200 "OK";
}
}
server {
listen 8081;
add_header X-SERVER-LEVEL-HEADER 1;
location / {
return 200 "OK";
}
location /test {
add_header X-LOCATION-LEVEL-HEADER 1;
return 200 "OK";
}
location /correct {
add_header X-HTTP-LEVEL-HEADER 1;
add_header X-ANOTHER-HTTP-LEVEL-HEADER 1;
add_header X-SERVER-LEVEL-HEADER 1;
add_header X-LOCATION-LEVEL-HEADER 1;
return 200 "OK";
}
}
}对于侦听端口8080的服务器,add_header指令既未出现在server{}块中,也未出现在location{}块中。因此,继承关系很清晰,可以看到在http{}上下文中定义的两个标头:
% curl -i localhost:8080
HTTP/1.1 200 OK
Server: nginx/1.21.5
Date: Mon, 21 Feb 2022 10:12:15 GMT
Content-Type: text/plain
Content-Length: 2
Connection: keep-alive
X-HTTP-LEVEL-HEADER: 1 X-ANOTHER-HTTP-LEVEL-HEADER: 1
OK对于侦听端口8081的服务器,add_header指令位于server{}块中,但不在其子location /块中。server{}块中定义的标头会覆盖http{}上下文中定义的两个标头:
% curl -i localhost:8081
HTTP/1.1 200 OK
Server: nginx/1.21.5
Date: Mon, 21 Feb 2022 10:12:20 GMT
Content-Type: text/plain
Content-Length: 2
Connection: keep-alive
X-SERVER-LEVEL-HEADER: 1
OK在子级location /test块中,有一条add_header指令,它会覆盖其父级server{}块中的标头,以及http{}上下文中的两个标头:
% curl -i localhost:8081/test
HTTP/1.1 200 OK
Server: nginx/1.21.5
Date: Mon, 21 Feb 2022 10:12:25 GMT
Content-Type: text/plain
Content-Length: 2
Connection: keep-alive
X-LOCATION-LEVEL-HEADER: 1
OK如果希望 location{} 块既保留其父级上下文中定义的标头,也保留本地定义的标头,则必须在 location{} 块中重新定义父级标头。我们已在 location /correct 块中这样做:
% curl -i localhost:8081/correct
HTTP/1.1 200 OK
Server: nginx/1.21.5
Date: Mon, 21 Feb 2022 10:12:30 GMT
Content-Type: text/plain
Content-Length: 2
Connection: keep-alive
X-HTTP-LEVEL-HEADER: 1 X-ANOTHER-HTTP-LEVEL-HEADER: 1 X-SERVER-LEVEL-HEADER: 1 X-LOCATION-LEVEL-HEADER: 1
OK错误5:proxy_buffering off指令
NGINX默认启用代理缓冲(proxy_buffering指令设置为on)。代理缓冲是指NGINX在接收服务器响应时将其存储在内部缓冲区中,直到整个响应缓冲完毕后才开始向客户端发送数据。缓冲有助于优化客户端速度较慢时的性能。由于NGINX会持续缓冲响应,直至客户端将其全部接收完毕,因此被代理服务器可以尽快返回响应,并恢复为可处理其他请求的状态。
禁用代理缓冲后,NGINX仅将服务器响应的第一部分存入缓冲区,然后便开始向客户端发送响应。该缓冲区的默认大小为一个内存页(4 KB或8 KB,具体取决于操作系统),通常仅够容纳响应标头。随后,NGINX在接收响应的同时将其同步发送给客户端,导致服务器在等待NGINX接收下一个响应片段期间处于空闲状态。
因此,我们很意外地发现,配置中经常将proxy_buffering设置为off。这样做或许是为了降低客户端感受到的延迟,但效果微乎其微,副作用却很多:禁用代理缓冲后,即使配置了速率限制和缓存,这些功能也不会生效,性能还会下降,等等。
只有少数用例可能适合禁用代理缓冲(例如长轮询),因此强烈建议不要更改默认设置。有关更多信息,请参阅《NGINX Plus管理指南》。
错误6:不当使用if指令
使用if指令需要格外谨慎,尤其是在location{}块中。它的行为往往不符合预期,甚至可能导致段错误。事实上,这个指令非常棘手,NGINX Wiki中有一篇题为“If is Evil”的文章,建议阅读该文章,详细了解相关问题及其规避方法。
通常,在if{}块中始终可以安全使用的指令只有return和rewrite。以下示例使用if检测包含X‑Test标头的请求(也可以使用要测试的任何其他条件)。NGINX返回430 (Request Header Fields Too Large)错误,在命名位置@error_430将其拦截,并将请求代理到名为b的上游组。
location / {
error_page 430 = @error_430;
if ($http_x_test) {
return 430;
}
proxy_pass http://a;
}
location @error_430 {
proxy_pass b;
}对于此处及许多其他使用if的情况,通常可以完全避免使用该指令。在以下示例中,当请求包含X‑Test标头时,map{}块会将$upstream_name变量设置为b,并将请求代理到同名的上游组。
map $http_x_test $upstream_name {
default "b";
"" "a";
}
# ...
location / {
proxy_pass http://$upstream_name;
}错误 7:运行状况检查过于频繁
It is quite common to configure multiple virtual servers to proxy requests to the same upstream group (in other words, to include the identical proxy_pass directive in multiple server{} blocks). The mistake in this situation is to include a health_check directive in every server{} block. This just creates more load on the upstream servers without yielding any additional information.
解决方法其实很简单:每个upstream{}块只定义一个健康检查。这里,我们在一个专用的命名位置中为名为b的上游组定义健康检查,并配置适当的超时和标头设置。
location / {
proxy_set_header Host $host;
proxy_set_header "Connection" "";
proxy_http_version 1.1;
proxy_pass http://b;
}
location @health_check {
health_check;
proxy_connect_timeout 2s;
proxy_read_timeout 3s;
proxy_set_header Host example.com;
proxy_pass http://b;
}在复杂配置中,可以像本例一样,将所有运行状况检查位置与NGINX Plus API和仪表板集中到同一个虚拟服务器中,从而进一步简化管理。
server {
listen 8080;
location / {
# …
}
location @health_check_b {
health_check;
proxy_connect_timeout 2s;
proxy_read_timeout 3s;
proxy_set_header Host example.com;
proxy_pass http://b;
}
location @health_check_c {
health_check;
proxy_connect_timeout 2s;
proxy_read_timeout 3s;
proxy_set_header Host api.example.com;
proxy_pass http://c;
}
location /api {
api write=on;
# directives limiting access to the API (see 'Mistake 8' below)
}
location = /dashboard.html {
root /usr/share/nginx/html;
}
}有关HTTP、TCP、UDP和gRPC服务器健康检查的更多信息,请参阅《NGINX Plus Admin Guide》。
错误8:指标访问未受保护
可通过Stub Status模块获取有关NGINX运行情况的基本指标。对于NGINX Plus,还可以使用NGINX Plus API收集更全面的指标。要启用指标收集,请分别在stub_status或api指令中,将其添加到server{}或location{}块中。该块将成为用于访问和查看指标的URL。(对于NGINX Plus API,还需要为要收集指标的NGINX实体配置共享内存区,包括虚拟服务器、上游组和缓存等;相关说明请参阅《NGINX Plus Admin Guide》。)
部分指标属于敏感信息,可能被用于攻击您的网站或由NGINX代理的应用。我们有时会发现,用户配置中未限制对相应URL的访问。下面介绍几种保护这些指标的方法。前几个示例将使用stub_status。
采用以下配置后,互联网上的任何人都可以通过http://example.com/basic_status访问这些指标。
server {
listen 80;
server_name example.com;
location = /basic_status {
stub_status;
}
}使用HTTP基本身份验证保护指标
要使用密码和HTTP基本身份验证来保护指标,请添加auth_basic和auth_basic_user_file指令。该文件(此处为 .htpasswd)列出了可登录并查看指标的客户端用户名和密码:
server {
listen 80;
server_name example.com;
location = /basic_status {
auth_basic “closed site”;
auth_basic_user_file conf.d/.htpasswd;
stub_status;
}
}使用allow和deny指令保护指标
如果不希望授权用户必须登录,并且已知他们访问指标时使用的IP地址,还可以选择使用allow指令。可以指定单个IPv4和IPv6地址以及CIDR范围。deny all指令可阻止来自任何其他地址的访问。
server {
listen 80;
server_name example.com;
location = /basic_status {
allow 192.168.1.0/24;
allow 10.1.1.0/16;
allow 2001:0db8::/32;
allow 96.1.2.23/32;
deny all;
stub_status;
}
}结合使用这两种方法
如果要结合使用这两种方法,该怎么做?我们可以允许来自特定地址的客户端无需密码即可访问指标,同时仍要求来自其他地址的客户端登录。为此,可以使用satisfy any指令。该指令会让NGINX允许满足以下任一条件的客户端访问:使用HTTP基本身份验证凭据登录,或使用预先批准的IP地址。为进一步提高安全性,可以将satisfy设置为all,这样即使来自特定地址的用户也必须登录。
server {
listen 80;
server_name monitor.example.com;
location = /basic_status {
satisfy any;
auth_basic “closed site”;
auth_basic_user_file conf.d/.htpasswd;
allow 192.168.1.0/24;
allow 10.1.1.0/16;
allow 2001:0db8::/32;
allow 96.1.2.23/32;
deny all;
stub_status;
}
}使用NGINX Plus时,可以采用相同的方法限制对NGINX Plus API端点(以下示例中的http://monitor.example.com:8080/api/)以及实时活动监控仪表板(地址为http://monitor.example.com/dashboard.html)的访问。
此配置仅允许来自96.1.2.23/32网络或localhost的客户端无需密码即可访问。由于这些指令是在server{}级别定义的,因此API和仪表盘均受相同限制。另外,write=on参数用于api时,表示这些客户端还可以使用API更改配置。
有关配置API和仪表板的更多信息,请参阅《NGINX Plus管理指南》。
server {
listen 8080;
server_name monitor.example.com;
satisfy any;
auth_basic “closed site”;
auth_basic_user_file conf.d/.htpasswd;
allow 127.0.0.1/32;
allow 96.1.2.23/32;
deny all;
location = /api/ {
api write=on;
}
location = /dashboard.html {
root /usr/share/nginx/html;
}
}错误9:当所有流量都来自同一/24 CIDR块时使用ip_hash When All Traffic Comes from the Same /24 CIDR Block
The ip_hash算法根据客户端IP地址的哈希值,在upstream{}块中的服务器之间对流量进行负载均衡。哈希键为IPv4地址的前3个八位字节或完整的IPv6地址。此方法可实现会话持久性,即除非服务器不可用,否则来自同一客户端的请求始终会转发到同一台服务器。
假设我们已在配置为高可用的虚拟专用网络中部署NGINX作为反向代理。我们在NGINX前端部署了各种防火墙、路由器、第4层负载均衡器和网关,用于接收来自不同来源(内部网络、合作伙伴网络、互联网等)的流量,并将其传递给NGINX,由NGINX反向代理到上游服务器。以下是初始NGINX配置:
http {
upstream {
ip_hash;
server 10.10.20.105:8080;
server 10.10.20.106:8080;
server 10.10.20.108:8080;
}
server {# …}
}但实际情况存在一个问题:所有“拦截”设备都位于同一个10.10.0.0/24网络中,因此在NGINX看来,所有流量都来自该CIDR范围内的地址。请注意,ip_hash算法会对IPv4地址的前3个八位字节进行哈希运算。在此部署中,每个客户端的前3个八位字节都相同,即10.10.0,因此它们的哈希值也相同,无法据此将流量分配到不同的服务器。
解决方法是改用hash算法,并将$binary_remote_addr变量用作哈希键。该变量会获取完整的客户端地址,并将其转换为二进制表示形式:IPv4地址占4字节,IPv6地址占16字节。这样,每个拦截设备的哈希值都不同,负载均衡便可按预期工作。
我们还添加了consistent参数,以使用ketama哈希方法替代默认方法。当服务器集合发生变化时,这可以大幅减少重新映射到其他上游服务器的键数量,从而提高缓存服务器的缓存命中率。
http {
upstream {
hash $binary_remote_addr consistent;
server 10.10.20.105:8080;
server 10.10.20.106:8080;
server 10.10.20.108:8080;
}
server {# …}
}错误10:未充分利用上游组
假设您在一个非常简单的用例中使用NGINX,将其作为单个NodeJS后端应用的反向代理,该应用监听3000端口。常见配置可能如下所示:
http {
server {
listen 80;
server_name example.com;
location / {
proxy_set_header Host $host;
proxy_pass http://localhost:3000/;
}
}
}很简单,对吧?proxy_pass指令会告知NGINX将客户端请求发送到何处。NGINX只需将主机名解析为IPv4或IPv6地址。连接建立后,NGINX会将请求转发到该服务器。
这里的误区在于,认为只有一台服务器,因此无需配置负载均衡,创建upstream{}块也就没有意义。事实上,upstream{}块可以启用多项有助于提升性能的功能,如以下配置所示:
http {
upstream node_backend {
zone upstreams 64K;
server 127.0.0.1:3000 max_fails=1 fail_timeout=2s;
keepalive 2;
}
server {
listen 80;
server_name example.com;
location / {
proxy_set_header Host $host;
proxy_pass http://node_backend/;
proxy_next_upstream error timeout http_500;
}
}
}The zone指令会创建一个共享内存区,主机上的所有NGINX工作进程均可在其中访问上游服务器的配置和状态信息。多个上游组可以共享该内存区。使用NGINX Plus时,该内存区还支持通过NGINX Plus API更改上游组中的服务器及各服务器的设置,而无需重启NGINX。有关详细信息,请参阅《NGINX Plus管理指南》。
The server指令提供多个参数,可用于调整服务器行为。在本例中,我们更改了NGINX用于判定服务器运行状况不佳、因而无法接受请求的条件。此处,如果每2秒内有一次通信尝试失败,NGINX就会将服务器视为运行状况不佳(默认条件为每10秒内有一次失败)。
我们将此设置与proxy_next_upstream指令结合使用,以配置NGINX将哪些情况视为通信尝试失败。发生此类情况时,NGINX会将请求传递给上游组中的下一台服务器。除默认的错误和超时条件外,我们还添加了http_500,使NGINX将上游服务器返回的HTTP 500 (Internal Server Error)代码视为尝试失败。
The keepalive指令用于设置每个工作进程的缓存中保留的、与上游服务器之间的空闲keepalive连接数。我们已在“错误3:未启用与上游服务器之间的keepalive连接”中讨论过其优势。
借助NGINX Plus,可以为上游组配置其他功能:
- 如上所述,NGINX Open Source仅在启动时将服务器主机名解析为IP地址一次。服务器指令的
resolve参数使NGINX Plus能够监控与上游服务器域名对应的IP地址变化,并自动修改上游配置,无需重启。使用service参数还可让NGINX Plus使用DNSSRV记录,其中包含端口号、权重和优先级信息。这对于服务端口号通常动态分配的微服务环境至关重要。有关解析服务器地址的更多信息,请参阅博客文章《使用DNS通过NGINX和NGINX Plus实现服务发现》。 - server指令的
slow_start参数使NGINX Plus能够逐步增加向刚刚恢复健康并可接收请求的服务器发送的请求量。这可以防止请求突然大量涌入,导致服务器过载并再次发生故障。 - 当无法选择上游服务器处理请求时,
queue指令可让NGINX Plus将请求放入队列,而不是立即向客户端返回错误。
资源
- 创建 NGINX Plus 和 NGINX 配置文件,位于《NGINX Plus 管理指南》中
- Gixy,一款托管在GitHub上的NGINX配置分析工具
- NGINX Amplify,其中包含Analyzer工具
如需试用NGINX Plus,可立即开始30天免费试用,或联系我们,讨论您的用例。
关于作者

相关博客文章
NGINX Plus R26 正式发布
NGINX Plus R26通过缓存JSON Web密钥集加快JWT验证,并强化TLS握手,从而提升安全性。NGINX JavaScript的新功能包括增强对异步函数的支持,以及实现WebCrypto API。
使用NGINX App Protect DoS保护gRPC应用,抵御严重的DoS攻击
gRPC具备开发人员设计和部署现代应用所需的速度与灵活性,但其开放性也使其极易受到第7层DoS攻击。NGINX App Protect DoS可保护gRPC应用免受此类破坏性攻击。
Ingress Controller 选型指南(第 2 部分):风险与面向未来的规划
了解选择错误的Ingress控制器可能带来的风险,以及如何从关键方面着手,让您的选择更好地适应未来需求。
NGINX Plus R19 正式发布
NGINX Plus R19扩展了监控功能,不仅提供更多指标,还新增了指标分析方式;增加试运行模式,用于测试限速效果;增强键值存储,以支持IP地址范围;并使限速更加动态。
NGINX现已正式加入F5
NGINX现已正式成为F5的一部分。Gus Robertson现任F5 NGINX业务部门负责人。他阐述了两家公司在人才、文化和愿景方面融合的价值,以及双方将如何携手增强NGINX的开源产品和商业产品。
