Nginx实用教程（二）：配置文件入门

Nginx配置文件结构

nginx配置文件由指令（directive）组成，指令分为两种形式，简单指令和区块指令。

一条简单指令由指令名、参数和结尾的分号（;）组成，例如： listen backlog ; ，其中“listen”是指令名，“80”、“backlog”、“4096”都是参数，“;”表示指令结尾。

区块指令由指令名、参数和花括号（{}）组成，例如： location /imag {} ，其中“location”是指令名，“/imag”是参数，“{}”用于包括其它指令和表示结尾。如果一个区块指令中的大括号可以包括其它简单指令或区块指令，那么这种区块指令称为“语境（context）”，大部分常用的区块指令都是“语境”。

不被任何其它区块指令包含的指令被认为处于main语境中，即main语境是nginx配置文件中最外层语境，任何指令都位于main语境或main语境的子级语境中。请看下面的配置文件例子：

 # nginx.conf
 worker_processes ;
 events {
     use epoll;
     worker_connections ;
 }
 http {
     include       mime.types;
     upstream server_group_a {
       server 192.168.1.1:;
       server 192.168.1.2:;
     }
     server {
         listen       ;
         server_name  www.example.com;
         location / {
            proxy_pass  http://server_group_a;
         }
     }
 }

上例中，worker_processes、event、http指令处于main语境中，use、worker_connections指令位于event语境中，include、upstream、server指令位于http语境中，两条server指令位于upstream语境中……

nginx软件是由各种不同功能的模块组成的，因此配置文件也遵照这种模块化的结构，nginx核心模块提供一些全局的配置指令，功能配置指令则由其他的功能模块提供。上例中的worker_processes、event指令都由nginx的核心模块提供，而http指令由http功能模块提供，proxy_pass指令则由http模块的一个子模块提供。

在安装nginx时，默认包含了一些常用功能模块，使用者也可以通过源码编译安装的方式自由选择安装其他功能模块，在配置nginx时可以查找功能模块的文档，文档中会说明这个功能模块包括哪些指令，以及这些指令应该在哪些语境下配置，而从语境（指令）查找它包含哪些可以配置的指令却是不靠谱的，因为安装的模块不同，包含的指令也不一样，因此配置nginx需要有一些经验，初入门者只能先从参考他人的示例着手。

功能模块除了http外，还有mail（邮件代理）、stream（TCP、UDP代理，v1.9.0以后）这两个功能模块。

全局配置指令

• 语法：include file | mask;
• 默认值：无
• 语境：任意

可在任意语境中使用，将其他配置文件中的指令引入到使用include指令的语境中。被引入的指令需要符合语法和引入的语境要求。举例：

