Nginx参数配置详细说明【全局、http块、server块、events块】【已亲测】

Nginx重点参数配置说明

本文包含Nginx参数配置说明全局块、http块、server块、events块共计30多个参数配置与解释，其中常见参数包含配置错误出现的错误日志，能让你更快的解决问题。
该文的所有参数大部分经过单独测试，错误都是自己收集出来的，如有疑问可以私聊，文档有误感谢指正，文章对你有帮助请点赞收藏，非常感谢！

一、全局块

1.worker_processes [size] 工作进程数量

用于指定工作进程的数量,通常情况下，建议将worker_processes设置为机器的CPU核心数。 grep -c processor /proc/cpuinfo查看cpu核心数，也可以设置为自动(worker_processes auto)，会根据核心数来设置。增加工作进程数可以提高并发处理请求的能力,worker_processes的设置过大会占用过多的系统资源，导致系统负载过高。

当使用量超出配置时可能会出现：1.资源耗尽：nginx的worker_processes配置定义了能同时处理的最大并发连接数。如果实际并发连接数超过了配置的数量，可能会导致服务器的资源（如CPU、内存）耗尽，导致服务器崩溃或变得不稳定。2.连接被拒绝：当并发连接数超过配置的最大数量时，新的连接请求可能会被拒绝。客户端会收到一个连接被拒绝的错误信息。3.响应时间延长

2.worker_rlimit_nofile [size] 最大文件描述符数

用来设置每个worker进程可以打开的最大文件描述符数（文件句柄）的限制。默认值是平台相关的，在大多数Linux系统中，默认值为1024。

在Linux系统中，每个进程都有一个文件描述符表。当进程打开一个文件时，系统会分配一个文件描述符给该文件。该文件描述符可以用来通过文件描述符表进行读写操作，简单的理解为可以建立连接的数量。

由于每一个socket都会打开一个文件描述符,所以服务器可以同时处理连接数量受到系统文件描述符数量的限制。文件描述符的数量是有限的，取决于系统配置（通常是1024个）和系统限制（ulimit设置），使用ulimit -n查看。

如果一个进程需要打开的文件数量超过了其允许的文件描述符数目上限，则会导致文件描述符用尽的问题，一般日志会报错：“…failed(24:Too many open files)”或者日志报错：“worker process 54219 exited with fatal code 2 and cannot be respawned”。浏览器会一致加载卡住。

二、Events块

1.use [method]; IO 模型

我们现在使用的 Linux 都支持包括 select、epoll、kqueue、epoll 这一类的 IO 模型。现在最主流的就是 epoll ，它是完全的事件机制，可以实现多路 IO 复用。当一个 IO 阻塞后，让其它的 IO 继续处理，然后这个 IO 处理完成后触发事件回调回来继续处理。这个选项通常不需要显式指定，因为 Nginx 会默认使用当前系统中最有效的模式。

2.multi_accept\ [on/off]; 连接多路复用

multi_accept是用于控制是否启用“接收新连接”的多路复用。它的默认值是off，即不启用多路复用。默认情况下，Nginx使用异步的方式处理请求，对于每个新的连接请求，Nginx会创建一个新的worker进程来处理。当multi_accept被设置为"on"时，Nginx允许同时接受多个新连接，多个worker进程可以同时接受新连接，提高并发处理能力。而当multi_accept被设置为"off"时，Nginx只会顺序地接受新连接，一个worker进程只能处理一个新连接，降低了并发能力。

设置multi_accept为"on"可以提高Nginx的性能，特别是在高并发的场景下。然而，在低并发或资源有限的情况下，多个worker进程同时接受连接可能导致系统资源的消耗。

3.worker_connections [size]; 每个进程最大连接数

worker_connections用于设置每个worker进程的最大连接数。每个客户端连接到nginx时，都会占用一个worker连接。如果达到了worker_connections的最大值，那么nginx将不再接受新的客户端连接，后续连接就会等待。这个数字包括所有连接（例如与后台服务器的连接等），而不仅仅是与客户端的连接。另一个考虑因素是，同时连接的实际数量不能超过当前打开文件的最大数量限制，也就是说，它不应该超过 worker_rlimit_nofile 设置的数量。

