Nginx 配置文件文档注解¶

文档概览¶

对照基准 ：nginx.org 官方文档（version_range 1.26.x / 1.28.x）
中文正文 ：官方说明准确直译 + ReferBe 生产注解（!!! Note / !!! Warning）；Syntax / Default / Context 键名保留便于与官方对照

核心功能（Core functionality）¶

accept_mutex¶

Syntax: accept_mutex on | off;
Default: accept_mutex off;
Context: events
@Since: None

若启用 accept_mutex，worker 进程将轮流接受新连接；否则所有 worker 都会收到新连接通知。当新连接量较低时，部分 worker 可能空耗系统资源。

Note

在支持 EPOLLEXCLUSIVE 标志的系统（1.11.3+）或使用 reuseport 时，无需启用 accept_mutex。
1.11.3 之前版本默认值为 on。

accept_mutex_delay¶

Syntax: accept_mutex_delay time;
Default: accept_mutex_delay 500ms;
Context: events
@Since: None

在启用 accept_mutex 时，指定当其他 worker 正在 accept 新连接时，本 worker 重试 accept 的最长等待时间。

daemon¶

Syntax: daemon on | off;
Default: daemon on;
Context: main
@Since: None

决定 nginx 是否以守护进程方式运行。主要用于开发调试。

debug_connection¶

Syntax: debug_connection address | CIDR | unix;
Default: —
Context: events
@Since: None

为选定的客户端连接启用调试日志；其余连接仍使用 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:;
    ...
}

须使用 --with-debug 编译 nginx 后本指令才生效，参见「调试日志」。

debug_points¶

Syntax: debug_points abort | stop;
Default: —
Context: main
@Since: None

用于调试。当检测到内部错误（例如 worker 重启时 socket 泄漏）时，启用 debug_points 将生成 core 文件（abort）或停止进程（stop），以便用系统调试器分析。

env¶

Syntax: env variable[=value];
Default: env TZ;
Context: main
@Since: None

默认情况下，nginx 会清除从父进程继承的除 TZ 外的所有环境变量。本指令可保留部分继承变量、修改其值或创建新环境变量。这些变量将：

在可执行文件热升级时被继承；
供 ngx_http_perl_module 使用；
供 worker 进程使用。注意：通过本指令控制系统库行为并不总是可行，库常在初始化阶段读取环境变量，早于本指令生效；可执行文件热升级是上述限制的例外。

TZ 始终继承并对 ngx_http_perl_module 可用，除非显式配置覆盖。

示例：

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

用户不应直接设置 nginx 内部使用的 NGINX 环境变量。

error_log¶

Syntax: error_log file [level];
Default: error_log logs/error.log error;
Context: main, http, mail, stream, server, location
@Since: None

配置日志。同一配置层级可指定多个日志（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。

调试日志须 --with-debug 编译，参见「调试日志」。

Note

自 1.7.11 起可在 stream 层级指定；自 1.9.0 起可在 mail 层级指定。

events¶

Syntax: events { ... }
Default: —
Context: main
@Since: None

提供配置上下文，用于书写影响 连接处理 的指令。

include¶

Syntax: include file | mask;
Default: —
Context: any
@Since: None

将另一个 file 或匹配 mask 的文件包含进配置。被包含文件须由语法正确的指令与块组成。

示例：

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

load_module¶

Syntax: load_module file;
Default: —
Context: main
@Since: 1.9.11

加载动态模块。

示例：

load_module modules/ngx_mail_module.so;

lock_file¶

Syntax: lock_file file;
Default: lock_file logs/nginx.lock;
Context: main
@Since: None

nginx 用锁机制实现 accept_mutex 及共享内存访问串行化。多数系统用原子操作实现锁，本指令被忽略；其他系统使用「锁文件」机制，本指令指定锁文件名前缀。

master_process¶

Syntax: master_process on | off;
Default: master_process on;
Context: main
@Since: None

决定是否启动 worker 进程。面向 nginx 开发者。

multi_accept¶

Syntax: multi_accept on | off;
Default: multi_accept off;
Context: events
@Since: None

若禁用 multi_accept，worker 每次只 accept 一个新连接；否则一次 accept 所有待接受的新连接。

使用 kqueue 连接处理方法时本指令被忽略，因 kqueue 会报告待 accept 连接数。

pcre_jit¶

Syntax: pcre_jit on | off;
Default: pcre_jit off;
Context: main
@Since: 1.1.12

启用或禁用在配置解析阶段已知正则的 PCRE JIT（即时编译）。PCRE JIT 可显著加速正则处理。

JIT 需 PCRE 8.20+ 且 --enable-jit 构建；nginx 自带 PCRE（--with-pcre=）时通过 --with-pcre-jit 启用 JIT。

pid¶

Syntax: pid file;
Default: pid logs/nginx.pid;
Context: main
@Since: None

指定存放主进程 PID 的 file。

ssl_engine¶

Syntax: ssl_engine device;
Default: —
Context: main
@Since: None

指定硬件 SSL 加速设备名称。

OpenSSL 可能在配置测试阶段动态加载该模块。

ssl_object_cache_inheritable¶

Syntax: ssl_object_cache_inheritable on | off;
Default: ssl_object_cache_inheritable on;
Context: main
@Since: 1.27.4

若启用，SSL 对象（证书、私钥、受信 CA、CRL 等）可在配置 reload 时继承。

从文件加载的对象，若自上次加载以来修改时间与文件索引未变则继承。engine:name:id 形式的私钥不继承；data:value 形式的私钥始终继承。

从变量加载的 SSL 对象无法继承。

示例：

ssl_object_cache_inheritable on;
http {
    ...
    server {
        ...
        ssl_certificate     example.com.crt;
        ssl_certificate_key example.com.key;
    }
}

stall_threshold [commercial]¶

Syntax: stall_threshold time;
Default: stall_threshold 1000ms;
Context: events
@Since: 1.29.0

覆盖事件循环迭代「卡顿」报告的默认时间阈值。默认当单次事件循环迭代超过 1000ms 时报告卡顿。若启用 timer_resolution，时间阈值将被忽略。

本指令属于商业订阅功能。

thread_pool¶

Syntax: thread_pool name threads=number [max_queue=number];
Default: thread_pool default threads=32 max_queue=65536;
Context: main
@Since: 1.7.11

定义线程池 name 及参数，用于多线程读/send 文件且 不阻塞 worker。

threads 为池中线程数。若池内线程均忙，新任务进入队列；max_queue 限制队列中等待任务数，默认最多 65536。队列溢出时任务以错误完成。

timer_resolution¶

Syntax: timer_resolution interval;
Default: —
Context: main
@Since: None

降低 worker 中定时器分辨率，从而减少 gettimeofday() 调用次数。默认每次收到内核事件都会调用；降低分辨率后，仅在指定 interval 内调用一次。

示例：

timer_resolution 100ms;

具体实现取决于所用方法：

kqueue：EVFILT_TIMER 过滤器；
eventport：timer_create()；
其他：setitimer()。

use¶

Syntax: use method;
Default: —
Context: events
@Since: None

指定连接处理 method。通常无需显式指定，nginx 默认选用最高效方法。

user¶

Syntax: user user [group];
Default: user nobody nobody;
Context: main
@Since: None

定义 worker 进程使用的 user 与 group。省略 group 时，使用与 user 同名的组。

Warning

生产环境应使用专用低权限账号（如 nginx），避免以 root 运行 worker。

worker_aio_requests¶

Syntax: worker_aio_requests number;
Default: worker_aio_requests 32;
Context: events
@Since: 1.1.4、1.0.7

在使用 epoll 连接处理且启用 aio 时，设置单个 worker 允许的最大未完成异步 I/O 操作数。

worker_connections¶

Syntax: worker_connections number;
Default: worker_connections 512;
Context: events
@Since: None

设置单个 worker 可打开的 最大并发连接数 。

该数值包含所有连接（含与上游等代理连接），不仅是客户端连接。实际并发还受系统最大打开文件数限制，可通过 worker_rlimit_nofile 调整。

worker_cpu_affinity¶

Syntax: worker_cpu_affinity cpumask ...; worker_cpu_affinity auto [cpumask];
Default: —
Context: main
@Since: None

将 worker 绑定到 CPU 集合。每个 CPU 集合用允许 CPU 的位掩码表示；每个 worker 应对应一个集合。默认不绑定特定 CPU。

示例：

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

将每个 worker 绑定到独立 CPU：

worker_processes    2;
worker_cpu_affinity 0101 1010;

第一个 worker 绑定 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¶

Syntax: worker_priority number;
Default: worker_priority 0;
Context: main
@Since: None

设置 worker 调度优先级，语义同 nice 命令：负的 number 表示更高优先级。允许范围通常为 -20 到 20。

示例：

worker_priority -10;

worker_processes¶

Syntax: worker_processes number | auto;
Default: worker_processes 1;
Context: main
@Since: None

定义 worker 进程数量。

最优值取决于 CPU 核心数、磁盘数量、负载模式等多种因素。不确定时，可先设为可用 CPU 核心数（"auto" 会尝试自动检测）。

auto 自 1.3.8、1.2.5 起支持。

worker_rlimit_core¶

Syntax: worker_rlimit_core size;
Default: —
Context: main
@Since: None

修改 worker 的 core 文件大小上限（RLIMIT_CORE）。用于在不重启主进程的情况下提高限制。

worker_rlimit_nofile¶

Syntax: worker_rlimit_nofile number;
Default: —
Context: main
@Since: None

修改 worker 的最大打开文件数（RLIMIT_NOFILE）。用于在不重启主进程的情况下提高限制。

Note

与 worker_connections 联动调优：高并发场景常需同时提高本项与系统 fs.file-max。

worker_shutdown_timeout¶

Syntax: worker_shutdown_timeout time;
Default: —
Context: main
@Since: 1.11.11

配置 worker 优雅退出 超时。超时后 nginx 将尝试关闭当前仍打开的连接以完成 shutdown。

working_directory¶

Syntax: working_directory directory;
Default: —
Context: main
@Since: None

定义 worker 进程的当前工作目录。主要用于写 core 文件时，worker 须对该目录有写权限。

ngx_http_core_module¶

absolute_redirect¶

Syntax: absolute_redirect on | off;
Default: absolute_redirect on;
Context: http, server, location
@Since: 1.11.8

若禁用，nginx 发出的重定向为 相对路径 。

另见 server_name_in_redirect、port_in_redirect。

aio¶

Syntax: aio on | off | threads[=pool];
Default: aio off;
Context: http, server, location
@Since: 0.8.11

在 FreeBSD 与 Linux 上启用或禁用异步文件 I/O（AIO）：

location /video/ {
    aio            on;
    output_buffers 1 64k;
}

在 FreeBSD 上，自 4.3 起可用 AIO。11.0 之前可将 AIO 静态链入内核：

options VFS_AIO

或动态加载内核模块：

kldload aio

在 Linux 上，自内核 2.6.22 起可用；须同时启用 directio，否则读操作会阻塞：

location /video/ {
    aio            on;
    directio       512;
    output_buffers 1 128k;
}

在 Linux 上，directio 仅适用于按 512 字节（XFS 为 4K）对齐的块；文件末尾未对齐部分以阻塞方式读取。字节范围请求及非文件开头的 FLV 请求同理：文件首尾未对齐数据的读取会阻塞。

Linux 上同时启用 AIO 与 sendfile 时：大于等于 directio 阈值的文件走 AIO，更小文件或禁用 directio 时走 sendfile。

location /video/ {
    sendfile       on;
    aio            on;
    directio       8m;
}

亦可用多线程（1.7.11+）读/send 文件，避免阻塞 worker：

location /video/ {
    sendfile       on;
    aio            threads;
}

读写操作卸载到指定线程池的线程；省略池名时使用 "default"。池名可用变量：

aio threads=pool$disk;

默认未启用多线程，编译时需 --with-threads。目前仅与 epoll、kqueue、eventport 兼容；多线程 send 文件仅 Linux 支持。

另见 sendfile。

aio_write¶

Syntax: aio_write on | off;
Default: aio_write off;
Context: http, server, location
@Since: 1.9.13

在启用 aio 时，指定是否用于 写文件 。目前仅在使用 aio threads 时有效，且限于写入从上游收到的数据所生成的临时文件。

alias¶

Syntax: alias path;
Default: —
Context: location
@Since: None

为指定 location 定义路径替换。例如：

location /i/ {
    alias /data/w3/images/;
}

请求 "/i/top.gif" 时，将发送文件 /data/w3/images/top.gif。

path 可含变量，但不可使用 $document_root、$realpath_root。

在正则 location 中使用 alias 时，正则须含捕获组，alias 须引用这些捕获（0.7.40+），例如：

location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
    alias /data/w3/images/$1;
}

当 location 匹配路径末尾与 alias 值末尾相同时：

location /images/ {
    alias /data/w3/images/;
}

更推荐使用 root：

location /images/ {
    root /data/w3;
}

Warning

alias 与 root 拼接 URI 的规则不同；生产环境写错会导致 404 或路径穿越风险，改配置后务必用真实 URI 回归。

auth_delay¶

Syntax: auth_delay time;
Default: auth_delay 0s;
Context: http, server, location
@Since: 1.17.10

对返回 401 的未授权请求 延迟处理 ，以降低计时攻击风险；适用于密码认证、子请求认证或 JWT 等访问控制场景。

chunked_transfer_encoding¶

Syntax: chunked_transfer_encoding on | off;
Default: chunked_transfer_encoding on;
Context: http, server, location
@Since: None

允许在 HTTP/1.1 下禁用分块传输编码。适用于对端实现不符合标准、无法正确处理 chunked 的遗留软件。

client_body_buffer_size¶

Syntax: client_body_buffer_size size;
Default: client_body_buffer_size 8k|16k;
Context: http, server, location
@Since: None

设置读取客户端请求体的缓冲区大小。若请求体大于缓冲区，整段或部分会写入临时文件。默认等于两个内存页：x86/32 位/x86-64 多为 8K，其他 64 位平台多为 16K。

client_body_in_file_only¶

Syntax: client_body_in_file_only on | clean | off;
Default: client_body_in_file_only off;
Context: http, server, location
@Since: None

决定是否将完整客户端请求体保存到文件。可用于调试，或配合 $request_body_file、ngx_http_perl_module 的 $r->request_body_file。

值为 on 时，请求处理结束后 不删除 临时文件。

值为 clean 时，处理结束后删除遗留临时文件。

client_body_in_single_buffer¶

Syntax: client_body_in_single_buffer on | off;
Default: client_body_in_single_buffer off;
Context: http, server, location
@Since: None

决定是否将完整请求体保存在单个缓冲区内。使用 $request_body 变量时建议开启，以减少拷贝次数。

client_body_temp_path¶

Syntax: client_body_temp_path path [level1 [level2 [level3]]];
Default: client_body_temp_path client_body_temp;
Context: http, server, location
@Since: None

指定存放客户端请求体临时文件的目录。可在该目录下使用最多三级子目录。例如：

client_body_temp_path /spool/nginx/client_temp 1 2;

临时文件路径可能形如：

/spool/nginx/client_temp/7/45/00000123457

client_body_timeout¶

Syntax: client_body_timeout time;
Default: client_body_timeout 60s;
Context: http, server, location
@Since: None

读取客户端请求体的超时时间。计时仅在 两次连续读操作之间 ，而非整个请求体传输过程。若在此时间内客户端无数据，返回 408（Request Time-out）。

Note

过低：慢速移动上传/大表单未完成即 408 。
过高：慢速 body 攻击可更长占用连接——配合 client_header_timeout 与 WAF。
常见起点 ：基线 60s；明确大上传场景再提高；与 client_max_body_size 一致。
关联：send_timeout、client_body_buffer_size。

client_header_buffer_size¶

Syntax: client_header_buffer_size size;
Default: client_header_buffer_size 1k;
Context: http, server
@Since: None

读取客户端请求头的缓冲区大小。多数请求 1K 足够；若 Cookie 很长或来自 WAP 客户端，可能不够。若请求行或某头域超出该缓冲，将分配由 large_client_header_buffers 配置的大缓冲。

若在 server 层级指定，可使用默认 server 的值。详见「Virtual server selection」。

client_header_timeout¶

Syntax: client_header_timeout time;
Default: client_header_timeout 60s;
Context: http, server
@Since: None

读取客户端请求头的超时。若在此时间内未传完整个头，返回 408（Request Time-out）。

client_max_body_size¶

Syntax: client_max_body_size size;
Default: client_max_body_size 1m;
Context: http, server, location
@Since: None

允许的上传/请求体 最大尺寸 。超出则返回 413（Request Entity Too Large）；浏览器往往无法友好展示该错误。设为 0 表示不检查。

Note

文件上传、API 大 JSON 等场景须与上游 client_body_buffer_size、磁盘临时目录容量一并评估；仅调大本项仍可能写盘失败。

connection_pool_size¶

Syntax: connection_pool_size size;
Default: connection_pool_size 256|512;
Context: http, server
@Since: None

用于精确调节每个连接的内存分配。对性能影响极小，一般无需使用。默认 32 位平台 256 字节，64 位平台 512 字节。

1.9.8 之前，各平台默认值均为 256。

default_type¶

Syntax: default_type mime-type;
Default: default_type text/plain;
Context: http, server, location
@Since: None

定义响应的默认 MIME 类型。扩展名到 MIME 类型的映射由 types 配置。

directio¶

Syntax: directio size | off;
Default: directio off;
Context: http, server, location
@Since: 0.7.7

读取大于等于指定 size 的文件时，启用 O_DIRECT（FreeBSD、Linux）、F_NOCACHE（macOS）或 directio()（Solaris）。该指令会自动（0.7.15）对相应请求禁用 sendfile。适用于大文件分发：

directio 4m;

或在 Linux 上配合 aio 使用。

directio_alignment¶

Syntax: directio_alignment size;
Default: directio_alignment 512;
Context: http, server, location
@Since: 0.8.11

设置 directio 的对齐值。多数情况下 512 字节即可；Linux 下使用 XFS 时需设为 4K。

disable_symlinks¶

Syntax: disable_symlinks off; disable_symlinks on | if_not_owner [from=part];
Default: disable_symlinks off;
Context: http, server, location
@Since: 1.1.15

决定打开文件时如何处理符号链接：

off：路径中的符号链接允许且不做检查。此为默认行为。
on：路径中任一分量为符号链接则拒绝访问。
if_not_owner：路径中任一分量为符号链接，且链接与其指向对象属主不同时，拒绝访问。
from=part：检查符号链接时（on 与 if_not_owner），通常检查路径各分量。可额外指定 from=part 跳过路径 初始部分 的符号链接检查；此后仅从指定初始部分之后的分量开始检查。若该值不是被检查路径的初始部分，则整段路径按未指定此参数处理。若该值与完整文件名相同，则不检查符号链接。参数值可含变量。

示例：

disable_symlinks on from=$document_root;

仅在有 openat()、fstatat() 接口的系统上可用，包括较新的 FreeBSD、Linux、Solaris。

参数 on、if_not_owner 会增加处理开销。

在不支持“仅搜索打开目录”的系统上，使用这些参数要求 worker 对受检目录均有读权限。

Note

ngx_http_autoindex_module、ngx_http_random_index_module、ngx_http_dav_module 目前忽略本指令。

early_hints¶

Syntax: early_hints string ...;
Default: —
Context: http, server, location
@Since: 1.29.0

定义向客户端传递 103（Early Hints）响应的条件。若字符串参数中至少有一个值非空且不等于 “0”，则传递该响应：

map $http_sec_fetch_mode $early_hints {
    navigate $http2$http3;
}

server {
    ...
    location / {
        early_hints $early_hints;
        proxy_pass http://example.com;
    }
}

error_page¶

Syntax: error_page code ... [=[response]] uri;
Default: —
Context: http, server, location, if in location
@Since: None

为指定错误定义要展示的 URI。uri 可含变量。

Note

误用：fallback URI 非 internal → 意外外跳；API location 继承 HTML 错误页。
常见写法 ：error_page 404 /404.html; + location = /404.html { internal; … }
关联：上游错误见 proxy_intercept_errors。

示例：

error_page 404             /404.html;
error_page 500 502 503 504 /50x.html;

会对指定 uri 做内部重定向，并将客户端请求方法改为 “GET”（“GET”、“HEAD” 除外）。

还可用 “=response” 语法将响应码改为其他值，例如：

error_page 404 =200 /empty.gif;

若错误由代理或 FastCGI/uwsgi/SCGI/gRPC 服务器处理，且上游可能返回不同状态码（如 200、302、401、404），可沿用上游返回的码：

error_page 404 = /404.php;

若内部重定向时无需改 URI 与方法，可将错误处理交给命名 location：

location / {
    error_page 404 = @fallback;
}

location @fallback {
    proxy_pass http://backend;
}

若 uri 处理过程中出错，向客户端返回最后发生的错误状态码。

也可用 URL 重定向处理错误：

error_page 403      http://example.com/forbidden.html;
error_page 404 =301 http://example.com/notfound.html;

此时默认向客户端返回 302；仅可改为重定向状态码之一（301、302、303、307、308）。

Note

307 直至 1.1.16、1.0.13 才被视为重定向。
308 直至 1.13.0 才被视为重定向。

仅当当前层级未定义 error_page 时，才从上一级继承这些指令。

etag¶

Syntax: etag on | off;
Default: etag on;
Context: http, server, location
@Since: 1.3.3

启用或禁用为静态资源自动生成 “ETag” 响应头。

http¶

Syntax: http { ... }
Default: —
Context: main
@Since: None

提供 HTTP 服务器指令的配置上下文。

if_modified_since¶

Syntax: if_modified_since off | exact | before;
Default: if_modified_since exact;
Context: http, server, location
@Since: 0.7.24

指定如何将响应修改时间与 “If-Modified-Since” 请求头中的时间比较：

off：响应始终视为已修改（0.7.34）；
exact：精确匹配；
before：响应修改时间小于等于 “If-Modified-Since” 中的时间。

ignore_invalid_headers¶

Syntax: ignore_invalid_headers on | off;
Default: ignore_invalid_headers on;
Context: http, server
@Since: None

控制是否忽略名称无效的请求头。有效名称由英文字母、数字、连字符及（由 underscores_in_headers 控制的）下划线组成。

若在 server 层级指定，可使用默认 server 的值。详见「Virtual server selection」。

internal¶

Syntax: internal;
Default: —
Context: location
@Since: None

指定该 location 仅用于内部请求 。外部请求返回 404（Not Found）。内部请求包括：

由 error_page、index、internal_redirect、random_index、try_files 重定向的请求；
由上游 “X-Accel-Redirect” 响应头重定向的请求；
由 ngx_http_ssi_module 的 “include virtual”、ngx_http_addition_module 指令，以及 auth_request、mirror 形成的子请求；
由 rewrite 改写的请求。

示例：

error_page 404 /404.html;

location = /404.html {
    internal;
}

为防止错误配置导致请求处理循环，每个请求最多 10 次内部重定向；超出则返回 500（Internal Server Error），错误日志中可见 “rewrite or internal redirection cycle”。

keepalive_disable¶

Syntax: keepalive_disable none | browser ...;
Default: keepalive_disable msie6;
Context: http, server, location
@Since: None

禁用与行为异常的浏览器的 keep-alive 连接。browser 指定受影响的浏览器。msie6 在收到 POST 后禁用与旧版 MSIE 的 keep-alive。safari 禁用与 macOS 及类 macOS 系统上 Safari 及类 Safari 浏览器的 keep-alive。none 对所有浏览器启用 keep-alive。

1.1.18 之前，safari 匹配所有系统上的 Safari 及类 Safari 浏览器，且默认禁用与其的 keep-alive。

keepalive_min_timeout¶

Syntax: keepalive_min_timeout timeout;
Default: keepalive_min_timeout 0;
Context: http, server, location
@Since: 1.27.4

设置 keep-alive 连接在服务端为复用或 worker 优雅退出时 不被关闭 的超时时间。

keepalive_requests¶

Syntax: keepalive_requests number;
Default: keepalive_requests 1000;
Context: http, server, location
@Since: 0.8.0

设置单条 keep-alive 连接可服务的最大请求数；达到上限后关闭连接。

须定期关闭连接以释放每连接内存；上限过高可能导致内存占用过大，不推荐。

1.19.10 之前，默认值为 100。

keepalive_time¶

Syntax: keepalive_time time;
Default: keepalive_time 1h;
Context: http, server, location
@Since: 1.19.10

限制单条 keep-alive 连接可处理请求的最长时间；超时后，在后续请求处理完毕时关闭连接。

keepalive_timeout¶

Syntax: keepalive_timeout timeout [header_timeout];
Default: keepalive_timeout 75s;
Context: http, server, location
@Since: None

第一参数为服务端保持 keep-alive 连接打开的超时；0 禁用 keep-alive。可选第二参数设置 “Keep-Alive: timeout=time” 响应头；两参数可不同。

Note

过低（相对 LB）：LB 认为仍存活而 nginx 已关 → 502 或多余握手。
过高：空闲客户端长时间占用 worker 连接与 fd。
常见起点 ：nginx 65s–75s； LB 空闲超时须大于 nginx keepalive_timeout。若 nginx 为 65s 而 ALB 保持默认 60s，ALB 会先断连 → 502 ；应 调高 ALB 或 调低 nginx（ALB 60s 在 nginx 更短如 55s 时完全可用）。
关联：upstream keepalive（不同层级，勿混淆）。

Mozilla、Konqueror 识别 “Keep-Alive: timeout=time”。MSIE 约 60 秒自行关闭 keep-alive。

large_client_header_buffers¶

Syntax: large_client_header_buffers number size;
Default: large_client_header_buffers 4 8k;
Context: http, server
@Since: None

设置读取大客户端请求头所用缓冲的 number 与 size。请求行不得超过单缓冲大小，否则返回 414（Request-URI Too Large）。单个头域亦不得超过单缓冲，否则返回 400（Bad Request）。缓冲按需分配；默认 8K。请求处理结束且连接进入 keep-alive 时释放这些缓冲。

Note

过小：大 Cookie/JWT/OAuth 头 → 414 或 header buffer 错误。
过大/过多 ：槽位 × worker × 并发抬升内存——勿全站预防性放大。
常见起点 ：先用默认 large_client_header_buffers 4 8k;；鉴权重的 vhost 可试 4 16k 或 8 8k。
关联：client_header_buffer_size。

若在 server 层级指定，可使用默认 server 的值。详见「Virtual server selection」。

limit_except¶

Syntax: limit_except method ... { ... }
Default: —
Context: location
@Since: None

限制 location 内允许的 HTTP 方法。method 可为：GET、HEAD、POST、PUT、DELETE、MKCOL、COPY、MOVE、OPTIONS、PROPFIND、PROPPATCH、LOCK、UNLOCK、PATCH。允许 GET 即同时允许 HEAD。其他方法的访问可由 ngx_http_access_module、ngx_http_auth_basic_module、ngx_http_auth_jwt_module（1.13.10）等限制：

limit_except GET {
    allow 192.168.1.0/32;
    deny  all;
}

注意：这将限制除 GET、HEAD 以外所有方法的访问。

limit_rate¶

Syntax: limit_rate rate;
Default: limit_rate 0;
Context: http, server, location, if in location
@Since: None

限制向客户端发送响应的速率。rate 单位为字节/秒；0 表示不限速。限制按 单个请求 计；若客户端同时开两条连接，总速率约为设定值的两倍。

参数值可含变量（1.17.0），便于按条件限速：

map $slow $rate {
    1     4k;
    2     8k;
}

limit_rate $rate;

亦可通过 $limit_rate 变量限速；自 1.17.0 起不推荐：

server {

    if ($slow) {
        set $limit_rate 4k;
    }

    ...
}

亦可在代理上游响应的 “X-Accel-Limit-Rate” 头中设置；可用 proxy_ignore_headers、fastcgi_ignore_headers、uwsgi_ignore_headers、scgi_ignore_headers 禁用。

limit_rate_after¶

Syntax: limit_rate_after size;
Default: limit_rate_after 0;
Context: http, server, location, if in location
@Since: 0.8.0

设置开始限速前可先发送的数据量。参数值可含变量（1.17.0）。

示例：

location /flv/ {
    flv;
    limit_rate_after 500k;
    limit_rate       50k;
}

lingering_close¶

Syntax: lingering_close off | on | always;
Default: lingering_close on;
Context: http, server, location
@Since: 1.1.0、1.0.6

控制 nginx 如何关闭客户端连接。

默认 on：在启发式判断客户端可能继续发送数据时，等待并处理额外数据后再完全关闭。

always：无条件等待并处理额外客户端数据。

off：从不等待，立即关闭；破坏协议，正常情况下不应使用。

控制 HTTP/2 连接关闭时，须在 server 层级指定（1.19.1）。

lingering_time¶

Syntax: lingering_time time;
Default: lingering_time 30s;
Context: http, server, location
@Since: None

lingering_close 生效时，指定 nginx 处理（读取并忽略）客户端额外数据的最长时间；超时后即使仍有数据也会关闭连接。

lingering_timeout¶

Syntax: lingering_timeout time;
Default: lingering_timeout 5s;
Context: http, server, location
@Since: None

lingering_close 生效时，指定等待更多客户端数据的最长时间。超时未收到数据则关闭；否则读取并忽略后继续等待。“等待—读取—忽略”循环重复，但总时长不超过 lingering_time。

listen address¶

Syntax: listen address[:port] [default_server] [ssl] [http2 | quic] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]]; listen port [default_server] [ssl] [http2 | quic] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]]; listen unix:path [default_server] [ssl] [http2 | quic] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Default: listen *:80 | *:8000;
Context: server
@Since: None

设置服务端接受请求的 IP address 与 port，或 UNIX 域套接字 path。可只指定 address 与 port、仅 address 或仅 port。address 亦可为主机名，例如：

listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;

IPv6 地址（0.7.36）用方括号：

listen [::]:8000;
listen [::1];

UNIX 域套接字（0.8.21）使用 "unix:" 前缀：

listen unix:/var/run/nginx.sock;

仅指定 address 时使用端口 80。

未配置本指令时，nginx 以超级用户运行则监听 *:80，否则 *:8000。

若指定 default_server，该 server 成为对应 address:port 的默认 server。若均无此参数，则该地址端口对上 第一个 server 为默认。

0.8.21 之前，该参数名为 default。

ssl 参数（0.7.14）表示该端口接受的连接均工作在 SSL 模式，便于同一 server 同时处理 HTTP/HTTPS。

http2 参数（1.9.5）配置端口接受 HTTP/2 连接。通常须同时指定 ssl，也可配置为无 SSL 的 HTTP/2。

该参数已弃用，应改用 http2 指令。

quic 参数（1.25.0）配置端口接受 QUIC 连接。

proxy_protocol 参数（1.5.12）表示该端口接受的连接均使用 PROXY protocol。

自 1.13.11 起支持 PROXY protocol 版本 2。

listen 还可带与套接字系统调用相关的附加参数；可在任一 listen 中指定，但同一 address:port 对每种参数仅一次。

0.8.21 之前，这些参数只能与 default 参数一同写在 listen 中。

setfib=number：该参数（0.8.44）为监听套接字设置关联路由表 FIB（SO_SETFIB）。目前仅 FreeBSD 有效。
fastopen=number：为监听套接字启用 “TCP Fast Open”（1.5.8），并限制尚未完成三次握手的连接队列最大长度。 >除非服务器能正确处理同一带数据的 SYN 包被多次接收，否则勿启用。
backlog=number：设置 listen() 的 backlog，限制待接受连接队列长度。FreeBSD、DragonFly BSD、macOS 默认 -1，其他平台 511。
rcvbuf=size：设置监听套接字接收缓冲（SO_RCVBUF）。
sndbuf=size：设置监听套接字发送缓冲（SO_SNDBUF）。
accept_filter=filter：设置 accept 过滤名（SO_ACCEPTFILTER），在 accept() 前过滤入站连接。仅 FreeBSD、NetBSD 5.0+。可选 dataready、httpready。
deferred：在 Linux 上使用延迟 accept()（TCP_DEFER_ACCEPT）。
bind：对给定 address:port 单独调用 bind()。当多个 listen 同端口不同地址且其一为 *:port 时，nginx 仅 bind() 到 *:port；此时会调用 getsockname() 确定接受连接的地址。若使用 setfib、fastopen、backlog、rcvbuf、sndbuf、accept_filter、deferred、ipv6only、reuseport 或 so_keepalive，则对该 address:port 总会单独 bind()。
ipv6only=on|off：该参数（0.7.42）通过 IPV6_V6ONLY 决定通配 [::] 的 IPv6 套接字仅接受 IPv6 还是同时接受 IPv4。默认开启；启动时只能设置一次。 >1.3.4 之前，省略该参数时沿用操作系统对套接字的设置。
reuseport：该参数（1.9.1）为每个 worker 创建独立监听套接字（Linux 3.9+、DragonFly BSD 用 SO_REUSEPORT，FreeBSD 12+ 用 SO_REUSEPORT_LB），由内核在 worker 间分发入站连接。目前仅 Linux 3.9+、DragonFly BSD、FreeBSD 12+（1.15.1）。 >不当使用可能有安全影响。
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]：该参数（1.1.11）配置监听套接字的 “TCP keepalive”。省略时沿用系统设置。on 开启 SO_KEEPALIVE；“off” 关闭。部分系统（Linux、NetBSD、Dragonfly、FreeBSD、macOS）支持按套接字设置 TCP_KEEPIDLE、TCP_KEEPINTVL、TCP_KEEPCNT，可通过 keepidle、keepintvl、keepcnt 配置；可省略一至两个参数，沿用系统默认。例如：
```
so_keepalive=30m::10
```
将空闲超时（TCP_KEEPIDLE）设为 30 分钟，探测间隔（TCP_KEEPINTVL）用系统默认，探测次数（TCP_KEEPCNT）为 10。

示例：

listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;

location¶

Syntax: location [ = | ~ | ~* | ^~ ] uri { ... } location @name { ... }
Default: —
Context: server, location
@Since: None

