Core functionality
- Example Configuration
- Directives
- accept_mutex
- accept_mutex_delay
- daemon
- debug_connection
- debug_points
- env
- error_log
- events
- include
- load_module
- lock_file
- master_process
- multi_accept
- pcre_jit
- pid
- ssl_engine
- thread_pool
- timer_resolution
- use
- user
- worker_aio_requests
- worker_connections
- worker_cpu_affinity
- worker_priority
- worker_processes
- worker_rlimit_core
- worker_rlimit_nofile
- worker_shutdown_timeout
- working_directory
Example Configuration
user www www;
worker_processes 2;
error_log /var/log/nginx-error.log info;
events {
use kqueue;
worker_connections 2048;
}
...
Directives
| Syntax: | accept_mutex on | off; |
| Default: | accept_mutex off; |
| Context: | events |
如果启用了accept_mutex，则工作进程将依次接受新的连接。否则，将通知所有工作进程有关新连接的信息，如果新连接的数量很少，则某些工作进程可能会浪费系统资源。
Note
在支持EPOLLEXCLUSIVE标志(1.11.3)的系统上或使用reuseport时，无需启用accept_mutex。
Note
在 1.11.3 版之前，默认值为on。
| Syntax: | accept_mutex_delay time; |
| Default: | accept_mutex_delay 500ms; |
| Context: | events |
如果启用了accept_mutex，则指定在另一个工作进程当前正在接受新连接的情况下，工作进程尝试重新启动接受新连接的最长时间。
| Syntax: | daemon on | off; |
| Default: | daemon on; |
| Context: | main |
确定 nginx 是否应成为守护程序。主要在开发过程中使用。
| Syntax: | debug_connection address | CIDR | unix:; |
| Default: | — |
| Context: | events |
为选定的客户端连接启用调试日志。其他连接将使用error_log指令设置的日志记录级别。调试连接由 IPv4 或 IPv6(1.3.0，1.2.1)地址或网络指定。也可以使用主机名指定连接。对于使用 UNIX 域套接字(1.3.0，1.2.1)的连接，调试日志通过“ unix:”参数启用。
events {
debug_connection 127.0.0.1;
debug_connection localhost;
debug_connection 192.0.2.0/24;
debug_connection ::1;
debug_connection 2001:0db8::/32;
debug_connection unix:;
...
}
Note
为了使此指令有效，需要使用--with-debug构建 nginx，请参见“ 调试日志”。
| Syntax: | debug_points abort | stop; |
| Default: | — |
| Context: | main |
该伪指令用于调试。
当检测到内部错误时，例如重新启动工作进程时套接字的泄漏，启用debug_points会导致创建核心文件(abort)或停止进程(stop)，以便使用系统调试器进行进一步分析。
| Syntax: | env variable[=value]; |
| Default: | env TZ; |
| Context: | main |
默认情况下，nginx 会删除从其父进程继承的所有环境变量(TZ 变量除外)。该指令允许保留某些继承的变量，更改其值或创建新的环境变量。这些变量是：
-
在可执行文件的live upgrade期间继承；
-
由ngx_http_perl_module模块使用；
-
由工作进程使用。应该记住的是，以这种方式控制系统库并非总是可行的，因为通常仅在初始化期间(即在使用此伪指令设置变量之前)检查变量是很常见的。exception 是上面提到的可执行文件的live upgrade。
除非明确配置，否则 TZ 变量始终是继承的并且可用于ngx_http_perl_module模块。
Usage example:
env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;
Note
NGINX 环境变量由 Nginx 在内部使用，不应由用户直接设置。
| Syntax: | error_log file [level]; |
| Default: | error_log logs/error.log error; |
| Context: | main , http , mail , stream , server , location |
配置日志记录。可以在同一级别(1.5.2)上指定多个日志。如果未在main配置级别上明确定义将日志写入文件，则将使用默认文件。
第一个参数定义一个file，它将存储日志。特殊值stderr选择标准错误文件。可以通过指定“ syslog:”前缀来配置登录到syslog。可以通过指定前缀“ memory:”和缓冲区size来配置登录到循环内存缓冲区，通常用于调试(1.7.11)。
第二个参数确定日志记录level，并且可以是以下之一：debug，info，notice，warn，error，crit，alert或emerg。以上日志级别按严重性从高到低的顺序列出。设置某个日志级别将导致记录所有指定级别或更严重的日志级别的消息。例如，默认级别error将导致记录error，crit，alert和emerg消息。如果省略此参数，则使用error。
Note
为使debug日志正常工作，需要使用--with-debug构建 nginx，请参阅“ 调试日志”。
Note
从 1.7.11 版本开始，可以在stream级别上指定指令；从 1.9.0 版本开始，可以在mail级别上指定指令。
| Syntax: | events { ... } |
| Default: | — |
| Context: | main |
提供配置文件上下文，在其中指定影响连接处理的指令。
| Syntax: | include file | mask; |
| Default: | — |
| Context: | any |
将另一个file或与指定的mask匹配的文件包含到配置中。包含的文件应包含语法正确的指令和块。
Usage example:
include mime.types;
include vhosts/*.conf;
| Syntax: | load_module file; |
| Default: | — |
| Context: | main |
该指令出现在 1.9.11 版中。
加载动态模块。
Example:
load_module modules/ngx_mail_module.so;
| Syntax: | lock_file file; |
| Default: | lock_file logs/nginx.lock; |
| Context: | main |
nginx 使用锁定机制来实现accept_mutex并序列化对共享内存的访问。在大多数系统上，锁是使用原子操作实现的，并且此指令将被忽略。在其他系统上，使用“锁定文件”机制。该伪指令为锁定文件的名称指定前缀。
| Syntax: | master_process on | off; |
| Default: | master_process on; |
| Context: | main |
确定是否启动工作进程。该指令适用于 Nginx 开发人员。
| Syntax: | multi_accept on | off; |
| Default: | multi_accept off; |
| Context: | events |
如果禁用了multi_accept，则辅助进程将一次接受一个新连接。否则，辅助进程将一次接受所有新连接。
Note
如果使用kqueue连接处理方法，则该指令将被忽略，因为该指令报告 await 接受的新连接数。
| Syntax: | pcre_jit on | off; |
| Default: | pcre_jit off; |
| Context: | main |
该指令出现在版本 1.1.12 中。
对配置解析时已知的正则表达式启用或禁用“即时编译”(PCRE JIT)。
PCRE JIT 可以大大加快正则表达式的处理速度。
Note
从使用--enable-jit配置参数构建的 8.20 版本开始，PCRE 库中提供了 JIT。当使用 nginx(--with-pcre=)构建 PCRE 库时，将通过--with-pcre-jit配置参数启用 JIT 支持。
| Syntax: | pid file; |
| Default: | pid logs/nginx.pid; |
| Context: | main |
定义一个file，它将存储主流程的流程 ID。
| Syntax: | ssl_engine device; |
| Default: | — |
| Context: | main |
定义硬件 SSL 加速器的名称。
| Syntax: | thread_pool name threads=number [max_queue=number]; |
| Default: | thread_pool default threads=32 max_queue=65536; |
| Context: | main |
该指令出现在 1.7.11 版本中。
定义用于多线程读取和发送文件without blocking工作进程的命名线程池。
threads参数定义池中的线程数。
如果池中的所有线程都处于繁忙状态，则新任务将在队列中 await。 max_queue参数限制了队列中允许 await 的任务数。默认情况下，队列中最多可以 await65536 个任务。队列溢出时，任务将完成并出现错误。
| Syntax: | timer_resolution interval; |
| Default: | — |
| Context: | main |
降低工作进程中的计时器分辨率，从而减少进行gettimeofday()个系统调用的次数。默认情况下，每次接收到内核事件时都会调用gettimeofday()。在降低分辨率的情况下，每个指定的interval只调用一次gettimeofday()。
Example:
timer_resolution 100ms;
间隔的内部实现取决于所使用的方法：
-
如果使用
kqueue，则使用EVFILT_TIMER过滤器； -
timer_create()(如果使用了eventport)； -
setitimer()否则。
| Syntax: | use method; |
| Default: | — |
| Context: | events |
指定要使用的connection processing method。通常无需显式指定它，因为默认情况下 nginx 将使用最有效的方法。
| Syntax: | user user [group]; |
| Default: | user nobody nobody; |
| Context: | main |
定义工作进程使用的user和group凭据。如果省略group，则使用名称等于user的组。
| Syntax: | worker_aio_requests number; |
| Default: | worker_aio_requests 32; |
| Context: | events |
该指令出现在 1.1.4 和 1.0.7 版本中。
当将aio与epoll连接处理方法一起使用时，请为单个工作进程设置最大number的未完成异步 I/O 操作。
| Syntax: | worker_connections number; |
| Default: | worker_connections 512; |
| Context: | events |
设置工作进程可以打开的最大同时连接数。
请记住，此数字包括所有连接(例如，与代理服务器的连接等)，而不仅包括与客户端的连接。另一个需要考虑的因素是，同时连接的实际数量不能超过打开文件最大数量的当前限制，可以通过worker_rlimit_nofile进行更改。
| Syntax: | worker_cpu_affinity cpumask ...; |
worker_cpu_affinity auto [cpumask]; | |
| 默认值： | — |
上下文： main |
将工作进程绑定到 CPU 组。每个 CPU 集由允许的 CPU 的位掩码表示。应该为每个工作进程定义一个单独的集合。默认情况下，辅助进程未绑定到任何特定的 CPU。
For example,
worker_processes 4;
worker_cpu_affinity 0001 0010 0100 1000;
将每个工作进程绑定到一个单独的 CPU，同时
worker_processes 2;
worker_cpu_affinity 0101 1010;
将第一个工作进程绑定到 CPU0/CPU2，将第二个工作进程绑定到 CPU1/CPU3.第二个示例适用于超线程。
特殊值auto(1.9.10)允许将工作进程自动绑定到可用的 CPU：
worker_processes auto;
worker_cpu_affinity auto;
可选的 mask 参数可用于限制可用于自动绑定的 CPU：
worker_cpu_affinity auto 01010101;
Note
该指令仅在 FreeBSD 和 Linux 上可用。
| Syntax: | worker_priority number; |
| Default: | worker_priority 0; |
| Context: | main |
定义工作进程的调度优先级，就像通过nice命令执行的调度一样：负number表示更高的优先级。允许范围通常为-20 至 20.
Example:
worker_priority -10;
| Syntax: | worker_processes number | auto; |
| Default: | worker_processes 1; |
| Context: | main |
定义工作进程数。
最佳值取决于许多因素，包括(但不限于)CPU 内核数，存储数据的硬盘驱动器数以及加载模式。如有疑问，请将其设置为可用的 CPU 内核数将是一个不错的开始(值“ auto”将尝试自动检测它)。
Note
从版本 1.3.8 和 1.2.5 开始支持auto参数。
| Syntax: | worker_rlimit_core size; |
| Default: | — |
| Context: | main |
更改工作进程的核心文件(RLIMIT_CORE)的最大大小限制。用于在不重新启动主进程的情况下增加限制。
| Syntax: | worker_rlimit_nofile number; |
| Default: | — |
| Context: | main |
更改工作进程最大打开文件数(RLIMIT_NOFILE)的限制。用于在不重新启动主进程的情况下增加限制。
| Syntax: | worker_shutdown_timeout time; |
| Default: | — |
| Context: | main |
该指令出现在 1.11.11 版中。
配置超时以正常关闭工作进程。 time过期后，nginx 将尝试关闭当前打开的所有连接，以方便关闭。
| Syntax: | working_directory directory; |
| Default: | — |
| Context: | main |
定义工作进程的当前工作目录。它主要在编写核心文件时使用，在这种情况下，工作进程应具有对指定目录的写许可权。