理论上nginx服务器的最大连接数为 worker_processes*worker_connections。作为反向代理的时候为：(worker_connections * worker_processes)/2。当超过worker_connections的设值时，客户端请求页面会卡住加载，等待空闲连接。nginx日志会报错：epoll_create() failed (22:inalid argument)。

三、http块

（一） 请求处理（客户端与nginx服务）

1.请求头处理

1.1 client_header_buffer_size ;请求头缓冲区空间

client_header_buffer_size 用于设置客户端请求的请求行+请求头缓冲区大小。client_header_buffer_size的默认值是1k或者4k，具体取决于操作系统，默认情况下，如果操作系统的页大小是4k，则client_header_buffer_size的默认值为1k，如果操作系统的页大小是8k，则client_header_buffer_size的默认值为4k，一般默认值为1k。当Nginx接收到一个HTTP请求时，它首先会读取请求行和头部，然后将其存储在一个缓冲区中。当请求行+请求头的大小超过了client_header_buffer_size指定的大小时，会首先按照large_client_header_buffers配置的大小，如果还是超出范围，Nginx会返回HTTP 400 Bad Request响应。

1.2 large_client_header_buffers 请求头最大缓冲区空间

large_client_header_buffers用于设置nginx服务器接收和缓存客户端请求头的缓冲区的大小。该指令用于处理大型或包含大量请求头的客户端请求。默认值为4 8k，表示nginx为请求头分配4个大小为8k的缓冲区。这意味着nginx服务器将使用总共32 KB的内存来缓存客户端请求头。请求行(request line)的大小不能超过8k，否则返回414 Request-URI Too Large错误。请求头(request header)中的每一个头部字段的大小也不能超过8k，否则返回400 Bad Request或者400 Request Header Or Cookie Too Large错误，总的(请求行+请求头)的大小不能超过32k(4 * 8k)。

1.3 client_header_timeout [time] 请求头超时时间\

client_header_timeout定义nginx读取客户端请求头部的超时时间。默认值是 60s,如果客户端在这段时间内没有传送完整的头部到 Nginx ，则会断开与客户端的连接，Nginx 将返回错误 408 (Request Time-out) 到客户端。

2. 请求体处理

2.1 client_max_body_size [size]

client_max_body_size 用于限制客户端请求的主体（body）的最大大小，默认值为1m（1024kb）。当客户端向NGINX发送请求时，请求的主体可以包含数据，例如在POST或PUT请求中发送的表单数据或文件。client_max_body_size指令用于设置NGINX接受的最大请求主体大小。如果客户端请求的主体超过了指定的最大大小，NGINX将返回一个错误响应，通常是"413 Request Entity Too Large"，并且不会将请求体传递给后端应用程序服务器。该值需要根据后台服务器接受请求体大小来配置，如使用的是JBoss需要根据standalone.xml文件中的参数的实际情况来配置client_max_body_size 的大小。

2.2client_body_buffer_size [size]

client_body_buffer_size 是用于指定客户端请求主体缓冲区大小的配置项。在旧版本的nginx中（在Nginx 1.17.x版本之前），默认值为client_body_buffer_size 8k，而在新版本的nginx中，默认值为client_body_buffer_size 16k。当客户端发送请求主体时，nginx会将数据暂存在缓冲区中，然后再根据配置的方式进行处理。如果请求的数据小于client_body_buffer_size直接将数据先在内存中存储。如果请求的值大于client_body_buffer_size小于client_max_body_size，就会将数据先存储到临时文件中，默认情况下，它是位于当前运行的 Nginx 程序目录下的 client_body_temp，可以由client_body_temp_path 手动设置。

2.3 client_body_timeout [size]

client_body_timeout用于定义读取客户端请求正文的超时时间。默认值60s，当客户端向服务器发送请求，并且请求中包含了请求体（如POST请求），服务器需要等待客户端将请求体完全发送过来。如果客户端在连接建立后这段时间内没有传输完数据，则会断开与客户端的连接,Nginx 将返回408（Request Time-out） 错误到客户端，这个和client_header_timeout一样。

2.4 client_body_temp_path

