核心模块#

该模块提供服务器基本运行所需的核心功能和配置指令， 处理诸如管理工作进程、 配置事件驱动模型、 以及处理传入连接和请求等关键任务。 它包含用于设置主进程、错误 日志记录以及在底层控制服务器行为的关键指令。

配置示例#

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 time;

默认值

accept_mutex_delay 500ms;

上下文

events

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

daemon#

语法

daemon on | off;

默认值

daemon on;

上下文

main

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

debug_connection#

语法

debug_connection address | 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 时启用 调试日志。

debug_points#

语法

debug_points abort | stop;

默认值

—

上下文

main

此指令用于调试。

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

env#

语法

env variable[=value];

默认值

env TZ;

上下文

main

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

这些变量随后：

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

示例：

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

备注

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

error_log#

语法

error_log file [level];

默认值

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

上下文

main, http, mail, stream, server, location

配置日志记录， 允许在同一配置级别指定多个日志。 如果在 main 配置级别没有明确定义日志文件， 将使用默认文件。

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

第二个参数设置日志级别，可以是以下之一： debug、info、notice、warn、error、 crit、alert 或 emerg。 这些级别按严重程度递增顺序列出。 设置日志级别将捕获相等和更高严重程度的消息：

设置

捕获的级别

debug

debug、info、notice、warn、error、 crit、alert、emerg

info

info、notice、warn、error、 crit、alert、emerg

notice

notice、warn、error、 crit、alert、emerg

warn

warn、error、crit、alert、emerg

error

error、crit、alert、emerg

crit

crit、alert、emerg

alert

alert、emerg

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 加速器的名称。

ssl_object_cache_inheritable#

语法

ssl_object_cache_inheritable on | off;

默认

ssl_object_cache_inheritable on;

上下文

main

如果启用，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 名称 threads=数量 [max_queue=数量];

默认

thread_pool default threads=32 max_queue=65536;

上下文

main

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

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

如果池中的所有线程都忙于执行任务，新任务将在队列中等待。max_queue 参数限制允许在队列中等待的任务数量。默认情况下，队列中最多可以有65536个任务。当队列溢出时，任务将以错误完成。

timer_resolution#

语法

timer_resolution 间隔;

默认

—

上下文

main

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

示例：

timer_resolution 100ms;

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

  • 如果使用 kqueue，则使用 EVFILT_TIMER 过滤器；

  • 如果使用 eventport，则使用 timer_create()；

  • 否则使用 setitimer()。

use#

语法

use 方法;

默认

—

上下文

events

指定用于 连接处理 的 方法。通常不需要明确指定它，因为Angie默认会使用最高效的方法。

user#

语法

user 用户 [组];

默认

user <build parameter --user> <build parameter --group>;

上下文

main

定义工作进程使用的 用户 和 组 凭据（另请参见 构建参数）。如果省略 组，则使用与 用户 同名的组。

worker_aio_requests#

语法

worker_aio_requests 数量;

默认

worker_aio_requests 32;

上下文

events

当使用 aio 与 epoll 连接处理方法时，设置单个工作进程的最大未完成异步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

定义工作进程的当前工作目录。 这主要用于写入核心文件， 在这种情况下，工作进程应该对指定目录具有写入权限。