http {
    include mime.types;
    include vhosts/*.conf;
}

将mime.types和vhosts目录下以“.conf”结尾的文件引入到http语境中。

• 语法：deamon on | off;
• 默认值：deamon on
• 语境：main

指定nginx是否以守护进程运行。

• 语法：debug_points abort | stop;
• 默认值：无
• 语境：main

用于debug，判断nginx内部错误，特别是判断工作中进程的socket溢出问题。nginx代码中包含了一些调试点，如果debug_points设置为abord，当运行到调试点时会产生一个核心运行信息dump文件，当设置为stop时会停止进程。

• 语法：error_log file [level]
• 默认值：error_log logs/error.log error;
• 语境：main, http, mail(v1.9.0后), stream(v1.7.11后), server, location

指定日志文件和日志级别。

file可以是指定的文件，也可以是标准错误输出文件stderr、syslog服务器或内存。输出到syslog服务器使用“syslog:”前缀，输出到循环内存缓冲区使用“memory:”前缀和缓冲区大小。

level参数指定输出日志的级别，高于指定级别的日志将被输出。支持的级别从低到高依次有：debug、info、notice、warn、error、crit、alert、emerg。

指定debug级别需要编译时安装了debug模块。

• 语法：env variable[=value];
• 默认值：env TZ;
• 语境：main

默认情况下，nginx只会继承TZ这个环境变量，这条指令可以将环境变量传递到nginx进程中，也可以定义新的变量传递到nginx进程中。

• 语法：load_module file;
• 默认值：无
• 语境：main

载入动态模块。例如：

load_module module/ngx_mail_module.so;

• 语法：lock_file file;
• 默认值：lock_file logs/nginx.lock;
• 语境：main

nginx使用锁的机制来实现accept_mutex功能和共享内存，大多数操作系统中锁都是一个原子操作，这种情况下这条指令无效，还有一些操作系统中使用“锁文件”的的机制来实现锁，此命令用来指定锁文件前缀名。

• 语法：master_process on | off;
• 默认值：master_process on;
• 语境：main

是否启用worker进程，如果设置为off，则不启用worker进程，由master进程处理请求。

• 语法：pcre_jit on | off;
• 默认值：pcre_jit off;
• 语境：main

在解析配置文件时对正则表达式启用或禁用实时编译（PCRE JIT）。

RCRE JIT能显著提升正则表达式的处理速度。

JIT依赖PCRE库8.20以后版本，并且在编译时需要指定--enable-jit参数。也可以将PCRE库作为nginx的模块编译安装（编译nginx指定--with-pcre=参数），并在编译时指定--with-pcre-jit参数启用JIT功能。

• 语法：pid file;
• 默认值：pid nginx.pid;
• 语境：main

指定pid文件。pid文件存放了master进程的进程号。

语法：ssl_engine device;

默认值：无

语境：main

如果使用了硬件ssl加速设备，使用此指令指定。

• 语法：thread_pool name threads=number [max_queue=number];
• 默认值：thread_pool default threads=32 max_queue=65535;
• 语境：main

在使用异步IO的情况下，定义命名线程池，并设置线程池大小和等待队列大小。当线程池中所有线程都繁忙时，新任务会放在等待队列中，如果等待队列满了，任务会报错退出。

命名线程池可以定义多个，供http模块的异步线程指令（aio）调用。

此指令在v1.7.11中出现。

• 语法：timer_resolution interval;
• 默认值：无
• 语境：main

设置时间精度，减少worker进程调用系统时间函数的次数。默认情况下，每个核心事件都会调用gettimeofday()接口来获得系统时间，以便nginx计算连接超时等工作，此指令指定更新时间的间隔，nginx在间隔时间内只调用一次系统时间函数。

• 语法：user user [group];
• 默认值：user nobody nodoby;
• 语境：main

指定master启动worker进程使用的linux用户和组。如果组（group）没有指定，那么会默认用一个和user同名的组名。

• 语法：worker_processes number | auto
• 默认值：worker_processes 1
• 语境：main

指定worker进程的数量。进程数最好是CPU核心数或CPU核心数的倍数。当设置为auto时，nginx会尝试自动获取CPU核心数并设置。

auto参数从v1.3.8和v1.2.5版本以后支持。

• 语法：worker_cpu_affinity cpumask ...;
• 　　　worker_cpu_affinity auto [cpumask];
• 默认值：无
• 语境：main

将worker进程绑定到CPU核心，每个worker进程对应一个二进制掩码，掩码的每一位对应一个CPU。默认情况下，worker不与cpu核心绑定。此指令只适用于Linux和FreeBSD。

举例：

worker_processes ;
worker_cpu_affinity    ;

表示有4个worker进程，第一个绑定到CPU0，第二个绑定到CPU1，以此类推，4个进程分别绑定一个CPU核心。

再例：

worker_processes ;
worker_cpu_affinity  ;

表示将第一个进程绑定到CPU0/CPU2，第二个worker进程绑定到CPU1/CPU3，这个例子适用于超线程场景，即一个核心虚拟出两个CPU线程。

值auto（v1.9.10）允许自动和可用的CPU绑定：

worker_process auto;
worker_cpu_affinity auto;

掩码（mask）可用用于限制某些CPU参加绑定。例如：

worker_cpu_affinity auto ;

只有CPU0/2/4/6参与绑定，其他的CPU不分配worker进程。

• 语法：worker_rlimit_core size;
• 默认值：无
• 语境：main

为worker进程修改系统核心转储文件（core file）的大小限制。通常提升这个值不需要重启主进程。

• 语法：worker_rlimit_nofile number;
• 默认值：无
• 语境：main

修改worker进程最大可打开句柄数限制。通常提升这个值不需要重启主进程。

• 语法：worker_shutdown_timeout time;
• 默认值：无
• 语境：main

此指令在v1.11.11中出现。用于设置安全地结束一个worker进程的超时时间。

当安全结束一个worker进程时，会停止对worker进程分配新连接，并等待他处理完当前的任务后再退出，如果设置了超时时间，超时后nginx会强制关闭worker进程的连接。

• 语法：working_directory directory;
• 默认值：无
• 语境：main

指定默认工作路径。主要用于worker进程导出内存转储文件，为worker进程指定的用户需要有改文件的写入权限。

连接处理控制指令

• 语法：events { ... }
• 默认值：无
• 语境：main

作用只是开辟一个指令区块，events语境中配置的指令用于控制连接处理行为。

• 语法：accept_mutex on | off;
• 默认值：accept_mutex off;
• 语境：events

当启用这个参数时，会使用互斥锁交替给worker进程分配新连接，否则话所有worker进程会争抢新连接，即或造成所谓的“惊群问题”，惊群问题会使nginx的空闲worker进程无法进入休眠状态，造成系统资源占用过多。启用此参数会一定程度上导致后台服务器负载不均衡，但是在高并发的情况下，关闭此参数可以提高nginx的吞吐量。

在支持epoll的操作系统上不需要启用accept_mutex（v1.11.3后），使用了reuseport功能也不需要启用（v1.9.1后，需要操作系统支持SO_REUSEPORT socket选项，Linux 3.9+）。

在v1.11.3以前版本中，默认值为on。

• 语法：accept_mutex_delay time;
• 默认值：accept_mutex_delay 500ms;
• 语境：events

如果accept_mutex参数启用，当一个空闲worker进程尝试获取互斥锁时发现有另一个worker进程已经获得互斥锁并处理新连接，这个空闲的worker进程等待下一次获取互斥锁尝试的时间。而获得互斥锁的进程在处理完当前连接后，会立即尝试获取互斥锁，因此此数值较大或连接压力较小时，会造成部分worker进程总是空闲，一部分进程总是繁忙的情况。

• 语法：debug_connection address | network | unix:;
• 默认值：无
• 语境：events

需要debug模块支持，需确认安装时包括了debug模块，可以使用nginx -V命令确定包含--wih-debug参数。

对特定的客户发起的连接开启debugging级别日志，用于分析和拍错。可以指定IPv4或者IPv6地址（v1.3.0,v1.2.1）或一个无类网段或域名，或UNIX socket（v1.3.0,v1.2.1）。例如：

events {
    debug_connection 127.0.0.1;
    debug_connection localhost;
    debug_connection 192.168.2.0/;
    debug_connection :0db8::/;
    debug_connection unix:;
}

非指定连接的日志级别依然由error_log指令决定。

• 语法：multi_accept on | off;
• 默认值：multi_accept off;
• 语境：events

当设置为off时，一个worker进程获得互斥锁时一次只处理一个新连接，如果设置为on，则一次性将所有新连接都分配给获得当前互斥锁的worker进程、当使用kqueue连接处理方式时（use kqueue），此项指令无效。

• 语法：use method;
• 默认值：无
• 语境：events

指定连接处理方式，通常不需要指定，nginx会自动使用最有效的方式。

连接处理方式用于决定用什么方法从当前的连接池中找出哪些连接已经准备好传输/接收数据。常见的连接处理方式有：

select（需要select模块）、poll（需要poll模块）、kqueue（macOS/FreeBSD 4.1+/OpenBSD 2.9+）、epoll（Linux 2.6+）、/dev/poll（Solaris 7 11/99+, HP/UX 11.22+ (eventport), IRIX 6.5.15+, and Tru64 UNIX 5.1A+）、eventport（Solaris 10+）

• 语法：worker_aio_requests number;
• 默认值：worker_aio_requests 32;
• 语境：events

在v1.1.4和1.0.7中出现。当启用aio（异步IO）和epoll连接处理方式后，单个worker进程最大的未完成异步IO操作数。

• 语法：worker_connections number;
• 默认值：worker_connections 512;
• 语境：events

单个worker进程可处理的最大并发连接数限制。

这个连接数包括和后台服务器之间的连接在内的所有的连接，而不仅是与客户的连接。所有worker进程的总连接数（即worker_connections × worker_processes ）不能超过操作系统最大可打开句柄数的限制（nofile），nofile限制可以通过worker_rlimit_nofile指令修改。

如果觉得本文对您有帮助，请扫描后面的二维码给予捐赠，您的支持是作者继续写出更好文章的动力！