核心模块#

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

相关指南

配置示例#

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 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] [[filter=part:match] ...] [rate=rate] [format=format];

默认值

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 作为默认日志级别。

可选的 filter=part:match 参数用于限制哪些消息写入日志， 使单个目标可以只收集感兴趣的事件。 每个参数针对消息的一个 part 测试 match 模式，其中 part 可以是：

  • logline — 在 format=default 时，为消息连同任何系统错误和上下文详情， 但不含时间戳、级别、进程、线程和连接前缀； 它不匹配 format=json 的条目；

  • message — 在 format=default 时，为不含系统错误或上下文详情的消息文本； 在 format=json 时，为包含 message 成员的、经转义的序列化片段， 而不是其原始值；

  • tag — 附加到消息的标签，包括由 error_log_user_tag 指令 及其 stream 和 mail 对应指令添加的标签；

  • sourcefile — 输出该消息的源文件；仅当 Angie 在启用 调试日志 的情况下构建时可用；

  • 任何其他名称 — 消息上下文的字段，例如下文 JSON 格式中显示的字段之一。

默认情况下，match 模式按子串匹配。加前缀 = 表示要求精确匹配， 加前缀 ~ 表示匹配正则表达式，这需要使用 PCRE 库构建。

在 format=json 时，对 message 的精确匹配必须覆盖整个序列化片段， 包括其 JSON 语法和转义。

一个指令可以给出多个 filter= 参数；仅当消息匹配所有参数时才会写入。 但是，每个上下文字段在每个指令中只能被一个 filter= 参数测试： 同一字段上的第二个参数永远不会匹配，因此不会有消息写入该目标。

可选的 rate=rate 参数限制写入日志的消息的最大速率，单位为每秒消息数； 该值可以以 m/s 后缀结尾（例如 rate=2000m/s）。 默认使用 rate=1000（每秒 1000 条消息）；设置 rate=0 可禁用该限制。

该限制分别应用于每个 error_log 指令，并且在每个工作进程中独立计算。 大量低严重级别的消息（例如 info）不会抑制更高严重级别的消息 （例如 error），因为更严重的级别被允许按比例更大的突发；反之则不成立。 超出的消息会被丢弃。这是对日志的节流而不是静音：在持续过载下， 消息仍以大约配置的速率写入。

当某个目标开始丢弃消息时，Angie 会向该目标写入一条同级别的 "too many log messages, limiting" 通知，以取代第一条被丢弃的消息； 在持续过载期间该通知可能重复出现。该通知不带上下文详情或标签， 且必须通过该目标的 filter= 参数，因此按 tag 或按上下文字段过滤的目标 永远不会收到它。此外，在生效的 error_log 指令中日志级别最详细的目标 （若多个指令共用该级别，则为最先声明的那个）也不会写入该通知， 因此只有单个目标时不会出现通知。

当 debug 日志级别对某条消息生效时，不适用速率限制， 无论是因为日志文件本身使用 debug 级别， 还是因为通过 debug_connection 为该连接启用了调试日志。

备注

要使 debug 日志级别生效, 必须在构建 Angie 时启用 调试日志。

可选的 format=format 参数选择日志条目使用的格式。 默认格式 format=default 生成下文所述的传统纯文本格式； format=json 则将每个条目写为单行的一个 JSON 对象。

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

timestamp [level] PID#TID: *connection_id message

其中:

  • timestamp — 事件的本地日期和时间

  • level — 事件的日志级别

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

  • *connection_id — 连接序列号,同一连接上的所有请求共用(如果适用)

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

使用 format=json 时，每个条目改为写成单个 JSON 对象， 此处为便于阅读而格式化显示；在日志文件中它占据一行：

{
    "time": "2026-02-14T09:23:10.874Z",
    "level": "error",
    "pid": 22738,
    "tid": 22738,
    "connection": 7,
    "message": "limiting requests, excess: 1.000 by zone \"one\"",
    "http": {
        "client": "127.0.0.1",
        "request": {
            "server": "localhost",
            "request_line": "GET /debug HTTP/1.1",
            "host": "localhost"
        }
    },
    "tags": [
        "http"
    ]
}

其中:

  • time — 事件的 UTC 日期和时间，采用 ISO 8601 格式并带 Z 后缀； 除非毫秒为零，否则包含毫秒

  • level — 事件的日志级别

  • pid 和 tid — 进程和线程标识符

  • connection — 连接编号（与纯文本格式中显示为 *connection_id 的值相同），当条目与某个连接关联时出现

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

  • error — 当消息与系统错误关联时出现； 一个包含 code 和 message 字段的对象

  • http、stream 或 mail — 一个包含条目上下文详情的对象， 以条目来源模块的名称为键（这些模块之外的上下文详情使用通用的 context 对象）；该对象仅出现在携带此类详情 且日志级别不是 debug 的条目中。每个模块的对象有各自的字段集； 例如，在 http 下，嵌套的 request 对象包含 request_line（请求行）以及其他请求详情

  • tags — 附加到条目的标签列表，至少有一个标签适用时出现； 包括模块自动添加的标签以及由 error_log_user_tag 指令添加的标签

  • truncated — true，仅当条目因适配错误日志缓冲区而被截断时出现

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;

如果动态模块是为不同的 Angie 构建版本构建的,加载将失败并显示类似以下的错误:"module "..." was built for "..." but you are running "Angie""。

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

默认

—

上下文

main

使 OpenSSL 默认使用指定名称的引擎来执行该引擎实现的所有算法。也可以在 OpenSSL 配置文件中设置该引擎。

ssl_object_cache_inheritable#

语法

ssl_object_cache_inheritable on | off;

默认值

ssl_object_cache_inheritable on;

上下文

main

如果启用,SSL 对象(SSL 证书、私钥、受信任的 CA 证书、 CRL 列表)在配置重新加载时会被继承。

如果从文件加载的 SSL 对象的修改时间和文件 索引自上次配置加载以来没有更改,则会被继承。通过 engine: 或 store: 前缀指定的密钥永远不会被继承，而使用 data: 前缀指定的证书和密钥始终会被继承。受密码短语保护的密钥不会被缓存，因此也永远不会被继承。

从变量加载的 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()。 降低分辨率后, 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 大小;

默认值

—

上下文

main

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

worker_rlimit_nofile#

语法

worker_rlimit_nofile number;

默认值

—

上下文

main

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

worker_shutdown_timeout#

语法

worker_shutdown_timeout 时间;

默认值

—

上下文

main

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

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

working_directory#

语法

working_directory directory;

默认值

—

上下文

main

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