核心功能
示例配置
user www www; worker_processes 2; error_log /var/log/nginx-error.log info; events { use kqueue; worker_connections 2048; } ...
指令
语法 |
accept_mutex |
---|---|
默认值 |
accept_mutex off; |
上下文 |
events |
如果启用了 accept_mutex
,工作进程将轮流接受新连接。否则,所有工作进程都会收到关于新连接的通知,如果新连接的数量很少,一些工作进程可能会浪费系统资源。
在支持 EPOLLEXCLUSIVE 标志 (1.11.3) 的系统上或使用 reuseport 时,无需启用 accept_mutex
。
在 1.11.3 版本之前,默认值是 on
。
语法 |
accept_mutex_delay |
---|---|
默认值 |
accept_mutex_delay 500ms; |
上下文 |
events |
如果启用了 accept_mutex,此指令指定了当其他工作进程正在接受新连接时,工作进程尝试重新开始接受新连接的最长时间。
语法 |
daemon |
---|---|
默认值 |
daemon on; |
上下文 |
main |
决定 nginx 是否应作为守护进程运行。主要用于开发期间。
语法 |
debug_connection |
---|---|
默认值 | — |
上下文 |
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:; ... }
要使此指令工作,nginx 需要使用 --with-debug
构建,请参阅“调试日志”。
语法 |
debug_points |
---|---|
默认值 | — |
上下文 |
main |
此指令用于调试。
当检测到内部错误时,例如工作进程重启时套接字泄漏,启用 debug_points
会导致生成核心文件 (abort
) 或停止进程 (stop
),以便使用系统调试器进行进一步分析。
语法 |
env |
---|---|
默认值 |
env TZ; |
上下文 |
main |
默认情况下,nginx 会移除从父进程继承的所有环境变量,除了 TZ 变量。此指令允许保留一些继承的变量、更改它们的值或创建新的环境变量。然后这些变量会
- 在可执行文件的热升级期间继承;
- 由 ngx_http_perl_module 模块使用;
- 由工作进程使用。需要注意的是,以这种方式控制系统库并不总是可能的,因为库通常只在初始化期间检查变量,而这远早于使用此指令设置变量的时间。上述的可执行文件热升级是例外情况。
除非明确配置,否则 TZ 变量总是被继承并可供 ngx_http_perl_module 模块使用。
使用示例
env MALLOC_OPTIONS; env PERL5LIB=/data/site/modules; env OPENSSL_ALLOW_PROXY_CERTS=1;
NGINX 环境变量在 nginx 内部使用,不应由用户直接设置。
语法 |
error_log |
---|---|
默认值 |
error_log logs/error.log error; |
上下文 |
main , http , mail , stream , server , location |
配置日志记录。可以在同一配置级别 (1.5.2) 指定多个日志。如果在 main
配置级别未明确定义日志文件写入,则使用默认文件。
第一个参数定义用于存储日志的 文件
。特殊值 stderr
选择标准错误文件。通过指定“syslog:
”前缀可以配置记录到 syslog。通过指定“memory:
”前缀和缓冲区 大小
可以配置记录到 循环内存缓冲区,这通常用于调试 (1.7.11)。
第二个参数确定日志的 级别
,可以是以下之一:debug
, info
, notice
, warn
, error
, crit
, alert
, 或 emerg
。以上日志级别按严重性递增的顺序列出。设置某个日志级别将导致记录指定级别及更严重级别的所有消息。例如,默认级别 error
将导致记录 error
, crit
, alert
, 和 emerg
消息。如果省略此参数,则使用 error
。
要使debug
日志记录工作,nginx 需要使用--with-debug
构建,请参阅“调试日志”。
此指令可在 1.7.11 版本起在stream
级别指定,并在 1.9.0 版本起在
语法 |
events { ... } |
---|---|
默认值 | — |
上下文 |
main |
提供配置文件上下文,其中指定了影响连接处理的指令。
语法 |
include |
---|---|
默认值 | — |
上下文 |
any |
将另一个 文件
或匹配指定 掩码
的文件包含到配置中。包含的文件应包含语法正确的指令和块。
使用示例
include mime.types; include vhosts/*.conf;
语法 |
load_module |
---|---|
默认值 | — |
上下文 |
main |
此指令出现在 1.9.11 版本中。
加载动态模块。
示例
load_module modules/ngx_mail_module.so;
语法 |
lock_file |
---|---|
默认值 |
lock_file logs/nginx.lock; |
上下文 |
main |
nginx 使用锁定机制来实现 accept_mutex 并串行化访问共享内存。在大多数系统上,锁定是使用原子操作实现的,此指令会被忽略。在其他系统上,使用“锁文件”机制。此指令指定锁文件名的前缀。
语法 |
master_process |
---|---|
默认值 |
master_process on; |
上下文 |
main |
确定是否启动工作进程。此指令旨在供 nginx 开发人员使用。
语法 |
multi_accept |
---|---|
默认值 |
multi_accept off; |
上下文 |
events |
如果禁用了 multi_accept
,工作进程将一次只接受一个新连接。否则,工作进程将一次接受所有新连接。
如果使用 kqueue 连接处理方法,此指令将被忽略,因为它会报告等待接受的新连接数量。
语法 |
pcre_jit |
---|---|
默认值 |
pcre_jit off; |
上下文 |
main |
此指令出现在 1.1.12 版本中。
为配置解析时已知的正则表达式启用或禁用“即时编译”(PCRE JIT)。
PCRE JIT 可以显著加速正则表达式的处理。
JIT 在 PCRE 库 8.20 版本及更高版本中可用,需要使用--enable-jit
配置参数构建。当 PCRE 库与 nginx 一起构建时 (--with-pcre=
),通过--with-pcre-jit
配置参数启用 JIT 支持。
语法 |
pid |
---|---|
默认值 |
pid logs/nginx.pid; |
上下文 |
main |
定义一个 文件
,用于存储主进程的进程 ID。
语法 |
ssl_engine |
---|---|
默认值 | — |
上下文 |
main |
定义硬件 SSL 加速器的名称。
此模块可以在配置测试期间由 OpenSSL 动态加载。
语法 |
ssl_object_cache_inheritable |
---|---|
默认值 |
ssl_object_cache_inheritable on; |
上下文 |
main |
此指令出现在 1.27.4 版本中。
如果启用,SSL 对象(SSL 证书、私钥、受信任的 CA 证书、CRL 列表)将在配置重载时继承。
如果自从上次配置加载以来文件修改时间和文件索引没有变化,则从文件加载的 SSL 对象会被继承。指定为 engine:name:id
的私钥永远不会被继承。指定为 data:value
的私钥总是会被继承。
从变量加载的 SSL 对象无法继承。
示例
ssl_object_cache_inheritable on; http { ... server { ... ssl_certificate example.com.crt; ssl_certificate_key example.com.key; } }
语法 |
thread_pool |
---|---|
默认值 |
thread_pool default threads=32 max_queue=65536; |
上下文 |
main |
此指令出现在 1.7.11 版本中。
定义用于不阻塞工作进程的多线程文件读写操作的线程池的 名称
和参数。
threads
参数定义了线程池中的线程数量。
如果线程池中的所有线程都忙,新任务将在队列中等待。max_queue
参数限制允许在队列中等待的任务数量。默认情况下,最多 65536 个任务可以在队列中等待。当队列溢出时,任务会以错误完成。
语法 |
timer_resolution |
---|---|
默认值 | — |
上下文 |
main |
降低工作进程中的计时器分辨率,从而减少 gettimeofday()
系统调用的次数。默认情况下,每次接收到内核事件时都会调用 gettimeofday()
。降低分辨率后,gettimeofday()
仅在指定的 间隔
内调用一次。
示例
timer_resolution 100ms;
内部实现间隔取决于使用的方法
- 如果使用
kqueue
,则使用EVFILT_TIMER
过滤器; -
如果使用
eventport
,则使用timer_create()
; -
否则使用
setitimer()
。
语法 |
use |
---|---|
默认值 | — |
上下文 |
events |
指定要使用的连接处理 方法
。通常无需明确指定,因为 nginx 默认会使用最有效的方法。
语法 |
user |
---|---|
默认值 |
user nobody nobody; |
上下文 |
main |
定义工作进程使用的 用户
和 组
凭据。如果省略 组
,则使用与 用户
同名的组。
语法 |
worker_aio_requests |
---|---|
默认值 |
worker_aio_requests 32; |
上下文 |
events |
此指令出现在 1.1.4 和 1.0.7 版本中。
当将 aio 与 epoll 连接处理方法一起使用时,设置单个工作进程的最大未完成异步 I/O 操作 数量
。
语法 |
worker_connections |
---|---|
默认值 |
worker_connections 512; |
上下文 |
events |
设置工作进程可以打开的最大并发连接数。
应该注意的是,这个数字包括所有连接(例如与代理服务器的连接等),而不仅仅是与客户端的连接。另一个考虑因素是,实际的并发连接数不能超过当前对最大打开文件数的限制,该限制可以通过 worker_rlimit_nofile 更改。
语法 |
worker_cpu_affinity worker_cpu_affinity |
---|---|
默认值 | — |
上下文 |
main |
将工作进程绑定到 CPU 集。每个 CPU 集由允许的 CPU 的位掩码表示。每个工作进程都应定义一个单独的集合。默认情况下,工作进程不绑定到任何特定的 CPU。
例如,
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;
此指令仅在 FreeBSD 和 Linux 上可用。
语法 |
worker_priority |
---|---|
默认值 |
worker_priority 0; |
上下文 |
main |
定义工作进程的调度优先级,就像 nice
命令所做的那样:负值 数值
表示更高的优先级。允许的范围通常在 -20 到 20 之间。
示例
worker_priority -10;
语法 |
worker_processes |
---|---|
默认值 |
worker_processes 1; |
上下文 |
main |
定义工作进程的数量。
最优值取决于许多因素,包括(但不限于)CPU 核心数量、存储数据的硬盘数量以及负载模式。如有疑问,将其设置为可用 CPU 核心的数量是一个不错的起点(值“auto
”将尝试自动检测)。
auto
参数从 1.3.8 和 1.2.5 版本开始支持。
语法 |
worker_rlimit_core |
---|---|
默认值 | — |
上下文 |
main |
更改工作进程核心文件最大大小 (RLIMIT_CORE
) 的限制。用于在不重启主进程的情况下提高限制。
语法 |
worker_rlimit_nofile |
---|---|
默认值 | — |
上下文 |
main |
更改工作进程最大打开文件数 (RLIMIT_NOFILE
) 的限制。用于在不重启主进程的情况下提高限制。
语法 |
worker_shutdown_timeout |
---|---|
默认值 | — |
上下文 |
main |
此指令出现在 1.11.11 版本中。
配置工作进程优雅关闭的超时时间。当 时间
到期时,nginx 将尝试关闭所有当前打开的连接以促进关闭。
语法 |
working_directory |
---|---|
默认值 | — |
上下文 |
main |
定义工作进程的当前工作目录。主要用于写入核心文件时,在这种情况下,工作进程应具有对指定目录的写入权限。