定义存储客户端请求正文的临时文件的目录，没错，就是超出 client_body_buffer_size 设置大小的数据所保存的临时文件的位置。默认情况下，它是位于当前运行的 Nginx 程序目录下的 client_body_temp。配置方式如：client_body_temp_path /spool/nginx/client_temp 1 2;

2.5 client_body_in_file_only [clean/off/on]

此指令禁用NGINX缓冲区并将请求体存储在临时文件中。文件包含纯文本数据。该指令在NGINX配置的http，server和location区块使用。可选值有：

off:该值将禁用文件写入。

clean：请求body将被写入文件。 该文件将在处理请求后删除。

on: 请求正文将被写入文件。 处理请求后，将不会删除该文件。

默认情况下，指令值为关闭。

2.6 client_body_in_single_buffer [on/off]

该指令设置NGINX将完整的请求主体存储在单个缓冲区中。 默认情况下，指令值为off。 如果启用，它将优化读取$request_body变量时涉及的I/O操作。推荐在使用 $request_body 变量时使用，可以节省引入的拷贝操作。

（二）代理区处理（nginx与后台服务器）

1.响应缓冲区

1.1 proxy_buffering [on/off] 开启响应缓冲区

proxy_buffering该指令开启从后端服务器的响应body缓冲。默认值为on。如果proxy_buffering开启,nginx假定后台服务器会以最快速度响应,并把内容保存在由指令 proxy_buffer_size 和 proxy_buffers 指定的缓冲区里。如果响应body无法放在内存里边,那么部分内容会被写到磁盘上。如果proxy_buffering被关闭了,那么响应body会按照获取body的多少立刻同步传送到客户端。nginx不尝试计算后台服务器整个响应body的大小,nginx能从服务器接受的最大数据,是由指令 proxy_buffer_size指定的。对于基于长轮询(long-polling)的Comet 应用来说,关闭 proxy_buffering 是重要的,不然异步响应将被缓存导致Comet无法工作。但是无论proxy_buffering是否开启，proxy_buffer_size都是生效的。如果这个设置为off，那么proxy_buffers和proxy_busy_buffers_size这两个指令将会失效。

1.2 proxy_buffers [number] [size]代理缓冲区空间

number：表示每个worker进程的代理缓冲区的数量。size：表示每个缓冲区的大小。可以使用字节（B）、千字节（K）、兆字节（M）或者高级（G）作为单位。

proxy_buffers默认值为proxy_buffers 8 4k|8k，是 4K 或 8K，具体取决于服务器。proxy_buffers 8 4k意味着每个worker进程可以使用8个大小为4k的缓冲区。可以使用proxy_buffering参数控制是否启用代理缓冲，默认为关闭。若禁用代理缓冲，则proxy_buffers参数将不起作用。

1.3 proxy_buffer_size [size] 单个代理缓冲区空间

proxy_buffer_size 这个指令指定了单个代理缓冲区的大小。默认值为4k或者8k，具体取决于服务器。当Nginx作为代理服务器时，它会将来自上游服务器的响应存储在缓冲区中，然后再将其传输给客户端。proxy_buffer_size所设置的size的作用是用来存储upstream端response的header（响应头）。如果超出该值则会返回502（Bad Gateway）。并会出现错误nginx提示界面。

1.4 proxy_busy_buffer_size [size] 响应临时缓冲区空间

proxy_busy_buffers_size默认值为proxy_buffer_size*2。Nginx服务器在读取上游服务器响应时的临时缓冲区大小。proxy_busy_buffers_size不是独立的空间，他是proxy_buffers和proxy_buffer_size的一部分。 nginx会在没有完全读完后端响应就开始向客户端传送数据，所以它会划出一部分busy状态的buffer来专门向客户端传送数据(建议为proxy_buffers中单个缓冲区的2倍)，然后它继续从后端取数据。proxy_busy_buffer_size参数用来设置处于busy状态的buffer有多大。（1）如果完整数据大小小于proxy_busy_buffer_size大小，当数据传输完成后，马上传给客户端；（2）如果完整数据大小不小于proxy_busy_buffer_size大小，则装满busy_buffer后，马上传给客户端。