按请求 URI 设置配置。

匹配针对规范化 URI：解码 “%XX” 编码、解析 “.”、“..” 相对路径，并可能将相邻多斜杠压缩为单斜杠。

location 可由前缀字符串或正则定义。正则前加 “~*”（不区分大小写）或 “~”（区分大小写）。查找时 nginx 先检查前缀 location，取最长匹配前缀并记住；再按配置文件顺序检查正则，首次匹配即停并使用对应配置。若无正则匹配，则使用先前记住的前缀 location。

location 块可嵌套（下文有例外）。

macOS、Cygwin 等大小写不敏感系统上，前缀匹配忽略大小写（0.7.7）；比较限于单字节 locale。

正则可含捕获（0.7.40），供其他指令引用。

最长匹配前缀 location 带 “^~” 时不再检查正则。

“=” 修饰符可定义 URI 与 location 的精确匹配；匹配成功即终止搜索。例如 “/” 请求频繁时，“location = /” 可在首次比较后即结束，加快处理；此类 location 显然不能嵌套子 location。

Note

0.7.1 至 0.8.41：若请求匹配无 “=”、“^~” 的前缀 location，搜索亦终止且不检查正则。

示例：

location = / {
    [ configuration A ]
}

location / {
    [ configuration B ]
}

location /documents/ {
    [ configuration C ]
}

location ^~ /images/ {
    [ configuration D ]
}

location ~* \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

“/” 匹配配置 A，“/index.html” 匹配 B，“/documents/document.html” 匹配 C，“/images/1.gif” 匹配 D，“/documents/1.jpg” 匹配 E。

“@” 前缀定义命名 location，不用于常规请求处理，而用于重定向；不可嵌套，亦不可含嵌套 location。

若前缀 location 以斜杠结尾，且请求由 proxy_pass、fastcgi_pass、uwsgi_pass、scgi_pass、memcached_pass 或 grpc_pass 处理，则作特殊处理：URI 等于该字符串但无尾斜杠时，返回 301 永久重定向到带斜杠的 URI。若不需要，可精确匹配 URI 与 location，例如：

location /user/ {
    proxy_pass http://user.example.com;
}

location = /user {
    proxy_pass http://login.example.com;
}

log_not_found¶

Syntax: log_not_found on | off;
Default: log_not_found on;
Context: http, server, location
@Since: None

启用或禁用将“文件未找到”类错误写入 error_log。

log_subrequest¶

Syntax: log_subrequest on | off;
Default: log_subrequest off;
Context: http, server, location
@Since: None

启用或禁用将子请求写入 access_log。

max_ranges¶

Syntax: max_ranges number;
Default: —
Context: http, server, location
@Since: 1.1.2

限制字节范围请求中允许的最大 range 数。超出则按未指定 byte range 处理。默认不限；0 完全禁用 byte range。

merge_slashes¶

Syntax: merge_slashes on | off;
Default: merge_slashes on;
Context: http, server
@Since: None

启用或禁用将 URI 中两个及以上相邻斜杠压缩为单个斜杠。

压缩对前缀与正则 location 的正确匹配至关重要。否则 “//scripts/one.php” 不会匹配：

location /scripts/ {
    ...
}

可能被当作静态文件处理；因此会转换为 “/scripts/one.php”。

若 URI 含 base64 编码名（内部使用 “/”），有时须关闭压缩；出于安全考虑，仍建议避免关闭。

若在 server 层级指定，可使用默认 server 的值。详见「Virtual server selection」。

msie_padding¶

Syntax: msie_padding on | off;
Default: msie_padding on;
Context: http, server, location
@Since: None

启用或禁用为状态码大于 400 的 MSIE 客户端响应添加注释，使响应体至少 512 字节。

msie_refresh¶

Syntax: msie_refresh on | off;
Default: msie_refresh off;
Context: http, server, location
@Since: None

启用或禁用对 MSIE 客户端使用刷新而非重定向。

open_file_cache¶

Syntax: open_file_cache off; open_file_cache max=N [inactive=time];
Default: open_file_cache off;
Context: http, server, location
@Since: None

配置可缓存：

Note

过小/ inactive 过短 ：静态命中率低，高 QPS 下 open() 增多。
过大/ valid 过长 ：原地发版后 inode/大小可能陈旧；worker fd 与内存占用升高——文件变化不会自动清缓存。
常见起点 ：open_file_cache max=10000 inactive=20s; open_file_cache_valid 30s;——valid 为校验间隔，inactive 为空闲淘汰。
运维/发版后 ：替换静态文件或缩短 valid 后执行 nginx -s reload ，让新 worker 加载配置并重建 cache；否则依赖 valid / inactive 自然过期（滚动发布时旧 worker 在 drain 前仍可能持陈旧 fd）。
关联：sendfile、静态资源发布流程。

已打开文件描述符及其大小、修改时间；
目录是否存在；
文件查找错误，如 “file not found”、“no read permission” 等。 >错误缓存须单独用 open_file_cache_errors 启用。

参数：

max：缓存元素最大数量；溢出时移除最近最少使用（LRU）项；
inactive：元素在此时间内未被访问则从缓存移除；默认 60 秒；
off：禁用缓存。

示例：

open_file_cache          max=1000 inactive=20s;
open_file_cache_valid    30s;
open_file_cache_min_uses 2;
open_file_cache_errors   on;

open_file_cache_errors¶

Syntax: open_file_cache_errors on | off;
Default: open_file_cache_errors off;
Context: http, server, location
@Since: None

启用或禁用 open_file_cache 对文件查找错误的缓存。

open_file_cache_min_uses¶

Syntax: open_file_cache_min_uses number;
Default: open_file_cache_min_uses 1;
Context: http, server, location
@Since: None

设置 open_file_cache 的 inactive 周期内文件至少被访问的 number 次，才在缓存中保持描述符打开。

open_file_cache_valid¶

Syntax: open_file_cache_valid time;
Default: open_file_cache_valid 60s;
Context: http, server, location
@Since: None

设置 open_file_cache 元素应重新校验的时间间隔。

output_buffers¶

Syntax: output_buffers number size;
Default: output_buffers 2 32k;
Context: http, server, location
@Since: None

设置从磁盘读取响应所用缓冲的 number 与 size。

1.9.5 之前，默认值为 1 32k。

port_in_redirect¶

Syntax: port_in_redirect on | off;
Default: port_in_redirect on;
Context: http, server, location
@Since: None

启用或禁用 nginx 发出的绝对重定向中是否包含端口。

重定向中是否使用主 server 名由 server_name_in_redirect 控制。

postpone_output¶

Syntax: postpone_output size;
Default: postpone_output 1460;
Context: http, server, location
@Since: None

若可能，推迟向客户端发送数据，直到 nginx 至少有 size 字节可发；0 禁用推迟。

read_ahead¶

Syntax: read_ahead size;
Default: read_ahead 0;
Context: http, server, location
@Since: None

设置内核读文件时的预读量。

Linux 使用 posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)，故忽略 size。

FreeBSD 使用 fcntl(O_READAHEAD, size)（FreeBSD 9.0-CURRENT+）；FreeBSD 7 须打补丁。

recursive_error_pages¶

Syntax: recursive_error_pages on | off;
Default: recursive_error_pages off;
Context: http, server, location
@Since: None

启用或禁用通过 error_page 进行多次重定向；次数受限。

request_pool_size¶

Syntax: request_pool_size size;
Default: request_pool_size 4k;
Context: http, server
@Since: None

用于精确调节每个请求的内存分配。对性能影响极小，一般无需使用。

reset_timedout_connection¶

Syntax: reset_timedout_connection on | off;
Default: reset_timedout_connection off;
Context: http, server, location
@Since: None

启用或禁用重置超时连接及以非标准码 444 关闭的连接（1.15.2）。重置方式：关闭套接字前对其设置 SO_LINGER 超时 0；关闭时向客户端发 TCP RST 并释放套接字占用的内存，避免已关闭但缓冲未空的套接字长期停在 FIN_WAIT1。

须注意：超时的 keep-alive 连接仍正常关闭。

resolver¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: —
Context: http, server, location
@Since: None

配置用于将上游服务器名解析为地址的 DNS 服务器，例如：

resolver 127.0.0.1 [::1]:5353;

地址可为域名或 IP，可选端口（1.3.1、1.2.2）；未指定端口则用 53。按轮询查询。

1.1.7 之前只能配置单个 DNS；1.3.1、1.2.2 起支持 IPv6 地址。

默认解析 IPv4 与 IPv6。若不需要其一，可指定 ipv4=off（1.23.1）或 ipv6=off。

1.5.8 起支持解析为 IPv6。

默认按响应 TTL 缓存；可选 valid 覆盖：

resolver 127.0.0.1 [::1]:5353 valid=30s;

Note

1.1.9 之前无法调整缓存时间，nginx 固定缓存 5 分钟。
为防 DNS 欺骗，建议在受信本地网络中配置 DNS。

可选 status_zone（1.17.1）在指定 zone 中收集 DNS 请求/响应统计；需商业订阅。

resolver_timeout¶

Syntax: resolver_timeout time;
Default: resolver_timeout 30s;
Context: http, server, location
@Since: None

设置名称解析超时，例如：

resolver_timeout 5s;

root¶

Syntax: root path;
Default: root html;
Context: http, server, location, if in location
@Since: None

设置请求的文档根目录。例如：

location /i/ {
    root /data/w3;
}

“/i/top.gif” 请求将发送 /data/w3/i/top.gif。

path 可含变量，但不可使用 $document_root、$realpath_root。

文件路径由 URI 直接拼到 root 值；若须改写 URI，应使用 alias。

satisfy¶

Syntax: satisfy all | any;
Default: satisfy all;
Context: http, server, location
@Since: None

当 ngx_http_access_module、ngx_http_auth_basic_module、ngx_http_auth_request_module、ngx_http_auth_jwt_module（1.13.10）或 ngx_http_oidc_module（1.27.4）全部（all）或至少一个（any）允许访问时，才放行。

示例：

location / {
    satisfy any;

    allow 192.168.1.0/32;
    deny  all;

    auth_basic           "closed site";
    auth_basic_user_file conf/htpasswd;
}

send_lowat¶

Syntax: send_lowat size;
Default: send_lowat 0;
Context: http, server, location
@Since: None

设为非零时，nginx 通过 kqueue 的 NOTE_LOWAT 或套接字 SO_SNDLOWAT 尽量减少对客户端套接字的发送次数；均使用指定 size。

Warning

Linux、Solaris、Windows 上忽略本指令。

send_timeout¶

Syntax: send_timeout time;
Default: send_timeout 60s;
Context: http, server, location
@Since: None

设置向客户端发送响应的超时；仅在两次连续写操作之间计时，非整段响应传输。若此时间内客户端未收到任何数据则关闭连接。

Note

过低：慢速下载客户端（移动网络）传输中途被断开。
过高：卡住不读的客户端更久占用 SEND 状态连接。
常见起点 ：默认 60s 多数够用；大文件慢网可适当提高；流式场景更依赖 proxy_buffering off 与 proxy_read_timeout。
关联：keepalive_timeout、上游路径 proxy_read_timeout。

sendfile¶

Syntax: sendfile on | off;
Default: sendfile off;
Context: http, server, location, if in location
@Since: None

启用或禁用 sendfile()。

Note

关闭：静态文件多一次用户态拷贝 → 大文件/高 QPS 静态站 CPU 升高。
开启：本地 ext4/xfs 收益大；部分网络盘/虚拟机收益有限或有怪癖——全站 off 前先压测。
常见做法 ：Linux 静态站 sendfile on;，配合 tcp_nopush。
关联：tcp_nopush。

自 nginx 0.8.12、FreeBSD 5.2.1 起，可用 aio 为 sendfile() 预加载数据：

location /video/ {
    sendfile       on;
    tcp_nopush     on;
    aio            on;
}

此配置下 sendfile() 带 SF_NODISKIO，不因磁盘 I/O 阻塞，而报告数据不在内存；nginx 通过读一字节发起异步加载。首次读时 FreeBSD 内核预载文件前 128K，后续每次 16K；可用 read_ahead 调整。

Note

1.7.11 之前可用 aio sendfile; 启用预加载。

sendfile_max_chunk¶

Syntax: sendfile_max_chunk size;
Default: sendfile_max_chunk 2m;
Context: http, server, location
@Since: None

限制单次 sendfile() 可传输的数据量。无限制时，高速连接可能独占 worker。

1.21.4 之前默认无限制。

server¶

Syntax: server { ... }
Default: —
Context: http
@Since: None

设置虚拟 server 配置。IP 虚拟主机（按 IP）与名称虚拟主机（按 “Host” 头）并无严格分界；listen 描述接受连接的地址与端口，server_name 列出所有名称。示例见 “How nginx processes a request”。

server_name¶

Syntax: server_name name ...;
Default: server_name "";
Context: server
@Since: None

设置虚拟 server 名称，例如：

Note

误用：TLS 默认站点滥用 _ → 证书或 vhost 错配；多 server 重名 → 匹配顺序混乱。
过宽：通配符无 DNS/ACME 覆盖 → 续期失败。
常见做法 ：每个 server {} 写明确 FQDN；仅 HTTP 跳转 HTTPS 保留单一 default_server。
关联：listen default_server、证书 SAN。

server {
    server_name example.com www.example.com;
}

第一个名称为主 server 名。

名称可含星号（“*”）替代首段或末段：

server {
    server_name example.com *.example.com www.example.*;
}

称为通配名称。

上述前两种可合并：

server {
    server_name .example.com;
}

亦可在名称前加波浪号（“~”）使用正则：

server {
    server_name www.example.com ~^www\d+\.example\.com$;
}

正则可含捕获（0.7.40），供其他指令使用：

