核心模块#

该模块提供了服务器基本操作所需的基本功能和配置指令,并处理关键任务,例如管理工作进程、配置事件驱动模型以及处理传入的连接和请求。它包括设置主进程、错误日志记录以及在低级别控制服务器行为的关键指令。

配置示例#

user www www;
worker_processes 2;

error_log /var/log/error.log info;

events {

    use kqueue; worker_connections 2048;
}

指令#

accept_mutex#

语法

accept_mutex on | off;

默认

accept_mutex off;

上下文

events

accept_mutex 启用时,工作进程将依次接受新连接。在没有此设置的情况下,所有工作进程都会被通知新连接,这可能导致在新连接量较低时系统资源的低效使用。

备注

在支持 EPOLLEXCLUSIVE 标志的系统上,或者使用 reuseport 指令时,没必要启用 accept_mutex

accept_mutex_delay#

语法

accept_mutex_delay 时间;

默认

accept_mutex_delay 500ms;

上下文

events

如果 accept_mutex 启用,此指令指定工作进程在另一个工作进程已经处理新连接时,继续接受新连接的最大等待时间。

daemon#

语法

daemon on | off;

默认

daemon on;

上下文

main

确定 Angie 是否应该作为守护进程运行。这主要在开发期间使用。

debug_connection#

语法

debug_connection 地址 | CIDR | unix:;

默认

上下文

events

为特定客户端连接启用调试日志。其他连接将使用 error_log 指令设置的日志级别。您可以通过 IPv4 或 IPv6 地址、网络或主机名指定连接。对于使用 UNIX 域套接字的连接,请使用 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:;
    #  ...
}

重要

为了使此指令有效,Angie 必须以启用 debugging log 的方式构建。

debug_points#

语法

debug_points abort | stop;

默认

上下文

main

此指令用于调试。当发生内部错误时,例如在工作进程重启期间发生套接字泄漏,启用 debug_points 将创建核心文件 (abort) 或停止进程 (stop),以便使用系统调试器进行进一步分析。

env#

语法

env 变量[=];

默认

env TZ;

上下文

main

默认情况下,Angie 删除从其父进程继承的所有环境变量,除了 TZ 变量。此指令允许您保留一些继承的变量,修改其值,或创建新的环境变量。

这些变量会在

  • 执行文件的 实时升级 时继承

  • Perl 模块使用

  • 可供工作进程使用

请注意,以这种方式控制系统库可能并不总是有效,因为库通常仅在初始化期间检查变量,而初始化发生在此指令生效之前。 TZ 变量始终被继承并可供 Perl 模块使用,除非明确定义为其他。

示例:

env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;

备注

ANGIE 环境变量在 Angie 内部使用,用户不应直接设置。

error_log#

语法

error_log 文件 [级别];

默认

error_log logs/error.log error; (路径取决于 --error-log-path 构建选项)

上下文

main, http, mail, stream, server, location

配置日志记录,允许在相同的配置级别指定多个日志。如果在 main 配置级别未明确定义日志文件,则将使用默认文件。

第一个参数指定存储日志的文件。特殊值 stderr 选择标准错误流。要配置日志记录到 syslog,请使用 "syslog:" 前缀。要记录到 循环内存缓冲区,请使用 "memory:" 前缀后跟缓冲区大小;这通常用于调试。

第二个参数设置日志级别,可以是以下之一:debuginfonoticewarnerrorcritalertemerg。这些级别按严重性递增的顺序列出。设置日志级别将捕获相等和更高严重性的消息:

设置

捕获的级别

debug

debuginfonoticewarnerrorcritalertemerg

info

infonoticewarnerrorcritalertemerg

notice

noticewarnerrorcritalertemerg

warn

warnerrorcritalertemerg

error

errorcritalertemerg

crit

critalertemerg

alert

alertemerg

emerg

emerg

如果省略此参数,则使用 error 作为默认日志级别。

重要

为了使 debug 日志级别有效,Angie 必须以启用 debugging log 的方式构建。

events#

语法

events { ... };

默认

上下文

main

提供影响连接处理的指令的配置文件上下文。

include#

语法

include 文件 | 掩码;

默认

上下文

任何

将另一个文件或与指定 掩码 匹配的文件包含到配置中。包含的文件必须包含语法正确的指令和块。

示例:

include mime.types;
include vhosts/*.conf;

load_module#

语法

load_module 文件;

默认

上下文

main

从指定文件加载动态模块。如果提供了相对路径,则根据 --prefix 构建选项 进行解释。要验证路径:

$ sudo angie -V

示例:

load_module modules/ngx_mail_module.so;

lock_file#

语法

lock_file 文件;

默认

lock_file logs/angie.lock; (路径取决于 --lock-path 构建选项)

上下文

main

Angie 使用锁定机制来实现 accept_mutex 并序列化对共享内存的访问。在大多数系统中,锁是使用原子操作进行管理的,因此此指令并非必需。然而,在某些系统上,使用替代的 lock file 机制。此指令设置锁文件名称的前缀。

master_process#

语法

master_process on | off;

默认

master_process on;

上下文

main

确定是否启动工作进程。此指令供 Angie 开发者使用。

multi_accept#

语法

multi_accept on | off;

默认

multi_accept off;

上下文

events

on

工作进程将同时接受所有新连接。

off

工作进程将一次接受一个新连接。

备注

如果使用 kqueue 连接处理方法,则此指令被忽略,因为它提供了准备接受的新连接的数量。

pcre_jit#

语法

pcre_jit on | off;

默认

pcre_jit off;

上下文

main

启用或禁用已知的 "即时编译"(PCRE JIT)正则表达式,在配置解析时可用。

PCRE JIT 可以显著加快正则表达式处理速度。

重要

JIT 在 PCRE 库 8.20 版本及以上可用,前提是它们是使用 --enable-jit 配置选项构建的。当 Angie 使用 PCRE 库(--with-pcre=)构建时,使用 --with-pcre-jit 选项启用 JIT 支持。

pid#

语法

pid 文件 | off;

默认

pid logs/angie.pid; (路径取决于 --pid-path 构建选项)

上下文

main

指定将存储Angie主进程ID的 文件。该文件是原子创建的,这确保其内容始终正确。设置为 off 则禁用该文件的创建。

备注

如果在重新配置期间修改了 文件 设置但指向的是先前PID文件的符号链接,则该文件不会被重新创建。

ssl_engine#

语法

ssl_engine 设备;

默认

上下文

main

指定硬件SSL加速器的名称。

thread_pool#

语法

thread_pool 名称 threads=数量 [max_queue=数量];

默认

thread_pool default threads=32 max_queue=65536;

上下文

main

定义用于多线程文件读取和发送的线程池的 名称 和参数,无阻塞 工作进程。

threads 参数指定池中的线程数量。

如果所有线程都忙,新任务将会在队列中等待。max_queue 参数限制可以在队列中等待的任务数量。默认情况下,队列最多可以容纳65536个任务。当队列溢出时,新任务将以错误方式完成。

timer_resolution#

语法

timer_resolution 间隔;

默认

上下文

main

在工作进程中减少计时器分辨率,从而减少 gettimeofday() 系统调用的频率。默认情况下,每当查询内核事件时,都会调用 gettimeofday()。通过降低分辨率,它仅在指定的间隔内调用一次。

示例:

timer_resolution 100ms;

间隔的内部实现取决于所使用的方法:

  • 如果使用 kqueue,则使用 EVFILT_TIMER 过滤器。

  • 如果使用 eventport,则使用 timer_create() 函数。

  • 否则使用 setitimer() 函数。

use#

语法

use 方法;

默认

上下文

events

指定要使用的 连接处理 方法。通常不需要明确指定,因为Angie默认使用最有效的方法。

user#

语法

user 用户 [];

默认

user <--user build option> <--group build option>;

上下文

main

定义工作进程的用户和组凭据(另请参见 构建选项)。如果仅设置了用户,指定的用户名也将用于组。

worker_aio_requests#

语法

worker_aio_requests 数量;

默认

worker_aio_requests 32;

上下文

events

在使用 aioepoll 连接处理方法时,设置单个工作进程的最大 数量 的异步I/O操作。

worker_connections#

语法

worker_connections 数量;

默认

worker_connections 512;

上下文

events

设置单个工作进程可以打开的最大并发连接数。

请注意,这个数字包括所有连接,例如与代理服务器的连接,而不仅仅是客户端连接。此外,实际的并发连接数不能超过系统对打开文件的限制,该限制可以使用 worker_rlimit_nofile 进行调整。

worker_cpu_affinity#

语法

worker_cpu_affinity cpumask ...;

worker_cpu_affinity auto [cpumask];

默认

上下文

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 允许将工作进程自动绑定到可用CPU:

worker_processes auto;
worker_cpu_affinity auto;

可选的掩码参数可用于限制可用于自动绑定的CPU:

worker_cpu_affinity auto 01010101;

重要

此指令仅在FreeBSD和Linux上可用。

worker_priority#

语法

worker_priority 数量;

默认

worker_priority 0;

上下文

main

定义工作进程的调度优先级,类似于 nice 命令:负数 数量 表示更高的优先级。允许的范围通常从 -20 到 20。

示例:

worker_priority -10;

worker_processes#

语法

worker_processes 数量 | auto;

默认

worker_processes 1;

上下文

main

定义工作进程的数量。

最佳值取决于多种因素,包括CPU核心数量、硬盘驱动器数量和负载模式。如果不确定,建议从可用CPU核心的数量开始。值 auto 尝试自动检测最佳工作进程数量。

worker_rlimit_core#

语法

worker_rlimit_core 大小;

默认

上下文

main

更改工作进程的核心文件最大大小的限制 (RLIMIT_CORE)。这允许在不重新启动主进程的情况下增加限制。

worker_rlimit_nofile#

语法

worker_rlimit_nofile 数量;

默认

上下文

main

更改工作进程的最大打开文件数量的限制 (RLIMIT_NOFILE)。这允许在不重新启动主进程的情况下增加限制。

worker_shutdown_timeout#

语法

worker_shutdown_timeout 时间;

默认

上下文

main

配置工作进程优雅关闭的超时。一旦 时间 到期,Angie将尝试关闭所有活动连接以完成关闭过程。

优雅关闭是通过向主进程发送 QUIT 信号 来启动的,这告诉工作进程停止接受新连接,同时允许现有连接完成。工作者继续处理活动请求直到完成,然后正常退出。如果连接在超过 worker_shutdown_timeout 的时间后仍然保持打开状态,Angie将强制关闭这些连接以完成关闭。此外,来自客户端的长连接仅在保持不活动至少持续 lingering_timeout 的时间后关闭。

working_directory#

语法

working_directory 目录;

默认

上下文

main

定义工作进程的当前工作目录。这主要用于写入核心文件,因此工作进程必须对指定目录具有写入权限。