以上配置工作原理：

在proxy_buffering 开启的情况下，Nginx将会尽可能的读取所有的upstream端传输的数据到buffer，直到proxy_buffers设置的所有buffer们 被写满或者数据被读取完(EOF)。此时nginx开始向客户端传输数据，会同时传输这一整串buffer们。同时如果response的内容很大的话，Nginx会接收并把他们写入到temp_file里去。大小由proxy_max_temp_file_size控制。如果busy的buffer 传输完了会从temp_file里面接着读数据，直到传输完毕。

一旦proxy_buffers设置的buffer被写入，直到buffer里面的数据被完整的传输完（传输到客户端），这个buffer将会一直处 在busy状态，我们不能对这个buffer进行任何别的操作。所有处在busy状态的buffer size加起来不能超过proxy_busy_buffers_size，所以proxy_busy_buffers_size是用来控制同时传输到客户 端的buffer数量的。

2.代理时间设置

2.1 proxy_connect_timeout [time];代理连接超时时间

代理连接超时时间：指定nginx与后端服务器建立连接的超时时间，默认为60秒。如果在这个时间内无法与后台服务器建立连接（跟服务器处理业务时间无关，如网络不可用），nginx会中断连接尝试。nginx会认为该服务器不可用，会自动切换到可用服务器上去。并且会记录到max_fails的次数中，当次数达到设置的值时，该服务器会被移除负载均衡，后续请求不在转发，移除时间根据 max_timeout决定，如果在max_timeout期间检测到该服务器可用会立马加入负载均衡中。如果在proxy_connect_timeout时间内后端服务恢复了，会立马建立连接。

日志错误记录：connect() failed (110: Connection timed out) while connecting to upstream

2.2 proxy_read_timeout [time];代理响应超时时间

Nginx服务器读取后台服务器响应的超时时间，默认的超时时间是60秒。如果在代理请求期间，Nginx在指定的时间内没有接收到后台服务器的响应，它将终止与后台服务器的连接，并且不会自动切换到其服务上去，并将错误返回给客户端504 Gateway Timeout。会算作一次错误记录到max_fails中，当达到错误次数时，下一次请求就会切换到其他可用后台服务器。

日志记录：upstream timed out (110: Connection timed out) while reading response header from upstream

2.3 proxy_send_timeout [time]；代理请求发送时间

用于设置nginx服务器向后端服务器发送请求的超时时间。默认值为60s。当nginx作为代理服务器转发请求给后端服务器时，如果发送请求的时间超过了proxy_send_timeout所设置的时间，nginx将会中断与后端服务器的连接。并添加错误次数，当达到max_fails次数后，下一次请求会切换到另一台服务器。

（三）server块

1.max_fails=[number] 最大失败次数

max_fails：默认值为1，表示在连续请求失败的次数，超过此值后，Nginx会认为该后端服务器不可用。当一个请求失败时，max_fails会被增加1；当一个请求成功时，max_fails会被重置为0。一旦达到max_fails的值，Nginx将不再将请求发送到该服务器，直到fail_timeout时间过去后，将重新尝试请求。

2.max_timeout=[time]；失败超时时间

max_timeout：默认值为10秒，表示在失败的连续请求达到max_fails之后，Nginx会暂时将该后端服务器标记为不可用，并等待fail_timeout时间后再重新尝试请求。在这段时间内，Nginx将不会将请求发送到该服务器。如果在fail_timeout时间内，这个服务器恢复正常，Nginx将重新开始将请求发送到该服务器。

（四）缓存模块

可以在一定程度上，减少服务器的处理请求压力。比如对一些图片，css或js做一些缓存，那么在每次刷新浏览器的时候，就不会重新请求了，而是从缓存里面读取。这样就可以减轻服务器的压力。注意：缓存中含有jsp代码时会出现的问题，jsp文件中的动态数据不正确问题，例如使用java代码赋值。因为nginx缓存jsp文件后，查看已缓存的文件可以发现，nginx缓存的jsp文件中的动态数据是写死的，后续的访问直接返回jsp，没有动态更新。

1.proxy_cache_path 缓存的路径和其他参数

例如：

