核心模块#

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

配置示例#

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

错误日志中的每个条目具有以下格式:

timestamp [level] PID#TID: *request_id message

其中:

  • timestamp — 事件的日期和时间

  • level — 事件的日志级别

  • PID#TID — 进程和线程标识符

  • *request_id — 唯一的请求标识符(如果适用)

  • message — 错误或事件消息文本

events#

语法

events { ... };

默认值

—

上下文

main

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

include#

语法

include file | mask;

默认值

—

上下文

any

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

示例:

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

load_module#

语法

load_module file;

默认值

—

上下文

main

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

$ sudo angie -V

示例:

load_module modules/ngx_mail_module.so;

lock_file#

语法

lock_file 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 配置选项构建。 当使用 PCRE 库构建 Angie 时 (--with-pcre=), 使用 --with-pcre-jit 选项启用 JIT 支持。

pid#

语法

pid file | off;

默认值

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

上下文

main

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

备注

如果在重新配置期间修改了 file 设置, 但它指向先前 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 name threads=number [max_queue=number];

默认值

thread_pool default threads=32 max_queue=65536;

上下文

main

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

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

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

timer_resolution#

语法

timer_resolution interval;

默认值

—

上下文

main

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

示例:

timer_resolution 100ms;

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

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

  • 如果使用 eventport,则使用 timer_create();

  • 否则使用 setitimer()。

use#

语法

use method;

默认值

—

上下文

events

指定用于 连接处理 的 method。 通常不需要显式指定, 因为 Angie 默认会使用最高效的方法。

user#

语法

user user [group];

默认值

user <构建参数 --user> <构建参数 --group>;

上下文

main

定义工作进程使用的 user 和 group 凭据 (另请参阅 构建参数)。 如果省略 group,则使用与 user 同名的组。

worker_aio_requests#

语法

worker_aio_requests number;

默认值

worker_aio_requests 32;

上下文

events

当使用 aio 和 epoll 连接处理方法时, 设置单个工作进程的最大未完成异步 I/O 操作数。

worker_connections#

语法

worker_connections number;

默认值

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

默认值

worker_priority 0;

上下文

main

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

示例:

worker_priority -10;

worker_processes#

语法

worker_processes number | auto;

默认值

worker_processes 1;

上下文

main

定义工作进程的数量。

最佳值取决于许多因素,包括(但不限于) CPU 核心数、存储数据的硬盘驱动器数量 以及负载模式。 如果不确定,将其设置为可用 CPU 核心数 是一个不错的起点(值"auto"将尝试自动检测)。

worker_rlimit_core#

语法

worker_rlimit_core size;

默认值

—

上下文

main

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

worker_rlimit_nofile#

语法

worker_rlimit_nofile number;

默认值

—

上下文

main

更改工作进程的最大打开文件数限制(RLIMIT_NOFILE)。 用于在不重启主进程的情况下增加限制。

worker_shutdown_timeout#

语法

worker_shutdown_timeout time;

默认值

—

上下文

main

配置工作进程优雅关闭的超时时间(以秒为单位)。 当指定的时间到期时, Angie 将尝试关闭当前打开的所有连接 以便于关闭。

优雅关闭通过向主进程发送 QUIT 信号 来启动,该信号指示工作进程 停止接受新连接并允许现有连接完成。 工作进程继续处理活动请求直到完成, 然后优雅地关闭。如果连接保持打开的时间 超过 worker_shutdown_timeout,Angie 将强制关闭这些 连接以完成关闭。 此外,客户端保持活动连接仅在空闲时间 至少达到 lingering_timeout 指定的时间时才会关闭。

working_directory#

语法

working_directory directory;

默认值

—

上下文

main

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