server {
    server_name ~^(www\.)?(.+)$;

    location / {
        root /sites/$2;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

正则命名捕获（0.8.25）会创建变量：

server {
    server_name ~^(www\.)?(?<domain>.+)$;

    location / {
        root /sites/$domain;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

参数为 “$hostname”（0.9.4）时插入本机主机名。

亦可指定空 server 名（0.7.11）：

server {
    server_name www.example.com "";
}

使该 server 处理给定 address:port 上无 “Host” 头的请求（替代默认 server）。此为默认行为。

0.8.48 之前默认使用本机主机名。

按名称查找虚拟 server 时，若多名匹配（如通配与正则同时匹配），按下列优先级取首个匹配：

精确名称
以 * 开头的最长通配，如 “*.example.com”
以 * 结尾的最长通配，如 “mail.*”
配置文件中首次匹配的正则

详见 Server names。

server_name_in_redirect¶

Syntax: server_name_in_redirect on | off;
Default: server_name_in_redirect off;
Context: http, server, location
@Since: None

启用或禁用 nginx 绝对重定向中使用 server_name 指定的主 server 名。禁用时使用 “Host” 请求头；若无该头则使用服务器 IP。

重定向是否含端口由 port_in_redirect 控制。

server_names_hash_bucket_size¶

Syntax: server_names_hash_bucket_size size;
Default: server_names_hash_bucket_size 32|64|128;
Context: http
@Since: None

设置 server 名称哈希表的桶 size；默认值取决于 CPU 缓存行大小。哈希表配置详见文档。

server_names_hash_max_size¶

Syntax: server_names_hash_max_size size;
Default: server_names_hash_max_size 512;
Context: http
@Since: None

设置 server 名称哈希表的最大尺寸。哈希表配置详见文档。

server_tokens [commercial]¶

Syntax: server_tokens on | off | build | string;
Default: server_tokens on;
Context: http, server, location
@Since: None

启用或禁用在错误页与 “Server” 响应头中输出 nginx 版本。

Warning

风险：on（默认）在 Server 头与错误页暴露版本——便于针对性攻击。
建议：在 http/server 设 server_tokens off;——降低指纹面， 不能替代 补丁与加固。
常见写法 ：生产全局 server_tokens off;。

build（1.11.10）同时输出构建名。

商业订阅自 1.9.13 起，可用含变量的 string 显式设置错误页与 “Server” 头；空字符串则不输出 “Server”。

subrequest_output_buffer_size¶

Syntax: subrequest_output_buffer_size size;
Default: subrequest_output_buffer_size 4k|8k;
Context: http, server, location
@Since: 1.13.10

设置存储子请求响应体的缓冲 size；默认等于一页内存（平台为 4K 或 8K），可改小。

仅适用于响应体保存在内存的子请求，例如 SSI 的 ssi_include_set。

tcp_nodelay¶

Syntax: tcp_nodelay on | off;
Default: tcp_nodelay on;
Context: http, server, location
@Since: None

启用或禁用 TCP_NODELAY。连接进入 keep-alive 时启用；SSL、无缓冲代理、WebSocket 代理时亦启用。

Note

关闭：启用 Nagle → keepalive/API 小响应延迟升高。
开启（默认）：交互/API 延迟更低——多数生产站点保持开启。
常见做法 ：保持 tcp_nodelay on;，除非遗留二进制协议明确要求 Nagle。
关联：keepalive_timeout。

tcp_nopush¶

Syntax: tcp_nopush on | off;
Default: tcp_nopush off;
Context: http, server, location
@Since: None

在 FreeBSD 上启用或禁用 TCP_NOPUSH，Linux 上为 TCP_CORK；仅在使用 sendfile 时生效。启用后可：

Note

关闭（且 sendfile on）：Linux 上可能产生更多小报文。
开启：合并响应头与文件首包——与 sendfile 同开通常有益。
常见做法 ：tcp_nopush on; + sendfile on;——默认常已合理，仅在抓包证明有问题时再改。
关联：tcp_nodelay、sendfile。

在 Linux 与 FreeBSD 4.* 上将响应头与文件开头合在一个包发送；
以完整包发送文件。

try_files¶

Syntax: try_files file ... uri; try_files file ... =code;
Default: —
Context: server, location
@Since: None

按指定顺序检查文件是否存在，用首个找到的文件处理请求；在当前 context 中执行。路径由 root、alias 与 file 参数构成。名称末尾加斜杠可检查目录，如 “$uri/”。若均未找到，内部重定向到最后一个参数的 uri。例如：

Note

误用：fallback 落入错误 location（绕过鉴权）；顺序错误 → 意外 404。
常见写法 ：SPA 静态根：try_files $uri $uri/ /index.html;，/index.html 用专用或 internal location。
关联：error_page、index。

location /images/ {
    try_files $uri /images/default.gif;
}

location = /images/default.gif {
    expires 30s;
}

最后参数亦可指向命名 location；自 0.7.51 起可为 code：

location / {
    try_files $uri $uri/index.html $uri.html =404;
}

代理 Mongrel 示例：

location / {
    try_files /system/maintenance.html
              $uri $uri/index.html $uri.html
              @mongrel;
}

location @mongrel {
    proxy_pass http://mongrel;
}

Drupal/FastCGI 示例：

location / {
    try_files $uri $uri/ @drupal;
}

location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    fastcgi_param SCRIPT_NAME     $fastcgi_script_name;
    fastcgi_param QUERY_STRING    $args;

    ... other fastcgi_param's
}

location @drupal {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    fastcgi_param SCRIPT_NAME     /index.php;
    fastcgi_param QUERY_STRING    q=$uri&$args;

    ... other fastcgi_param's
}

下例中：

location / {
    try_files $uri $uri/ @drupal;
}

等价于：

location / {
    error_page 404 = @drupal;
    log_not_found off;
}

而：

location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;

    ...
}

try_files 在交给 FastCGI 前先检查 PHP 文件是否存在。

WordPress/Joomla 示例：

location / {
    try_files $uri $uri/ @wordpress;
}

location ~ \.php$ {
    try_files $uri @wordpress;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    ... other fastcgi_param's
}

location @wordpress {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    ... other fastcgi_param's
}

types¶

Syntax: types { ... }
Default: types { text/html html; image/gif gif; image/jpeg jpg; }
Context: http, server, location
@Since: None

将扩展名映射为响应 MIME 类型。扩展名不区分大小写；多个扩展名可映射同一类型，例如：

types {
    application/octet-stream bin exe dll;
    application/octet-stream deb;
    application/octet-stream dmg;
}

nginx 在 conf/mime.types 中提供较完整的映射表。

若某 location 对所有请求返回 “application/octet-stream”，可：

location /download/ {
    types        { }
    default_type application/octet-stream;
}

types_hash_bucket_size¶

Syntax: types_hash_bucket_size size;
Default: types_hash_bucket_size 64;
Context: http, server, location
@Since: None

设置 types 哈希表桶大小。哈希表配置详见文档。

1.5.13 之前，默认值取决于 CPU 缓存行大小。

types_hash_max_size¶

Syntax: types_hash_max_size size;
Default: types_hash_max_size 1024;
Context: http, server, location
@Since: None

设置 types 哈希表最大尺寸。哈希表配置详见文档。

underscores_in_headers¶

Syntax: underscores_in_headers on | off;
Default: underscores_in_headers off;
Context: http, server
@Since: None

启用或禁用客户端请求头名称中的下划线。禁用时，含下划线的头域视为无效，受 ignore_invalid_headers 约束。

若在 server 层级指定，可使用默认 server 的值。详见 “Virtual server selection”。

variables_hash_bucket_size¶

Syntax: variables_hash_bucket_size size;
Default: variables_hash_bucket_size 64;
Context: http
@Since: None

设置变量哈希表桶大小。哈希表配置详见文档。

variables_hash_max_size¶

Syntax: variables_hash_max_size size;
Default: variables_hash_max_size 1024;
Context: http
@Since: None

设置变量哈希表最大 size。哈希表配置详见文档。

1.5.13 之前，默认值为 512。

ngx_http_access_module¶

allow¶

Syntax: allow address | CIDR | unix: | all;
Default: —
Context: http, server, location, limit_except
@Since: None

允许指定网络或地址访问。若指定特殊值 unix:（1.5.1），则允许所有 UNIX 域套接字访问。

deny¶

Syntax: deny address | CIDR | unix: | all;
Default: —
Context: http, server, location, limit_except
@Since: None

拒绝指定网络或地址访问。若指定特殊值 unix:（1.5.1），则拒绝所有 UNIX 域套接字访问。

ngx_http_addition_module¶

add_before_body¶

Syntax: add_before_body uri;
Default: —
Context: http, server, location
@Since: None

在响应体之前追加处理给定子请求后返回的文本。参数为空字符串 "" 时，取消从上一级继承的追加设置。

add_after_body¶

Syntax: add_after_body uri;
Default: —
Context: http, server, location
@Since: None

在响应体之后追加处理给定子请求后返回的文本。参数为空字符串 "" 时，取消从上一级继承的追加设置。

addition_types¶

Syntax: addition_types mime-type ...;
Default: addition_types text/html;
Context: http, server, location
@Since: 0.7.9

除 “text/html” 外，还允许在指定 MIME 类型的响应中追加文本。特殊值 “*” 匹配任意 MIME 类型（0.8.29）。

ngx_http_api_module¶

api¶

Syntax: api [write=on|off];
Default: —
Context: location
@Since: None

在所在 location 启用 REST API 接口。须限制对该 location 的访问。

Note

API location 应配合 allow/deny、auth_basic 或 IP 白名单，禁止对公网开放写操作（write=on）。

[api] status_zone¶

Syntax: status_zone zone;
Default: —
Context: server, location, if in location
@Since: 1.13.12

在指定 zone 中收集虚拟 http 或 stream server 的状态信息。多个 server 可共用同一 zone。

ngx_http_auth_basic_module¶

auth_basic¶

Syntax: auth_basic string | off;
Default: auth_basic off;
Context: http, server, location, limit_except
@Since: None

使用 “HTTP Basic Authentication” 协议校验用户名与密码。指定参数用作 realm（认证域）；参数值可含变量（1.3.10、1.2.7）。特殊值 off 取消从上一级继承的 auth_basic 效果。

auth_basic_user_file¶

Syntax: auth_basic_user_file file;
Default: —
Context: http, server, location, limit_except
@Since: None

指定保存用户名与密码的文件，格式如下：

ngx_http_auth_jwt_module¶

auth_jwt¶

Syntax: auth_jwt string [token=$variable] | off;
Default: auth_jwt off;
Context: http, server, location, limit_except
@Since: None

启用 JSON Web Token（JWT）校验。指定字符串用作 realm（认证域）；参数值可含变量。

auth_jwt_claim_set¶

Syntax: auth_jwt_claim_set $variable name ...;
Default: —
Context: http
@Since: 1.11.10

将变量设为 JWT claim 参数（由键名标识）。名称匹配自 JSON 树顶层开始。对数组，变量保存以逗号分隔的元素列表。

auth_jwt_header_set¶

Syntax: auth_jwt_header_set $variable name ...;
Default: —
Context: http
@Since: 1.11.10

将变量设为 JOSE 头参数（由键名标识）。名称匹配自 JSON 树顶层开始。对数组，变量保存以逗号分隔的元素列表。

auth_jwt_key_cache¶

Syntax: auth_jwt_key_cache time;
Default: auth_jwt_key_cache 0;
Context: http, server, location
@Since: 1.21.4

启用或禁用对自文件或子请求获得的密钥的缓存，并设置缓存时间。不支持缓存来自变量的密钥。默认禁用密钥缓存。

Note

使用 auth_jwt_key_request 拉取 JWKS 时，建议设置合理 time（如 12h），避免每次请求都打密钥端点。

auth_jwt_key_file¶

Syntax: auth_jwt_key_file file;
Default: —
Context: http, server, location, limit_except
@Since: None

指定 JSON Web Key Set（JWKS）格式文件，用于校验 JWT 签名。参数值可含变量。

auth_jwt_key_request¶

Syntax: auth_jwt_key_request uri;
Default: —
Context: http, server, location, limit_except
@Since: 1.15.6

允许通过子请求获取 JWKS 文件以校验 JWT 签名，并设置子请求发送到的 URI。参数值可含变量。为降低校验开销，建议缓存密钥文件：

auth_jwt_leeway¶

Syntax: auth_jwt_leeway time;
Default: auth_jwt_leeway 0s;
Context: http, server, location
@Since: 1.13.10

设置校验 JWT exp 与 nbf claim 时，补偿时钟偏差的最大允许宽限时间。

auth_jwt_type¶

Syntax: auth_jwt_type signed | encrypted | nested;
Default: auth_jwt_type signed;
Context: http, server, location, limit_except
@Since: 1.19.7

指定期望的 JSON Web Token 类型：JWS（签名）、JWE（加密），或先签名再加密的 Nested JWT（nested，1.21.0）。

auth_jwt_require¶

Syntax: auth_jwt_require $value ... [error=401 | 403] ;
Default: —
Context: http, server, location, limit_except
@Since: 1.21.2

指定 JWT 校验的附加条件。值可含文本、变量及其组合，且须以变量开头（1.21.7）。仅当所有值均非空且不等于 “0” 时认证成功。

ngx_http_auth_request_module¶

auth_request¶

Syntax: auth_request uri | off;
Default: auth_request off;
Context: http, server, location
@Since: None

基于子请求结果启用授权，并设置子请求将发送到的 URI。

auth_request_set¶

Syntax: auth_request_set $variable value;
Default: —
Context: http, server, location
@Since: None

授权子请求完成后，将请求变量设为给定值。值可含来自授权子请求的变量，例如 $upstream_http_*。

ngx_http_autoindex_module¶

autoindex¶

Syntax: autoindex on | off;
Default: autoindex off;
Context: http, server, location
@Since: None

启用或禁用目录列表输出。

Warning

生产环境勿对公网 location 开启 autoindex on，易泄露目录结构与敏感文件名；必要时配合 allow/deny 限制访问。

autoindex_exact_size¶

Syntax: autoindex_exact_size on | off;
Default: autoindex_exact_size on;
Context: http, server, location
@Since: None

HTML 格式下，指定目录列表是否输出精确文件大小；禁用时四舍五入为 KB、MB、GB。

autoindex_format¶

Syntax: autoindex_format html | xml | json | jsonp;
Default: autoindex_format html;
Context: http, server, location
@Since: 1.7.9

设置目录列表的输出格式。

autoindex_localtime¶

Syntax: autoindex_localtime on | off;
Default: autoindex_localtime off;
Context: http, server, location
@Since: None

HTML 格式下，指定目录列表中的时间以本地时区还是 UTC 输出。

ngx_http_browser_module¶

ancient_browser¶

Syntax: ancient_browser string ...;
Default: —
Context: http, server, location
@Since: None

若在 “User-Agent” 请求头中发现任一指定子串，则将该浏览器视为过时浏览器。特殊字符串 “netscape4” 对应正则 “^Mozilla/[1-4]”。

ancient_browser_value¶

Syntax: ancient_browser_value string;
Default: ancient_browser_value 1;
Context: http, server, location
@Since: None

设置 $ancient_browser 变量的值。

modern_browser¶

Syntax: modern_browser browser version; modern_browser unlisted;
Default: —
Context: http, server, location
@Since: None

指定自某版本起浏览器视为现代浏览器。browser 可为：msie、gecko（基于 Mozilla 的浏览器）、opera、safari 或 konqueror。

modern_browser_value¶

Syntax: modern_browser_value string;
Default: modern_browser_value 1;
Context: http, server, location
@Since: None

设置 $modern_browser 变量的值。

ngx_http_charset_module¶

charset¶

Syntax: charset charset | off;
Default: charset off;
Context: http, server, location, if in location
@Since: None

在 “Content-Type” 响应头中加入指定字符集。若与 source_charset 指定字符集不同，则进行转码。

charset_map¶

Syntax: charset_map charset1 charset2 { ... }
Default: —
Context: http
@Since: None

描述两种字符集之间的转换表；相同数据亦用于构建反向转换表。字符码以十六进制给出。80–FF 范围内缺失字符替换为 “?”。自 UTF-8 转换时，单字节字符集中缺失字符替换为 “&#XXXX;”。

charset_types¶

Syntax: charset_types mime-type ...;
Default: charset_types text/html text/xml text/plain text/vnd.wap.wml application/javascript application/rss+xml;
Context: http, server, location
@Since: 0.7.9

除 “text/html” 外，还在指定 MIME 类型的响应中启用本模块处理。特殊值 “*” 匹配任意 MIME 类型（0.8.29）。

override_charset¶

Syntax: override_charset on | off;
Default: override_charset off;
Context: http, server, location, if in location
@Since: None

当来自代理或 FastCGI/uwsgi/SCGI/gRPC 服务器的响应已在 “Content-Type” 头中带字符集时，决定是否仍执行转码。启用时，以响应中指定的字符集作为源字符集。

source_charset¶

Syntax: source_charset charset;
Default: —
Context: http, server, location, if in location
@Since: None

定义响应的源字符集。若与 charset 指定字符集不同，则进行转码。

ngx_http_dav_module¶

create_full_put_path¶

Syntax: create_full_put_path on | off;
Default: create_full_put_path off;
Context: http, server, location
@Since: None

WebDAV 规范仅允许在 已存在 的目录中创建文件。本指令允许自动创建所需的全部中间目录。

dav_access¶

Syntax: dav_access users:permissions ...;
Default: dav_access user:rw;
Context: http, server, location
@Since: None

设置新建文件与目录的访问权限，例如：

dav_methods¶

Syntax: dav_methods off | method ...;
Default: dav_methods off;
Context: http, server, location
@Since: None

允许指定的 HTTP 与 WebDAV 方法。参数 off 拒绝本模块处理的全部方法。支持：PUT、DELETE、MKCOL、COPY、MOVE。

min_delete_depth¶

Syntax: min_delete_depth number;
Default: min_delete_depth 0;
Context: http, server, location
@Since: None

仅当请求路径中的元素个数不少于指定值时，才允许 DELETE 删除文件。例如指令

ngx_http_empty_gif_module¶

empty_gif¶

Syntax: empty_gif;
Default: —
Context: location
@Since: None

在所在 location 启用本模块处理。

ngx_http_f4f_module¶

f4f¶

Syntax: f4f;
Default: —
Context: location
@Since: None

在所在 location 启用本模块处理。

f4f_buffer_size¶

Syntax: f4f_buffer_size size;
Default: f4f_buffer_size 512k;
Context: http, server, location
@Since: None

设置读取 .f4x 索引文件所用缓冲区大小。

ngx_http_fastcgi_module¶

fastcgi_bind¶

Syntax: fastcgi_bind address [transparent] | off;
Default: —
Context: http, server, location
@Since: 0.8.22

使发往 FastCGI 服务器的出站连接从指定的本地 IP 地址（1.11.2 起可选端口）发起。参数值可含变量（1.3.12）。特殊值 off（1.3.12）取消从上一级继承的 fastcgi_bind 效果，由系统自动分配本地 IP 与端口。

fastcgi_buffer_size¶

Syntax: fastcgi_buffer_size size;
Default: fastcgi_buffer_size 4k|8k;
Context: http, server, location
@Since: None

设置用于读取 FastCGI 服务器响应首段的缓冲区大小；该段通常含较小的响应头。默认等于一个内存页，平台相关为 4K 或 8K，亦可改小。

fastcgi_buffering¶

Syntax: fastcgi_buffering on | off;
Default: fastcgi_buffering on;
Context: http, server, location
@Since: 1.5.6

启用或禁用对 FastCGI 服务器响应的缓冲。

fastcgi_buffers¶

Syntax: fastcgi_buffers number size;
Default: fastcgi_buffers 8 4k|8k;
Context: http, server, location
@Since: None

设置单连接读取 FastCGI 服务器响应所用缓冲区的数量与大小。默认单缓冲等于一个内存页，平台相关为 4K 或 8K。

fastcgi_busy_buffers_size¶

Syntax: fastcgi_busy_buffers_size size;
Default: fastcgi_busy_buffers_size 8k|16k;
Context: http, server, location
@Since: None

启用 FastCGI 响应缓冲时，限制在响应尚未完全读入时、可向客户端发送响应的 busy 缓冲区总大小。其余缓冲区可用于读响应，必要时将部分响应缓冲至临时文件。默认上限约为 fastcgi_buffer_size 与 fastcgi_buffers 所设两个缓冲区的大小。

fastcgi_cache¶

Syntax: fastcgi_cache zone | off;
Default: fastcgi_cache off;
Context: http, server, location
@Since: None

定义用于缓存的共享内存区。同一 zone 可在多处使用。参数值可含变量（1.7.9）。参数 off 禁用从上一级继承的缓存。

fastcgi_cache_background_update¶

Syntax: fastcgi_cache_background_update on | off;
Default: fastcgi_cache_background_update off;
Context: http, server, location
@Since: 1.11.10

允许在向客户端返回过期缓存项的同时，启动后台子请求更新该项。须同时允许在更新过程中使用 stale 缓存响应。

fastcgi_cache_bypass¶

Syntax: fastcgi_cache_bypass string ...;
Default: —
Context: http, server, location
@Since: None

定义不从缓存取响应的条件。若任一字串参数值非空且不等于 “0”，则不从缓存取响应：

fastcgi_cache_key¶

Syntax: fastcgi_cache_key string;
Default: —
Context: http, server, location
@Since: None

定义缓存键，例如

fastcgi_cache_lock¶

Syntax: fastcgi_cache_lock on | off;
Default: fastcgi_cache_lock off;
Context: http, server, location
@Since: 1.1.12

启用时，按 fastcgi_cache_key 标识的新缓存项同一时刻仅允许一个请求向 FastCGI 服务器填充。同键其他请求将等待缓存中出现响应或锁释放，最长 fastcgi_cache_lock_timeout。

fastcgi_cache_lock_age¶

Syntax: fastcgi_cache_lock_age time;
Default: fastcgi_cache_lock_age 5s;
Context: http, server, location
@Since: 1.7.8

若填充新缓存项的最后一条发往 FastCGI 的请求在指定时间内未完成，可再向 FastCGI 发送一条请求。

fastcgi_cache_lock_timeout¶

Syntax: fastcgi_cache_lock_timeout time;
Default: fastcgi_cache_lock_timeout 5s;
Context: http, server, location
@Since: 1.1.12

设置 fastcgi_cache_lock 超时。超时后请求仍会发往 FastCGI，但响应不会写入缓存。

fastcgi_cache_max_range_offset¶

Syntax: fastcgi_cache_max_range_offset number;
Default: —
Context: http, server, location
@Since: 1.11.6

设置字节范围（byte-range）请求的偏移上限（字节）。若请求范围超出该偏移，范围请求将发往 FastCGI 服务器且响应不会被缓存。

fastcgi_cache_methods¶

Syntax: fastcgi_cache_methods GET | HEAD | POST ...;
Default: fastcgi_cache_methods GET HEAD;
Context: http, server, location
@Since: 0.7.59

若客户端请求方法列在本指令中，则缓存响应。“GET” 与 “HEAD” 始终加入列表，仍建议显式写出。另见 fastcgi_no_cache。

fastcgi_cache_min_uses¶

Syntax: fastcgi_cache_min_uses number;
Default: fastcgi_cache_min_uses 1;
Context: http, server, location
@Since: None

设置响应被缓存前需收到的请求次数。

fastcgi_cache_path¶

Syntax: fastcgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default: —
Context: http
@Since: None

设置 FastCGI 缓存路径及其他参数。缓存数据存于文件；键与文件名均为对被代理 URL 做 MD5 的结果。levels 定义缓存目录层级（1–3 级，每级取值 1 或 2）。例如下列配置

Note

keys_zone 须覆盖活跃键元数据；max_size、inactive 与磁盘 min_free 需与 PHP/应用响应大小、QPS 一并规划。

fastcgi_cache_purge¶

Syntax: fastcgi_cache_purge string ...;
Default: —
Context: http, server, location
@Since: 1.5.7

定义将请求视为缓存清除（purge）请求的条件。若字符串参数中至少有一个值非空且不等于 “0”，则删除对应缓存键的缓存项。成功时返回 204（No Content）。

fastcgi_cache_revalidate¶

Syntax: fastcgi_cache_revalidate on | off;
Default: fastcgi_cache_revalidate off;
Context: http, server, location
@Since: 1.5.7

启用后，对过期缓存项使用带 “If-Modified-Since” 与 “If-None-Match” 头的条件请求进行再验证。

fastcgi_cache_use_stale¶

Syntax: fastcgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off ...;
Default: fastcgi_cache_use_stale off;
Context: http, server, location
@Since: None

确定在与 FastCGI 服务器通信出错时，哪些情况下可使用陈旧缓存响应。本指令参数与 fastcgi_next_upstream 相同。

fastcgi_cache_valid¶

Syntax: fastcgi_cache_valid [code ...] time;
Default: —
Context: http, server, location
@Since: None

为不同响应码设置缓存时间。例如下列指令

fastcgi_catch_stderr¶

Syntax: fastcgi_catch_stderr string;
Default: —
Context: http, server, location
@Since: None

设置用于在 FastCGI 服务器响应 错误流 中搜索的字符串。若找到该字符串，则视为 FastCGI 返回无效响应，便于在 nginx 侧处理应用错误，例如：

fastcgi_connect_timeout¶

Syntax: fastcgi_connect_timeout time;
Default: fastcgi_connect_timeout 60s;
Context: http, server, location
@Since: None

定义与 FastCGI 服务器 建立连接 的超时。通常该值不能超过 75 秒。

fastcgi_force_ranges¶

Syntax: fastcgi_force_ranges on | off;
Default: fastcgi_force_ranges off;
Context: http, server, location
@Since: 1.7.7

无论 FastCGI 响应是否含 “Accept-Ranges” 头，均为缓存与未缓存响应启用字节范围（byte-range）支持。

fastcgi_hide_header¶

Syntax: fastcgi_hide_header field;
Default: —
Context: http, server, location
@Since: None

默认情况下，nginx 不会将 FastCGI 响应中的 “Status” 与 “X-Accel-...” 头传给客户端。fastcgi_hide_header 可追加不传递的头字段。若需允许传递，可使用 fastcgi_pass_header。

fastcgi_ignore_client_abort¶

Syntax: fastcgi_ignore_client_abort on | off;
Default: fastcgi_ignore_client_abort off;
Context: http, server, location
@Since: None

决定客户端未等待响应即断开时，是否同时关闭与 FastCGI 服务器的连接。

fastcgi_ignore_headers¶

Syntax: fastcgi_ignore_headers field ...;
Default: —
Context: http, server, location
@Since: None

禁用对 FastCGI 服务器响应中某些头字段的处理。可忽略：“X-Accel-Redirect”、“X-Accel-Expires”、“X-Accel-Limit-Rate”（1.1.6）、“X-Accel-Buffering”（1.1.6）、“X-Accel-Charset”（1.1.6）、“Expires”、“Cache-Control”、“Set-Cookie”（0.8.44）、“Vary”（1.7.7）。

fastcgi_index¶

Syntax: fastcgi_index name;
Default: —
Context: http, server, location
@Since: None

设置当 URI 以斜杠结尾时，追加到 $fastcgi_script_name 中的文件名。例如下列配置

fastcgi_intercept_errors¶

Syntax: fastcgi_intercept_errors on | off;
Default: fastcgi_intercept_errors off;
Context: http, server, location
@Since: None

决定 FastCGI 响应码 ≥ 300 时直接返回客户端，还是由 nginx 拦截并通过 error_page 处理。

fastcgi_keep_conn¶

Syntax: fastcgi_keep_conn on | off;
Default: fastcgi_keep_conn off;
Context: http, server, location
@Since: 1.1.4

默认 FastCGI 服务器发送响应后即关闭连接。设为 on 时，nginx 指示 FastCGI 保持连接，对 FastCGI keepalive 尤为重要。

fastcgi_limit_rate¶

Syntax: fastcgi_limit_rate rate;
Default: fastcgi_limit_rate 0;
Context: http, server, location
@Since: 1.7.7

限制从 FastCGI 服务器读取响应的速率（字节/秒）。0 表示不限速。限速按 单请求 计；若同时打开两条 FastCGI 连接，总速率约为设定值的两倍。仅当启用 FastCGI 响应缓冲时生效。参数值可含变量（1.27.0）。

fastcgi_max_temp_file_size¶

Syntax: fastcgi_max_temp_file_size size;
Default: fastcgi_max_temp_file_size 1024m;
Context: http, server, location
@Since: None

启用 FastCGI 响应缓冲且整段响应无法放入 fastcgi_buffer_size 与 fastcgi_buffers 时，部分响应可写入临时文件。本指令设置临时文件最大尺寸；单次写入量由 fastcgi_temp_file_write_size 控制。

fastcgi_next_upstream¶

Syntax: fastcgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default: fastcgi_next_upstream error timeout;
Context: http, server, location
@Since: None

指定在哪些情况下将请求转发至下一台服务器：

fastcgi_next_upstream_timeout¶

Syntax: fastcgi_next_upstream_timeout time;
Default: fastcgi_next_upstream_timeout 0;
Context: http, server, location
@Since: 1.7.5

限制可将请求转发至下一台服务器的最长时间。0 表示不限制。

fastcgi_next_upstream_tries¶

Syntax: fastcgi_next_upstream_tries number;
Default: fastcgi_next_upstream_tries 0;
Context: http, server, location
@Since: 1.7.5

限制转发至下一台服务器的最大尝试次数。0 表示不限制。

fastcgi_no_cache¶

Syntax: fastcgi_no_cache string ...;
Default: —
Context: http, server, location
@Since: None

定义不将响应写入缓存的条件。若任一字串参数值非空且不等于 “0”，则不保存：

fastcgi_param¶

Syntax: fastcgi_param parameter value [if_not_empty];
Default: —
Context: http, server, location
@Since: None

设置应传给 FastCGI 服务器的参数。值可含文本、变量及其组合。仅当当前层级未定义任何 fastcgi_param 时，才从上一级继承。

fastcgi_pass¶

Syntax: fastcgi_pass address;
Default: —
Context: location, if in location
@Since: None

设置 FastCGI 服务器地址，可为域名或 IP，并可选端口：

Note

常与 fastcgi_param SCRIPT_FILENAME 配合；指向 upstream 时使用 fastcgi_pass upstream_name;。修改后须 nginx -t 验证。

fastcgi_pass_header¶

Syntax: fastcgi_pass_header field;
Default: —
Context: http, server, location
@Since: None

允许传递本会被禁用的、来自 FastCGI 服务器的头字段。

fastcgi_pass_request_body¶

Syntax: fastcgi_pass_request_body on | off;
Default: fastcgi_pass_request_body on;
Context: http, server, location
@Since: None

指示是否将原始请求体转发至 FastCGI 服务器。另见 fastcgi_pass_request_headers。

fastcgi_pass_request_headers¶

Syntax: fastcgi_pass_request_headers on | off;
Default: fastcgi_pass_request_headers on;
Context: http, server, location
@Since: None

指示是否将原始请求头转发至 FastCGI 服务器。另见 fastcgi_pass_request_body。

fastcgi_read_timeout¶

Syntax: fastcgi_read_timeout time;
Default: fastcgi_read_timeout 60s;
Context: http, server, location
@Since: None

定义从 FastCGI 服务器读取响应的超时。计时仅在 两次连续读操作之间 ，而非整段响应传输。若在此时间内 FastCGI 未发送任何数据，则关闭连接。

Note

PHP/长耗时脚本场景常需调大本项（如 300s），并与 fastcgi_send_timeout 一并评估。

fastcgi_request_buffering¶

Syntax: fastcgi_request_buffering on | off;
Default: fastcgi_request_buffering on;
Context: http, server, location
@Since: 1.7.11

启用或禁用对客户端请求体的缓冲。

fastcgi_send_lowat¶

Syntax: fastcgi_send_lowat size;
Default: fastcgi_send_lowat 0;
Context: http, server, location
@Since: None

设为非零值时，nginx 将尝试通过 kqueue 的 NOTE_LOWAT 标志或 SO_SNDLOWAT 套接字选项（指定大小）减少向 FastCGI 出站连接的发送次数。

fastcgi_send_timeout¶

Syntax: fastcgi_send_timeout time;
Default: fastcgi_send_timeout 60s;
Context: http, server, location
@Since: None

设置向 FastCGI 服务器传输请求的超时。计时仅在 两次连续写操作之间 ，而非整段请求传输。若在此时间内 FastCGI 未收到任何数据，则关闭连接。

fastcgi_socket_keepalive¶

Syntax: fastcgi_socket_keepalive on | off;
Default: fastcgi_socket_keepalive off;
Context: http, server, location
@Since: 1.15.6

配置至 FastCGI 服务器出站连接的 “TCP keepalive” 行为。默认使用操作系统套接字设置。设为 “on” 时为套接字启用 SO_KEEPALIVE 选项。

fastcgi_split_path_info¶

Syntax: fastcgi_split_path_info regex;
Default: —
Context: location
@Since: None

定义用于捕获 $fastcgi_path_info 的正则表达式。正则须含两个捕获组：第一个赋给 $fastcgi_script_name，第二个赋给 $fastcgi_path_info。例如下列配置

fastcgi_store¶

Syntax: fastcgi_store on | off | string;
Default: fastcgi_store off;
Context: http, server, location
@Since: None

启用将文件保存至磁盘。参数 on 时按 alias 或 root 对应路径保存；off 禁用。亦可用含变量的字符串显式指定文件名：

fastcgi_store_access¶

Syntax: fastcgi_store_access users:permissions ...;
Default: fastcgi_store_access user:rw;
Context: http, server, location
@Since: None

设置新建文件与目录的访问权限，例如：

fastcgi_temp_file_write_size¶

Syntax: fastcgi_temp_file_write_size size;
Default: fastcgi_temp_file_write_size 8k|16k;
Context: http, server, location
@Since: None

启用将 FastCGI 响应缓冲至临时文件时，限制每次写入临时文件的数据量。默认上限约为 fastcgi_buffer_size 与 fastcgi_buffers 所设两个缓冲区的大小。临时文件最大尺寸由 fastcgi_max_temp_file_size 设置。

fastcgi_temp_path¶

Syntax: fastcgi_temp_path path [level1 [level2 [level3]]];
Default: fastcgi_temp_path fastcgi_temp;
Context: http, server, location
@Since: None

定义存放从 FastCGI 服务器接收数据的临时文件目录。可在指定目录下使用最多三级子目录层次。例如下列配置

ngx_http_flv_module¶

flv¶

Syntax: flv;
Default: —
Context: location
@Since: None

在所在 location 启用本模块处理。

ngx_http_geo_module¶

geo¶

Syntax: geo [$address] $variable { ... }
Default: —
Context: http
@Since: None

描述指定变量值对客户端 IP 地址的依赖关系。默认地址取自 $remote_addr，亦可取自其他变量（0.7.27），例如：

ngx_http_geoip_module¶

geoip_country¶

Syntax: geoip_country file;
Default: —
Context: http
@Since: None

指定用于根据客户端 IP 判定国家的数据库。使用该库时可用下列变量：

geoip_city¶

Syntax: geoip_city file;
Default: —
Context: http
@Since: None

指定用于根据客户端 IP 判定国家、地区与 city 的数据库。使用该库时可用下列变量：

geoip_org¶

Syntax: geoip_org file;
Default: —
Context: http
@Since: 1.0.3

指定用于根据客户端 IP 判定组织的数据库。使用该库时可用下列变量：

geoip_proxy¶

Syntax: geoip_proxy address | CIDR;
Default: —
Context: http
@Since: 1.3.0、1.2.1

定义可信地址。请求来自可信地址时，改用 “X-Forwarded-For” 请求头中的地址。

geoip_proxy_recursive¶

Syntax: geoip_proxy_recursive on | off;
Default: geoip_proxy_recursive off;
Context: http
@Since: 1.3.0、1.2.1

禁用递归搜索时：若原始客户端地址匹配某可信地址，则使用 “X-Forwarded-For” 中 最后一个 地址。启用递归搜索时：则使用 “X-Forwarded-For” 中 最后一个不可信 地址。

ngx_http_grpc_module¶

grpc_bind¶

Syntax: grpc_bind address [transparent ] | off;
Default: —
Context: http, server, location
@Since: None

使发往 gRPC 服务器的出站连接从指定的本地 IP 地址（可选端口）发起。参数值可含变量。特殊值 off 取消从上一级继承的 grpc_bind 效果，由系统自动分配本地 IP 与端口。

grpc_buffer_size¶

Syntax: grpc_buffer_size size;
Default: grpc_buffer_size 4k|8k;
Context: http, server, location
@Since: None

设置读取 gRPC 服务器响应所用缓冲区大小。响应一经收到即同步传给客户端。

grpc_connect_timeout¶

Syntax: grpc_connect_timeout time;
Default: grpc_connect_timeout 60s;
Context: http, server, location
@Since: None

定义与 gRPC 服务器 建立连接 的超时。通常该值不能超过 75 秒。

grpc_hide_header¶

Syntax: grpc_hide_header field;
Default: —
Context: http, server, location
@Since: None

默认情况下，nginx 不会将 gRPC 响应中的 “Date”、“Server” 与 “X-Accel-...” 头传给客户端。grpc_hide_header 可追加不传递的头字段。若需允许传递，可使用 grpc_pass_header。

grpc_ignore_headers¶

Syntax: grpc_ignore_headers field ...;
Default: —
Context: http, server, location
@Since: None

禁用对 gRPC 服务器响应中某些头字段的处理。可忽略：“X-Accel-Redirect”、“X-Accel-Charset”。

grpc_intercept_errors¶

Syntax: grpc_intercept_errors on | off;
Default: grpc_intercept_errors off;
Context: http, server, location
@Since: None

决定 gRPC 响应码 ≥ 300 时直接返回客户端，还是由 nginx 拦截并通过 error_page 处理。

grpc_next_upstream¶

Syntax: grpc_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default: grpc_next_upstream error timeout;
Context: http, server, location
@Since: None

指定在哪些情况下将请求转发至下一台服务器：

grpc_next_upstream_timeout¶

Syntax: grpc_next_upstream_timeout time;
Default: grpc_next_upstream_timeout 0;
Context: http, server, location
@Since: None

限制可将请求转发至下一台服务器的最长时间。0 表示不限制。

grpc_next_upstream_tries¶

Syntax: grpc_next_upstream_tries number;
Default: grpc_next_upstream_tries 0;
Context: http, server, location
@Since: None

限制转发至下一台服务器的最大尝试次数。0 表示不限制。

grpc_pass¶

Syntax: grpc_pass address;
Default: —
Context: location, if in location
@Since: None

设置 gRPC 服务器地址，可为域名或 IP，并可选端口：

Note

gRPC 须使用 HTTP/2；常与 grpc_set_header 配合。指向 upstream 时用 grpc_pass grpc://upstream_name;。修改后须 nginx -t 验证。

grpc_pass_header¶

Syntax: grpc_pass_header field;
Default: —
Context: http, server, location
@Since: None

允许传递本会被禁用的、来自 gRPC 服务器的头字段。

grpc_read_timeout¶

Syntax: grpc_read_timeout time;
Default: grpc_read_timeout 60s;
Context: http, server, location
@Since: None

定义从 gRPC 服务器读取响应的超时。计时仅在 两次连续读操作之间 ，而非整段响应传输。若在此时间内 gRPC 未发送任何数据，则关闭连接。

grpc_send_timeout¶

Syntax: grpc_send_timeout time;
Default: grpc_send_timeout 60s;
Context: http, server, location
@Since: None

设置向 gRPC 服务器传输请求的超时。计时仅在 两次连续写操作之间 ，而非整段请求传输。若在此时间内 gRPC 未收到任何数据，则关闭连接。

grpc_set_header¶

Syntax: grpc_set_header field value;
Default: grpc_set_header Content-Length $content_length;
Context: http, server, location
@Since: None

允许重定义或追加转发至 gRPC 服务器的请求头。值可含文本、变量及其组合。仅当当前层级未定义任何 grpc_set_header 时，才从上一级继承。

grpc_socket_keepalive¶

Syntax: grpc_socket_keepalive on | off;
Default: grpc_socket_keepalive off;
Context: http, server, location
@Since: 1.15.6

配置至 gRPC 服务器出站连接的 “TCP keepalive” 行为。默认使用操作系统套接字设置。设为 “on” 时为套接字启用 SO_KEEPALIVE 选项。

grpc_ssl_certificate¶

Syntax: grpc_ssl_certificate file;
Default: —
Context: http, server, location
@Since: None

指定用于向 gRPC SSL 服务器认证的 PEM 格式证书文件。

grpc_ssl_certificate_cache¶

Syntax: grpc_ssl_certificate_cache off; grpc_ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: grpc_ssl_certificate_cache off;
Context: http, server, location
@Since: 1.27.4

定义缓存，用于存放以变量指定的 SSL 证书与私钥。

grpc_ssl_certificate_key¶

Syntax: grpc_ssl_certificate_key file;
Default: —
Context: http, server, location
@Since: None

指定用于向 gRPC SSL 服务器认证的 PEM 格式私钥文件。

grpc_ssl_ciphers¶

Syntax: grpc_ssl_ciphers ciphers;
Default: grpc_ssl_ciphers DEFAULT;
Context: http, server, location
@Since: None

指定访问 gRPC SSL 服务器时启用的密码套件；格式为 OpenSSL 可识别的写法。

grpc_ssl_conf_command¶

Syntax: grpc_ssl_conf_command name value;
Default: —
Context: http, server, location
@Since: 1.19.4

在与 gRPC SSL 服务器建立连接时设置任意 OpenSSL 配置命令。

grpc_ssl_crl¶

Syntax: grpc_ssl_crl file;
Default: —
Context: http, server, location
@Since: None

指定 PEM 格式吊销证书列表（CRL）文件，用于验证 gRPC SSL 服务器证书。

grpc_ssl_key_log¶

Syntax: grpc_ssl_key_log path;
Default: —
Context: http, server, location
@Since: 1.27.2

启用 gRPC SSL 连接密钥日志，并指定密钥日志文件路径。密钥以与 Wireshark 兼容的 SSLKEYLOGFILE 格式记录。

grpc_ssl_name¶

Syntax: grpc_ssl_name name;
Default: grpc_ssl_name host from grpc_pass;
Context: http, server, location
@Since: None

允许覆盖用于验证 gRPC SSL 服务器证书的服务器名，以及通过 SNI 建立连接时传递的名称。

grpc_ssl_password_file¶

Syntax: grpc_ssl_password_file file;
Default: —
Context: http, server, location
@Since: None

指定私钥口令文件，每行一个口令；加载密钥时依次尝试。

grpc_ssl_protocols¶

Syntax: grpc_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: grpc_ssl_protocols TLSv1.2 TLSv1.3;
Context: http, server, location
@Since: None

启用访问 gRPC SSL 服务器时允许的协议。

grpc_ssl_server_name¶

Syntax: grpc_ssl_server_name on | off;
Default: grpc_ssl_server_name off;
Context: http, server, location
@Since: None

启用或禁用在与 gRPC SSL 服务器建立连接时通过 TLS 服务器名称指示（SNI，RFC 6066）传递服务器名。

grpc_ssl_session_reuse¶

Syntax: grpc_ssl_session_reuse on | off;
Default: grpc_ssl_session_reuse on;
Context: http, server, location
@Since: None

确定是否可复用与 gRPC 服务器通信时的 SSL 会话。若日志出现 “digest check failed”，可尝试关闭会话复用。

grpc_ssl_trusted_certificate¶

Syntax: grpc_ssl_trusted_certificate file;
Default: —
Context: http, server, location
@Since: None

指定 PEM 格式可信 CA 证书文件，用于验证 gRPC SSL 服务器证书。

grpc_ssl_verify¶

Syntax: grpc_ssl_verify on | off;
Default: grpc_ssl_verify off;
Context: http, server, location
@Since: None

启用或禁用对 gRPC SSL 服务器证书的验证。

Note

生产环境访问 TLS gRPC 后端应启用 grpc_ssl_verify on 并配置 grpc_ssl_trusted_certificate；内网自签场景亦须显式信任 CA，勿长期依赖默认 off。

grpc_ssl_verify_depth¶

Syntax: grpc_ssl_verify_depth number;
Default: grpc_ssl_verify_depth 1;
Context: http, server, location
@Since: None

设置 gRPC SSL 服务器证书链的验证深度。

ngx_http_gunzip_module¶

gunzip¶

Syntax: gunzip on | off;
Default: gunzip off;
Context: http, server, location
@Since: None

对不支持 gzip 的客户端启用或禁用对已 gzip 压缩响应的解压。启用时，判定客户端是否支持 gzip 还会参考 gzip_http_version、gzip_proxied、gzip_disable。另见 gzip_vary。

gunzip_buffers¶

Syntax: gunzip_buffers number size;
Default: gunzip_buffers 32 4k|16 8k;
Context: http, server, location
@Since: None

设置解压响应所用缓冲区的数量与大小。默认单缓冲等于一个内存页，平台相关为 4K 或 8K。

ngx_http_gzip_module¶

gzip¶

Syntax: gzip on | off;
Default: gzip off;
Context: http, server, location, if in location
@Since: None

启用或禁用对响应的 gzip 压缩。

Note

生产环境通常开启 gzip on，并配合 gzip_types 覆盖 application/json、text/css、application/javascript 等；高 CPU 场景可调低 gzip_comp_level（默认 1 已偏保守）。

gzip_buffers¶

Syntax: gzip_buffers number size;
Default: gzip_buffers 32 4k|16 8k;
Context: http, server, location
@Since: None

设置压缩响应所用缓冲区的数量与大小。默认单缓冲等于一个内存页，平台相关为 4K 或 8K。

gzip_comp_level¶

Syntax: gzip_comp_level level;
Default: gzip_comp_level 1;
Context: http, server, location
@Since: None

设置响应 gzip 压缩级别，取值范围 1–9。

gzip_disable¶

Syntax: gzip_disable regex ...;
Default: —
Context: http, server, location
@Since: 0.6.23

对 “User-Agent” 头匹配任一指定正则的请求禁用 gzip 压缩。

gzip_http_version¶

Syntax: gzip_http_version 1.0 | 1.1;
Default: gzip_http_version 1.1;
Context: http, server, location
@Since: None

设置允许压缩响应所需的请求最低 HTTP 版本。

gzip_min_length¶

Syntax: gzip_min_length length;
Default: gzip_min_length 20;
Context: http, server, location
@Since: None

设置将被 gzip 压缩的响应最小长度；长度仅根据 “Content-Length” 响应头判定。

gzip_proxied¶

Syntax: gzip_proxied off | expired | no-cache | no-store | private | no_last_modified | no_etag | auth | any ...;
Default: gzip_proxied off;
Context: http, server, location
@Since: None

根据请求与响应，对代理请求启用或禁用 gzip。是否代理由 “Via” 请求头是否存在判定。本指令可接受多个参数：

gzip_types¶

Syntax: gzip_types mime-type ...;
Default: gzip_types text/html;
Context: http, server, location
@Since: None

除 “text/html” 外，还对指定 MIME 类型的响应启用 gzip。特殊值 “” 匹配任意 MIME 类型（0.8.29）。“text/html” 类型响应 **始终* 压缩。

gzip_vary¶

Syntax: gzip_vary on | off;
Default: gzip_vary off;
Context: http, server, location
@Since: None

当 gzip、gzip_static 或 gunzip 生效时，启用或禁用插入 “Vary: Accept-Encoding” 响应头。

ngx_http_gzip_static_module¶

gzip_static¶

Syntax: gzip_static on | off | always;
Default: gzip_static off;
Context: http, server, location
@Since: None

启用（on）或禁用（off）检查预压缩文件（如 .gz）是否存在。还会参考 gzip_http_version、gzip_proxied、gzip_disable、gzip_vary。

Note

静态资源构建阶段预压缩 + gzip_static on 可显著降低在线 CPU；always 可在无 Accept-Encoding: gzip 时也服务 .gz 文件（须确保客户端能处理）。

ngx_http_headers_module¶

add_header¶

Syntax: add_header name value [always];
Default: —
Context: http, server, location, if in location
@Since: None

在响应码为 200、201（1.3.10）、204、206、301、302、303、304、307（1.1.16、1.0.13）或 308（1.13.0）时，向响应头追加指定字段。参数值可含变量。

Note

默认不对 4xx/5xx 追加头；安全头（如 X-Frame-Options）在错误页也需出现时须加 always 参数。

add_trailer¶

Syntax: add_trailer name value [always];
Default: —
Context: http, server, location, if in location
@Since: 1.13.2

在响应码为 200、201、206、301、302、303、307 或 308 时，向响应尾部追加指定字段。参数值可含变量。

expires¶

Syntax: expires [modified] time; expires epoch | max | off;
Default: expires off;
Context: http, server, location, if in location
@Since: None

在响应码为 200、201（1.3.10）、204、206、301、302、303、304、307（1.1.16、1.0.13）或 308（1.13.0）时，启用或禁用添加/修改 “Expires” 与 “Cache-Control” 响应头。参数可为正或负时间值。

ngx_http_hls_module¶

hls¶

Syntax: hls;
Default: —
Context: location
@Since: None

在所在 location 启用 HLS 流媒体。

hls_buffers¶

Syntax: hls_buffers number size;
Default: hls_buffers 8 2m;
Context: http, server, location
@Since: None

设置用于读写数据帧的缓冲区最大数量与大小。

hls_forward_args¶

Syntax: hls_forward_args on | off;
Default: hls_forward_args off;
Context: http, server, location
@Since: 1.5.12

将播放列表请求中的参数追加到分片 URI。可用于在请求分片时做客户端授权，或与 ngx_http_secure_link_module 配合保护 HLS 流。

hls_fragment¶

Syntax: hls_fragment time;
Default: hls_fragment 5s;
Context: http, server, location
@Since: None

定义未带 “len” 参数的播放列表 URI 的默认分片时长。

hls_mp4_buffer_size¶

Syntax: hls_mp4_buffer_size size;
Default: hls_mp4_buffer_size 512k;
Context: http, server, location
@Since: None

设置处理 MP4 与 MOV 文件所用缓冲区的初始大小。

hls_mp4_max_buffer_size¶

Syntax: hls_mp4_max_buffer_size size;
Default: hls_mp4_max_buffer_size 10m;
Context: http, server, location
@Since: None

处理元数据时可能需要更大缓冲区。其大小不得超过指定值，否则 nginx 返回 500（Internal Server Error）并记录如下消息：

ngx_http_image_filter_module¶

image_filter¶

Syntax: image_filter off; image_filter test; image_filter size; image_filter rotate 90 | 180 | 270; image_filter resize width height; image_filter crop width height;
Default: image_filter off;
Context: location
@Since: None

设置对图像执行的变换类型：

Warning

image_filter 在 worker 内同步处理图像，高 QPS 或大图会显著占用 CPU/内存；生产环境优先用 CDN/独立图像服务，或严格限制来源与尺寸。

image_filter_buffer¶

Syntax: image_filter_buffer size;
Default: image_filter_buffer 1M;
Context: http, server, location
@Since: None

设置读取图像所用缓冲区的最大大小。超出时服务器返回 415（Unsupported Media Type）。

image_filter_interlace¶

Syntax: image_filter_interlace on | off;
Default: image_filter_interlace off;
Context: http, server, location
@Since: 1.3.15

启用时，输出图像为隔行扫描。对 JPEG，输出为 “progressive JPEG” 格式。

image_filter_jpeg_quality¶

Syntax: image_filter_jpeg_quality quality;
Default: image_filter_jpeg_quality 75;
Context: http, server, location
@Since: None

设置输出 JPEG 的目标质量。可接受值为 1–100；值越低通常画质越差、传输数据越少。建议最高不超过 95。参数值可含变量。

image_filter_sharpen¶

Syntax: image_filter_sharpen percent;
Default: image_filter_sharpen 0;
Context: http, server, location
@Since: None

提高输出图像锐度。锐度百分比可超过 100。0 禁用锐化。参数值可含变量。

image_filter_transparency¶

Syntax: image_filter_transparency on|off;
Default: image_filter_transparency on;
Context: http, server, location
@Since: None

定义变换 GIF 或使用调色板 PNG 时是否保留透明。放弃透明可得到更高画质。PNG 的 alpha 通道透明始终保留。

image_filter_webp_quality¶

Syntax: image_filter_webp_quality quality;
Default: image_filter_webp_quality 80;
Context: http, server, location
@Since: 1.11.6

设置输出 WebP 的目标质量。可接受值为 1–100；值越低通常画质越差、传输数据越少。参数值可含变量。

ngx_http_index_module¶

index¶

Syntax: index file ...;
Default: index index.html;
Context: http, server, location
@Since: None

定义用作索引页的文件名。文件名可含变量；按所列顺序检查。列表最后一项可为绝对路径文件。示例：

ngx_http_internal_redirect_module¶

internal_redirect¶

Syntax: internal_redirect uri;
Default: —
Context: server, location
@Since: None

设置请求内部重定向的目标 URI；亦可用命名 location 代替 URI。uri 可含变量；为空则不重定向。

ngx_http_js_module¶

js_body_filter¶

Syntax: js_body_filter function | module.function [buffer_type=string | buffer];
Default: —
Context: location, if in location, limit_except
@Since: 0.5.2

将 njs 函数设为响应体过滤器。过滤器对每个响应体数据块调用，参数如下：

js_content¶

Syntax: js_content function | module.function;
Default: —
Context: location, if in location, limit_except
@Since: None

将 njs 函数设为 location 内容处理程序。自 0.4.0 起可引用模块函数。

js_context_reuse¶

Syntax: js_context_reuse number;
Default: js_context_reuse 128;
Context: http, server, location
@Since: 0.8.6

设置 QuickJS 引擎可复用的 JS 上下文最大数量。每个上下文服务单个请求；完成后放入可复用池，池满则销毁。

js_engine¶

Syntax: js_engine njs | qjs;
Default: js_engine njs;
Context: http, server, location
@Since: 0.8.6

设置 njs 脚本使用的 JavaScript 引擎。njs 为默认 njs 引擎；qjs 为 QuickJS 引擎。

js_fetch_buffer_size¶

Syntax: js_fetch_buffer_size size;
Default: js_fetch_buffer_size 16k;
Context: http, server, location
@Since: 0.7.4

设置 Fetch API 读写所用缓冲区大小。

js_fetch_ciphers¶

Syntax: js_fetch_ciphers ciphers;
Default: js_fetch_ciphers HIGH:!aNULL:!MD5;
Context: http, server, location
@Since: 0.7.0

指定 Fetch API HTTPS 请求启用的密码套件；格式为 OpenSSL 可识别的写法。

js_fetch_max_response_buffer_size¶

Syntax: js_fetch_max_response_buffer_size size;
Default: js_fetch_max_response_buffer_size 1m;
Context: http, server, location
@Since: 0.7.4

设置 Fetch API 接收响应的最大大小。

js_fetch_protocols¶

Syntax: js_fetch_protocols [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;
Context: http, server, location
@Since: 0.7.0

启用 Fetch API HTTPS 请求允许的协议。

js_fetch_timeout¶

Syntax: js_fetch_timeout time;
Default: js_fetch_timeout 60s;
Context: http, server, location
@Since: 0.7.4

定义 Fetch API 读写的超时。超时仅在两次连续读/写操作之间计时，而非整段响应。若在此时间内无数据传输，则关闭连接。

js_fetch_trusted_certificate¶

Syntax: js_fetch_trusted_certificate file;
Default: —
Context: http, server, location
@Since: 0.7.0

指定 PEM 格式可信 CA 证书文件，用于验证 Fetch API 的 HTTPS 证书。

js_fetch_verify¶

Syntax: js_fetch_verify on | off;
Default: js_fetch_verify on;
Context: http, server, location
@Since: 0.7.4

启用或禁用 Fetch API 对 HTTPS 服务器证书的验证。

Note

njs 通过 Fetch 访问外部 HTTPS 时，生产环境应保持 js_fetch_verify on 并配置 js_fetch_trusted_certificate。

js_fetch_verify_depth¶

Syntax: js_fetch_verify_depth number;
Default: js_fetch_verify_depth 100;
Context: http, server, location
@Since: 0.7.0

设置 Fetch API HTTPS 服务器证书链的验证深度。

js_header_filter¶

Syntax: js_header_filter function | module.function;
Default: —
Context: location, if in location, limit_except
@Since: 0.5.1

将 njs 函数设为响应头过滤器；可修改响应头中的任意头字段。

js_import¶

Syntax: js_import module.js | export_name from module.js;
Default: —
Context: http, server, location
@Since: 0.4.0

导入实现 location 与变量处理程序的 njs 模块。export_name 用作访问模块函数的命名空间；未指定时以模块名为命名空间。

js_include¶

Syntax: js_include file;
Default: —
Context: http
@Since: None

指定实现 location 与变量处理程序的 njs 文件：

js_path¶

Syntax: js_path path;
Default: —
Context: http, server, location
@Since: 0.3.0

设置 njs 模块的附加搜索路径。

js_periodic¶

Syntax: js_periodic function | module.function [interval=time] [jitter=number] [worker_affinity=mask];
Default: —
Context: location
@Since: 0.8.1

指定按固定间隔运行的内容处理程序。处理程序以 session 对象为第一参数，并可访问 ngx 等全局对象。

js_preload_object¶

Syntax: js_preload_object name.json | name from file.json;
Default: —
Context: http, server, location
@Since: 0.7.8

在配置阶段预加载不可变对象。name 作为 njs 代码中访问该对象的全局变量名；未指定时使用文件名。

js_set¶

Syntax: js_set $variable function | module.function [nocache];
Default: —
Context: http, server, location
@Since: None

为指定变量设置 njs 函数。自 0.4.0 起可引用模块函数。

js_shared_dict_zone¶

Syntax: js_shared_dict_zone zone=name:size [timeout=time] [type=string|number] [evict] [state=file];
Default: —
Context: http
@Since: 0.8.0

设置 worker 进程间共享键值字典的共享内存区名称与大小。

js_var¶

Syntax: js_var $variable [value];
Default: —
Context: http, server, location
@Since: 0.5.3

声明可写变量。值可含文本、变量及其组合。与 set 创建的变量不同，重定向后不会被覆盖。

ngx_http_keyval_module¶

keyval¶

Syntax: keyval key $variable zone=name;
Default: —
Context: http
@Since: None

创建新变量 $variable，其值由键在键值数据库中查得。匹配规则由 keyval_zone 的 type 参数定义。数据库存于 zone 参数指定的共享内存区。

keyval_zone¶

Syntax: keyval_zone zone=name:size [state=file] [timeout=time] [type=string|ip|prefix] [sync];
Default: —
Context: http
@Since: None

设置保存键值数据库的共享内存区名称与大小。键值对由 API 管理。

ngx_http_limit_conn_module¶

limit_conn¶

Syntax: limit_conn zone number;
Default: —
Context: http, server, location
@Since: None

设置共享内存区及给定键值允许的最大连接数。超出限制时，服务器将返回错误响应。例如指令

Note

须先在 http 块配置 limit_conn_zone，再于 server/location 使用 limit_conn；按 $binary_remote_addr 限连接是常见防刷/防 CC 手段。

limit_conn_dry_run¶

Syntax: limit_conn_dry_run on | off;
Default: limit_conn_dry_run off;
Context: http, server, location
@Since: 1.17.6

启用 dry run（试运行）模式：不实际限连，但在共享内存区仍照常统计超额连接数。

limit_conn_log_level¶

Syntax: limit_conn_log_level info | notice | warn | error;
Default: limit_conn_log_level error;
Context: http, server, location
@Since: 0.8.18

设置因连接数受限而触发限流时的日志级别。

limit_conn_status¶

Syntax: limit_conn_status code;
Default: limit_conn_status 503;
Context: http, server, location
@Since: 1.3.15

设置拒绝请求时返回的 HTTP 状态码。

limit_conn_zone¶

Syntax: limit_conn_zone key zone=name:size;
Default: —
Context: http
@Since: None

设置用于保存各键状态的共享内存区参数；状态含当前连接数。键可含文本、变量及其组合。键值为空的请求不计入。

limit_zone¶

Syntax: limit_zone name $variable size;
Default: —
Context: http
@Since: None

该指令在 1.1.8 已废弃，1.7.6 已移除。应改用语法变更后的等效指令 limit_conn_zone：

ngx_http_limit_req_module¶

limit_req¶

Syntax: limit_req zone=name [burst=number] [nodelay | delay=number];
Default: —
Context: http, server, location
@Since: None

设置共享内存区及请求最大突发（burst）大小。若请求速率超过 zone 配置，处理将被延迟以维持定义速率；超额请求延迟排队，直至超过最大 burst 则以错误终止。默认 burst 为 0。例如指令

Note

API 防刷常用 limit_req_zone ... rate=10r/s + limit_req zone=one burst=20 nodelay；burst 与 nodelay/delay 组合决定排队还是立即 503。

limit_req_dry_run¶

Syntax: limit_req_dry_run on | off;
Default: limit_req_dry_run off;
Context: http, server, location
@Since: 1.17.1

启用 dry run 模式：不实际限速，但在共享内存区仍统计超额请求数。

limit_req_log_level¶

Syntax: limit_req_log_level info | notice | warn | error;
Default: limit_req_log_level error;
Context: http, server, location
@Since: 0.8.18

设置因超速拒绝或延迟处理请求时的日志级别。延迟的日志级别比拒绝低一级；例如指定 limit_req_log_level notice 时，延迟以 info 级别记录。

limit_req_status¶

Syntax: limit_req_status code;
Default: limit_req_status 503;
Context: http, server, location
@Since: 1.3.15

设置拒绝请求时返回的 HTTP 状态码。

limit_req_zone¶

Syntax: limit_req_zone key zone=name:size rate=rate [sync];
Default: —
Context: http
@Since: None

设置用于保存各键状态的共享内存区参数；状态保存当前超额请求数。键可含文本、变量及其组合。键值为空的请求不计入。

ngx_http_log_module¶

access_log¶

Syntax: access_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]]; access_log off;
Default: access_log logs/access.log combined;
Context: http, server, location, if in location, limit_except
@Since: None

设置缓冲写访问日志的路径、格式与选项。同一配置层级可指定多条日志。首参数以 “syslog:” 开头可写入 syslog。特殊值 off 取消当前层级全部 access_log。未指定格式时使用预定义 “combined”。

Note

生产环境建议独立 log_format（含 $request_time、$upstream_response_time），并按域名/应用分 access_log；高 QPS 可配 buffer= 与 flush=，日志盘须纳入轮转与监控。

log_format¶

Syntax: log_format name [escape=default|json|none] string ...;
Default: log_format combined "...";
Context: http
@Since: None

定义日志格式。

Note

过少字段 ：缺 $upstream_response_time / $request_time → 故障无法区分客户端与上游耗时。
过多/敏感 ：记录完整 Cookie/PII → 合规与磁盘风险。
常见写法 ：log_format main_ext '… rt=$request_time urt=$upstream_response_time uaddr=$upstream_addr';（按合规裁剪字段）。
关联：高 QPS 下 access_log 的 buffer= / flush=。

open_log_file_cache¶

Syntax: open_log_file_cache max=N [inactive=time] [min_uses=N] [valid=time]; open_log_file_cache off;
Default: open_log_file_cache off;
Context: http, server, location
@Since: None

定义缓存，用于保存名称含变量的、频繁使用的日志文件描述符。本指令参数如下：

ngx_http_map_module¶

map¶

Syntax: map string $variable { ... }
Default: —
Context: http
@Since: None

创建新变量，其值取决于第一个参数所指定的一个或多个源变量的值。

Note

误用：无谓超大 map → 内存；过复杂 map 不如拆 location。
优先替代 ：复杂 if 做 host/scheme 规范化、特性开关、A/B 分桶。
常见写法 ：在 http 定义 map $http_host $canonical_host { … }——排查时在 access_log 打 $canonical_host。
关联：split_clients、geo。

map_hash_bucket_size¶

Syntax: map_hash_bucket_size size;
Default: map_hash_bucket_size 32|64|128;
Context: http
@Since: None

设置 map 变量哈希表桶大小。默认值取决于处理器缓存行大小。哈希表配置详见文档。

map_hash_max_size¶

Syntax: map_hash_max_size size;
Default: map_hash_max_size 2048;
Context: http
@Since: None

设置 map 变量哈希表最大尺寸。哈希表配置详见文档。

ngx_http_memcached_module¶

memcached_bind¶

Syntax: memcached_bind address [transparent ] | off;
Default: —
Context: http, server, location
@Since: 0.8.22

使发往 memcached 服务器的出站连接从指定的本地 IP 地址（1.11.2 起可选端口）发起。参数值可含变量（1.3.12）。特殊值 off（1.3.12）取消从上一级继承的 memcached_bind 效果，由系统自动分配本地 IP 与端口。

memcached_buffer_size¶

Syntax: memcached_buffer_size size;
Default: memcached_buffer_size 4k|8k;
Context: http, server, location
@Since: None

设置用于读取 memcached 服务器响应的缓冲区大小。响应一经收到即同步传给客户端。

memcached_connect_timeout¶

Syntax: memcached_connect_timeout time;
Default: memcached_connect_timeout 60s;
Context: http, server, location
@Since: None

定义与 memcached 服务器建立连接的超时。该超时通常不得超过 75 秒。

memcached_gzip_flag¶

Syntax: memcached_gzip_flag flag;
Default: —
Context: http, server, location
@Since: 1.3.6

检测 memcached 服务器响应中的标志位；若标志已设置，则将 “Content-Encoding” 响应头设为 “gzip”。

memcached_next_upstream¶

Syntax: memcached_next_upstream error | timeout | invalid_response | not_found | off ...;
Default: memcached_next_upstream error timeout;
Context: http, server, location
@Since: None

指定在何种情况下将请求转发至下一台服务器：

memcached_next_upstream_timeout¶

Syntax: memcached_next_upstream_timeout time;
Default: memcached_next_upstream_timeout 0;
Context: http, server, location
@Since: 1.7.5

限制可将请求转发至下一台服务器的时长。0 表示不限制。

memcached_next_upstream_tries¶

Syntax: memcached_next_upstream_tries number;
Default: memcached_next_upstream_tries 0;
Context: http, server, location
@Since: 1.7.5

限制将请求转发至下一台服务器的最大尝试次数。0 表示不限制。

memcached_pass¶

Syntax: memcached_pass address;
Default: —
Context: location, if in location
@Since: None

设置 memcached 服务器地址。地址可指定为域名或 IP 及端口：

memcached_read_timeout¶

Syntax: memcached_read_timeout time;
Default: memcached_read_timeout 60s;
Context: http, server, location
@Since: None

定义从 memcached 服务器读取响应的超时。超时仅在两次连续读操作之间计时，而非整段响应传输。若 memcached 服务器在此时间内未发送任何数据，则关闭连接。

memcached_send_timeout¶

Syntax: memcached_send_timeout time;
Default: memcached_send_timeout 60s;
Context: http, server, location
@Since: None

设置向 memcached 服务器发送请求的超时。超时仅在两次连续写操作之间计时，而非整段请求传输。若 memcached 服务器在此时间内未收到任何数据，则关闭连接。

memcached_socket_keepalive¶

Syntax: memcached_socket_keepalive on | off;
Default: memcached_socket_keepalive off;
Context: http, server, location
@Since: 1.15.6

配置发往 memcached 服务器出站连接的 “TCP keepalive” 行为。默认使用操作系统对套接字的设置。设为 on 时，为套接字启用 SO_KEEPALIVE 选项。

ngx_http_mirror_module¶

mirror¶

Syntax: mirror uri | off;
Default: mirror off;
Context: http, server, location
@Since: None

设置原始请求将被镜像到的 URI。可在同一配置层级指定多条 mirror 指令。

mirror_request_body¶

Syntax: mirror_request_body on | off;
Default: mirror_request_body on;
Context: http, server, location
@Since: None

指示是否镜像客户端请求体。启用时，将在创建镜像子请求之前读取客户端请求体。此时由 proxy_request_buffering、fastcgi_request_buffering、scgi_request_buffering 与 uwsgi_request_buffering 所设的无缓冲客户端请求体代理将被禁用。

ngx_http_mp4_module¶

mp4¶

Syntax: mp4;
Default: —
Context: location
@Since: None

在所在 location 启用本模块处理。

mp4_buffer_size¶

Syntax: mp4_buffer_size size;
Default: mp4_buffer_size 512K;
Context: http, server, location
@Since: None

设置处理 MP4 文件所用缓冲区的初始大小。

mp4_max_buffer_size¶

Syntax: mp4_max_buffer_size size;
Default: mp4_max_buffer_size 10M;
Context: http, server, location
@Since: None

处理元数据时可能需要更大缓冲区。其大小不得超过指定值，否则 nginx 返回 500（Internal Server Error）并记录如下消息：

mp4_limit_rate¶

Syntax: mp4_limit_rate on | off | factor;
Default: mp4_limit_rate off;
Context: http, server, location
@Since: None

限制向客户端发送响应的速率。速率基于所服务 MP4 文件的平均码率；计算时将码率乘以指定因子。特殊值 on 对应因子 1.1；off 禁用限速。限制按请求计，若客户端同时打开两条连接，总速率可达指定限制的两倍。

mp4_limit_rate_after¶

Syntax: mp4_limit_rate_after time;
Default: mp4_limit_rate_after 60s;
Context: http, server, location
@Since: None

设置初始媒体数据量（以播放时长计），超过后对客户端的后续响应传输将限速。

mp4_start_key_frame¶

Syntax: mp4_start_key_frame on | off;
Default: mp4_start_key_frame off;
Context: http, server, location
@Since: 1.21.4

强制输出视频始终以关键帧开始。若 start 参数未指向关键帧，则通过 mp4 edit list 隐藏初始帧。Chrome、Safari、QuickTime、ffmpeg 等主流播放器与浏览器支持 edit list；Firefox 部分支持。

ngx_http_oidc_module¶

oidc_provider¶

Syntax: oidc_provider name { ... }
Default: —
Context: http
@Since: None

定义供 auth_oidc 使用的 OpenID Provider。

auth_oidc¶

Syntax: auth_oidc name | off;
Default: auth_oidc off;
Context: http, server, location
@Since: None

使用指定 OpenID Provider 启用终端用户认证。

issuer¶

Syntax: issuer URL;
Default: —
Context: oidc_provider
@Since: None

设置 OpenID Provider 的 Issuer Identifier URL；必填。URL 须与 Provider 元数据中 issuer 完全一致，且须为 https 方案。

client_id¶

Syntax: client_id string;
Default: —
Context: oidc_provider
@Since: None

指定 Relying Party 的 client ID；必填。

client_secret¶

Syntax: client_secret string;
Default: —
Context: oidc_provider
@Since: None

指定用于向 OpenID Provider 认证 Relying Party 的密钥。

config_url¶

Syntax: config_url URL;
Default: config_url <issuer>/.well-known/openid-configuration;
Context: oidc_provider
@Since: None

设置获取 OpenID Provider 元数据的自定义 URL。

cookie_name¶

Syntax: cookie_name name;
Default: cookie_name NGX_OIDC_SESSION;
Context: oidc_provider
@Since: None

设置 session cookie 名称。

extra_auth_args¶

Syntax: extra_auth_args string;
Default: —
Context: oidc_provider
@Since: None

设置认证请求 URL 的附加查询参数。

redirect_uri¶

Syntax: redirect_uri uri;
Default: redirect_uri /oidc_callback;
Context: oidc_provider
@Since: None

定义模块期望 OpenID Provider 在认证后重定向的 URI 路径。uri 须与 Provider 侧配置一致。

scope¶

Syntax: scope scope ...;
Default: scope openid;
Context: oidc_provider
@Since: None

设置请求的 scope。OIDC 始终需要 openid scope。

session_store¶

Syntax: session_store name;
Default: —
Context: oidc_provider
@Since: None

指定存储 session 数据的自定义键值数据库。默认自动创建名为 oidc_default_store_<provider name> 的 8MB 键值库。

session_timeout¶

Syntax: session_timeout time;
Default: session_timeout 8h;
Context: oidc_provider
@Since: None

设置 session 超时；超时后删除 session，除非已刷新。

[oidc_provider] ssl_crl¶

Syntax: ssl_crl file;
Default: —
Context: oidc_provider
@Since: None

指定 PEM 格式吊销证书列表（CRL）文件，用于验证 OpenID Provider 端点证书。

[oidc_provider] ssl_trusted_certificate¶

Syntax: ssl_trusted_certificate file;
Default: ssl_trusted_certificate system CA bundle;
Context: oidc_provider
@Since: None

指定 PEM 格式可信 CA 证书文件，用于验证 OpenID Provider 端点证书。

Note

生产 OIDC 应显式配置 ssl_trusted_certificate（自签 IdP 须导入 CA），并保护 client_secret 与 session cookie。

ngx_http_perl_module¶

perl¶

Syntax: perl module::function|'sub { ... }';
Default: —
Context: location, limit_except
@Since: None

为给定 location 设置 Perl 处理程序。

Warning

perl 模块在 worker 内同步执行，生产环境慎用；优先 njs 或应用层实现同等逻辑。

perl_modules¶

Syntax: perl_modules path;
Default: —
Context: http
@Since: None

设置 Perl 模块的附加搜索路径。

perl_require¶

Syntax: perl_require module;
Default: —
Context: http
@Since: None

定义每次重载配置时加载的模块名。可存在多条 perl_require 指令。

perl_set¶

Syntax: perl_set $variable module::function|'sub { ... }';
Default: —
Context: http
@Since: None

为指定变量安装 Perl 处理程序。

ngx_http_proxy_module¶

proxy_bind¶

Syntax: proxy_bind address [transparent] | off;
Default: —
Context: http, server, location
@Since: 0.8.22

使发往被代理服务器的出站连接从指定的本地 IP 地址（1.11.2 起可选端口）发起。参数值可含变量（1.3.12）。特殊值 off（1.3.12）取消从上一级继承的 proxy_bind 效果，由系统自动分配本地 IP 与端口。

proxy_buffer_size¶

Syntax: proxy_buffer_size size;
Default: proxy_buffer_size 4k|8k;
Context: http, server, location
@Since: None

设置用于读取被代理服务器响应首段的缓冲区大小；该段通常含较小的响应头。默认等于一个内存页，平台相关为 4K 或 8K，亦可改小。

Note

过小：响应头过大（长 Set-Cookie、JWT）→ 502 upstream sent too big header。
过大：浪费单请求内存；且须小于 proxy_buffers 的单个槽位。
常见起点 ：默认常够用；出现 header 错误可试 16k/32k，并联动调 proxy_buffers。
关联：proxy_buffers、proxy_busy_buffers_size。

proxy_buffering¶

Syntax: proxy_buffering on | off;
Default: proxy_buffering on;
Context: http, server, location
@Since: None

启用或禁用对被代理服务器响应的缓冲。

Note

默认开启缓冲，nginx 可尽快释放上游连接并提高吞吐；SSE、长轮询、流式下载等需实时转发场景应设为 off，并配合调大 proxy_read_timeout。关闭缓冲时 proxy_limit_rate 不生效。

proxy_buffers¶

Syntax: proxy_buffers number size;
Default: proxy_buffers 8 4k|8k;
Context: http, server, location
@Since: None

设置单连接读取被代理服务器响应时缓冲区的 数量与大小 。默认单块大小等于一个内存页（平台相关 4K 或 8K）。

Note

过小/过少 ：大 JSON/HTML 易落临时文件或阻塞上游 → 延迟与磁盘 I/O。
过大/过多 ：缓冲在 正在读取上游响应体 的请求上按 单槽 × 数量 分配， 空闲 keepalive 不会占满整组 ；仅当高 QPS 且 同时大量大响应 在缓冲时，worker 内存压力才急剧上升，而非连接数一高就线性 OOM。
常见起点 ：proxy_buffers 8 16k; 仅作基线——按响应体大小与 同时缓冲中的请求峰值 调整，勿用总连接数估算。
关联：proxy_buffer_size、proxy_busy_buffers_size、proxy_buffering。

proxy_busy_buffers_size¶

Syntax: proxy_busy_buffers_size size;
Default: proxy_busy_buffers_size 8k|16k;
Context: http, server, location
@Since: None

启用对被代理服务器响应的缓冲时，限制在响应尚未完全读入时、可同时用于向客户端发送响应的缓冲区总大小。其余缓冲区可用于继续读取响应，必要时将部分响应写入临时文件。默认上限约为 proxy_buffer_size 与 proxy_buffers 所设两个缓冲区的大小之和。

Note

过小：上游仍在填缓冲时向客户端发送的 busy 区偏小 → 吞吐下降。
过大：违反与 proxy_buffers 的大小关系（须 ≤ 总容量减一槽）或不当增大内存压力。
约束：≥ proxy_buffer_size，且 ≤ proxy_buffers 总容量减一槽。
关联：proxy_buffers、proxy_buffer_size。

proxy_cache¶

Syntax: proxy_cache zone | off;
Default: proxy_cache off;
Context: http, server, location
@Since: None

定义用于缓存的共享内存区；同一 zone 可在多处使用。参数值可含变量（1.7.9）。off 关闭从上一级继承的缓存。

Note

误用：未区分用户/鉴权即缓存 → 串数据；键或 bypass 配置不当尤为危险。
缺项：仅 on 而无 proxy_cache_path、proxy_cache_valid → 缓存不生效。
常见写法 ：proxy_cache my_zone; + proxy_cache_valid 200 10m; + 按会话/鉴权设置 bypass（示例，须贴合业务）。
关联：proxy_cache_path、proxy_cache_key、proxy_no_cache。

proxy_cache_background_update¶

Syntax: proxy_cache_background_update on | off;
Default: proxy_cache_background_update off;
Context: http, server, location
@Since: 1.11.10

允许在将过期缓存项以陈旧响应返回客户端的同时，启动后台子请求更新该项。须同时允许在更新过程中使用陈旧缓存响应。

proxy_cache_bypass¶

Syntax: proxy_cache_bypass string ...;
Default: —
Context: http, server, location
@Since: None

定义不从缓存取响应的条件。若字符串参数中至少有一个值非空且不等于 “0”，则不从缓存取响应：

proxy_cache_convert_head¶

Syntax: proxy_cache_convert_head on | off;
Default: proxy_cache_convert_head on;
Context: http, server, location
@Since: 1.9.7

启用或禁用在缓存时将 “HEAD” 方法转换为 “GET”。禁用转换时，缓存键应包含 $request_method。

proxy_cache_key¶

Syntax: proxy_cache_key string;
Default: proxy_cache_key $scheme$proxy_host$request_uri;
Context: http, server, location
@Since: None

定义缓存键，例如

Note

过细（高基数键：完整 $http_authorization、session cookie、JWT 全文）：缓存碎片化、 命中率趋近 0% 、keys zone 膨胀。
过粗（用户上下文 API：即无 Authorization 头，Session 在 Cookie 里也算）：同 URI、不同 body → 错误命中/串数据——切勿对 /api/ 或任何随用户变化的 route 仅用默认 key。
切勿：在可共享/公开端点把完整 Bearer（$http_authorization）写入 cache key——每用户 Token 不同，缓存形同虚设；body 随用户变化时用 proxy_no_cache / proxy_cache_bypass，而非按 Token 分键。
常见做法 ：仅 真正可共享 内容用默认 $scheme$proxy_host$request_uri；仅需区分租户/角色等 稳定维度 时，用衍生 ID 或最小 Cookie 片段——勿用完整 Token 或 per-session 键。 不确定时 优先 proxy_cache_bypass / proxy_no_cache，勿因路径「像静态」就对 API 用默认 key。
关联：proxy_cache_bypass、proxy_no_cache、proxy_cache。

proxy_cache_lock¶

Syntax: proxy_cache_lock on | off;
Default: proxy_cache_lock off;
Context: http, server, location
@Since: 1.1.12

启用时，对由 proxy_cache_key 标识的新缓存项，同一时间仅允许一个请求转发至被代理服务器以填充缓存。同一缓存项的其他请求将等待响应出现在缓存中，或等待该元素缓存锁释放，最长等待时间由 proxy_cache_lock_timeout 指定。

proxy_cache_lock_age¶

Syntax: proxy_cache_lock_age time;
Default: proxy_cache_lock_age 5s;
Context: http, server, location
@Since: 1.7.8

若填充新缓存项时最后一次转发至被代理服务器的请求在指定时间内尚未完成，可再向被代理服务器发送一个请求。

proxy_cache_lock_timeout¶

Syntax: proxy_cache_lock_timeout time;
Default: proxy_cache_lock_timeout 5s;
Context: http, server, location
@Since: 1.1.12

设置 proxy_cache_lock 的超时。超时后请求仍会转发至被代理服务器，但响应不会被缓存。

proxy_cache_max_range_offset¶

Syntax: proxy_cache_max_range_offset number;
Default: —
Context: http, server, location
@Since: 1.11.6

设置字节范围（byte-range）请求的偏移上限（字节）。若请求范围超出该偏移，范围请求将转发至被代理服务器且响应不会被缓存。

proxy_cache_methods¶

Syntax: proxy_cache_methods GET | HEAD | POST ...;
Default: proxy_cache_methods GET HEAD;
Context: http, server, location
@Since: 0.7.59

若客户端请求方法列在本指令中，则缓存响应。“GET” 与 “HEAD” 始终加入列表，仍建议显式写出。另见 proxy_no_cache。

proxy_cache_min_uses¶

Syntax: proxy_cache_min_uses number;
Default: proxy_cache_min_uses 1;
Context: http, server, location
@Since: None

设置响应被缓存前需收到的请求次数。

proxy_cache_path¶

Syntax: proxy_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default: —
Context: http
@Since: None

设置缓存路径及其他参数。缓存数据存于文件；文件名由缓存键经 MD5 得到。levels 定义缓存目录层级（1–3 级，每级取值 1 或 2）。例如下列配置

Note

keys_zone 大小须覆盖活跃键元数据（通常每键约 128 字节量级）；max_size、inactive 与磁盘 min_free 需与业务流量、对象大小一并规划，避免缓存区打满或 keys 区溢出导致频繁淘汰或无法写入。

proxy_cache_purge¶

Syntax: proxy_cache_purge string ...;
Default: —
Context: http, server, location
@Since: 1.5.7

定义将请求视为缓存清除（purge）请求的条件。若字符串参数中至少有一个值非空且不等于 “0”，则删除对应缓存键的缓存项。成功时返回 204（No Content）。

proxy_cache_revalidate¶

Syntax: proxy_cache_revalidate on | off;
Default: proxy_cache_revalidate off;
Context: http, server, location
@Since: 1.5.7

启用后，对过期缓存项使用带 “If-Modified-Since” 与 “If-None-Match” 头的条件请求进行再验证。

proxy_cache_use_stale¶

Syntax: proxy_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | off ...;
Default: proxy_cache_use_stale off;
Context: http, server, location
@Since: None

确定在与被代理服务器通信时，哪些情况下可使用陈旧缓存响应。本指令参数与 proxy_next_upstream 相同。

Note

关闭：刷新时上游故障即硬失败——短故障窗口可用性下降。
开启（如 error timeout updating http_500）：返回 stale——可用性更好；客户端可能短暂看到旧数据。
常见写法 ：读多写少的公开内容可用 proxy_cache_use_stale error timeout updating http_500 http_503;；强一致 API 慎用。
关联：proxy_cache_background_update。

proxy_cache_valid¶

Syntax: proxy_cache_valid [code ...] time;
Default: —
Context: http, server, location
@Since: None

为不同响应码设置缓存时间。例如下列指令

Note

过短：命中率低，上游压力仍大。
过长：发版后内容陈旧；错误响应缓存过久 → 全员“粘住”404/500。
常见写法 ：proxy_cache_valid 200 302 10m; proxy_cache_valid 404 1m;——错误码 TTL 宜短；与应用 Cache-Control、expires 一致。
关联：proxy_cache、proxy_cache_use_stale。

proxy_connect_timeout¶

Syntax: proxy_connect_timeout time;
Default: proxy_connect_timeout 60s;
Context: http, server, location
@Since: None

定义与被代理服务器 建立连接 的超时。通常该值不能超过 75 秒。

Note

过低：TCP/TLS 偏慢（高 RTT、丢包、SYN 重传）→ 误报 502/504 ；跨 AZ 在丢包明显时 10s 仍可能偏紧。
过高：故障或握手极慢的上游会更晚才失败，拉长请求占用时间。
常见起点 ：本机/同可用区上游 10s；跨可用区或跨区域 TLS 30s–60s。经验法则：宜 >（TCP 建连 + TLS 握手往返，含 SYN 重传）× 约 1.5 ；RTT 高或丢包多应上调；仅本机低延迟且需快速失败时可压低。仅覆盖建连阶段，读响应见 proxy_read_timeout。

proxy_cookie_domain¶

Syntax: proxy_cookie_domain off; proxy_cookie_domain domain replacement;
Default: proxy_cookie_domain off;
Context: http, server, location
@Since: 1.1.15

设置在被代理服务器响应 “Set-Cookie” 头中 domain 属性上应替换的文本。设被代理服务器返回 “Set-Cookie” 且 domain=localhost。指令

proxy_cookie_flags¶

Syntax: proxy_cookie_flags off | cookie [flag ...];
Default: proxy_cookie_flags off;
Context: http, server, location
@Since: 1.19.3

为 cookie 设置一个或多个标志。cookie 可含文本、变量及其组合；标志亦可（1.19.8）。secure、httponly、samesite=strict、samesite=lax、samesite=none 添加对应标志；nosecure、nohttponly、nosamesite 移除对应标志。

proxy_cookie_path¶

Syntax: proxy_cookie_path off; proxy_cookie_path path replacement;
Default: proxy_cookie_path off;
Context: http, server, location
@Since: 1.1.15

设置在被代理服务器响应 “Set-Cookie” 头中 path 属性上应替换的文本。设被代理服务器返回 “Set-Cookie” 且 path=/two/some/uri/。指令

proxy_force_ranges¶

Syntax: proxy_force_ranges on | off;
Default: proxy_force_ranges off;
Context: http, server, location
@Since: 1.7.7

无论响应中 “Accept-Ranges” 字段如何，均为来自被代理服务器的已缓存与未缓存响应启用字节范围支持。

proxy_headers_hash_bucket_size¶

Syntax: proxy_headers_hash_bucket_size size;
Default: proxy_headers_hash_bucket_size 64;
Context: http, server, location
@Since: None

设置 proxy_hide_header 与 proxy_set_header 所用哈希表的桶大小。哈希表配置详见文档。

proxy_headers_hash_max_size¶

Syntax: proxy_headers_hash_max_size size;
Default: proxy_headers_hash_max_size 512;
Context: http, server, location
@Since: None

设置 proxy_hide_header 与 proxy_set_header 所用哈希表的最大尺寸。哈希表配置详见文档。

proxy_hide_header¶

Syntax: proxy_hide_header field;
Default: —
Context: http, server, location
@Since: None

默认情况下，nginx 不会将被代理服务器响应中的 “Date”、“Server”、“X-Pad” 及 “X-Accel-...” 头传给客户端。proxy_hide_header 可指定额外不传递的字段。若需允许传递，可使用 proxy_pass_header。

Note

误用：隐藏应用或浏览器依赖的头（如 Cache-Control、CORS）→ 隐蔽故障。
常见写法 ：proxy_hide_header X-Powered-By; proxy_hide_header Server;（上游）——与 nginx 侧 server_tokens 互补。
关联：proxy_pass_header。

proxy_http_version¶

Syntax: proxy_http_version 1.0 | 1.1;
Default: proxy_http_version 1.0;
Context: http, server, location
@Since: 1.1.4

设置代理所用 HTTP 协议版本。默认 1.0；与 keepalive 连接及 NTLM 认证配合时建议使用 1.1。

Note

误用：默认 1.0 每请求新建上游连接，无法复用 keepalive 池。
常见写法 ：配合 upstream keepalive 时使用 proxy_http_version 1.1; 与 proxy_set_header Connection "";。
关联：proxy_set_header、keepalive。

proxy_ignore_client_abort¶

Syntax: proxy_ignore_client_abort on | off;
Default: proxy_ignore_client_abort off;
Context: http, server, location
@Since: None

确定客户端在未等待响应即关闭连接时，是否关闭与被代理服务器的连接。

proxy_ignore_headers¶

Syntax: proxy_ignore_headers field ...;
Default: —
Context: http, server, location
@Since: None

禁用对被代理服务器某些响应头的处理。可忽略：“X-Accel-Redirect”、“X-Accel-Expires”、“X-Accel-Limit-Rate”（1.1.6）、“X-Accel-Buffering”（1.1.6）、“X-Accel-Charset”（1.1.6）、“Expires”、“Cache-Control”、“Set-Cookie”（0.8.44）及 “Vary”（1.7.7）。

proxy_intercept_errors¶

Syntax: proxy_intercept_errors on | off;
Default: proxy_intercept_errors off;
Context: http, server, location
@Since: None

确定状态码大于等于 300 的被代理响应是直接返回客户端，还是拦截并由 nginx 通过 error_page 处理。

Note

关闭（默认） ：上游 4xx/5xx 原样透传——适合返回 JSON 错误的 API。
开启：由 error_page 接管——适合 HTML 站点； 会破坏 依赖上游 JSON 错误体的 API。
常见做法 ：/api/ 保持 off；仅静态/HTML location 显式 on 并配置 error_page。
关联：error_page。

proxy_limit_rate¶

Syntax: proxy_limit_rate rate;
Default: proxy_limit_rate 0;
Context: http, server, location
@Since: 1.7.7

限制从被代理服务器读取响应的速率（字节/秒）。0 表示不限速。限制按 单个请求 计；若 nginx 同时打开两条至被代理服务器的连接，总速率约为设定值的两倍。仅当启用对被代理响应的缓冲时生效。参数值可含变量（1.27.0）。

proxy_max_temp_file_size¶

Syntax: proxy_max_temp_file_size size;
Default: proxy_max_temp_file_size 1024m;
Context: http, server, location
@Since: None

启用对被代理服务器响应的缓冲且整段响应无法放入 proxy_buffer_size 与 proxy_buffers 所设缓冲区时，部分响应可写入临时文件。本指令设置临时文件最大尺寸。每次写入临时文件的数据量由 proxy_temp_file_write_size 设置。

proxy_method¶

Syntax: proxy_method method;
Default: —
Context: http, server, location
@Since: None

指定转发至被代理服务器时使用的 HTTP 方法，替代客户端请求中的方法。参数值可含变量（1.11.6）。

proxy_next_upstream¶

Syntax: proxy_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default: proxy_next_upstream error timeout;
Context: http, server, location
@Since: None

指定在何种情况下将请求转发至 下一台 服务器：

Note

误用：upstream 可能已处理过的 非幂等 POST/PUT 仍重试 → 重复写入；对大量 4xx 重试 → 放大负载。无应用层幂等键时勿加 non_idempotent。
细微（POST/PUT） ：重复写入风险最高的是 upstream 已收齐请求并已处理 、响应途中断连。失败发生在 send 阶段（body 未完整送达，如 proxy_send_timeout）时重试通常较安全；Nginx 默认在 send 完成后不会对非幂等请求 next_upstream，除非配置含 non_idempotent——边界情况仍依赖应用幂等。
过激进（次数多/超时 long）：上游恢复时易引发惊群。
常见写法 ：proxy_next_upstream error timeout http_502 http_503;，proxy_next_upstream_tries 宜小（如 2）。
关联：proxy_next_upstream_tries、proxy_next_upstream_timeout、proxy_send_timeout。

proxy_next_upstream_timeout¶

Syntax: proxy_next_upstream_timeout time;
Default: proxy_next_upstream_timeout 0;
Context: http, server, location
@Since: 1.7.5

限制可将请求转发至下一台服务器的总时间。0 表示不限制。

proxy_next_upstream_tries¶

Syntax: proxy_next_upstream_tries number;
Default: proxy_next_upstream_tries 0;
Context: http, server, location
@Since: 1.7.5

限制将请求转发至下一台服务器的最大尝试次数。0 表示不限制。

proxy_no_cache¶

Syntax: proxy_no_cache string ...;
Default: —
Context: http, server, location
@Since: None

定义不将响应写入缓存的条件。若字符串参数中至少有一个值非空且不等于 “0”，则响应不会被保存：

proxy_pass¶

Syntax: proxy_pass URL;
Default: —
Context: location, if in location, limit_except
@Since: None

设置被代理服务器的协议、地址，以及 location 可选映射的 URI。协议可为 “http” 或 “https”；地址可为域名或 IP，并可选端口：

Note

proxy_pass 末尾是否带 URI 路径决定请求 URI 如何拼接：带路径时通常替换 location 匹配部分；指向 upstream 块时常省略路径。修改后须用 nginx -t 验证，避免 404 或重复前缀。

proxy_pass_header¶

Syntax: proxy_pass_header field;
Default: —
Context: http, server, location
@Since: None

允许传递本会被禁用的、来自被代理服务器的头字段。

proxy_pass_request_body¶

Syntax: proxy_pass_request_body on | off;
Default: proxy_pass_request_body on;
Context: http, server, location
@Since: None

指示是否将原始请求体转发至被代理服务器。

proxy_pass_request_headers¶

Syntax: proxy_pass_request_headers on | off;
Default: proxy_pass_request_headers on;
Context: http, server, location
@Since: None

指示是否将原始请求头转发至被代理服务器。

proxy_pass_trailers¶

Syntax: proxy_pass_trailers on | off;
Default: proxy_pass_trailers off;
Context: http, server, location
@Since: 1.27.2

允许将被代理服务器的 trailer 字段传递给客户端。

proxy_read_timeout¶

Syntax: proxy_read_timeout time;
Default: proxy_read_timeout 60s;
Context: http, server, location
@Since: None

定义从被代理服务器读取响应的超时。计时仅在 两次连续读操作之间 ，而非整段响应传输。若在此时间内被代理服务器未发送任何数据，则关闭连接。

Note

过低：上游仍在出响应（慢 API、报表导出）→ 504 ；proxy_buffering off 的 SSE/长轮询尤其敏感。
过高：上游卡住或慢客户端长时间占用 worker 与上游连接，故障时更易连接耗尽。
常见起点 ：普通 API 60s；长轮询/SSE/大导出 300s–3600s，必要时 proxy_buffering off。
关联：proxy_send_timeout、proxy_connect_timeout、LB 空闲超时。

proxy_redirect¶

Syntax: proxy_redirect default; proxy_redirect off; proxy_redirect redirect replacement;
Default: proxy_redirect default;
Context: http, server, location
@Since: None

设置在被代理服务器响应 “Location” 与 “Refresh” 头中应替换的文本。设被代理服务器返回 “Location: http://localhost:8000/two/some/uri/”。指令

Note

误用：规则错误 → 重定向环 或 Location 仍指向内网主机名。
默认 on ：上游返回相对或同 host 重定向时通常可用；OAuth/登录需细测。
常见写法 ：上游已是公网 URL 时可 proxy_redirect off;；否则按 proxy_redirect http://backend/ /; 类规则——变更后必测登录/OAuth 。
关联：proxy_pass URI 组合规则。

proxy_request_buffering¶

Syntax: proxy_request_buffering on | off;
Default: proxy_request_buffering on;
Context: http, server, location
@Since: 1.7.11

启用或禁用对客户端请求体的缓冲。

proxy_send_lowat¶

Syntax: proxy_send_lowat size;
Default: proxy_send_lowat 0;
Context: http, server, location
@Since: None

设为非零值时，nginx 将尝试通过 kqueue 的 NOTE_LOWAT 标志或 SO_SNDLOWAT 套接字选项（指定大小）减少向被代理服务器出站连接的发送次数。

proxy_send_timeout¶

Syntax: proxy_send_timeout time;
Default: proxy_send_timeout 60s;
Context: http, server, location
@Since: None

设置向被代理服务器传输请求的超时。计时仅在 两次连续写操作之间 ，而非整段请求传输。若在此时间内被代理服务器未收到任何数据，则关闭连接。

Note

过低：Nginx 向上游转发请求（含 body）时，上游接收慢或两次写之间超时 → 上游可能 未收齐 body → 502 。客户端上传慢见 client_body_timeout；客户端下载/读响应慢见 send_timeout——勿混淆。
过高：上游或链路异常慢时，proxy send 阶段占用连接更久——需配合 WAF/LB 限制。
常见起点 ：按 Nginx 需 转发到上游 的最大 body 耗时设定；对称 API 常与 proxy_read_timeout 同量级（send 发请求，read 读响应）。
关联：client_body_timeout、send_timeout、proxy_read_timeout、client_max_body_size。

proxy_set_body¶

Syntax: proxy_set_body value;
Default: —
Context: http, server, location
@Since: None

允许重定义转发至被代理服务器的请求体。值可含文本、变量及其组合。

proxy_set_header¶

Syntax: proxy_set_header field value;
Default: proxy_set_header Host $proxy_host; proxy_set_header Connection close;
Context: http, server, location
@Since: None

允许重定义或追加转发至被代理服务器的请求头。值可含文本、变量及其组合。仅当当前层级未定义任何 proxy_set_header 时，才从上一级继承。默认仅重定义两个字段：

Note

误用：缺 Host / X-Forwarded-* 会导致 TLS 终结后应用路由错误；透传客户端 Connection 会破坏上游 keepalive。
常见写法（按应用调整）：Host $host; X-Real-IP $remote_addr; X-Forwarded-For $proxy_add_x_forwarded_for; X-Forwarded-Proto $scheme;
关联：proxy_hide_header、CDN/ set_real_ip_from 相关头。

proxy_socket_keepalive¶

Syntax: proxy_socket_keepalive on | off;
Default: proxy_socket_keepalive off;
Context: http, server, location
@Since: 1.15.6

配置至被代理服务器出站连接的 “TCP keepalive” 行为。默认使用操作系统套接字设置。设为 “on” 时为套接字启用 SO_KEEPALIVE 选项。

proxy_ssl_certificate¶

Syntax: proxy_ssl_certificate file;
Default: —
Context: http, server, location
@Since: 1.7.8

指定用于向被代理 HTTPS 服务器认证的 PEM 格式证书文件。

proxy_ssl_certificate_cache¶

Syntax: proxy_ssl_certificate_cache off; proxy_ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: proxy_ssl_certificate_cache off;
Context: http, server, location
@Since: 1.27.4

定义缓存，用于存放以变量指定的 SSL 证书与私钥。

proxy_ssl_certificate_key¶

Syntax: proxy_ssl_certificate_key file;
Default: —
Context: http, server, location
@Since: 1.7.8

指定用于向被代理 HTTPS 服务器认证的 PEM 格式私钥文件。

proxy_ssl_ciphers¶

Syntax: proxy_ssl_ciphers ciphers;
Default: proxy_ssl_ciphers DEFAULT;
Context: http, server, location
@Since: 1.5.6

指定访问被代理 HTTPS 服务器时启用的密码套件；格式为 OpenSSL 可识别的写法。

proxy_ssl_conf_command¶

Syntax: proxy_ssl_conf_command name value;
Default: —
Context: http, server, location
@Since: 1.19.4

在与被代理 HTTPS 服务器建立连接时设置任意 OpenSSL 配置命令。

proxy_ssl_crl¶

Syntax: proxy_ssl_crl file;
Default: —
Context: http, server, location
@Since: 1.7.0

指定 PEM 格式吊销证书列表（CRL）文件，用于验证被代理 HTTPS 服务器证书。

proxy_ssl_key_log¶

Syntax: proxy_ssl_key_log path;
Default: —
Context: http, server, location
@Since: 1.27.2

启用被代理 HTTPS 连接 SSL 密钥日志，并指定密钥日志文件路径。密钥以与 Wireshark 兼容的 SSLKEYLOGFILE 格式记录。

proxy_ssl_name¶

Syntax: proxy_ssl_name name;
Default: proxy_ssl_name $proxy_host;
Context: http, server, location
@Since: 1.7.0

允许覆盖用于验证被代理 HTTPS 服务器证书的服务器名，以及通过 SNI 建立连接时传递的名称。

proxy_ssl_password_file¶

Syntax: proxy_ssl_password_file file;
Default: —
Context: http, server, location
@Since: 1.7.8

指定私钥口令文件，每行一个口令；加载密钥时依次尝试。

proxy_ssl_protocols¶

Syntax: proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: proxy_ssl_protocols TLSv1.2 TLSv1.3;
Context: http, server, location
@Since: 1.5.6

启用访问被代理 HTTPS 服务器时允许的协议。

proxy_ssl_server_name¶

Syntax: proxy_ssl_server_name on | off;
Default: proxy_ssl_server_name off;
Context: http, server, location
@Since: 1.7.0

启用或禁用在与被代理 HTTPS 服务器建立连接时通过 TLS 服务器名称指示（SNI，RFC 6066）传递服务器名。

proxy_ssl_session_reuse¶

Syntax: proxy_ssl_session_reuse on | off;
Default: proxy_ssl_session_reuse on;
Context: http, server, location
@Since: None

确定是否可复用与被代理服务器通信时的 SSL 会话。若日志出现 “digest check failed”，可尝试关闭会话复用。

proxy_ssl_trusted_certificate¶

Syntax: proxy_ssl_trusted_certificate file;
Default: —
Context: http, server, location
@Since: 1.7.0

指定 PEM 格式可信 CA 证书文件，用于验证被代理 HTTPS 服务器证书。

proxy_ssl_verify¶

Syntax: proxy_ssl_verify on | off;
Default: proxy_ssl_verify off;
Context: http, server, location
@Since: 1.7.0

启用或禁用对被代理 HTTPS 服务器证书的验证。

proxy_ssl_verify_depth¶

Syntax: proxy_ssl_verify_depth number;
Default: proxy_ssl_verify_depth 1;
Context: http, server, location
@Since: 1.7.0

设置被代理 HTTPS 服务器证书链的验证深度。

proxy_store¶

Syntax: proxy_store on | off | string;
Default: proxy_store off;
Context: http, server, location
@Since: None

启用将文件保存到磁盘。on 时按 alias 或 root 对应路径保存；off 禁用。亦可用含变量的字符串显式指定文件名：

proxy_store_access¶

Syntax: proxy_store_access users:permissions ...;
Default: proxy_store_access user:rw;
Context: http, server, location
@Since: None

设置新建文件与目录的访问权限，例如：

proxy_temp_file_write_size¶

Syntax: proxy_temp_file_write_size size;
Default: proxy_temp_file_write_size 8k|16k;
Context: http, server, location
@Since: None

启用将被代理服务器响应缓冲至临时文件时，限制每次写入临时文件的数据量。默认上限约为 proxy_buffer_size 与 proxy_buffers 所设两个缓冲区的大小。临时文件最大尺寸由 proxy_max_temp_file_size 设置。

proxy_temp_path¶

Syntax: proxy_temp_path path [level1 [level2 [level3]]];
Default: proxy_temp_path proxy_temp;
Context: http, server, location
@Since: None

定义存放从被代理服务器接收数据的临时文件目录。可在指定目录下使用最多三级子目录层次。例如下列配置

ngx_http_proxy_protocol_vendor_module¶

ngx_http_random_index_module¶

random_index¶

Syntax: random_index on | off;
Default: random_index off;
Context: location
@Since: None

在所在 location 启用或禁用本模块处理。

ngx_http_realip_module¶

set_real_ip_from¶

Syntax: set_real_ip_from address | CIDR | unix:;
Default: —
Context: http, server, location
@Since: None

定义已知会发送正确替换地址的可信地址。特殊值 unix: 表示信任所有 UNIX 域套接字。亦可用主机名指定可信地址（1.13.1）。

Note

CDN/七层反代后取真实 IP：仅信任上游 LB 网段，配合 real_ip_header X-Forwarded-For 与 real_ip_recursive on；勿对公网开放 set_real_ip_from 0.0.0.0/0。

real_ip_header¶

Syntax: real_ip_header field | X-Real-IP | X-Forwarded-For | proxy_protocol;
Default: real_ip_header X-Real-IP;
Context: http, server, location
@Since: None

定义用于替换客户端地址的请求头字段。

real_ip_recursive¶

Syntax: real_ip_recursive on | off;
Default: real_ip_recursive off;
Context: http, server, location
@Since: 1.3.0、1.2.1

禁用递归时：若原始客户端地址匹配某可信地址，则用 real_ip_header 所定义头字段中的 最后一个 地址替换。启用递归时：则用该头字段中 最后一个不可信 地址替换。

ngx_http_referer_module¶

referer_hash_bucket_size¶

Syntax: referer_hash_bucket_size size;
Default: referer_hash_bucket_size 64;
Context: server, location
@Since: 1.0.5

设置 valid referers 哈希表桶大小。哈希表配置详见文档。

referer_hash_max_size¶

Syntax: referer_hash_max_size size;
Default: referer_hash_max_size 2048;
Context: server, location
@Since: 1.0.5

设置 valid referers 哈希表最大尺寸。哈希表配置详见文档。

valid_referers¶

Syntax: valid_referers none | blocked | server_names | string ...;
Default: —
Context: server, location
@Since: None

指定哪些 “Referer” 请求头值会使内建变量 $invalid_referer 为空字符串；否则设为 “1”。匹配不区分大小写。

ngx_http_rewrite_module¶

break¶

Syntax: break;
Default: —
Context: server, location, if
@Since: None

停止处理当前 ngx_http_rewrite_module 指令集。

if¶

Syntax: if (condition) { ... }
Default: —
Context: server, location
@Since: None

对指定条件求值。若为真，则执行大括号内本模块指令，并将请求赋给 if 指令内的配置。if 指令内的配置自上一级配置层级继承。

Warning

if 在 location 内行为复杂，易与 try_files、proxy_pass 等组合出非预期结果；优先用 map、return 或独立 location 替代复杂 if。

return¶

Syntax: return code [text]; return code URL; return URL;
Default: —
Context: server, location, if
@Since: None

停止处理并向客户端返回指定 code。非标准码 444 关闭连接且不发送响应头。

rewrite¶

Syntax: rewrite regex replacement [flag];
Default: —
Context: server, location, if
@Since: None

若指定正则与请求 URI 匹配，则按 replacement 字符串改写 URI。rewrite 指令按在配置文件中出现的顺序依次执行。可用 flag 终止后续指令处理。若 replacement 以 “http://”、“https://” 或 “$scheme” 开头，则停止处理并向客户端返回重定向。

rewrite_log¶

Syntax: rewrite_log on | off;
Default: rewrite_log off;
Context: http, server, location, if
@Since: None

启用或禁用将 ngx_http_rewrite_module 指令处理结果以 notice 级别写入 error_log。

set¶

Syntax: set $variable value;
Default: —
Context: server, location, if
@Since: None

为指定变量赋值。value 可含文本、变量及其组合。

uninitialized_variable_warn¶

Syntax: uninitialized_variable_warn on | off;
Default: uninitialized_variable_warn on;
Context: http, server, location, if
@Since: None

控制是否记录未初始化变量的警告。

ngx_http_scgi_module¶

scgi_bind¶

Syntax: scgi_bind address [transparent] | off;
Default: —
Context: http, server, location
@Since: None

使发往 SCGI 服务器的出站连接从指定的本地 IP 地址（1.11.2 起可选端口）发起。参数值可含变量（1.3.12）。特殊值 off（1.3.12）取消从上一级继承的 scgi_bind 效果，由系统自动分配本地 IP 与端口。

scgi_buffer_size¶

Syntax: scgi_buffer_size size;
Default: scgi_buffer_size 4k|8k;
Context: http, server, location
@Since: None

设置用于读取 SCGI 服务器响应首段的缓冲区大小；该段通常含较小的响应头。默认等于一个内存页，平台相关为 4K 或 8K，亦可改小。

scgi_buffering¶

Syntax: scgi_buffering on | off;
Default: scgi_buffering on;
Context: http, server, location
@Since: None

启用或禁用对 SCGI 服务器响应的缓冲。

scgi_buffers¶

Syntax: scgi_buffers number size;
Default: scgi_buffers 8 4k|8k;
Context: http, server, location
@Since: None

设置单连接读取 SCGI 服务器响应所用缓冲区的数量与大小。默认单缓冲等于一个内存页，平台相关为 4K 或 8K。

scgi_busy_buffers_size¶

Syntax: scgi_busy_buffers_size size;
Default: scgi_busy_buffers_size 8k|16k;
Context: http, server, location
@Since: None

启用 SCGI 响应缓冲时，限制在响应尚未完全读入时、可向客户端发送响应的 busy 缓冲区总大小。其余缓冲区可用于读响应，必要时将部分响应缓冲至临时文件。默认上限约为 scgi_buffer_size 与 scgi_buffers 所设两个缓冲区的大小。

scgi_cache¶

Syntax: scgi_cache zone | off;
Default: scgi_cache off;
Context: http, server, location
@Since: None

定义用于缓存的共享内存区。同一 zone 可在多处使用。参数值可含变量（1.7.9）。参数 off 禁用从上一级继承的缓存。

scgi_cache_background_update¶

Syntax: scgi_cache_background_update on | off;
Default: scgi_cache_background_update off;
Context: http, server, location
@Since: 1.11.10

允许在向客户端返回过期缓存项的同时，启动后台子请求更新该项。须同时允许在更新过程中使用 stale 缓存响应。

scgi_cache_bypass¶

Syntax: scgi_cache_bypass string ...;
Default: —
Context: http, server, location
@Since: None

定义不从缓存取响应的条件。若任一字串参数值非空且不等于 “0”，则不从缓存取响应：

scgi_cache_key¶

Syntax: scgi_cache_key string;
Default: —
Context: http, server, location
@Since: None

定义缓存键，例如

scgi_cache_lock¶

Syntax: scgi_cache_lock on | off;
Default: scgi_cache_lock off;
Context: http, server, location
@Since: 1.1.12

启用时，按 scgi_cache_key 标识的新缓存项同一时刻仅允许一个请求向 SCGI 服务器填充。同键其他请求将等待缓存中出现响应或锁释放，最长 scgi_cache_lock_timeout。

scgi_cache_lock_age¶

Syntax: scgi_cache_lock_age time;
Default: scgi_cache_lock_age 5s;
Context: http, server, location
@Since: 1.7.8

若填充新缓存项的最后一条发往 SCGI 的请求在指定时间内未完成，可再向 SCGI 发送一条请求。

scgi_cache_lock_timeout¶

Syntax: scgi_cache_lock_timeout time;
Default: scgi_cache_lock_timeout 5s;
Context: http, server, location
@Since: 1.1.12

设置 scgi_cache_lock 超时。超时后请求仍会发往 SCGI，但响应不会写入缓存。

scgi_cache_max_range_offset¶

Syntax: scgi_cache_max_range_offset number;
Default: —
Context: http, server, location
@Since: 1.11.6

设置字节范围（byte-range）请求的偏移上限（字节）。若请求范围超出该偏移，范围请求将发往 SCGI 服务器且响应不会被缓存。

scgi_cache_methods¶

Syntax: scgi_cache_methods GET | HEAD | POST ...;
Default: scgi_cache_methods GET HEAD;
Context: http, server, location
@Since: None

若客户端请求方法列在本指令中，则缓存响应。“GET” 与 “HEAD” 始终加入列表，仍建议显式写出。另见 scgi_no_cache。

scgi_cache_min_uses¶

Syntax: scgi_cache_min_uses number;
Default: scgi_cache_min_uses 1;
Context: http, server, location
@Since: None

设置响应被缓存前需收到的请求次数。

scgi_cache_path¶

Syntax: scgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default: —
Context: http
@Since: None

设置 SCGI 缓存路径及其他参数。缓存数据存于文件；键与文件名均为对缓存键做 MD5 的结果。levels 定义缓存目录层级（1–3 级，每级取值 1 或 2）。例如下列配置

scgi_cache_purge¶

Syntax: scgi_cache_purge string ...;
Default: —
Context: http, server, location
@Since: 1.5.7

定义将请求视为缓存清除（purge）请求的条件。若字符串参数中至少有一个值非空且不等于 “0”，则删除对应缓存键的缓存项。成功时返回 204（No Content）。

scgi_cache_revalidate¶

Syntax: scgi_cache_revalidate on | off;
Default: scgi_cache_revalidate off;
Context: http, server, location
@Since: 1.5.7

启用后，对过期缓存项使用带 “If-Modified-Since” 与 “If-None-Match” 头的条件请求进行再验证。

scgi_cache_use_stale¶

Syntax: scgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off ...;
Default: scgi_cache_use_stale off;
Context: http, server, location
@Since: None

确定在与 SCGI 服务器通信出错时，哪些情况下可使用陈旧缓存响应。本指令参数与 scgi_next_upstream 相同。

scgi_cache_valid¶

Syntax: scgi_cache_valid [code ...] time;
Default: —
Context: http, server, location
@Since: None

为不同响应码设置缓存时间。例如下列指令

scgi_connect_timeout¶

Syntax: scgi_connect_timeout time;
Default: scgi_connect_timeout 60s;
Context: http, server, location
@Since: None

定义与 SCGI 服务器 建立连接 的超时。通常该值不能超过 75 秒。

scgi_force_ranges¶

Syntax: scgi_force_ranges on | off;
Default: scgi_force_ranges off;
Context: http, server, location
@Since: 1.7.7

无论 SCGI 响应是否含 “Accept-Ranges” 头，均为缓存与未缓存响应启用字节范围（byte-range）支持。

scgi_hide_header¶

Syntax: scgi_hide_header field;
Default: —
Context: http, server, location
@Since: None

默认情况下，nginx 不会将 SCGI 响应中的 “Status” 与 “X-Accel-...” 头传给客户端。scgi_hide_header 可追加不传递的头字段。若需允许传递，可使用 scgi_pass_header。

scgi_ignore_client_abort¶

Syntax: scgi_ignore_client_abort on | off;
Default: scgi_ignore_client_abort off;
Context: http, server, location
@Since: None

决定客户端未等待响应即断开时，是否同时关闭与 SCGI 服务器的连接。

scgi_ignore_headers¶

Syntax: scgi_ignore_headers field ...;
Default: —
Context: http, server, location
@Since: None

禁用对 SCGI 服务器响应中某些头字段的处理。可忽略：“X-Accel-Redirect”、“X-Accel-Expires”、“X-Accel-Limit-Rate”（1.1.6）、“X-Accel-Buffering”（1.1.6）、“X-Accel-Charset”（1.1.6）、“Expires”、“Cache-Control”、“Set-Cookie”（0.8.44）、“Vary”（1.7.7）。

scgi_intercept_errors¶

Syntax: scgi_intercept_errors on | off;
Default: scgi_intercept_errors off;
Context: http, server, location
@Since: None

决定 SCGI 响应码 ≥ 300 时直接返回客户端，还是由 nginx 拦截并通过 error_page 处理。

scgi_limit_rate¶

Syntax: scgi_limit_rate rate;
Default: scgi_limit_rate 0;
Context: http, server, location
@Since: 1.7.7

限制从 SCGI 服务器读取响应的速率（字节/秒）。0 表示不限速。限速按 单请求 计；若 nginx 同时打开两条 SCGI 连接，总速率约为设定值的两倍。仅当启用 SCGI 响应缓冲时生效。参数值可含变量（1.27.0）。

scgi_max_temp_file_size¶

Syntax: scgi_max_temp_file_size size;
Default: scgi_max_temp_file_size 1024m;
Context: http, server, location
@Since: None

启用 SCGI 响应缓冲且整段响应无法放入 scgi_buffer_size 与 scgi_buffers 时，部分响应可写入临时文件。本指令设置临时文件最大尺寸；单次写入量由 scgi_temp_file_write_size 控制。

scgi_next_upstream¶

Syntax: scgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default: scgi_next_upstream error timeout;
Context: http, server, location
@Since: None

指定在哪些情况下将请求转发至下一台服务器：

scgi_next_upstream_timeout¶

Syntax: scgi_next_upstream_timeout time;
Default: scgi_next_upstream_timeout 0;
Context: http, server, location
@Since: 1.7.5

限制可将请求转发至下一台服务器的最长时间。0 表示不限制。

scgi_next_upstream_tries¶

Syntax: scgi_next_upstream_tries number;
Default: scgi_next_upstream_tries 0;
Context: http, server, location
@Since: 1.7.5

限制转发至下一台服务器的最大尝试次数。0 表示不限制。

scgi_no_cache¶

Syntax: scgi_no_cache string ...;
Default: —
Context: http, server, location
@Since: None

定义不将响应写入缓存的条件。若任一字串参数值非空且不等于 “0”，则不保存：

scgi_param¶

Syntax: scgi_param parameter value [if_not_empty];
Default: —
Context: http, server, location
@Since: None

设置应传给 SCGI 服务器的参数。值可含文本、变量及其组合。仅当当前层级未定义任何 scgi_param 时，才从上一级继承。

scgi_pass¶

Syntax: scgi_pass address;
Default: —
Context: location, if in location
@Since: None

设置 SCGI 服务器地址，可为域名或 IP，并可选端口：

scgi_pass_header¶

Syntax: scgi_pass_header field;
Default: —
Context: http, server, location
@Since: None

允许传递本会被禁用的、来自 SCGI 服务器的头字段。

scgi_pass_request_body¶

Syntax: scgi_pass_request_body on | off;
Default: scgi_pass_request_body on;
Context: http, server, location
@Since: None

指示是否将原始请求体转发至 SCGI 服务器。另见 scgi_pass_request_headers。

scgi_pass_request_headers¶

Syntax: scgi_pass_request_headers on | off;
Default: scgi_pass_request_headers on;
Context: http, server, location
@Since: None

指示是否将原始请求头转发至 SCGI 服务器。另见 scgi_pass_request_body。

scgi_read_timeout¶

Syntax: scgi_read_timeout time;
Default: scgi_read_timeout 60s;
Context: http, server, location
@Since: None

定义从 SCGI 服务器读取响应的超时。计时仅在 两次连续读操作之间 ，而非整段响应传输。若在此时间内 SCGI 未发送任何数据，则关闭连接。

scgi_request_buffering¶

Syntax: scgi_request_buffering on | off;
Default: scgi_request_buffering on;
Context: http, server, location
@Since: 1.7.11

启用或禁用客户端请求体缓冲。

scgi_send_timeout¶

Syntax: scgi_send_timeout time;
Default: scgi_send_timeout 60s;
Context: http, server, location
@Since: None

设置向 SCGI 服务器传输请求的超时。计时仅在 两次连续写操作之间 ，而非整段请求传输。若在此时间内 SCGI 未收到任何数据，则关闭连接。

scgi_socket_keepalive¶

Syntax: scgi_socket_keepalive on | off;
Default: scgi_socket_keepalive off;
Context: http, server, location
@Since: 1.15.6

配置至 SCGI 服务器出站连接的 “TCP keepalive” 行为。默认使用操作系统套接字设置。设为 on 时为套接字启用 SO_KEEPALIVE 选项。

scgi_store¶

Syntax: scgi_store on | off | string;
Default: scgi_store off;
Context: http, server, location
@Since: None

启用将文件保存至磁盘。参数 on 时按 alias 或 root 对应路径保存；off 禁用。亦可用含变量的字符串显式指定文件名：

scgi_store_access¶

Syntax: scgi_store_access users:permissions ...;
Default: scgi_store_access user:rw;
Context: http, server, location
@Since: None

设置新建文件与目录的访问权限，例如：

scgi_temp_file_write_size¶

Syntax: scgi_temp_file_write_size size;
Default: scgi_temp_file_write_size 8k|16k;
Context: http, server, location
@Since: None

启用将 SCGI 响应缓冲至临时文件时，限制每次写入临时文件的数据量。默认上限约为 scgi_buffer_size 与 scgi_buffers 所设两个缓冲区的大小。临时文件最大尺寸由 scgi_max_temp_file_size 设置。

scgi_temp_path¶

Syntax: scgi_temp_path path [level1 [level2 [level3]]];
Default: scgi_temp_path scgi_temp;
Context: http, server, location
@Since: None

定义存放从 SCGI 服务器接收数据的临时文件目录。可在指定目录下使用最多三级子目录层次。例如下列配置

ngx_http_secure_link_module¶

secure_link¶

Syntax: secure_link expression;
Default: —
Context: http, server, location
@Since: None

定义含变量的字符串，从中提取链接的校验和值与有效期。

secure_link_md5¶

Syntax: secure_link_md5 expression;
Default: —
Context: http, server, location
@Since: None

定义将计算 MD5 并与请求中传入值比较的表达式。

secure_link_secret¶

Syntax: secure_link_secret word;
Default: —
Context: location
@Since: None

定义用于校验请求链接真实性的密钥词。

ngx_http_session_log_module¶

session_log¶

Syntax: session_log name | off;
Default: session_log off;
Context: http, server, location
@Since: None

启用指定 session 日志。特殊值 off 取消从上一级继承的 session_log 指令效果。

session_log_format¶

Syntax: session_log_format name string ...;
Default: session_log_format combined "...";
Context: http
@Since: None

指定日志输出格式。$body_bytes_sent 在 session 内所有请求上聚合；其余可记录变量取 session 中首个请求的值。

session_log_zone¶

Syntax: session_log_zone path zone=name:size [format=format] [timeout=time] [id=id] [md5=md5] ;
Default: —
Context: http
@Since: None

设置日志文件路径，并配置用于存储当前活跃 session 的共享内存 zone。

ngx_http_slice_module¶

slice¶

Syntax: slice size;
Default: slice 0;
Context: http, server, location
@Since: None

设置 slice 大小。0 禁用将响应拆分为 slice。值过低可能导致内存占用过高并打开大量文件。

Note

大文件缓存/代理场景配合 slice 与 Range 可分段回源；需与上游 Accept-Ranges 及缓存键策略一致。

ngx_http_split_clients_module¶

split_clients¶

Syntax: split_clients string $variable { ... }
Default: —
Context: http
@Since: None

创建用于 A/B 测试的变量，例如：

ngx_http_ssi_module¶

ssi¶

Syntax: ssi on | off;
Default: ssi off;
Context: http, server, location, if in location
@Since: None

启用或禁用对响应中 SSI 指令的处理。

ssi_last_modified¶

Syntax: ssi_last_modified on | off;
Default: ssi_last_modified off;
Context: http, server, location
@Since: 1.5.1

允许在 SSI 处理过程中保留原始响应的 “Last-Modified” 头，便于响应缓存。

ssi_min_file_chunk¶

Syntax: ssi_min_file_chunk size;
Default: ssi_min_file_chunk 1k;
Context: http, server, location
@Since: None

设置磁盘上响应片段的最小尺寸，达到该尺寸后才适合用 sendfile 发送。

ssi_silent_errors¶

Syntax: ssi_silent_errors on | off;
Default: ssi_silent_errors off;
Context: http, server, location
@Since: None

启用时，若 SSI 处理出错，则抑制输出 “[an error occurred while processing the directive]” 字符串。

ssi_types¶

Syntax: ssi_types mime-type ...;
Default: ssi_types text/html;
Context: http, server, location
@Since: None

除 “text/html” 外，对指定 MIME 类型的响应启用 SSI 指令处理。特殊值 “*” 匹配任意 MIME 类型（0.8.29）。

ssi_value_length¶

Syntax: ssi_value_length length;
Default: ssi_value_length 256;
Context: http, server, location
@Since: None

设置 SSI 指令中参数值的最大长度。

ngx_http_ssl_module¶

ssl¶

Syntax: ssl on | off;
Default: ssl off;
Context: http, server
@Since: None

自 1.15.0 起已废弃，1.25.1 已移除；应改用 listen 指令的 ssl 参数。

ssl_buffer_size¶

Syntax: ssl_buffer_size size;
Default: ssl_buffer_size 16k;
Context: http, server
@Since: 1.5.9

设置用于发送数据的缓冲区大小。

ssl_certificate¶

Syntax: ssl_certificate file;
Default: —
Context: http, server
@Since: None

为指定虚拟 server 指定 PEM 格式证书文件。除主证书外若需指定中间证书，应写入同一文件，顺序为：主证书在前，中间证书在后。PEM 格式私钥也可放在同一文件中。

Note

生产环境应提供完整证书链（主证书 + 中间 CA）；私钥宜单独用 ssl_certificate_key 存放并限制文件权限（如 600）。配合自动续期（如 certbot/acme）时，reload 前须 nginx -t 验证路径与链完整性。

ssl_certificate_cache¶

Syntax: ssl_certificate_cache off; ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: ssl_certificate_cache off;
Context: http, server
@Since: 1.27.4

定义缓存，用于存放以变量指定的 SSL 证书与私钥。

ssl_certificate_key¶

Syntax: ssl_certificate_key file;
Default: —
Context: http, server
@Since: None

为指定虚拟 server 指定 PEM 格式私钥文件。

ssl_ciphers¶

Syntax: ssl_ciphers ciphers;
Default: ssl_ciphers HIGH:!aNULL:!MD5;
Context: http, server
@Since: None

指定启用的密码套件；格式为 OpenSSL 可识别的写法，例如：

Note

生产环境应显式配置现代密码套件（优先 ECDHE + AEAD），避免依赖默认 HIGH:!aNULL:!MD5 可能包含的弱算法。可用 openssl ciphers 或 Mozilla SSL Configuration Generator 校验与调优。

ssl_client_certificate¶

Syntax: ssl_client_certificate file;
Default: —
Context: http, server
@Since: None

指定 PEM 格式受信 CA 证书文件，用于验证客户端证书；若启用 ssl_stapling，也用于验证 OCSP 响应。

ssl_conf_command¶

Syntax: ssl_conf_command name value;
Default: —
Context: http, server
@Since: 1.19.4

设置任意 OpenSSL 配置命令。

ssl_crl¶

Syntax: ssl_crl file;
Default: —
Context: http, server
@Since: 0.8.7

指定 PEM 格式吊销证书列表（CRL）文件，用于验证客户端证书。

ssl_dhparam¶

Syntax: ssl_dhparam file;
Default: —
Context: http, server
@Since: 0.7.2

指定 DHE 密码套件所用的 DH 参数文件。

ssl_early_data¶

Syntax: ssl_early_data on | off;
Default: ssl_early_data off;
Context: http, server
@Since: 1.15.3

启用或禁用 TLS 1.3 early data（0-RTT）。

ssl_ecdh_curve¶

Syntax: ssl_ecdh_curve curve;
Default: ssl_ecdh_curve auto;
Context: http, server
@Since: 1.1.0、1.0.6

指定 ECDHE 密码套件所用的椭圆曲线。

ssl_key_log¶

Syntax: ssl_key_log path;
Default: —
Context: http, server
@Since: 1.27.2

启用客户端连接 SSL 密钥日志，并指定密钥日志文件路径。密钥以与 Wireshark 兼容的 SSLKEYLOGFILE 格式记录。

ssl_ocsp¶

Syntax: ssl_ocsp on | off | leaf;
Default: ssl_ocsp off;
Context: http, server
@Since: 1.19.0

启用客户端证书链的 OCSP 校验。leaf 参数仅校验客户端叶证书。

ssl_ocsp_cache¶

Syntax: ssl_ocsp_cache off | [shared:name:size];
Default: ssl_ocsp_cache off;
Context: http, server
@Since: 1.19.0

设置用于 OCSP 校验时存放客户端证书状态的缓存名称与大小。缓存在所有 worker 进程间共享；同名缓存可在多个虚拟 server 中使用。

ssl_ocsp_responder¶

Syntax: ssl_ocsp_responder url;
Default: —
Context: http, server
@Since: 1.19.0

覆盖证书 “Authority Information Access” 扩展中指定的 OCSP 响应器 URL，用于校验客户端证书。

ssl_password_file¶

Syntax: ssl_password_file file;
Default: —
Context: http, server
@Since: 1.7.3

指定私钥口令文件，每行一个口令；加载密钥时依次尝试。

ssl_prefer_server_ciphers¶

Syntax: ssl_prefer_server_ciphers on | off;
Default: ssl_prefer_server_ciphers off;
Context: http, server
@Since: None

使用 SSLv3 与 TLS 协议时，指定优先采用服务端密码套件而非客户端提议的套件。

ssl_protocols¶

Syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: ssl_protocols TLSv1.2 TLSv1.3;
Context: http, server
@Since: None

启用指定的协议。

Note

生产环境仅启用 TLSv1.2 TLSv1.3，禁用 SSLv2/SSLv3/TLSv1/TLSv1.1 等已弃用协议；合规扫描（如 PCI、Mozilla 指南）通常要求如此。

ssl_reject_handshake¶

Syntax: ssl_reject_handshake on | off;
Default: ssl_reject_handshake off;
Context: http, server
@Since: 1.19.4

若启用，server 块中的 SSL 握手将被拒绝。

ssl_session_cache¶

Syntax: ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
Default: ssl_session_cache none;
Context: http, server
@Since: None

设置存放会话参数的缓存类型与大小。缓存可为下列类型之一：

Note

生产 HTTPS 站点建议启用共享会话缓存以减轻握手开销，例如 ssl_session_cache shared:SSL:10m;（大小按并发与 ssl_session_timeout 规划）。多 worker 须用 shared: 前缀；纯静态或极低 QPS 可保持 none。

ssl_session_ticket_key¶

Syntax: ssl_session_ticket_key file;
Default: —
Context: http, server
@Since: 1.5.7

指定用于加密与解密 TLS session ticket 的密钥文件。多台 server 须共享同一密钥时须配置本指令；默认使用随机生成的密钥。

ssl_session_tickets¶

Syntax: ssl_session_tickets on | off;
Default: ssl_session_tickets on;
Context: http, server
@Since: 1.5.9

启用或禁用通过 TLS session ticket 恢复会话。

ssl_session_timeout¶

Syntax: ssl_session_timeout time;
Default: ssl_session_timeout 5m;
Context: http, server
@Since: None

指定客户端可复用会话参数的时间上限。

ssl_stapling¶

Syntax: ssl_stapling on | off;
Default: ssl_stapling off;
Context: http, server
@Since: 1.3.7

启用或禁用由服务端装订（staple）OCSP 响应。示例：

ssl_stapling_file¶

Syntax: ssl_stapling_file file;
Default: —
Context: http, server
@Since: 1.3.7

配置后，装订的 OCSP 响应取自指定文件，而非向服务端证书中指定的 OCSP 响应器发起查询。

ssl_stapling_responder¶

Syntax: ssl_stapling_responder url;
Default: —
Context: http, server
@Since: 1.3.7

覆盖证书 “Authority Information Access” 扩展中指定的 OCSP 响应器 URL。

ssl_stapling_verify¶

Syntax: ssl_stapling_verify on | off;
Default: ssl_stapling_verify off;
Context: http, server
@Since: 1.3.7

启用或禁用服务端对 OCSP 响应的校验。

ssl_trusted_certificate¶

Syntax: ssl_trusted_certificate file;
Default: —
Context: http, server
@Since: 1.3.7

指定 PEM 格式受信 CA 证书文件，用于验证客户端证书；若启用 ssl_stapling，也用于验证 OCSP 响应。

ssl_verify_client¶

Syntax: ssl_verify_client on | off | optional | optional_no_ca;
Default: ssl_verify_client off;
Context: http, server
@Since: None

启用客户端证书校验。校验结果存入 $ssl_client_verify 变量。

ssl_verify_depth¶

Syntax: ssl_verify_depth number;
Default: ssl_verify_depth 1;
Context: http, server
@Since: None

设置客户端证书链的校验深度。

ngx_http_status_module¶

status¶

Syntax: status;
Default: —
Context: location
@Since: None

状态信息可在所在 location 访问。应限制对该 location 的访问。

Warning

与 stub_status 类似，/status 含 upstream/server 指标，生产环境须 allow/deny 或内网限制，勿对公网暴露。

status_format¶

Syntax: status_format json; status_format jsonp [callback];
Default: status_format json;
Context: http, server, location
@Since: None

默认以 JSON 格式输出状态信息。

[status] status_zone¶

Syntax: status_zone zone;
Default: —
Context: server
@Since: None

在指定 zone 中收集虚拟 http 或 stream（1.7.11）server 的状态信息。多个 server 可共享同一 zone。

ngx_http_stub_status_module¶

stub_status¶

Syntax: stub_status;
Default: —
Context: server, location
@Since: None

基本状态信息可在所在 location 访问。

Note

生产环境应对 /stub_status 做 allow/deny 或内网 IP 限制，勿对公网暴露。

ngx_http_sub_module¶

sub_filter¶

Syntax: sub_filter string replacement;
Default: —
Context: http, server, location
@Since: None

设置待替换字符串与替换字符串。匹配时忽略大小写。待替换串（1.9.4）与替换串可含变量。可在同一配置层级指定多条 sub_filter（1.9.4）。仅当当前层级未定义任何 sub_filter 时，才从上一级继承。

sub_filter_last_modified¶

Syntax: sub_filter_last_modified on | off;
Default: sub_filter_last_modified off;
Context: http, server, location
@Since: 1.5.1

允许在替换过程中保留原始响应的 “Last-Modified” 头，便于响应缓存。

sub_filter_once¶

Syntax: sub_filter_once on | off;
Default: sub_filter_once on;
Context: http, server, location
@Since: None

指示对每个待替换字符串仅查找一次还是重复查找。

sub_filter_types¶

Syntax: sub_filter_types mime-type ...;
Default: sub_filter_types text/html;
Context: http, server, location
@Since: None

除 “text/html” 外，对指定 MIME 类型的响应启用字符串替换。特殊值 “*” 匹配任意 MIME 类型（0.8.29）。

ngx_http_upstream_module¶

upstream¶

Syntax: upstream name { ... }
Default: —
Context: http
@Since: None

定义一组服务器。各服务器可监听不同端口；此外，监听 TCP 与 UNIX 域套接字的服务器可混用。

Note

生产环境若需动态增删后端、主动健康检查或跨 worker 共享状态，应在 upstream 内配置 zone，并配合 ngx_http_upstream_hc_module 等模块；修改后执行 nginx -t 再 reload。

[upstream] server¶

Syntax: server address [parameters];
Default: —
Context: upstream
@Since: None

定义服务器的地址及其他参数。地址可为域名或 IP（可选端口），或在 “unix:” 前缀后指定 UNIX 域套接字路径。未指定端口时使用 80。解析到多个 IP 的域名会一次性定义多台服务器。

zone¶

Syntax: zone name [size];
Default: —
Context: upstream
@Since: 1.9.0

定义共享内存区名称与大小，用于保存组配置及 worker 进程间共享的运行时状态。多个组可共用同一 zone；此时只需指定一次 size。

Note

启用 ngx_http_upstream_conf_module 动态配置或 upstream 健康检查时通常必须配置 zone；size 过小会导致状态写入失败，建议按后端数量与检查频率预留足够空间（常见起步 64k–256k）。

state¶

Syntax: state file;
Default: —
Context: upstream
@Since: 1.9.7

指定用于保存可动态配置组状态的文件。

hash key¶

Syntax: hash key [consistent];
Default: —
Context: upstream
@Since: 1.7.2

指定基于哈希键值的负载均衡方式，客户端与服务器的映射由键值哈希决定。键可含文本、变量及其组合。注意：向组内增删服务器可能导致大部分键被重新映射到不同服务器。该方法与 Cache::Memcached Perl 库兼容。

ip_hash¶

Syntax: ip_hash;
Default: —
Context: upstream
@Since: None

指定组使用基于客户端 IP 的负载均衡：请求按客户端 IP 分发。哈希键取 IPv4 地址前三段，或完整 IPv6 地址。同一客户端的请求会固定转发到同一台服务器，除非该服务器不可用；此时请求会转发到其他服务器，且多半仍会固定到同一台备用服务器。

keepalive¶

Syntax: keepalive connections;
Default: —
Context: upstream
@Since: 1.1.4

启用与上游服务器连接的缓存（连接池）。

Note

在 location 中使用 proxy_pass 指向该 upstream 时，须同时设置 proxy_http_version 1.1; 并清除 Connection 头（如 proxy_set_header Connection "";），否则 keepalive 不会生效。连接数应结合上游并发与 keepalive_timeout 调优，避免过少导致频繁建连、过多占用文件描述符。

[upstream] keepalive_requests¶

Syntax: keepalive_requests number;
Default: keepalive_requests 1000;
Context: upstream
@Since: 1.15.3

设置单条 keepalive 连接可服务的最大请求数；达到上限后连接关闭。

[upstream] keepalive_time¶

Syntax: keepalive_time time;
Default: keepalive_time 1h;
Context: upstream
@Since: 1.19.10

限制单条 keepalive 连接可处理请求的最长时间；超时后在下一次请求处理完毕时关闭连接。

[upstream] keepalive_timeout¶

Syntax: keepalive_timeout timeout;
Default: keepalive_timeout 60s;
Context: upstream
@Since: 1.15.3

设置上游 keepalive 连接在空闲状态下保持打开的超时时间。

ntlm¶

Syntax: ntlm;
Default: —
Context: upstream
@Since: 1.9.2

允许代理 NTLM 认证请求。当客户端发送的请求头 “Authorization” 以 “Negotiate” 或 “NTLM” 开头时，上游连接即绑定到该客户端连接；后续客户端请求经同一上游连接代理，以保持认证上下文。

least_conn¶

Syntax: least_conn;
Default: —
Context: upstream
@Since: 1.3.1、1.2.2

指定组使用最少连接负载均衡：请求转发到当前活跃连接数最少的服务器（计入 weight）。若多台服务器并列最少，则按带权轮询依次尝试。

least_time¶

Syntax: least_time header | last_byte [inflight];
Default: —
Context: upstream
@Since: 1.7.10

指定组使用最小响应时间负载均衡：请求转发到平均响应时间最短且活跃连接数最少的服务器（计入 weight）。若多台服务器并列，则按带权轮询依次尝试。

queue¶

Syntax: queue number [timeout=time];
Default: —
Context: upstream
@Since: 1.5.12

处理请求时若无法立即选出上游服务器，请求将进入队列。本指令指定队列中可同时存在的最大请求数。若队列已满，或在 timeout 指定时间内仍无法选出目标服务器，则向客户端返回 502（Bad Gateway）。

random¶

Syntax: random [two [method]];
Default: —
Context: upstream
@Since: 1.15.1

指定组使用随机负载均衡：请求转发到随机选中的服务器（计入 weight）。

[upstream] resolver¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: —
Context: upstream
@Since: 1.27.3

配置用于将上游服务器名称解析为地址的 DNS 服务器，例如：

[upstream] resolver_timeout¶

Syntax: resolver_timeout time;
Default: resolver_timeout 30s;
Context: upstream
@Since: 1.27.3

设置名称解析超时，例如：

sticky¶

Syntax: sticky cookie name [expires=time] [domain=domain] [httponly] [samesite=strict|lax|none|$variable] [secure] [path=path]; sticky route $variable ...; sticky learn create=$variable lookup=$variable zone=name:size [timeout=time] [header] [sync];
Default: —
Context: upstream
@Since: 1.5.7

启用会话亲和（session affinity），使同一客户端的请求固定转发到组内同一台服务器。提供三种方式：

sticky_cookie_insert¶

Syntax: sticky_cookie_insert name [expires=time] [domain=domain] [path=path];
Default: —
Context: upstream
@Since: None

自 1.5.7 起已废弃，应改用语法更新的等价 sticky 指令：

ngx_http_upstream_conf_module¶

upstream_conf¶

Syntax: upstream_conf;
Default: —
Context: location
@Since: None

在所在 location 启用 upstream 配置的 HTTP 接口。应限制对该 location 的访问。

Warning

动态 upstream 管理接口具备变更后端能力，须严格限制来源 IP 并配合认证；勿对公网开放。

ngx_http_upstream_hc_module¶

health_check¶

Syntax: health_check [parameters];
Default: —
Context: location
@Since: None

启用对所在 location 引用的 upstream 组内服务器的周期性健康检查。

Note

须与 zone 共享内存 upstream 配合；可配合 match 自定义探测响应校验。

match¶

Syntax: match name { ... }
Default: —
Context: http
@Since: None

定义用于校验健康检查请求响应的命名测试集。

ngx_http_userid_module¶

userid¶

Syntax: userid on | v1 | log | off;
Default: userid off;
Context: http, server, location
@Since: None

启用或禁用设置 cookie 及记录收到的 cookie：

userid_domain¶

Syntax: userid_domain name | none;
Default: userid_domain none;
Context: http, server, location
@Since: None

定义 cookie 的 Domain。参数 none 表示不设置 Domain。

userid_expires¶

Syntax: userid_expires time | max | off;
Default: userid_expires off;
Context: http, server, location
@Since: None

设置浏览器保留 cookie 的时长。max 使 cookie 在 “31 Dec 2037 23:55:55 GMT” 过期；off 使 cookie 在浏览器会话结束时过期。

userid_flags¶

Syntax: userid_flags off | flag ...;
Default: userid_flags off;
Context: http, server, location
@Since: 1.19.3

若非 off，则为 cookie 定义一个或多个附加标志：secure、httponly、samesite=strict、samesite=lax、samesite=none。

Note

生产环境 HTTPS 站点应至少启用 secure httponly，并按跨站需求配置 samesite。

userid_mark¶

Syntax: userid_mark letter | digit | = | off;
Default: userid_mark off;
Context: http, server, location
@Since: None

若非 off，则启用 cookie 标记机制并设置用作标记的字符。该机制用于在保留客户端标识的同时修改 userid_p3p 和/或 cookie 过期时间。标记可为英文字母（区分大小写）、数字或 “=”。

userid_name¶

Syntax: userid_name name;
Default: userid_name uid;
Context: http, server, location
@Since: None

设置 cookie 名称。

userid_p3p¶

Syntax: userid_p3p string | none;
Default: userid_p3p none;
Context: http, server, location
@Since: None

设置随 cookie 发送的 “P3P” 头字段值。特殊值 none 表示响应中不发送 “P3P” 头。

userid_path¶

Syntax: userid_path path;
Default: userid_path /;
Context: http, server, location
@Since: None

定义 cookie 的 Path。

userid_service¶

Syntax: userid_service number;
Default: userid_service IP address of the server;
Context: http, server, location
@Since: None

若标识由多台服务器（服务）签发，应为各服务分配独立编号以保证客户端标识唯一。v1 cookie 默认值为 0；v2 cookie 默认值为由服务器 IP 地址最后四段组成的数字。

ngx_http_uwsgi_module¶

uwsgi_bind¶

Syntax: uwsgi_bind address [transparent] | off;
Default: —
Context: http, server, location
@Since: None

使发往 uwsgi 服务器的出站连接从指定的本地 IP 地址（1.11.2 起可选端口）发起。参数值可含变量（1.3.12）。特殊值 off（1.3.12）取消从上一级继承的 uwsgi_bind 效果，由系统自动分配本地 IP 与端口。

uwsgi_buffer_size¶

Syntax: uwsgi_buffer_size size;
Default: uwsgi_buffer_size 4k|8k;
Context: http, server, location
@Since: None

设置用于读取 uwsgi 服务器响应首段的缓冲区大小；该段通常含较小的响应头。默认等于一个内存页，平台相关为 4K 或 8K，亦可改小。

uwsgi_buffering¶

Syntax: uwsgi_buffering on | off;
Default: uwsgi_buffering on;
Context: http, server, location
@Since: None

启用或禁用对 uwsgi 服务器响应的缓冲。

uwsgi_buffers¶

Syntax: uwsgi_buffers number size;
Default: uwsgi_buffers 8 4k|8k;
Context: http, server, location
@Since: None

设置单连接读取 uwsgi 服务器响应所用缓冲区的数量与大小。默认单缓冲等于一个内存页，平台相关为 4K 或 8K。

uwsgi_busy_buffers_size¶

Syntax: uwsgi_busy_buffers_size size;
Default: uwsgi_busy_buffers_size 8k|16k;
Context: http, server, location
@Since: None

启用 uwsgi 响应缓冲时，限制在响应尚未完全读入时、可向客户端发送响应的 busy 缓冲区总大小。其余缓冲区可用于读响应，必要时将部分响应缓冲至临时文件。默认上限约为 uwsgi_buffer_size 与 uwsgi_buffers 所设两个缓冲区的大小。

uwsgi_cache¶

Syntax: uwsgi_cache zone | off;
Default: uwsgi_cache off;
Context: http, server, location
@Since: None

定义用于缓存的共享内存区。同一 zone 可在多处使用。参数值可含变量（1.7.9）。参数 off 禁用从上一级继承的缓存。

uwsgi_cache_background_update¶

Syntax: uwsgi_cache_background_update on | off;
Default: uwsgi_cache_background_update off;
Context: http, server, location
@Since: 1.11.10

允许在向客户端返回过期缓存项的同时，启动后台子请求更新该项。须同时允许在更新过程中使用 stale 缓存响应。

uwsgi_cache_bypass¶

Syntax: uwsgi_cache_bypass string ...;
Default: —
Context: http, server, location
@Since: None

定义不从缓存取响应的条件。若任一字串参数值非空且不等于 “0”，则不从缓存取响应：

uwsgi_cache_key¶

Syntax: uwsgi_cache_key string;
Default: —
Context: http, server, location
@Since: None

定义缓存键，例如

uwsgi_cache_lock¶

Syntax: uwsgi_cache_lock on | off;
Default: uwsgi_cache_lock off;
Context: http, server, location
@Since: 1.1.12

启用时，按 uwsgi_cache_key 标识的新缓存项同一时刻仅允许一个请求向 uwsgi 服务器填充。同键其他请求将等待缓存中出现响应或锁释放，最长 uwsgi_cache_lock_timeout。

uwsgi_cache_lock_age¶

Syntax: uwsgi_cache_lock_age time;
Default: uwsgi_cache_lock_age 5s;
Context: http, server, location
@Since: 1.7.8

若填充新缓存项的最后一条发往 uwsgi 的请求在指定时间内未完成，可再向 uwsgi 发送一条请求。

uwsgi_cache_lock_timeout¶

Syntax: uwsgi_cache_lock_timeout time;
Default: uwsgi_cache_lock_timeout 5s;
Context: http, server, location
@Since: 1.1.12

设置 uwsgi_cache_lock 超时。超时后请求仍会发往 uwsgi，但响应不会写入缓存。

uwsgi_cache_max_range_offset¶

Syntax: uwsgi_cache_max_range_offset number;
Default: —
Context: http, server, location
@Since: 1.11.6

设置字节范围（byte-range）请求的偏移上限（字节）。若请求范围超出该偏移，范围请求将发往 uwsgi 服务器且响应不会被缓存。

uwsgi_cache_methods¶

Syntax: uwsgi_cache_methods GET | HEAD | POST ...;
Default: uwsgi_cache_methods GET HEAD;
Context: http, server, location
@Since: None

若客户端请求方法列在本指令中，则缓存响应。“GET” 与 “HEAD” 始终加入列表，仍建议显式写出。另见 uwsgi_no_cache。

uwsgi_cache_min_uses¶

Syntax: uwsgi_cache_min_uses number;
Default: uwsgi_cache_min_uses 1;
Context: http, server, location
@Since: None

设置响应被缓存前需收到的请求次数。

uwsgi_cache_path¶

Syntax: uwsgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default: —
Context: http
@Since: None

设置 uwsgi 缓存路径及其他参数。缓存数据存于文件；键与文件名均为对缓存键做 MD5 的结果。levels 定义缓存目录层级（1–3 级，每级取值 1 或 2）。例如下列配置

uwsgi_cache_purge¶

Syntax: uwsgi_cache_purge string ...;
Default: —
Context: http, server, location
@Since: 1.5.7

定义将请求视为缓存清除（purge）请求的条件。若字符串参数中至少有一个值非空且不等于 “0”，则删除对应缓存键的缓存项。成功时返回 204（No Content）。

uwsgi_cache_revalidate¶

Syntax: uwsgi_cache_revalidate on | off;
Default: uwsgi_cache_revalidate off;
Context: http, server, location
@Since: 1.5.7

启用后，对过期缓存项使用带 “If-Modified-Since” 与 “If-None-Match” 头的条件请求进行再验证。

uwsgi_cache_use_stale¶

Syntax: uwsgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off ...;
Default: uwsgi_cache_use_stale off;
Context: http, server, location
@Since: None

确定在与 uwsgi 服务器通信出错时，哪些情况下可使用陈旧缓存响应。本指令参数与 uwsgi_next_upstream 相同。

uwsgi_cache_valid¶

Syntax: uwsgi_cache_valid [code ...] time;
Default: —
Context: http, server, location
@Since: None

为不同响应码设置缓存时间。例如下列指令

uwsgi_connect_timeout¶

Syntax: uwsgi_connect_timeout time;
Default: uwsgi_connect_timeout 60s;
Context: http, server, location
@Since: None

定义与 uwsgi 服务器 建立连接 的超时。通常该值不能超过 75 秒。

uwsgi_force_ranges¶

Syntax: uwsgi_force_ranges on | off;
Default: uwsgi_force_ranges off;
Context: http, server, location
@Since: 1.7.7

无论 uwsgi 响应是否含 “Accept-Ranges” 头，均为缓存与未缓存响应启用字节范围（byte-range）支持。

uwsgi_hide_header¶

Syntax: uwsgi_hide_header field;
Default: —
Context: http, server, location
@Since: None

默认情况下，nginx 不会将 uwsgi 响应中的 “Status” 与 “X-Accel-...” 头传给客户端。uwsgi_hide_header 可追加不传递的头字段。若需允许传递，可使用 uwsgi_pass_header。

uwsgi_ignore_client_abort¶

Syntax: uwsgi_ignore_client_abort on | off;
Default: uwsgi_ignore_client_abort off;
Context: http, server, location
@Since: None

决定客户端未等待响应即断开时，是否同时关闭与 uwsgi 服务器的连接。

uwsgi_ignore_headers¶

Syntax: uwsgi_ignore_headers field ...;
Default: —
Context: http, server, location
@Since: None

禁用对 uwsgi 服务器响应中某些头字段的处理。可忽略：“X-Accel-Redirect”、“X-Accel-Expires”、“X-Accel-Limit-Rate”（1.1.6）、“X-Accel-Buffering”（1.1.6）、“X-Accel-Charset”（1.1.6）、“Expires”、“Cache-Control”、“Set-Cookie”（0.8.44）、“Vary”（1.7.7）。

uwsgi_intercept_errors¶

Syntax: uwsgi_intercept_errors on | off;
Default: uwsgi_intercept_errors off;
Context: http, server, location
@Since: None

决定 uwsgi 响应码 ≥ 300 时直接返回客户端，还是由 nginx 拦截并通过 error_page 处理。

uwsgi_limit_rate¶

Syntax: uwsgi_limit_rate rate;
Default: uwsgi_limit_rate 0;
Context: http, server, location
@Since: 1.7.7

限制从 uwsgi 服务器读取响应的速率（字节/秒）。0 表示不限速。限速按 单请求 计；若 nginx 同时打开两条 uwsgi 连接，总速率约为设定值的两倍。仅当启用 uwsgi 响应缓冲时生效。参数值可含变量（1.27.0）。

uwsgi_max_temp_file_size¶

Syntax: uwsgi_max_temp_file_size size;
Default: uwsgi_max_temp_file_size 1024m;
Context: http, server, location
@Since: None

启用 uwsgi 响应缓冲且整段响应无法放入 uwsgi_buffer_size 与 uwsgi_buffers 时，部分响应可写入临时文件。本指令设置临时文件最大尺寸；单次写入量由 uwsgi_temp_file_write_size 控制。

uwsgi_modifier1¶

Syntax: uwsgi_modifier1 number;
Default: uwsgi_modifier1 0;
Context: http, server, location
@Since: None

设置 uwsgi 包头 modifier1 字段的值。

uwsgi_modifier2¶

Syntax: uwsgi_modifier2 number;
Default: uwsgi_modifier2 0;
Context: http, server, location
@Since: None

设置 uwsgi 包头 modifier2 字段的值。

uwsgi_next_upstream¶

Syntax: uwsgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default: uwsgi_next_upstream error timeout;
Context: http, server, location
@Since: None

指定在哪些情况下将请求转发至下一台服务器：

uwsgi_next_upstream_timeout¶

Syntax: uwsgi_next_upstream_timeout time;
Default: uwsgi_next_upstream_timeout 0;
Context: http, server, location
@Since: 1.7.5

限制可将请求转发至下一台服务器的最长时间。0 表示不限制。

uwsgi_next_upstream_tries¶

Syntax: uwsgi_next_upstream_tries number;
Default: uwsgi_next_upstream_tries 0;
Context: http, server, location
@Since: 1.7.5

限制转发至下一台服务器的最大尝试次数。0 表示不限制。

uwsgi_no_cache¶

Syntax: uwsgi_no_cache string ...;
Default: —
Context: http, server, location
@Since: None

定义不将响应写入缓存的条件。若任一字串参数值非空且不等于 “0”，则不保存：

uwsgi_param parameter¶

Syntax: uwsgi_param parameter value [if_not_empty];
Default: —
Context: http, server, location
@Since: None

设置应传给 uwsgi 服务器的参数。值可含文本、变量及其组合。仅当当前层级未定义任何 uwsgi_param 时，才从上一级继承。

uwsgi_pass¶

Syntax: uwsgi_pass [protocol://]address;
Default: —
Context: location, if in location
@Since: None

设置 uwsgi 服务器的协议与地址。协议可为 uwsgi 或 suwsgi（安全 uwsgi，即 uwsgi over SSL）。地址可指定为域名或 IP，并可选端口：

Note

Python/Django 场景常用 uwsgi_pass + uwsgi_param UWSGI_*；指向 upstream 时使用 uwsgi_pass upstream_name;。suwsgi:// 须配合 uwsgi_ssl_* 指令。

uwsgi_pass_header¶

Syntax: uwsgi_pass_header field;
Default: —
Context: http, server, location
@Since: None

允许传递本会被禁用的、来自 uwsgi 服务器的头字段。

uwsgi_pass_request_body¶

Syntax: uwsgi_pass_request_body on | off;
Default: uwsgi_pass_request_body on;
Context: http, server, location
@Since: None

指示是否将原始请求体转发至 uwsgi 服务器。另见 uwsgi_pass_request_headers。

uwsgi_pass_request_headers¶

Syntax: uwsgi_pass_request_headers on | off;
Default: uwsgi_pass_request_headers on;
Context: http, server, location
@Since: None

指示是否将原始请求头转发至 uwsgi 服务器。另见 uwsgi_pass_request_body。

uwsgi_read_timeout¶

Syntax: uwsgi_read_timeout time;
Default: uwsgi_read_timeout 60s;
Context: http, server, location
@Since: None

定义从 uwsgi 服务器读取响应的超时。计时仅在 两次连续读操作之间 ，而非整段响应传输。若在此时间内 uwsgi 未发送任何数据，则关闭连接。

uwsgi_request_buffering¶

Syntax: uwsgi_request_buffering on | off;
Default: uwsgi_request_buffering on;
Context: http, server, location
@Since: 1.7.11

启用或禁用客户端请求体缓冲。

uwsgi_send_timeout¶

Syntax: uwsgi_send_timeout time;
Default: uwsgi_send_timeout 60s;
Context: http, server, location
@Since: None

设置向 uwsgi 服务器传输请求的超时。计时仅在 两次连续写操作之间 ，而非整段请求传输。若在此时间内 uwsgi 未收到任何数据，则关闭连接。

uwsgi_socket_keepalive¶

Syntax: uwsgi_socket_keepalive on | off;
Default: uwsgi_socket_keepalive off;
Context: http, server, location
@Since: 1.15.6

配置至 uwsgi 服务器出站连接的 “TCP keepalive” 行为。默认使用操作系统套接字设置。设为 on 时为套接字启用 SO_KEEPALIVE 选项。

uwsgi_ssl_certificate¶

Syntax: uwsgi_ssl_certificate file;
Default: —
Context: http, server, location
@Since: 1.7.8

指定用于向安全 uwsgi 服务器认证的 PEM 格式证书文件。

uwsgi_ssl_certificate_cache¶

Syntax: uwsgi_ssl_certificate_cache off; uwsgi_ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: uwsgi_ssl_certificate_cache off;
Context: http, server, location
@Since: 1.27.4

定义缓存，用于存放以变量指定的 SSL 证书与私钥。

uwsgi_ssl_certificate_key¶

Syntax: uwsgi_ssl_certificate_key file;
Default: —
Context: http, server, location
@Since: 1.7.8

指定用于向安全 uwsgi 服务器认证的 PEM 格式私钥文件。

uwsgi_ssl_ciphers¶

Syntax: uwsgi_ssl_ciphers ciphers;
Default: uwsgi_ssl_ciphers DEFAULT;
Context: http, server, location
@Since: 1.5.8

指定访问安全 uwsgi 服务器时启用的密码套件；格式为 OpenSSL 可识别的写法。

uwsgi_ssl_conf_command¶

Syntax: uwsgi_ssl_conf_command name value;
Default: —
Context: http, server, location
@Since: 1.19.4

在与安全 uwsgi 服务器建立连接时设置任意 OpenSSL 配置命令。

uwsgi_ssl_crl¶

Syntax: uwsgi_ssl_crl file;
Default: —
Context: http, server, location
@Since: 1.7.0

指定 PEM 格式吊销证书列表（CRL）文件，用于验证安全 uwsgi 服务器证书。

uwsgi_ssl_key_log¶

Syntax: uwsgi_ssl_key_log path;
Default: —
Context: http, server, location
@Since: 1.27.2

启用安全 uwsgi 连接密钥日志，并指定密钥日志文件路径。密钥以与 Wireshark 兼容的 SSLKEYLOGFILE 格式记录。

uwsgi_ssl_name¶

Syntax: uwsgi_ssl_name name;
Default: uwsgi_ssl_name host from uwsgi_pass;
Context: http, server, location
@Since: 1.7.0

允许覆盖用于验证安全 uwsgi 服务器证书的服务器名，以及通过 SNI 建立连接时传递的名称。

uwsgi_ssl_password_file¶

Syntax: uwsgi_ssl_password_file file;
Default: —
Context: http, server, location
@Since: 1.7.8

指定私钥口令文件，每行一个口令；加载密钥时依次尝试。

uwsgi_ssl_protocols¶

Syntax: uwsgi_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: uwsgi_ssl_protocols TLSv1.2 TLSv1.3;
Context: http, server, location
@Since: 1.5.8

启用访问安全 uwsgi 服务器时允许的协议。

uwsgi_ssl_server_name¶

Syntax: uwsgi_ssl_server_name on | off;
Default: uwsgi_ssl_server_name off;
Context: http, server, location
@Since: 1.7.0

启用或禁用在与安全 uwsgi 服务器建立连接时通过 TLS 服务器名称指示（SNI，RFC 6066）传递服务器名。

uwsgi_ssl_session_reuse¶

Syntax: uwsgi_ssl_session_reuse on | off;
Default: uwsgi_ssl_session_reuse on;
Context: http, server, location
@Since: 1.5.8

确定是否可复用与安全 uwsgi 服务器通信时的 SSL 会话。若日志出现 “digest check failed”，可尝试关闭会话复用。

uwsgi_ssl_trusted_certificate¶

Syntax: uwsgi_ssl_trusted_certificate file;
Default: —
Context: http, server, location
@Since: 1.7.0

指定 PEM 格式可信 CA 证书文件，用于验证安全 uwsgi 服务器证书。

uwsgi_ssl_verify¶

Syntax: uwsgi_ssl_verify on | off;
Default: uwsgi_ssl_verify off;
Context: http, server, location
@Since: 1.7.0

启用或禁用对安全 uwsgi 服务器证书的验证。

Note

生产环境访问 suwsgi:// 后端应启用 uwsgi_ssl_verify on 并配置 uwsgi_ssl_trusted_certificate。

uwsgi_ssl_verify_depth¶

Syntax: uwsgi_ssl_verify_depth number;
Default: uwsgi_ssl_verify_depth 1;
Context: http, server, location
@Since: 1.7.0

设置安全 uwsgi 服务器证书链的验证深度。

uwsgi_store¶

Syntax: uwsgi_store on | off | string;
Default: uwsgi_store off;
Context: http, server, location
@Since: None

启用将文件保存至磁盘。参数 on 时按 alias 或 root 对应路径保存；off 禁用。亦可用含变量的字符串显式指定文件名：

uwsgi_store_access¶

Syntax: uwsgi_store_access users:permissions ...;
Default: uwsgi_store_access user:rw;
Context: http, server, location
@Since: None

设置新建文件与目录的访问权限，例如：

uwsgi_temp_file_write_size¶

Syntax: uwsgi_temp_file_write_size size;
Default: uwsgi_temp_file_write_size 8k|16k;
Context: http, server, location
@Since: None

启用将 uwsgi 响应缓冲至临时文件时，限制每次写入临时文件的数据量。默认上限约为 uwsgi_buffer_size 与 uwsgi_buffers 所设两个缓冲区的大小。临时文件最大尺寸由 uwsgi_max_temp_file_size 设置。

uwsgi_temp_path¶

Syntax: uwsgi_temp_path path [level1 [level2 [level3]]];
Default: uwsgi_temp_path uwsgi_temp;
Context: http, server, location
@Since: None

定义存放从 uwsgi 服务器接收数据的临时文件目录。可在指定目录下使用最多三级子目录层次。例如下列配置

ngx_http_v2_module¶

http2¶

Syntax: http2 on | off;
Default: http2 off;
Context: http, server
@Since: 1.25.1

启用 HTTP/2 协议。

Note

1.25.1+ 推荐在 listen 上使用 http2 参数（如 listen 443 ssl http2;），而非单独依赖本指令；启用后须确认 TLS 与 ALPN 配置正确。

http2_body_preread_size¶

Syntax: http2_body_preread_size size;
Default: http2_body_preread_size 64k;
Context: http, server
@Since: 1.11.0

设置每个请求在开始处理前可缓存请求体的缓冲区大小。

http2_chunk_size¶

Syntax: http2_chunk_size size;
Default: http2_chunk_size 8k;
Context: http, server, location
@Since: None

设置响应体切分块的最大大小。过小会增加开销；过大则会因 HOL 阻塞削弱优先级调度。

http2_idle_timeout¶

Syntax: http2_idle_timeout time;
Default: http2_idle_timeout 3m;
Context: http, server
@Since: None

None

http2_max_concurrent_pushes¶

Syntax: http2_max_concurrent_pushes number;
Default: http2_max_concurrent_pushes 10;
Context: http, server
@Since: 1.13.9

None

http2_max_concurrent_streams¶

Syntax: http2_max_concurrent_streams number;
Default: http2_max_concurrent_streams 128;
Context: http, server
@Since: None

设置单连接内并发 HTTP/2 流的最大数量。

http2_max_field_size¶

Syntax: http2_max_field_size size;
Default: http2_max_field_size 4k;
Context: http, server
@Since: None

None

http2_max_header_size¶

Syntax: http2_max_header_size size;
Default: http2_max_header_size 16k;
Context: http, server
@Since: None

None

http2_max_requests¶

Syntax: http2_max_requests number;
Default: http2_max_requests 1000;
Context: http, server
@Since: 1.11.6

None

http2_push¶

Syntax: http2_push uri | off;
Default: http2_push off;
Context: http, server, location
@Since: 1.13.9

None

http2_push_preload¶

Syntax: http2_push_preload on | off;
Default: http2_push_preload off;
Context: http, server, location
@Since: 1.13.9

None

http2_recv_buffer_size¶

Syntax: http2_recv_buffer_size size;
Default: http2_recv_buffer_size 256k;
Context: http
@Since: None

设置每个 worker 的输入缓冲区大小。

http2_recv_timeout¶

Syntax: http2_recv_timeout time;
Default: http2_recv_timeout 30s;
Context: http, server
@Since: None

None

ngx_http_v3_module¶

http3¶

Syntax: http3 on | off;
Default: http3 on;
Context: http, server
@Since: None

启用 HTTP/3 协议协商。

Note

HTTP/3 基于 QUIC，须在 listen 上配置 quic/reuseport 并配合 TLS 1.3；防火墙须放行 UDP 443。

http3_hq¶

Syntax: http3_hq on | off;
Default: http3_hq off;
Context: http, server
@Since: None

启用 QUIC 互操作测试所用的 HTTP/0.9 协议协商。

http3_max_concurrent_streams¶

Syntax: http3_max_concurrent_streams number;
Default: http3_max_concurrent_streams 128;
Context: http, server
@Since: None

设置单连接内并发 HTTP/3 请求流的最大数量。

http3_stream_buffer_size¶

Syntax: http3_stream_buffer_size size;
Default: http3_stream_buffer_size 64k;
Context: http, server
@Since: None

设置读写 QUIC 流所用缓冲区的大小。

quic_active_connection_id_limit¶

Syntax: quic_active_connection_id_limit number;
Default: quic_active_connection_id_limit 2;
Context: http, server
@Since: None

设置 QUIC active_connection_id_limit 传输参数，即服务端可存储的客户端连接 ID 最大数量。

quic_bpf¶

Syntax: quic_bpf on | off;
Default: quic_bpf off;
Context: main
@Since: None

启用通过 eBPF 路由 QUIC 数据包；启用后可支持 QUIC 连接迁移。

quic_gso¶

Syntax: quic_gso on | off;
Default: quic_gso off;
Context: http, server
@Since: None

启用使用分段卸载（segmentation offloading）的优化批量发送模式。

quic_host_key¶

Syntax: quic_host_key file;
Default: —
Context: http, server
@Since: None

设置用于加密无状态重置与地址验证令牌的秘密密钥文件。默认每次 reload 生成随机密钥；旧密钥签发的令牌将不再被接受。

quic_retry¶

Syntax: quic_retry on | off;
Default: quic_retry off;
Context: http, server
@Since: None

启用 QUIC 地址验证：在 Retry 包或 NEW_TOKEN 帧中发送新令牌，并校验 Initial 包中收到的令牌。

ngx_http_xslt_module¶

xml_entities¶

Syntax: xml_entities path;
Default: —
Context: http, server, location
@Since: None

指定声明字符实体的 DTD 文件。该文件在配置阶段编译。因技术原因，模块无法使用被处理 XML 中声明的外部子集，故忽略之并使用专门定义的文件。该文件无需描述 XML 结构，仅声明所需字符实体即可，例如：

xslt_last_modified¶

Syntax: xslt_last_modified on | off;
Default: xslt_last_modified off;
Context: http, server, location
@Since: 1.5.1

允许在 XSLT 变换过程中保留原始响应的 “Last-Modified” 头，便于响应缓存。

xslt_param parameter¶

Syntax: xslt_param parameter value;
Default: —
Context: http, server, location
@Since: 1.1.18

定义 XSLT 样式表参数。值按 XPath 表达式处理，可含变量。若需向样式表传递字符串值，可使用 xslt_string_param。

xslt_string_param parameter¶

Syntax: xslt_string_param parameter value;
Default: —
Context: http, server, location
@Since: 1.1.18

定义 XSLT 样式表的字符串参数。值中的 XPath 表达式不会被解析。值可含变量。

xslt_stylesheet¶

Syntax: xslt_stylesheet stylesheet [parameter=value ...];
Default: —
Context: location
@Since: None

定义 XSLT 样式表及其可选参数。样式表在配置阶段编译。

xslt_types¶

Syntax: xslt_types mime-type ...;
Default: xslt_types text/xml;
Context: http, server, location
@Since: None

除 “text/xml” 外，对指定 MIME 类型的响应启用变换。特殊值 “*” 匹配任意 MIME 类型（0.8.29）。若变换结果为 HTML 响应，其 MIME 类型将改为 “text/html”。

ngx_mail_core_module¶

listen¶

Syntax: listen address:port [ssl] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [bind] [ipv6only=on|off] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Default: —
Context: server
@Since: None

设置 mail server 接受请求的套接字地址与端口。可仅指定端口；地址也可为 hostname，例如：

Note

1.25.1+ 使用 listen 的 ssl 参数启用 TLS（如 listen 993 ssl;），勿再依赖已移除的 [mail] ssl 指令。

mail¶

Syntax: mail { ... }
Default: —
Context: main
@Since: None

提供 mail server 指令的配置文件上下文。

max_errors¶

Syntax: max_errors number;
Default: max_errors 5;
Context: mail, server
@Since: 1.21.0

设置触发关闭连接的协议错误次数。

protocol¶

Syntax: protocol imap | pop3 | smtp;
Default: —
Context: server
@Since: None

设置被代理服务器的协议。支持 IMAP、POP3、SMTP。

[mail] resolver¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone]; resolver off;
Default: resolver off;
Context: mail, server
@Since: None

配置用于解析客户端 hostname（传给认证服务器）及 SMTP 代理时 XCLIENT 命令的 DNS 服务器，例如：

[mail] resolver_timeout¶

Syntax: resolver_timeout time;
Default: resolver_timeout 30s;
Context: mail, server
@Since: None

设置 DNS 操作超时，例如：

[mail] server¶

Syntax: server { ... }
Default: —
Context: mail
@Since: None

设置 server 配置。

[mail] server_name¶

Syntax: server_name name;
Default: server_name hostname;
Context: mail, server
@Since: None

设置使用的 server 名称：

[mail] timeout¶

Syntax: timeout time;
Default: timeout 60s;
Context: mail, server
@Since: None

设置开始代理至后端之前的超时。

ngx_mail_auth_http_module¶

auth_http¶

Syntax: auth_http URL;
Default: —
Context: mail, server
@Since: None

设置 HTTP 认证服务器的 URL。协议说明见下文。

Note

认证服务应内网可达，并配合 auth_http_header 共享密钥校验请求来源。

auth_http_header¶

Syntax: auth_http_header header value;
Default: —
Context: mail, server
@Since: None

向发往认证服务器的请求追加指定头。该头可用作共享密钥，验证请求来自 nginx，例如：

auth_http_pass_client_cert¶

Syntax: auth_http_pass_client_cert on | off;
Default: auth_http_pass_client_cert off;
Context: mail, server
@Since: 1.7.11

向发往认证服务器的请求追加 “Auth-SSL-Cert” 头，值为 URL 编码的 PEM 格式客户端证书。

auth_http_timeout¶

Syntax: auth_http_timeout time;
Default: auth_http_timeout 60s;
Context: mail, server
@Since: None

设置与认证服务器通信的超时。

ngx_mail_proxy_module¶

proxy_buffer¶

Syntax: proxy_buffer size;
Default: proxy_buffer 4k|8k;
Context: mail, server
@Since: None

设置代理所用缓冲区大小。默认等于一个内存页，平台相关为 4K 或 8K。

proxy_pass_error_message¶

Syntax: proxy_pass_error_message on | off;
Default: proxy_pass_error_message off;
Context: mail, server
@Since: None

指示是否将后端认证期间获得的错误消息传给客户端。

proxy_protocol¶

Syntax: proxy_protocol on | off;
Default: proxy_protocol off;
Context: mail, server
@Since: 1.19.8

为至后端的连接启用 PROXY protocol。

proxy_smtp_auth¶

Syntax: proxy_smtp_auth on | off;
Default: proxy_smtp_auth off;
Context: mail, server
@Since: 1.19.4

启用或禁用使用 AUTH 命令对 SMTP 后端进行用户认证。

proxy_timeout¶

Syntax: proxy_timeout timeout;
Default: proxy_timeout 24h;
Context: mail, server
@Since: None

设置客户端或被代理服务器连接上两次连续读/写操作之间的超时。若在此时间内无数据传输，则关闭连接。

xclient¶

Syntax: xclient on | off;
Default: xclient on;
Context: mail, server
@Since: None

启用或禁用在连接 SMTP 后端时发送带客户端参数的 XCLIENT 命令。

ngx_mail_realip_module¶

[mail] set_real_ip_from¶

Syntax: set_real_ip_from address | CIDR | unix:;
Default: —
Context: mail, server
@Since: None

定义已知会发送正确替换地址的可信地址。特殊值 unix: 表示信任所有 UNIX 域套接字。

ngx_mail_ssl_module¶

[mail] ssl¶

Syntax: ssl on | off;
Default: ssl off;
Context: mail, server
@Since: None

该指令在 1.15.0 已废弃，1.25.1 已移除；应改用 listen 的 ssl 参数。

[mail] ssl_certificate¶

Syntax: ssl_certificate file;
Default: —
Context: mail, server
@Since: None

为指定 server 指定 PEM 格式证书文件。除主证书外若需指定中间证书，应写入同一文件，顺序为：主证书在前，中间证书在后。PEM 格式私钥也可放在同一文件中。

[mail] ssl_certificate_key¶

Syntax: ssl_certificate_key file;
Default: —
Context: mail, server
@Since: None

为指定 server 指定 PEM 格式私钥文件。

[mail] ssl_ciphers¶

Syntax: ssl_ciphers ciphers;
Default: ssl_ciphers HIGH:!aNULL:!MD5;
Context: mail, server
@Since: None

指定启用的密码套件；格式为 OpenSSL 可识别的写法，例如：

[mail] ssl_client_certificate¶

Syntax: ssl_client_certificate file;
Default: —
Context: mail, server
@Since: 1.7.11

指定 PEM 格式受信 CA 证书文件，用于验证客户端证书。

[mail] ssl_conf_command¶

Syntax: ssl_conf_command name value;
Default: —
Context: mail, server
@Since: 1.19.4

设置任意 OpenSSL 配置命令。

[mail] ssl_crl¶

Syntax: ssl_crl file;
Default: —
Context: mail, server
@Since: 1.7.11

指定 PEM 格式吊销证书列表（CRL）文件，用于验证客户端证书。

[mail] ssl_dhparam¶

Syntax: ssl_dhparam file;
Default: —
Context: mail, server
@Since: 0.7.2

指定 DHE 密码套件所用的 DH 参数文件。

[mail] ssl_ecdh_curve¶

Syntax: ssl_ecdh_curve curve;
Default: ssl_ecdh_curve auto;
Context: mail, server
@Since: 1.1.0、1.0.6

指定 ECDHE 密码套件所用的椭圆曲线。

[mail] ssl_password_file¶

Syntax: ssl_password_file file;
Default: —
Context: mail, server
@Since: 1.7.3

指定私钥口令文件，每行一个口令；加载密钥时依次尝试。

[mail] ssl_prefer_server_ciphers¶

Syntax: ssl_prefer_server_ciphers on | off;
Default: ssl_prefer_server_ciphers off;
Context: mail, server
@Since: None

使用 SSLv3 与 TLS 时，指定是否优先采用 server 端密码套件。

[mail] ssl_protocols¶

Syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: ssl_protocols TLSv1.2 TLSv1.3;
Context: mail, server
@Since: None

启用指定的协议。

[mail] ssl_session_cache¶

Syntax: ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
Default: ssl_session_cache none;
Context: mail, server
@Since: None

设置存储 session 参数的缓存类型与大小。缓存可为下列类型之一：

[mail] ssl_session_ticket_key¶

Syntax: ssl_session_ticket_key file;
Default: —
Context: mail, server
@Since: 1.5.7

设置用于加解密 TLS session ticket 的密钥文件。多台 server 需共享同一密钥时必须配置；默认每次使用随机生成的密钥。

[mail] ssl_session_tickets¶

Syntax: ssl_session_tickets on | off;
Default: ssl_session_tickets on;
Context: mail, server
@Since: 1.5.9

启用或禁用通过 TLS session ticket 恢复 session。

[mail] ssl_session_timeout¶

Syntax: ssl_session_timeout time;
Default: ssl_session_timeout 5m;
Context: mail, server
@Since: None

指定客户端可复用 session 参数的时长。

[mail] ssl_trusted_certificate¶

Syntax: ssl_trusted_certificate file;
Default: —
Context: mail, server
@Since: 1.7.11

指定 PEM 格式可信 CA 证书文件，用于验证客户端证书。

[mail] ssl_verify_client¶

Syntax: ssl_verify_client on | off | optional | optional_no_ca;
Default: ssl_verify_client off;
Context: mail, server
@Since: 1.7.11

启用客户端证书验证。验证结果通过认证请求的 “Auth-SSL-Verify” 头传递。

[mail] ssl_verify_depth¶

Syntax: ssl_verify_depth number;
Default: ssl_verify_depth 1;
Context: mail, server
@Since: 1.7.11

设置客户端证书链的校验深度。

[mail] starttls¶

Syntax: starttls on | off | only;
Default: starttls off;
Context: mail, server
@Since: None

None

ngx_mail_imap_module¶

[mail] imap_auth¶

Syntax: imap_auth method ...;
Default: imap_auth plain;
Context: mail, server
@Since: None

设置 IMAP 客户端允许的认证方法。支持的方法有：

[mail] imap_capabilities¶

Syntax: imap_capabilities extension ...;
Default: imap_capabilities IMAP4 IMAP4rev1 UIDPLUS;
Context: mail, server
@Since: None

设置 CAPABILITY 命令响应中返回的 IMAP 协议扩展列表。imap_auth 指定的认证方法及 STARTTLS 会依 starttls 值自动加入列表。

[mail] imap_client_buffer¶

Syntax: imap_client_buffer size;
Default: imap_client_buffer 4k|8k;
Context: mail, server
@Since: None

设置读取 IMAP 命令所用缓冲区大小。默认等于一个内存页，平台相关为 4K 或 8K。

ngx_mail_pop3_module¶

pop3_auth¶

Syntax: pop3_auth method ...;
Default: pop3_auth plain;
Context: mail, server
@Since: None

设置 POP3 客户端允许的认证方法。支持的方法有：

pop3_capabilities¶

Syntax: pop3_capabilities extension ...;
Default: pop3_capabilities TOP USER UIDL;
Context: mail, server
@Since: None

设置 CAPA 命令响应中返回的 POP3 协议扩展列表。pop3_auth 指定的认证方法（SASL 扩展）及 STLS 会依 starttls 值自动加入列表。

ngx_mail_smtp_module¶

smtp_auth¶

Syntax: smtp_auth method ...;
Default: smtp_auth plain login;
Context: mail, server
@Since: None

设置 SMTP 客户端允许的 SASL 认证方法。支持的方法有：

smtp_capabilities¶

Syntax: smtp_capabilities extension ...;
Default: —
Context: mail, server
@Since: None

设置 EHLO 命令响应中返回的 SMTP 协议扩展列表。smtp_auth 指定的认证方法及 STARTTLS 会依 starttls 值自动加入列表。

smtp_client_buffer¶

Syntax: smtp_client_buffer size;
Default: smtp_client_buffer 4k|8k;
Context: mail, server
@Since: None

设置读取 SMTP 命令所用缓冲区大小。默认等于一个内存页，平台相关为 4K 或 8K。

smtp_greeting_delay¶

Syntax: smtp_greeting_delay time;
Default: smtp_greeting_delay 0;
Context: mail, server
@Since: None

允许在发送 SMTP 问候语前设置延迟，以拒绝未等待问候语即发送 SMTP 命令的客户端。

ngx_stream_core_module¶

[stream] listen¶

Syntax: listen address:port [default_server] [ssl] [udp] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Default: —
Context: server
@Since: None

设置 stream server 接受连接的套接字地址与端口。可仅指定端口；地址也可为 hostname，例如：

Note

TCP/UDP 四层代理常用 listen 443 ssl; 或 listen 53 udp reuseport;；HTTP/3 同端口需 udp + quic（见 http3）。

preread_buffer_size¶

Syntax: preread_buffer_size size;
Default: preread_buffer_size 16k;
Context: stream, server
@Since: 1.11.5

设置 preread 缓冲区大小。

preread_timeout¶

Syntax: preread_timeout timeout;
Default: preread_timeout 30s;
Context: stream, server
@Since: 1.11.5

设置 preread 阶段超时。

proxy_protocol_timeout¶

Syntax: proxy_protocol_timeout timeout;
Default: proxy_protocol_timeout 30s;
Context: stream, server
@Since: 1.11.4

设置读取 PROXY protocol 头完成的超时。若在此时间内未传完整头，则关闭连接。

[stream] resolver¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: —
Context: stream, server
@Since: 1.11.3

配置用于将上游服务器名解析为地址的 DNS 服务器，例如：

[stream] resolver_timeout¶

Syntax: resolver_timeout time;
Default: resolver_timeout 30s;
Context: stream, server
@Since: 1.11.3

设置名称解析超时，例如：

[stream] server¶

Syntax: server { ... }
Default: —
Context: stream
@Since: None

设置虚拟 server 配置。基于 IP 的虚拟 server（按 IP 地址）与基于名称的虚拟 server（按 TLS SNI，RFC 6066）（1.25.5）并无清晰分界；由 listen 描述 server 应接受连接的所有地址与端口，server_name 列出所有 server 名称。

[stream] server_name¶

Syntax: server_name name ...;
Default: server_name "";
Context: server
@Since: 1.25.5

设置虚拟 server 名称，例如：

[stream] server_names_hash_bucket_size¶

Syntax: server_names_hash_bucket_size size;
Default: server_names_hash_bucket_size 32|64|128;
Context: stream
@Since: 1.25.5

设置 server 名称哈希表桶大小。默认值取决于处理器 cache line 大小。哈希表配置详见文档。

[stream] server_names_hash_max_size¶

Syntax: server_names_hash_max_size size;
Default: server_names_hash_max_size 512;
Context: stream
@Since: 1.25.5

设置 server 名称哈希表最大尺寸。哈希表配置详见文档。

stream¶

Syntax: stream { ... }
Default: —
Context: main
@Since: None

提供 stream server 指令的配置文件上下文。

[stream] tcp_nodelay¶

Syntax: tcp_nodelay on | off;
Default: tcp_nodelay on;
Context: stream, server
@Since: 1.9.4

启用或禁用 TCP_NODELAY 选项；对客户端与被代理 server 连接均生效。

[stream] variables_hash_bucket_size¶

Syntax: variables_hash_bucket_size size;
Default: variables_hash_bucket_size 64;
Context: stream
@Since: 1.11.2

设置变量哈希表桶大小。哈希表配置详见文档。

[stream] variables_hash_max_size¶

Syntax: variables_hash_max_size size;
Default: variables_hash_max_size 1024;
Context: stream
@Since: 1.11.2

设置变量哈希表最大尺寸。哈希表配置详见文档。

ngx_stream_access_module¶

[stream] allow¶

Syntax: allow address | CIDR | unix: | all;
Default: —
Context: stream, server
@Since: None

允许指定网络或地址访问。若指定特殊值 unix:，则允许所有 UNIX 域套接字访问。

[stream] deny¶

Syntax: deny address | CIDR | unix: | all;
Default: —
Context: stream, server
@Since: None

拒绝指定网络或地址访问。若指定特殊值 unix:，则拒绝所有 UNIX 域套接字访问。

ngx_stream_geo_module¶

[stream] geo¶

Syntax: geo [$address] $variable { ... }
Default: —
Context: stream
@Since: None

描述指定变量值对客户端 IP 地址的依赖关系。默认地址取自 $remote_addr，亦可取自其他变量，例如：

ngx_stream_geoip_module¶

[stream] geoip_country¶

Syntax: geoip_country file;
Default: —
Context: stream
@Since: None

指定用于根据客户端 IP 判定国家的数据库。使用该库时可用下列变量：

[stream] geoip_city¶

Syntax: geoip_city file;
Default: —
Context: stream
@Since: None

指定用于根据客户端 IP 判定国家、地区与 city 的数据库。使用该库时可用下列变量：

[stream] geoip_org¶

Syntax: geoip_org file;
Default: —
Context: stream
@Since: None

指定用于根据客户端 IP 判定组织的数据库。使用该库时可用下列变量：

ngx_stream_js_module¶

js_access¶

Syntax: js_access function | module.function;
Default: —
Context: stream, server
@Since: None

设置将在 access 阶段调用的 njs 函数。自 0.4.0 起可引用模块函数。

[stream] js_context_reuse¶

Syntax: js_context_reuse number;
Default: js_context_reuse 128;
Context: stream, server
@Since: 0.8.6

设置 QuickJS 引擎可复用的 JS 上下文最大数量。每个上下文服务单个 stream session；完成后放入可复用池，池满则销毁。

[stream] js_engine¶

Syntax: js_engine njs | qjs;
Default: js_engine njs;
Context: stream, server
@Since: 0.8.6

设置 njs 脚本使用的 JavaScript 引擎。njs 为默认 njs 引擎；qjs 为 QuickJS 引擎。

[stream] js_fetch_buffer_size¶

Syntax: js_fetch_buffer_size size;
Default: js_fetch_buffer_size 16k;
Context: stream, server
@Since: 0.7.4

设置 Fetch API 读写所用缓冲区大小。

[stream] js_fetch_ciphers¶

Syntax: js_fetch_ciphers ciphers;
Default: js_fetch_ciphers HIGH:!aNULL:!MD5;
Context: stream, server
@Since: 0.7.0

指定 Fetch API HTTPS 连接启用的密码套件；格式为 OpenSSL 可识别的写法。

[stream] js_fetch_max_response_buffer_size¶

Syntax: js_fetch_max_response_buffer_size size;
Default: js_fetch_max_response_buffer_size 1m;
Context: stream, server
@Since: 0.7.4

设置 Fetch API 接收响应的最大大小。

[stream] js_fetch_protocols¶

Syntax: js_fetch_protocols [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;
Context: stream, server
@Since: 0.7.0

启用 Fetch API HTTPS 连接允许的协议。

[stream] js_fetch_timeout¶

Syntax: js_fetch_timeout time;
Default: js_fetch_timeout 60s;
Context: stream, server
@Since: 0.7.4

定义 Fetch API 读写的超时。超时仅在两次连续读/写操作之间计时，而非整段响应。若在此时间内无数据传输，则关闭连接。

[stream] js_fetch_trusted_certificate¶

Syntax: js_fetch_trusted_certificate file;
Default: —
Context: stream, server
@Since: 0.7.0

指定 PEM 格式可信 CA 证书文件，用于验证 Fetch API 的 HTTPS 证书。

[stream] js_fetch_verify¶

Syntax: js_fetch_verify on | off;
Default: js_fetch_verify on;
Context: stream, server
@Since: 0.7.4

启用或禁用 Fetch API 对 HTTPS 服务器证书的验证。

Note

stream njs 通过 Fetch 访问外部 HTTPS 时，生产环境应保持 js_fetch_verify on 并配置 js_fetch_trusted_certificate。

[stream] js_fetch_verify_depth¶

Syntax: js_fetch_verify_depth number;
Default: js_fetch_verify_depth 100;
Context: stream, server
@Since: 0.7.0

设置 Fetch API HTTPS 服务器证书链的验证深度。

[stream] js_filter¶

Syntax: js_filter function | module.function;
Default: —
Context: stream, server
@Since: None

设置数据过滤器。自 0.4.0 起可引用模块函数。stream session 进入 content 阶段时调用一次。

[stream] js_import¶

Syntax: js_import module.js | export_name from module.js;
Default: —
Context: stream, server
@Since: 0.4.0

导入实现 location 与变量处理程序的 njs 模块。export_name 用作访问模块函数的命名空间；未指定时以模块名为命名空间。

Note

官方原文写 location，stream 实际指 server 处理程序（参见 js_include）。

[stream] js_include¶

Syntax: js_include file;
Default: —
Context: stream
@Since: None

指定实现 server 与变量处理程序的 njs 文件：

[stream] js_path¶

Syntax: js_path path;
Default: —
Context: stream, server
@Since: 0.3.0

设置 njs 模块的附加搜索路径。

[stream] js_periodic¶

Syntax: js_periodic function | module.function [interval=time] [jitter=number] [worker_affinity=mask];
Default: —
Context: server
@Since: 0.8.1

指定按固定间隔运行的内容处理程序。处理程序以 session 对象为第一参数，并可访问 ngx 等全局对象。

[stream] js_preload_object¶

Syntax: js_preload_object name.json | name from file.json;
Default: —
Context: stream, server
@Since: 0.7.8

在配置阶段预加载不可变对象。name 作为 njs 代码中访问该对象的全局变量名；未指定时使用文件名。

[stream] js_preread¶

Syntax: js_preread function | module.function;
Default: —
Context: stream, server
@Since: None

设置将在 preread 阶段调用的 njs 函数。自 0.4.0 起可引用模块函数。

[stream] js_set¶

Syntax: js_set $variable function | module.function [nocache];
Default: —
Context: stream, server
@Since: None

为指定变量设置 njs 函数。自 0.4.0 起可引用模块函数。

[stream] js_shared_dict_zone¶

Syntax: js_shared_dict_zone zone=name:size [timeout=time] [type=string|number] [evict] [state=file];
Default: —
Context: stream
@Since: 0.8.0

设置 worker 进程间共享键值字典的共享内存区名称与大小。

[stream] js_var¶

Syntax: js_var $variable [value];
Default: —
Context: stream, server
@Since: 0.5.3

声明可写变量。值可含文本、变量及其组合。

ngx_stream_keyval_module¶

[stream] keyval¶

Syntax: keyval key $variable zone=name;
Default: —
Context: stream
@Since: None

创建新变量 $variable，其值由键在键值数据库中查得。匹配规则由 keyval_zone 的 type 参数定义。数据库存于 zone 参数指定的共享内存区。

[stream] keyval_zone¶

Syntax: keyval_zone zone=name:size [state=file] [timeout=time] [type=string|ip|prefix] [sync];
Default: —
Context: stream
@Since: None

设置保存键值数据库的共享内存区名称与大小。键值对由 API 管理。

ngx_stream_limit_conn_module¶

[stream] limit_conn¶

Syntax: limit_conn zone number;
Default: —
Context: stream, server
@Since: None

设置共享内存区及给定键值允许的最大连接数。超出限制时，服务器将关闭连接。例如指令

Note

须先在 stream 块配置 limit_conn_zone，再于 server 使用 limit_conn；按 $binary_remote_addr 限连接是常见防刷手段。

[stream] limit_conn_dry_run¶

Syntax: limit_conn_dry_run on | off;
Default: limit_conn_dry_run off;
Context: stream, server
@Since: 1.17.6

启用 dry run 模式。在此模式下连接数不受限制，但共享内存区中仍照常统计超限连接数。

[stream] limit_conn_log_level¶

Syntax: limit_conn_log_level info | notice | warn | error;
Default: limit_conn_log_level error;
Context: stream, server
@Since: None

设置超出连接限制时日志记录的级别。

[stream] limit_conn_zone¶

Syntax: limit_conn_zone key zone=name:size;
Default: —
Context: stream
@Since: None

设置保存各键状态的共享内存区参数。状态含当前连接数等。键可含文本、变量及其组合（1.11.2）。空键值的连接不计入。用法示例：

ngx_stream_log_module¶

[stream] access_log¶

Syntax: access_log path format [buffer=size] [gzip[=level]] [flush=time] [if=condition]; access_log off;
Default: access_log off;
Context: stream, server
@Since: None

设置缓冲写日志的路径、格式及配置。同一配置级别可指定多条日志。在第一个参数中使用 "syslog:" 前缀可配置 syslog 日志。特殊值 off 取消当前级别全部 access_log 指令。

[stream] log_format¶

Syntax: log_format name [escape=default|json|none] string ...;
Default: —
Context: stream
@Since: None

指定日志格式，例如：

[stream] open_log_file_cache¶

Syntax: open_log_file_cache max=N [inactive=time] [min_uses=N] [valid=time]; open_log_file_cache off;
Default: open_log_file_cache off;
Context: stream, server
@Since: None

定义缓存，用于保存名称含变量的、频繁使用的日志文件描述符。本指令参数如下：

ngx_stream_map_module¶

[stream] map¶

Syntax: map string $variable { ... }
Default: —
Context: stream
@Since: None

创建新变量，其值取决于第一个参数所指定的一个或多个源变量的值。

[stream] map_hash_bucket_size¶

Syntax: map_hash_bucket_size size;
Default: map_hash_bucket_size 32|64|128;
Context: stream
@Since: None

设置 map 变量哈希表 bucket 的大小。默认值取决于处理器缓存行大小。哈希表配置细节见单独文档。

[stream] map_hash_max_size¶

Syntax: map_hash_max_size size;
Default: map_hash_max_size 2048;
Context: stream
@Since: None

设置 map 变量哈希表的最大大小。哈希表配置细节见单独文档。

ngx_stream_mqtt_preread_module¶

mqtt_preread¶

Syntax: mqtt_preread on | off;
Default: mqtt_preread off;
Context: stream, server
@Since: None

在 preread 阶段从 MQTT CONNECT 消息中提取信息。

ngx_stream_mqtt_filter_module¶

mqtt¶

Syntax: mqtt on | off;
Default: mqtt off;
Context: stream, server
@Since: None

为指定虚拟服务器启用 MQTT 协议。

mqtt_buffers¶

Syntax: mqtt_buffers number size;
Default: mqtt_buffers 100 1k;
Context: stream, server
@Since: 1.25.1

设置单连接处理 MQTT 消息所用缓冲区的数量与大小。

mqtt_rewrite_buffer_size¶

Syntax: mqtt_rewrite_buffer_size size;
Default: mqtt_rewrite_buffer_size 4k|8k;
Context: server
@Since: None

None

mqtt_set_connect¶

Syntax: mqtt_set_connect field value;
Default: —
Context: server
@Since: None

为 CONNECT 消息将指定字段设为给定值。支持 clientid、username、password。值可含文本、变量及其组合。

ngx_stream_pass_module¶

pass¶

Syntax: pass address;
Default: —
Context: server
@Since: None

设置将客户端连接转发的服务器地址。地址可指定为 IP 与端口：

ngx_stream_proxy_module¶

[stream] proxy_bind¶

Syntax: proxy_bind address [transparent] | off;
Default: —
Context: stream, server
@Since: 1.9.2

使发往被代理服务器的出站连接从指定本地 IP 发起。参数值可含变量（1.11.2）。特殊值 off 取消自上级配置继承的 proxy_bind 效果，由系统自动分配本地 IP。

[stream] proxy_buffer_size¶

Syntax: proxy_buffer_size size;
Default: proxy_buffer_size 16k;
Context: stream, server
@Since: 1.9.4

设置从被代理服务器读取数据所用缓冲区大小；亦用于从客户端读取数据的缓冲区。

[stream] proxy_connect_timeout¶

Syntax: proxy_connect_timeout time;
Default: proxy_connect_timeout 60s;
Context: stream, server
@Since: None

定义与被代理服务器建立连接的超时。

[stream] proxy_download_rate¶

Syntax: proxy_download_rate rate;
Default: proxy_download_rate 0;
Context: stream, server
@Since: 1.9.3

限制从被代理服务器读取数据的速度，单位为字节/秒。0 表示不限速。限制按单连接计算；若 nginx 同时与被代理服务器建立两条连接，总速率约为设定值的两倍。

[stream] proxy_half_close¶

Syntax: proxy_half_close on | off;
Default: proxy_half_close off;
Context: stream, server
@Since: 1.21.4

启用或禁用 TCP 连接各方向独立关闭（“TCP half-close”）。启用后，TCP 代理将保持至双方均关闭连接。

[stream] proxy_next_upstream¶

Syntax: proxy_next_upstream on | off;
Default: proxy_next_upstream on;
Context: stream, server
@Since: None

当无法与被代理服务器建立连接时，决定是否将客户端连接转发至下一台服务器。

[stream] proxy_next_upstream_timeout¶

Syntax: proxy_next_upstream_timeout time;
Default: proxy_next_upstream_timeout 0;
Context: stream, server
@Since: None

限制将连接转发至下一台服务器所允许的时间。0 表示不限制。

[stream] proxy_next_upstream_tries¶

Syntax: proxy_next_upstream_tries number;
Default: proxy_next_upstream_tries 0;
Context: stream, server
@Since: None

限制将连接转发至下一台服务器的最大尝试次数。0 表示不限制。

[stream] proxy_pass¶

Syntax: proxy_pass address;
Default: —
Context: server
@Since: None

设置被代理服务器地址。地址可指定为域名或 IP 及端口：

[stream] proxy_protocol¶

Syntax: proxy_protocol on | off;
Default: proxy_protocol off;
Context: stream, server
@Since: 1.9.2

为与被代理服务器的连接启用 PROXY 协议。

[stream] proxy_requests¶

Syntax: proxy_requests number;
Default: proxy_requests 0;
Context: stream, server
@Since: 1.15.7

设置客户端 UDP 报文数量阈值，达到后解除客户端与现有 UDP stream session 的绑定。收到指定数量报文后，同一客户端的下一条报文将开启新 session。session 在客户端报文全部转发至被代理服务器且收到预期响应数后终止，或达到超时后终止。

[stream] proxy_responses¶

Syntax: proxy_responses number;
Default: —
Context: stream, server
@Since: 1.9.13

使用 UDP 协议时，设置针对客户端单条报文预期从被代理服务器收到的响应报文数，作为 session 终止提示。默认不限制报文数量。

[stream] proxy_session_drop¶

Syntax: proxy_session_drop on | off;
Default: proxy_session_drop off;
Context: stream, server
@Since: 1.15.8

在被代理服务器从组中移除或标记为永久不可用时，启用终止其全部 session。这可能由 re-resolve 或 API DELETE 命令触发。服务器若被判定不健康，或通过 API PATCH 命令，可被标记为永久不可用。每个 session 在客户端或被代理服务器下一次读/写事件处理时终止。

[stream] proxy_socket_keepalive¶

Syntax: proxy_socket_keepalive on | off;
Default: proxy_socket_keepalive off;
Context: stream, server
@Since: 1.15.6

配置发往被代理服务器出站连接的 “TCP keepalive” 行为。默认使用操作系统套接字设置。设为 on 时为套接字启用 SO_KEEPALIVE 选项。

[stream] proxy_ssl¶

Syntax: proxy_ssl on | off;
Default: proxy_ssl off;
Context: stream, server
@Since: None

为与被代理服务器的连接启用 SSL/TLS 协议。

[stream] proxy_ssl_certificate¶

Syntax: proxy_ssl_certificate file;
Default: —
Context: stream, server
@Since: None

指定用于向被代理服务器认证的 PEM 格式证书文件。

[stream] proxy_ssl_certificate_cache¶

Syntax: proxy_ssl_certificate_cache off; proxy_ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: proxy_ssl_certificate_cache off;
Context: stream, server
@Since: 1.27.4

定义缓存，用于存放以变量指定的 SSL 证书与私钥。

[stream] proxy_ssl_certificate_key¶

Syntax: proxy_ssl_certificate_key file;
Default: —
Context: stream, server
@Since: None

亦可指定 store:scheme:id（1.29.0）代替文件，用于通过已注册 OpenSSL Provider URI scheme（如 pkcs11）加载指定 id 的私钥。

[stream] proxy_ssl_ciphers¶

Syntax: proxy_ssl_ciphers ciphers;
Default: proxy_ssl_ciphers DEFAULT;
Context: stream, server
@Since: None

指定与被代理服务器连接时启用的密码套件；格式为 OpenSSL 可识别的写法。

[stream] proxy_ssl_conf_command¶

Syntax: proxy_ssl_conf_command name value;
Default: —
Context: stream, server
@Since: 1.19.4

在与被代理服务器建立连接时设置任意 OpenSSL 配置命令。

[stream] proxy_ssl_crl¶

Syntax: proxy_ssl_crl file;
Default: —
Context: stream, server
@Since: None

指定 PEM 格式吊销证书列表（CRL）文件，用于验证被代理服务器证书。

[stream] proxy_ssl_key_log¶

Syntax: proxy_ssl_key_log path;
Default: —
Context: stream, server
@Since: 1.27.2

启用被代理服务器连接 SSL 密钥日志，并指定密钥日志文件路径。密钥以与 Wireshark 兼容的 SSLKEYLOGFILE 格式记录。

[stream] proxy_ssl_name¶

Syntax: proxy_ssl_name name;
Default: proxy_ssl_name host from proxy_pass;
Context: stream, server
@Since: None

允许覆盖用于验证被代理服务器证书的服务器名，以及建立连接时通过 SNI 传递的名称。亦可用变量指定（1.11.3）。

[stream] proxy_ssl_password_file¶

Syntax: proxy_ssl_password_file file;
Default: —
Context: stream, server
@Since: None

指定私钥口令文件，每行一个口令；加载密钥时依次尝试。

[stream] proxy_ssl_protocols¶

Syntax: proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: proxy_ssl_protocols TLSv1.2 TLSv1.3;
Context: stream, server
@Since: None

启用与被代理服务器连接时允许的协议。

[stream] proxy_ssl_server_name¶

Syntax: proxy_ssl_server_name on | off;
Default: proxy_ssl_server_name off;
Context: stream, server
@Since: None

启用或禁用在与被代理服务器建立连接时通过 TLS 服务器名称指示（SNI，RFC 6066）传递服务器名。

[stream] proxy_ssl_session_reuse¶

Syntax: proxy_ssl_session_reuse on | off;
Default: proxy_ssl_session_reuse on;
Context: stream, server
@Since: None

确定是否可复用与被代理服务器通信时的 SSL 会话。若日志出现 “digest check failed”，可尝试关闭会话复用。

[stream] proxy_ssl_trusted_certificate¶

Syntax: proxy_ssl_trusted_certificate file;
Default: —
Context: stream, server
@Since: None

指定 PEM 格式可信 CA 证书文件，用于验证被代理服务器证书。

[stream] proxy_ssl_verify¶

Syntax: proxy_ssl_verify on | off;
Default: proxy_ssl_verify off;
Context: stream, server
@Since: None

启用或禁用对被代理服务器证书的验证。

Note

生产环境 stream 代理至 TLS 后端时，建议启用 proxy_ssl_verify 并配置 proxy_ssl_trusted_certificate。

[stream] proxy_ssl_verify_depth¶

Syntax: proxy_ssl_verify_depth number;
Default: proxy_ssl_verify_depth 1;
Context: stream, server
@Since: None

设置被代理服务器证书链的验证深度。

[stream] proxy_timeout¶

Syntax: proxy_timeout timeout;
Default: proxy_timeout 10m;
Context: stream, server
@Since: None

设置客户端或被代理服务器连接上两次连续读/写操作之间的超时。若在此时间内无数据传输，则关闭连接。

[stream] proxy_upload_rate¶

Syntax: proxy_upload_rate rate;
Default: proxy_upload_rate 0;
Context: stream, server
@Since: 1.9.3

限制从客户端读取数据的速度，单位为字节/秒。0 表示不限速。限制按单连接计算；若客户端同时建立两条连接，总速率约为设定值的两倍。

ngx_stream_proxy_protocol_vendor_module¶

None

ngx_stream_realip_module¶

[stream] set_real_ip_from¶

Syntax: set_real_ip_from address | CIDR | unix:;
Default: —
Context: stream, server
@Since: None

定义已知会发送正确替换地址的可信地址。特殊值 unix: 表示信任所有 UNIX 域套接字。

ngx_stream_return_module¶

[stream] return value¶

Syntax: return value;
Default: —
Context: server
@Since: None

指定发送给客户端的值。值可含文本、变量及其组合。

ngx_stream_set_module¶

[stream] set¶

Syntax: set $variable value;
Default: —
Context: server
@Since: None

为指定变量设置值。值可含文本、变量及其组合。

ngx_stream_split_clients_module¶

[stream] split_clients¶

Syntax: split_clients string $variable { ... }
Default: —
Context: stream
@Since: None

创建用于 A/B 测试的变量，例如：

ngx_stream_ssl_module¶

[stream] ssl_alpn¶

Syntax: ssl_alpn protocol ...;
Default: —
Context: stream, server
@Since: 1.21.4

指定支持的 ALPN 协议列表。若客户端使用 ALPN，须协商其中一种协议：

[stream] ssl_certificate¶

Syntax: ssl_certificate file;
Default: —
Context: stream, server
@Since: None

为指定虚拟 server 指定 PEM 格式证书文件。除主证书外若需指定中间证书，应写入同一文件，顺序为：主证书在前，中间证书在后。PEM 格式私钥也可放在同一文件中。

Note

stream TLS 终结（如数据库/L4 代理）应提供完整证书链；私钥宜单独用 ssl_certificate_key 存放并限制文件权限。

[stream] ssl_certificate_cache¶

Syntax: ssl_certificate_cache off; ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: ssl_certificate_cache off;
Context: stream, server
@Since: 1.27.4

定义缓存，用于存放以变量指定的 SSL 证书与私钥。

[stream] ssl_certificate_key¶

Syntax: ssl_certificate_key file;
Default: —
Context: stream, server
@Since: None

为指定虚拟 server 指定 PEM 格式私钥文件。

[stream] ssl_ciphers¶

Syntax: ssl_ciphers ciphers;
Default: ssl_ciphers HIGH:!aNULL:!MD5;
Context: stream, server
@Since: None

指定启用的密码套件；格式为 OpenSSL 可识别的写法，例如：

[stream] ssl_client_certificate¶

Syntax: ssl_client_certificate file;
Default: —
Context: stream, server
@Since: 1.11.8

指定 PEM 格式受信 CA 证书文件，用于验证客户端证书；若启用 ssl_stapling，也用于验证 OCSP 响应。

[stream] ssl_conf_command¶

Syntax: ssl_conf_command name value;
Default: —
Context: stream, server
@Since: 1.19.4

设置任意 OpenSSL 配置命令。

[stream] ssl_crl¶

Syntax: ssl_crl file;
Default: —
Context: stream, server
@Since: 1.11.8

指定 PEM 格式吊销证书列表（CRL）文件，用于验证客户端证书。

[stream] ssl_dhparam¶

Syntax: ssl_dhparam file;
Default: —
Context: stream, server
@Since: None

指定 DHE 密码套件所用的 DH 参数文件。

[stream] ssl_ecdh_curve¶

Syntax: ssl_ecdh_curve curve;
Default: ssl_ecdh_curve auto;
Context: stream, server
@Since: None

指定 ECDHE 密码套件所用的椭圆曲线。

[stream] ssl_handshake_timeout¶

Syntax: ssl_handshake_timeout time;
Default: ssl_handshake_timeout 60s;
Context: stream, server
@Since: None

指定 SSL 握手完成的超时。

[stream] ssl_key_log¶

Syntax: ssl_key_log path;
Default: —
Context: stream, server
@Since: 1.27.2

启用客户端连接 SSL 密钥日志，并指定密钥日志文件路径。密钥以与 Wireshark 兼容的 SSLKEYLOGFILE 格式记录。

[stream] ssl_ocsp¶

Syntax: ssl_ocsp on | off | leaf;
Default: ssl_ocsp off;
Context: stream, server
@Since: 1.27.2

启用客户端证书链的 OCSP 校验。leaf 参数仅校验客户端叶证书。

[stream] ssl_ocsp_cache¶

Syntax: ssl_ocsp_cache off | [shared:name:size];
Default: ssl_ocsp_cache off;
Context: stream, server
@Since: 1.27.2

设置用于 OCSP 校验时存放客户端证书状态的缓存名称与大小。缓存在所有 worker 进程间共享；同名缓存可在多个虚拟 server 中使用。

[stream] ssl_ocsp_responder¶

Syntax: ssl_ocsp_responder url;
Default: —
Context: stream, server
@Since: 1.27.2

覆盖证书 “Authority Information Access” 扩展中指定的 OCSP 响应器 URL，用于校验客户端证书。

[stream] ssl_password_file¶

Syntax: ssl_password_file file;
Default: —
Context: stream, server
@Since: None

指定私钥口令文件，每行一个口令；加载密钥时依次尝试。

[stream] ssl_prefer_server_ciphers¶

Syntax: ssl_prefer_server_ciphers on | off;
Default: ssl_prefer_server_ciphers off;
Context: stream, server
@Since: None

使用 SSLv3 与 TLS 协议时，指定优先采用服务端密码套件而非客户端提议的套件。

[stream] ssl_protocols¶

Syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: ssl_protocols TLSv1.2 TLSv1.3;
Context: stream, server
@Since: None

启用指定的协议。

Note

生产环境 stream TLS 仅启用 TLSv1.2 TLSv1.3，禁用已弃用协议。

[stream] ssl_reject_handshake¶

Syntax: ssl_reject_handshake on | off;
Default: ssl_reject_handshake off;
Context: stream, server
@Since: 1.25.5

若启用，server 块中的 SSL 握手将被拒绝。

[stream] ssl_session_cache¶

Syntax: ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
Default: ssl_session_cache none;
Context: stream, server
@Since: None

设置存放会话参数的缓存类型与大小。缓存可为下列类型之一：

[stream] ssl_session_ticket_key¶

Syntax: ssl_session_ticket_key file;
Default: —
Context: stream, server
@Since: None

指定用于加密与解密 TLS session ticket 的密钥文件。多台 server 须共享同一密钥时须配置本指令；默认使用随机生成的密钥。

[stream] ssl_session_tickets¶

Syntax: ssl_session_tickets on | off;
Default: ssl_session_tickets on;
Context: stream, server
@Since: None

启用或禁用通过 TLS session ticket 恢复会话。

[stream] ssl_session_timeout¶

Syntax: ssl_session_timeout time;
Default: ssl_session_timeout 5m;
Context: stream, server
@Since: None

指定客户端可复用会话参数的时间上限。

[stream] ssl_stapling¶

Syntax: ssl_stapling on | off;
Default: ssl_stapling off;
Context: stream, server
@Since: 1.27.2

启用或禁用由服务端装订（staple）OCSP 响应。示例：

[stream] ssl_stapling_file¶

Syntax: ssl_stapling_file file;
Default: —
Context: stream, server
@Since: 1.27.2

配置后，装订的 OCSP 响应取自指定文件，而非向服务端证书中指定的 OCSP 响应器发起查询。

[stream] ssl_stapling_responder¶

Syntax: ssl_stapling_responder url;
Default: —
Context: stream, server
@Since: 1.27.2

覆盖证书 “Authority Information Access” 扩展中指定的 OCSP 响应器 URL。

[stream] ssl_stapling_verify¶

Syntax: ssl_stapling_verify on | off;
Default: ssl_stapling_verify off;
Context: stream, server
@Since: 1.27.2

启用或禁用服务端对 OCSP 响应的校验。

[stream] ssl_trusted_certificate¶

Syntax: ssl_trusted_certificate file;
Default: —
Context: stream, server
@Since: 1.11.8

指定 PEM 格式受信 CA 证书文件，用于验证客户端证书；若启用 ssl_stapling，也用于验证 OCSP 响应。

[stream] ssl_verify_client¶

Syntax: ssl_verify_client on | off | optional | optional_no_ca;
Default: ssl_verify_client off;
Context: stream, server
@Since: 1.11.8

启用客户端证书校验。校验结果存入 $ssl_client_verify 变量。若校验出错或客户端未提供所需证书，则关闭连接。

[stream] ssl_verify_depth¶

Syntax: ssl_verify_depth number;
Default: ssl_verify_depth 1;
Context: stream, server
@Since: 1.11.8

设置客户端证书链的校验深度。

ngx_stream_ssl_preread_module¶

[stream] ssl_preread¶

Syntax: ssl_preread on | off;
Default: ssl_preread off;
Context: stream, server
@Since: None

在 preread 阶段从 ClientHello 消息中提取信息。

ngx_stream_upstream_module¶

[upstream] upstream¶

Syntax: upstream name { ... }
Default: —
Context: stream
@Since: None

定义一组服务器。各服务器可监听不同端口；此外，监听 TCP 与 UNIX 域套接字的服务器可混用。

[upstream] server address¶

Syntax: server address [parameters];
Default: —
Context: upstream
@Since: None

定义服务器的地址及其他参数。地址可为域名或 IP 及必填端口，或在 “unix:” 前缀后指定 UNIX 域套接字路径。解析到多个 IP 的域名会一次性定义多台服务器。

[upstream] zone¶

Syntax: zone name [size];
Default: —
Context: upstream
@Since: None

定义共享内存区名称与大小，用于保存组配置及 worker 进程间共享的运行时状态。多个组可共用同一 zone；此时只需指定一次 size。

[upstream] state¶

Syntax: state file;
Default: —
Context: upstream
@Since: 1.9.7

指定用于保存可动态配置组状态的文件。

[upstream] hash¶

Syntax: hash key [consistent];
Default: —
Context: upstream
@Since: None

指定基于哈希键值的负载均衡方式，客户端与服务器的映射由键值哈希决定。键可含文本、变量及其组合（1.11.2）。用法示例：

[upstream] least_conn¶

Syntax: least_conn;
Default: —
Context: upstream
@Since: None

指定组使用最少连接负载均衡：连接转发到当前活跃连接数最少的服务器（计入 weight）。若多台服务器并列最少，则按带权轮询依次尝试。

[upstream] least_time¶

Syntax: least_time connect | first_byte | last_byte [inflight];
Default: —
Context: upstream
@Since: None

指定组使用最小时间与最少连接负载均衡：连接转发到平均时间最短且活跃连接数最少的服务器（计入 weight）。若多台服务器并列，则按带权轮询依次尝试。

[upstream] random¶

Syntax: random [two [method]];
Default: —
Context: upstream
@Since: 1.15.1

指定组使用随机负载均衡：连接转发到随机选中的服务器（计入 weight）。

[upstream] resolver address¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: —
Context: upstream
@Since: 1.27.3

配置用于将上游服务器名称解析为地址的 DNS 服务器，例如：

[upstream] resolver_timeout time¶

Syntax: resolver_timeout time;
Default: resolver_timeout 30s;
Context: upstream
@Since: 1.27.3

设置名称解析超时，例如：

ngx_stream_upstream_hc_module¶

[upstream] health_check¶

Syntax: health_check [parameters];
Default: —
Context: server
@Since: None

启用对组内服务器的周期性健康检查。

[upstream] health_check_timeout¶

Syntax: health_check_timeout timeout;
Default: health_check_timeout 5s;
Context: stream, server
@Since: None

为健康检查覆盖 proxy_timeout 的值。

[upstream] match¶

Syntax: match name { ... }
Default: —
Context: stream
@Since: None

定义用于校验健康检查服务器响应的命名测试集。

ngx_stream_zone_sync_module¶

zone_sync¶

Syntax: zone_sync;
Default: —
Context: server
@Since: None

启用集群节点间共享内存区的同步。集群节点通过 zone_sync_server 指令定义。

zone_sync_buffers¶

Syntax: zone_sync_buffers number size;
Default: zone_sync_buffers 8 4k|8k;
Context: stream, server
@Since: None

设置用于推送 zone 内容的 per-zone 缓冲区数量与大小。默认缓冲区大小等于一个内存页（4K 或 8K，取决于平台）。

zone_sync_connect_retry_interval¶

Syntax: zone_sync_connect_retry_interval time;
Default: zone_sync_connect_retry_interval 1s;
Context: stream, server
@Since: None

定义连接另一集群节点的重试间隔。

zone_sync_connect_timeout¶

Syntax: zone_sync_connect_timeout time;
Default: zone_sync_connect_timeout 5s;
Context: stream, server
@Since: None

定义与另一集群节点建立连接的超时。

zone_sync_interval¶

Syntax: zone_sync_interval time;
Default: zone_sync_interval 1s;
Context: stream, server
@Since: None

定义轮询共享内存区更新的间隔。

zone_sync_recv_buffer_size¶

Syntax: zone_sync_recv_buffer_size size;
Default: zone_sync_recv_buffer_size 4k|8k;
Context: stream, server
@Since: None

设置用于解析同步消息流的 per-connection 接收缓冲区大小。缓冲区须大于等于任一 zone_sync_buffers 的大小。默认等于 zone_sync_buffers 大小乘以数量。

zone_sync_server¶

Syntax: zone_sync_server address [resolve];
Default: —
Context: server
@Since: None

定义集群节点地址。地址可为域名或 IP 及必填端口，或在 “unix:” 前缀后指定 UNIX 域套接字路径。解析到多个 IP 的域名会一次性定义多个节点。

zone_sync_ssl¶

Syntax: zone_sync_ssl on | off;
Default: zone_sync_ssl off;
Context: stream, server
@Since: None

为与另一集群 server 的连接启用 SSL/TLS 协议。

zone_sync_ssl_certificate¶

Syntax: zone_sync_ssl_certificate file;
Default: —
Context: stream, server
@Since: None

指定用于向另一集群 server 认证的 PEM 格式证书文件。

zone_sync_ssl_certificate_key¶

Syntax: zone_sync_ssl_certificate_key file;
Default: —
Context: stream, server
@Since: None

指定用于向另一集群 server 认证的 PEM 格式私钥文件。

zone_sync_ssl_ciphers¶

Syntax: zone_sync_ssl_ciphers ciphers;
Default: zone_sync_ssl_ciphers DEFAULT;
Context: stream, server
@Since: None

指定与另一集群 server 连接时启用的密码套件；格式为 OpenSSL 可识别的写法。

zone_sync_ssl_conf_command¶

Syntax: zone_sync_ssl_conf_command name value;
Default: —
Context: stream, server
@Since: 1.19.4

在与另一集群 server 建立连接时设置任意 OpenSSL 配置命令。

zone_sync_ssl_crl¶

Syntax: zone_sync_ssl_crl file;
Default: —
Context: stream, server
@Since: None

指定 PEM 格式吊销证书列表（CRL）文件，用于验证另一集群 server 证书。

zone_sync_ssl_name¶

Syntax: zone_sync_ssl_name name;
Default: zone_sync_ssl_name host from zone_sync_server;
Context: stream, server
@Since: 1.15.7

允许覆盖用于验证集群 server 证书的服务器名，以及建立连接时通过 SNI 传递的名称。

zone_sync_ssl_password_file¶

Syntax: zone_sync_ssl_password_file file;
Default: —
Context: stream, server
@Since: None

指定私钥口令文件，每行一个口令；加载密钥时依次尝试。

zone_sync_ssl_protocols¶

Syntax: zone_sync_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: zone_sync_ssl_protocols TLSv1.2 TLSv1.3;
Context: stream, server
@Since: None

启用与另一集群 server 连接时允许的协议。

zone_sync_ssl_server_name¶

Syntax: zone_sync_ssl_server_name on | off;
Default: zone_sync_ssl_server_name off;
Context: stream, server
@Since: 1.15.7

启用或禁用在与另一集群 server 建立连接时通过 TLS 服务器名称指示（SNI，RFC 6066）传递服务器名。

zone_sync_ssl_trusted_certificate¶

Syntax: zone_sync_ssl_trusted_certificate file;
Default: —
Context: stream, server
@Since: None

指定 PEM 格式可信 CA 证书文件，用于验证另一集群 server 证书。

zone_sync_ssl_verify¶

Syntax: zone_sync_ssl_verify on | off;
Default: zone_sync_ssl_verify off;
Context: stream, server
@Since: None

启用或禁用对另一集群 server 证书的验证。

zone_sync_ssl_verify_depth¶

Syntax: zone_sync_ssl_verify_depth number;
Default: zone_sync_ssl_verify_depth 1;
Context: stream, server
@Since: None

设置另一集群 server 证书链的验证深度。

zone_sync_timeout¶

Syntax: zone_sync_timeout timeout;
Default: zone_sync_timeout 5s;
Context: stream, server
@Since: None

设置与另一集群节点连接上两次连续读/写操作之间的超时。若在此时间内无数据传输，则关闭连接。

ngx_google_perftools_module¶

google_perftools_profiles¶

Syntax: google_perftools_profiles file;
Default: —
Context: main
@Since: None

设置保存 nginx worker 进程性能剖析信息的文件名。worker 进程 ID 始终为文件名的一部分，以点号追加在文件名末尾。

Note

本模块用于性能剖析与调试，须使用 --with-google_perftools 编译；生产环境默认不启用。

ngx_mgmt_module¶

mgmt¶

Syntax: mgmt { ... }
Default: —
Context: main
@Since: None

提供配置上下文，用于指定用量上报与许可证管理相关指令。

enforce_initial_report¶

Syntax: enforce_initial_report on | off;
Default: enforce_initial_report on;
Context: mgmt
@Since: 1.27.2

启用或禁用发送首次用量上报的 180 天宽限期。

license_token¶

Syntax: license_token file;
Default: license_token license.jwt;
Context: mgmt
@Since: 1.27.2

指定 JWT 许可证文件。默认在 Linux 上期望路径为 /etc/nginx/license.jwt，FreeBSD 为 /usr/local/etc/nginx/license.jwt。

proxy¶

Syntax: proxy host:port;
Default: —
Context: mgmt
@Since: 1.27.4

设置用于发送用量上报的 HTTP CONNECT 代理。

proxy_username¶

Syntax: proxy_username string;
Default: —
Context: mgmt
@Since: 1.27.4

设置代理认证所用的用户名。

proxy_password¶

Syntax: proxy_password string;
Default: —
Context: mgmt
@Since: 1.27.4

设置代理认证所用的密码。

[mgmt] resolver¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: —
Context: mgmt
@Since: None

配置用于解析用量上报端点名称的 DNS 服务器。默认使用系统解析器。

[mgmt] ssl_crl¶

Syntax: ssl_crl file;
Default: —
Context: mgmt
@Since: None

指定 PEM 格式吊销证书列表（CRL）文件，用于验证用量上报端点证书。

[mgmt] ssl_trusted_certificate¶

Syntax: ssl_trusted_certificate file;
Default: ssl_trusted_certificate system CA bundle;
Context: mgmt
@Since: None

指定 PEM 格式可信 CA 证书文件，用于验证用量上报端点证书。

[mgmt] ssl_verify¶

Syntax: ssl_verify on | off;
Default: ssl_verify on;
Context: mgmt
@Since: None

启用或禁用对用量上报端点证书的验证。

[mgmt] state_path¶

Syntax: state_path path;
Default: —
Context: mgmt
@Since: 1.27.2

定义存放 ngx_mgmt_module 所创建状态文件（nginx-mgmt-*）的目录。Linux 默认 /var/lib/nginx/state，FreeBSD 默认 /var/db/nginx/state。

[mgmt] usage_report¶

Syntax: usage_report [endpoint=address] [interval=time];
Default: usage_report endpoint=product.connect.nginx.com interval=1h;
Context: mgmt
@Since: None

设置用量上报端点的地址与端口。interval 参数设置两次连续上报之间的间隔。

ngx_otel_module¶

otel_exporter¶

Syntax: otel_exporter { ... }
Default: —
Context: http
@Since: None

指定 OTel 数据导出参数：

otel_service_name¶

Syntax: otel_service_name name;
Default: otel_service_name unknown_service:nginx;
Context: http
@Since: None

设置 OTel 资源的 service.name 属性。

otel_resource_attr¶

Syntax: otel_resource_attr name value;
Default: —
Context: http
@Since: 0.1.2

设置自定义 OTel 资源属性。

otel_trace¶

Syntax: otel_trace on | off | $variable;
Default: otel_trace off;
Context: http, server, location
@Since: None

启用或禁用 OpenTelemetry 追踪。亦可通过指定变量启用：

otel_trace_context¶

Syntax: otel_trace_context extract | inject | propagate | ignore;
Default: otel_trace_context ignore;
Context: http, server, location
@Since: None

指定 traceparent/tracestate 头的传播方式：

otel_span_name¶

Syntax: otel_span_name name;
Default: —
Context: http, server, location
@Since: None

定义 OTel span 名称。默认为请求的 location 名称。名称可含变量。

otel_span_attr¶

Syntax: otel_span_attr name value;
Default: —
Context: http, server, location
@Since: None

添加自定义 OTel span 属性。值可含变量。