http{

proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=my_cache:10m max_size=10g inactive=60m use_temp_path=off;

}

path：强制参数，指定缓存文件的存放路径。

levels：定义了缓存目录的层级。每层可以用1（最多16种选择，0-f）或2（最多256种选择，00-ff）表示，中间用 : 分隔。

proxy_cache_path /data/nginx/cache; 代表所有缓存只有一个目录，比如/data/nginx/cache/d7b6e5978e3f042f52e875005925e51b

proxy_cache_path /data/nginx/cache levels=1:2; 代表缓存是二层目录（有16*256=4096个目录），比如/data/nginx/cache/b/51/d7b6e5978e3f042f52e875005925e51

keys_zone：强制参数，定义共享内存区的名称和大小，该共享内存用于保存缓存项目的元数据（所有活动的key和缓存数据相关的信息），这样nginx可以快速判断一个request是否命中或者未命中缓存，1m可以存储8000个key，10m可以存储80000个key。

inactive：删除指定时间内未被访问的缓存文件，默认10分钟。

max_size：设置了缓存存储的上限，如果不指定，最大会用掉所有磁盘空间，一般10g起。

use_temp_path：直接把临时文件放在缓存目录中，一般不建议开启。

2.proxy_cache [zone] 缓存区域

proxy_cache指令用于配置HTTP代理缓存。它用于控制NGINX是否应该缓存来自上游服务器的响应，并在后续请求中提供缓存的响应，而无需再次访问上游服务>器。zone 是自定义的缓存名称，zone名称由proxy_cache_path指令定义，用于标识特定的缓存区域。off为不使用。

3.proxy_cache_valid response_code1 [response_code2 …] time;有效期

用于指定代理缓存中缓存的不同HTTP响应的有效期。response_code1, response_code2, … 是HTTP响应码，可以指定多个，比如：proxy_cache_valid 200 302 5m。对于状态码200和302的响应，缓存将保留5分钟。可以配置多个proxy_cache_valid，建议这个指令跟随在proxy_cache指令之后。

4.proxy_cache_key [string] 缓存键值

proxy_cache_key指令用于定义代理缓存的键值。键值决定了缓存内容的唯一性，并且可以根据特定的请求属性进行定制。string可以是一个包含变量和静态文本的字符串，用于构建缓存键值。例如配置为：proxy_cache_key scheme$reques{t}_{m}ethod$host$request_uri; http协议 + 请求方式 + 主机名 + uri 把这四个作为一个单独的key来缓存。

5.proxy_cache_bypass [string] 绕过缓存

proxy_cache_bypass 指令用于在特定条件下绕过缓存并直接向后端服务器发起请求。可以使用一个或多个条件来配置。如果满足任何一个条件，将绕过缓存。这里的string通常为nginx的的一些内置变量或者自己定义的变量。

例如：proxy_cache_bypass $cookie_nocache $arg_nocache $arg_comment $http_pragma $htt{p}_{a}uthorization;其中，$cookie_nocache、$ar{g}_{n}ocache、$arg_comment、$htt{p}_{p}ragma和$http_authorization 都是Nginx配置文件的变量。

例如：proxy_cache_bypass $http_pragma $http_authorization; 在这个示例中，如果请求头部中包含 “pragma” 或 “authorization” 的字段，则会绕过缓存。

6.proxy_no_cache 不缓存指令

proxy_no_cache指令用于控制哪些响应不应该被缓存。可以在location块中使用proxy_no_cache指令来定义不应该缓存的条件。proxy_no_cache $http_cookie $arg_nocache;在示例中，如果请求中包含名为nocache的查询参数或者有Cookie头，则该请求的响应将不会被缓存。proxy_no_cache $reques{t}_{u}ri\dot{j}son$;表示不缓存以".json"结尾的URL。

7.proxy_cache_background_update 后台更新缓存

proxy_cache_background_update指令用于控制是否在后台更新缓存。 当使用NGINX作为代理服务器时，它通常会将请求的响应存储在缓存中，以减少重复请求的响应时间。然而，有时候后端服务器可能需要一些时间才能生成响应，或者在响应生成之前发生了错误。在这种情况下，NGINX默认会等待后端服务器生成响应并缓存，然后再将响应发送给客户端。

但是，有时候你可能希望在后端服务器正在生成响应时，NGINX能够立即将响应发送给客户端，并在后台异步地更新缓存。这种情况下，就可以使用proxy_cache_background_update指令。

当指令的值为on时，NGINX将允许在后台更新缓存。这意味着当后端服务器正在生成响应时，NGINX将立即将响应发送给客户端，并在后台异步地更新缓存。

8.proxy_cache_lock 缓存锁

proxy_cache_lock 是一个用于控制缓存锁的指令。当多个请求同时访问缓存时，可以使用proxy_cache_lock来确保只有一个请求能够更新缓存，而其他请求将等待锁释放。proxy_cache_lock on;：启用缓存锁。当一个请求开始更新缓存时，其他请求将等待锁释放。proxy_cache_lock off;：禁用缓存锁。多个请求可以同时更新缓存，可能导致缓存不一致的情况。

（五）其他配置

1.keepalive_timeout [time]

keepalive_timeout指令用于设置持久化连接的超时时间。默认值是 75 秒，有些浏览器最多只保持 60 秒，所以可以设定为 60 秒。持久化连接也称为长连接，它允许客户端和nginx服务器之间保持一段时间的连接，而不需要为每个请求都建立新的连接。即在点击一个链接后，在指定时间内没有点击另一个链接，则会关闭当前TCP连接。如果在指定时间内点击了其它链接，则会复用当前的TCP连接，不用进行三次握手，超时时间为 0 表示不使用 TCP 长连接。通过使用持久化连接，可以减少建立连接的开销，提高网络性能和响应速度。

2.send_timeout [time]

send_timeout用来限制nginx服务器向客户端发送响应的时间，如果在指定的时间内服务器没有能够发送完整的响应，则会断开连接。默认情况下，send_timeout的值为60s。

3.reset_timedout_connection [on/off]

reset_timedout_connection用于在 Nginx 服务器上处理超时的连接。当 Nginx 接收到一个来自客户端的请求，但是在设定的超时时间内没有接收到完整的请求数据时，Nginx 将会强制关闭这个连接，会立即关闭该连接，客户端不会收到任何关于超时连接的错误信息。使用 reset_timedout_connection 指令可以防止在多个后端服务器上同时进行请求时，连接超时后 Nginx 服务器继续等待请求完成的情况，从而释放服务器资源。

四、检测模块

（一）nginx http_stub_status 相关参数

1.配置：

location nginx_status {

Stub_status on;

}

访问：ip+端口+/nginx_status可以实时查看nginx状态信息

2.参数说明：

Active connections: 1161 

server accepts handled requests

 207378 207378 3625441 

Reading: 0 Writing: 777 Waiting: 384 
1
2
3
4
5
6
7

说明：

Active connections：当前活动客户端连接数，包括等待连接。

accepts：接受的客户端连接总数。

Handled:已处理的连接总数。 一般情况下，除非达到某些资源限制，否则该参数值与accepts相同 （例如，worker_connections 限制）。

requests：客户端请求总数。

Reading:nginx 正在读取请求标头的当前连接数。

Writing: nginx 将响应写回客户端的当前连接数。

Waiting:当前等待请求的空闲客户端连接数。

活动连接 – 所有打开的连接数。 这并不意味着用户数量。

单个用户对于单个综合浏览量可以打开许多到服务器的并发连接。

服务器接受已处理的请求 - 这显示三个值。

首先是接受的连接总数。

其次是处理的连接总数。 通常前 2 个值是相同的。

第三个值是请求的数量和处理量。 这通常大于第二个值。

将第三个值除以第二个值将得到 Nginx 处理的每个连接的请求数。

在上面的示例中，10993/7368，每个连接有 1.49 个请求。

Reading —nginx读取请求头

Writing —nginx 读取请求正文、处理请求或将响应写入客户端

Waiting —keep-alive连接，实际上它是active – (reading + writing).

该值取决于 keepalive-timeout。

不要将非零等待值与性能不佳相混淆。 可以忽略不计。

不过，您可以通过设置 keepalive_timeout 0 来强制零等待；