这个 OpenResty 发行版是基于自身需要编译打包的，通常会实时跟进官方 OpenResty 的版本。
本发行版在官方的版本上增加了大量第三方模块和 nginx 官方代码的补丁（用于扩展原生 nginx 的功能），以同时满足 WEB 服务器、API 网关和 CDN 分发等用途。所有打包模块都已经开源（包括我自己写的模块），详情见 GitHub 链接或者下面介绍。
仓库提供 Dockerfile，可以直接构建使用。基于本仓库编译的 Docker 镜像可在 Docker Hub 获取。
项目背景与定位
在 CDN 和 API 网关的场景下，官方 OpenResty 并不能完全满足生产环境的需求。许多常见的运维操作（如缓存精细化管理、安全防护、请求溯源）需要依赖额外的第三方模块或自定义补丁才能实现。本发行版的目标就是填补这些空白，提供开箱即用的全功能 OpenResty 发行版。
本发行版在以下方面做了大量增强：
- 缓存控制增强：支持按 MIME 类型、最大/最小长度、强制过期/失效等精细化缓存策略，让 CDN 缓存行为更可控。
- 安全防护：内置 WAF 模块（ngx_waf）和 OWASP Core Rule Set 规则集，支持细粒度的 WAF 开关控制；提供多种鉴权模块（HMAC、Akamai G2O 等）。
- 可观测性：新增大量时间戳和耗时变量，覆盖 HTTP 请求处理、SSL 握手、上游连接建立等全链路环节，便于性能分析和故障排查。
- 请求路由与重写：增强的 if 指令支持多条件组合（&& / ||）和 elif / else，支持更多比较运算符。
- 压缩优化：支持 Brotli 和 Zstd 压缩/解压，并提供动态 TLS 记录大小优化以降低首字节延迟。
- Stream 模块支持：TCP/UDP 代理层面也增加了丰富的变量和配置指令，支持 SSL 握手时间戳、上游状态等。
- Lua配置控制：支持Lua配置指令（lua_config、lua_init_config、lua_upstream等），允许在配置文件中通过NGINX指令的方式控制Lua模块的行为，提供和NGINX原生模块相似的开发和使用体验。
开源地址：
描述
OpenResty 是一个功能齐全的 Web 应用服务器，它捆绑了标准 nginx 核心、大量第三方 nginx 模块以及它们的大部分外部依赖项。
这个定制的 OpenResty 软件包旨在充当功能齐全的 CDN 缓存服务器，同时保留 OpenResty 作为高性能动态 Web 平台的功能。
此软件包基于官方 OpenResty，包含 LuaRocks、附加补丁、第三方 nginx 模块和 Lua 库。
此软件包由 Hanada ([email protected]) 维护。
捆绑软件组件的版权归各自的版权所有者所有。
本捆绑包版本号会在官方 OpenResty 版本号基础上增加一个发行序列号。假设官方 OpenResty 的版本号是 1.27.1.1，代表 nginx 版本号是 1.27.1，官方 OpenResty 增加了 .1，本捆绑包的版本号会是 1.27.1.1.xxx，此版本号会出现在 server 标头（如果指令 server_token 值为 on）、默认错误页面（如果指令 server_token 值为 on）、变量 $nginx_version 中。
组件
OpenResty 官方软件包的组件
有关 OpenResty 捆绑组件和功能的详细信息，请参阅 openresty.org。
此 OpenResty 软件包的组件
以下组件是本 OpenResty 软件包额外捆绑的，其中一部分由我开发和维护。
- ngx_backtrace_module
- ngx_geoip2_module
- ngx_http_access_control_module
- ngx_http_auth_akamai_g2o_module
- ngx_http_auth_hash_module
- ngx_http_auth_hmac_module
- ngx_http_auth_internal_module
- ngx_http_auth_ldap_module
- ngx_http_brotli_module
- ngx_http_cache_purge_module
- ngx_http_compression_normalize_module
- ngx_http_compression_vary_filter_module
- ngx_http_cors_module
- ngx_http_delay_module
- ngx_http_error_log_write_module
- ngx_http_extra_variables_module
- ngx_http_flv_live_module
- ngx_http_internal_redirect_module
- ngx_http_label_module
- ngx_http_limit_traffic_rate_filter_module
- ngx_http_log_var_set_module
- ngx_http_loop_detect_module
- ngx_http_lua_config_module
- ngx_http_proxy_auth_aws_module
- ngx_http_proxy_auth_netstorage_module
- ngx_http_proxy_var_set_module
- ngx_http_qrcode_module
- ngx_http_replace_filter_module
- ngx_http_cookies_filter_module
- ngx_http_rewrite_status_filter_module
- ngx_http_security_headers_module
- ngx_http_server_redirect_module
- ngx_http_sorted_args_module
- ngx_http_sysguard_module
- ngx_http_trim_filter_module
- ngx_http_cache_dechunk_filter_module
- ngx_http_ua_parser_module
- ngx_http_unbrotli_filter_module
- ngx_http_undeflate_filter_module
- ngx_http_unzstd_filter_module
- ngx_http_upstream_log_module
- ngx_http_var_module
- ngx_http_waf_module
- ngx_http_weserv_module
- ngx_http_zstd_module
- ngx_lua_events_module
- ngx_lua_load_var_index_module
- ngx_lua_resty_lmdb_module
- ngx_ssl_fingerprint_module
- ngx_stream_lua_config_module
- ngx_stream_lua_upstream_module
- ngx_stream_access_control_module
- ngx_stream_error_log_write_module
- ngx_stream_log_var_set_module
- ngx_stream_label_module
- ngx_stream_var_module
- ngx_stream_extra_variables_module
- coreruleset
- uap-core
- luarocks
- lua-resty-multipart-parser
- lua-resty-balancer
- jsonschema
- lua-resty-dns-client
- lua-resty-mlcache
- lua-lolhtml
来自 LuaRocks 的组件
- binaryheap
- luafilesystem
- penlight
- net-url
- api7-dkjson
- lyaml
- lrandom
- luaxxhash
- xml2lua
- lua-ffi-zlib
- lua-resty-openssl
- lua-resty-http
- lua-resty-hmac-ffi
- lua-resty-jwt
- lua-resty-session
- lua-resty-openidc
- lua-resty-timer
- lua-resty-kafka
- lua-resty-template
- lua-resty-m3u8
- lua-resty-cookie
- lua-resty-worker-events
- lua-resty-healthcheck
- lua-resty-ipmatcher
- lua-resty-expr
- api7-lua-resty-redis-connector
- lua-resty-redis-cluster
- lua-resty-timer-ng
- lua-resty-maxminddb
- lua-resty-ctx
附加功能
此软件包通过补丁扩展了 Nginx 核心和第三方模块的功能。
以下是此软件包支持的附加功能，为了简洁起见，官方 OpenResty 软件包中已包含的功能已省略。
ngx_http
用于记录时间戳和相关操作耗时情况的变量
必须编译模块 ngx_http_extra_variables_module 才能使用这些变量。
| 变量 | 描述 |
|---|---|
| $response_header_sent_msec | 响应头发送时间戳（以秒为单位，精度为毫秒）。 |
| $request_handling_time | 记录从接收请求到将响应头发送到客户端期间内部处理请求所花费的时间。 |
| $response_body_time | 记录将响应主体发送到客户端所花费的时间。 |
| $request_header_lenth | 请求头长度。 |
| $request_body_lenth | 请求体长度。 |
ngx_http_core_module
listen 指令支持 https_allow_http
允许服务器在同一端口同时接受 HTTP 和 HTTPS 请求，这在使用特殊端口的场景中非常有用。原代码来自 Tengine。
| 指令 | listen |
|---|---|
| 语法 | 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]] [https_allow_http]; 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]] [https_allow_http]; 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]] [https_allow_http]; |
| 默认值 | listen *:80; | *:8000; |
| 上下文 | server |
当 listen 指令同时启用 ssl 和 https_allow_http 参数时，将允许 https 和 http 请求。
唯一请求 ID 增强
基于原有 nginx 内置变量 $request_id，支持从请求头或任何变量继承唯一 ID。除了随机十六进制 ID 之外，唯一 ID 生成还支持根据请求特征生成跟踪 ID。
| 指令 | request_id_algorithm |
|---|---|
| 语法 | request_id_algorithm hexid | traceid; |
| 默认值 | request_id_algorithm hexid; |
| 上下文 | http, server, location |
指定请求 ID 的格式。
| 指令 | request_id_header |
|---|---|
| 语法 | request_id_header header_name; |
| 默认值 | – |
| 上下文 | http, server, location |
指定请求 ID 继承的标头名称。如果未指定标头，则请求 ID 将始终重新生成。
默认错误页面优化
优化默认错误页面显示的信息，以便于收集客户端的错误反馈。
| 指令 | error_page_server_info |
|---|---|
| 语法 | error_page_server_info on | off; |
| 默认值 | error_page_server_info on; |
| 上下文 | http, server, location |
在默认的 4xx/5xx 错误页面中显示以下信息：包含日期、请求客户端 IP、请求 ID 以及服务请求的主机名。
| 指令 | error_page_client_ip |
|---|---|
| 语法 | error_page_client_ip $variable; |
| 默认值 | error_page_client_ip $remote_addr; |
| 上下文 | http, server, location |
指定在默认 4xx/5xx 错误页面上显示的 IP 项的值。参数值可以包含变量。仅当启用 error_page_server_info 指令时，该值才会显示在默认的 4xx/5xx 错误页面上。
支持忽略无效的 Range 标头
| 指令 | ignore_invalid_range |
|---|---|
| 语法 | ignore_invalid_range on | off; |
| 默认值 | ignore_invalid_range off; |
| 上下文 | http, server, location |
指定是否忽略无效的范围标头。如果启用，则忽略无效的范围标头，并将完整内容响应给客户端。否则，客户端将收到 416 状态。无效的范围标头不会被清除，只是被忽略。
支持带有 if 参数的 error_page 指令
| 指令 | error_page |
|---|---|
| 语法 | error_page code … [=[response]] uri [if=condition]; |
| 默认值 | – |
| 上下文 | http, server, location |
有关原始用法，请参阅 nginx 文档的 error_page。
if 参数启用条件错误页面。在处理错误页面之前，会先评估条件。如果条件值不为空或 0，则会处理错误页面。否则，不会处理错误页面。您也可以通过将 if= 更改为 if!= 来实现相反的效果。
更多用于未修改（304）检查的指令
| 指令 | ignore_if_unmodified_since |
|---|---|
| 语法 | ignore_if_unmodified_since on | off; |
| 默认值 | ignore_if_unmodified_since off; |
| 上下文 | http, server, location |
指定是否忽略 If-Unmodified-Since 请求标头。如果启用，则会忽略 If-Unmodified-Since 请求标头。否则，将检查 If-Unmodified-Since 请求标头。
| 指令 | ignore_if_match |
|---|---|
| 语法 | ignore_if_match on | off; |
| 默认值 | ignore_if_match off; |
| 上下文 | http, server, location |
指定是否忽略 If-Match 请求标头。如果启用，则将忽略 If-Match 请求标头。否则，将检查 If-Match 请求标头。
| 指令 | not_modified_check |
|---|---|
| 语法 | not_modified_check on | any | strict | prefer_if_none_match; |
| 默认值 | not_modified_check strict; |
| 上下文 | http, server, location |
指定如何检查响应是否未经修改（304 Not Modified）：
off：不检查响应是否未经修改。响应始终被视为已修改。any：如果存在If-Modified-Since或If-None-Match请求标头，则检查响应是否未经修改。如果任何一个标头的检查通过，则返回 304 响应。strict：- 如果仅存在一个标头（
If-Modified-Since或If-None-Match），则检查该标头。如果满足其条件，则返回 304（未修改）。 - 如果两个标头都存在，必须同时通过其检查才能返回 304（未修改）。
- 如果两个标头均不存在，则认为响应已修改。
- 如果仅存在一个标头（
prefer_if_none_match：- 如果仅存在一个标头（
If-Modified-Since或If-None-Match），则检查该标头。如果满足条件，则返回 304（未修改）。 - 如果 两个标头 都存在，只需满足
If-None-Match标头的条件 即可返回 304（未修改）。 - 如果两个标头均不存在，则响应被视为已修改。
- 如果仅存在一个标头（
ngx_http_ssl_module
优化 TCP 上的 TLS 以降低延迟
通过初始发送较小（1 个 TCP 段）的记录，我们可以避免第一个字节的 HoL 阻塞。这意味着 TTFB 有时会缩短整个 RTT。
通过在连接后期发送越来越大的记录，当 HoL 不再是问题时，我们可以减少 TLS 记录的开销（使用 GCM/CHACHA-POLY 时，每个记录 29 字节）。
每个连接都以较小的记录启动（默认为 1369 字节，可以使用 ssl_dyn_rec_size_lo 进行更改）。
在达到给定数量的记录（40，使用 ssl_dyn_rec_threshold 进行更改）后，开始发送更大的记录（4229，使用 ssl_dyn_rec_size_hi）。
最终，在达到相同数量的记录后，开始发送最大的记录（ssl_buffer_size）。
如果连接空闲了给定的时间（1 秒，ssl_dyn_rec_timeout），则该过程将重复（即再次开始发送小记录）。
| 指令 | ssl_dyn_rec |
|---|---|
| 语法 | ssl_dyn_rec on | off; |
| 默认值 | ssl_dyn_rec off; |
| 上下文 | http, server |
启用动态 TLS 记录。
与原始补丁不同，该指令名称从 ssl_dyn_rec_enable 更改为 ssl_dyn_rec。
| 指令 | ssl_dyn_rec_timeout |
|---|---|
| 语法 | ssl_dyn_rec_timeout time; |
| 默认值 | ssl_dyn_rec_timeout 1s; |
| 上下文 | http, server |
我们希望初始记录能够放入一个 TCP 段中，这样就不会因为 TCP 慢启动而导致 TCP HoL 阻塞。
连接始终以较小的记录开始，但在发送了一定数量的记录后，我们会增加记录大小以减少标头开销。
连接空闲一段时间后，将从头开始处理。实际参数可配置。如果 ssl_dyn_rec_timeout 为 0，则我们假定 ssl_dyn_rec 处于关闭状态。
| 指令 | ssl_dyn_rec_size_lo |
|---|---|
| 语法 | ssl_dyn_rec_size_lo number; |
| 默认值 | ssl_dyn_rec_size_lo 1369; |
| 上下文 | http, server |
动态记录大小的默认大小定义为：对于 lo，单个 TCP 段包含最大 TLS + IPv6 开销；对于 hi，包含 3 个 TCP 段：1369 = 1500 – 40 (IP) – 20 (TCP) – 10 (时间) – 61 (最大 TLS 开销)
| 指令 | ssl_dyn_rec_size_hi |
|---|---|
| 语法 | ssl_dyn_rec_size_hi number; |
| 默认值 | ssl_dyn_rec_size_hi 4229; |
| 上下文 | http, server |
4229 = (1500 – 40 – 20 – 10) * 3 – 61
| 指令 | ssl_dyn_rec_threshold |
|---|---|
| 语法 | ssl_dyn_rec_threshold number; |
| 默认值 | ssl_dyn_rec_threshold 40; |
| 上下文 | http, server |
访问 ngx_http_tls_dyn_size 代码库了解更多信息。
严格 SNI 验证
添加 SNI 和 Host 头的验证步骤，当请求违反规则时，立即返回状态码 421 Misdirected Request。
| 指令 | ssl_strict_server_name |
|---|---|
| 语法 | ssl_strict_server_name on | off | mtls_only; |
| 默认值 | ssl_strict_server_name mtls_only; |
| 上下文 | http, server |
启用严格 SNI 验证。当请求的 SNI 和主机头不同时，会立即返回状态码 421 Misdirected Request。mtls_only 用于仅在启用 ssl_verify_client 的情况下启用严格的 SNI 验证。
关于 SSL 握手时间戳和耗时变量
引入了新的变量来获取 SSL 握手的开始时间戳、结束时间戳和耗时。
| 变量 | 描述 |
|---|---|
| $ssl_handshake_start_msec | SSL 握手开始时间戳（以秒为单位，精度为毫秒）。 |
| $ssl_handshake_end_msec | SSL 握手结束时间戳（以秒为单位，精度为毫秒）。 |
| $ssl_handshake_time | 以毫秒为单位记录 SSL 握手耗时。 |
ngx_http_slice_filter_module
slice_allow_methods
| 指令 | slice_allow_methods |
|---|---|
| 语法 | slice_allow_methods GET | HEAD …; |
| 默认值 | slice_allow_methods GET HEAD; |
| 上下文 | http, server, location |
如果客户端请求方法在此指令中列出，则允许将响应拆分为多个切片。请注意，即使未设置 slice 指令或该指令值为零，仍将禁用将响应拆分为多个切片的功能。
slice_check_etag
| 指令 | slice_check_etag |
|---|---|
| 语法 | slice_check_etag on | off; |
| 默认值 | slice_check_etag on; |
| 上下文 | http, server, location |
是否检查切片中 Etag 头的一致性。如果启用，当切片响应中的 Etag 不匹配时，请求将被终止并报错。
slice_check_last_modified
| 指令 | slice_check_last_modified |
|---|---|
| 语法 | slice_check_last_modified on | off; |
| 默认值 | slice_check_last_modified off; |
| 上下文 | http, server, location |
是否检查切片中 Last-Modified 头的一致性。如果启用，当切片响应中的 Last-Modified 不匹配时，请求将被终止并报错。
ngx_http_sub_filter_module
条件响应替换绕过
此补丁引入了 sub_filter_bypass 指令，用于根据一组变量的值绕过 sub_filter。
| 指令 | sub_filter_bypass |
|---|---|
| 语法 | sub_filter_bypass string …; |
| 默认值 | – |
| 上下文 | http, server, location |
定义响应不会被替换的条件。如果字符串参数中至少有一个值不为空且不等于”0″，则响应不会被替换。
sub_filter_bypass $cookie_nocache $arg_nocache$arg_comment;
sub_filter_bypass $http_pragma $http_authorization;
ngx_http_proxy_module 及相关模块
在”proxy_set_header”及其相关模块中支持继承
引入”proxy_set_header_inherit”指令，该指令设置为 off 时，会在接收上下文中阻止合并继承。添加此机制的目的是减少 nginx 配置中通用设置（或样板）请求标头的重复，同时保持为特定路径设置额外标头的灵活性。原始补丁来自[PATCH] 为 proxy_set_header 添加合并继承。
现有配置的行为保持不变。
| 指令 | proxy_set_header_inherit |
|---|---|
| 语法 | proxy_set_header_inherit on | off; |
| 默认值 | proxy_set_header_inherit off; |
| 上下文 | http, server, location |
允许在接收上下文中合并继承 proxy_set_header。
grpc_set_header_inherit 也可用。
| 指令 | fastcgi_param_inherit |
|---|---|
| 语法 | fastcgi_param_inherit on | off; |
| 默认值 | fastcgi_param_inherit off; |
| 上下文 | http, server, location |
允许在接收上下文中合并继承 fastcgi_param。
scgi_param_inherit 和 uwsgi_param_inherit 也可用。
增强上游 Cookie 处理
除了原有的三个指令（proxy_cookie_domain、proxy_cookie_flags 和 proxy_cookie_path）之外，还新增了更多处理指令，以便更高效地改写上游响应中的 “Set-Cookie” 头。
| 指令 | proxy_cookie_value |
|---|---|
| 语法 | proxy_cookie_value off; proxy_cookie_value cookie cookie_value replacement; |
| 默认值 | proxy_cookie_value off; |
| 上下文 | http, server, location |
设置上游服务器响应中 “Set-Cookie” 头字段的 Cookie 值应更改的文本。假设上游服务器返回了 “Set-Cookie” 头字段，cookie 名称为 “sessionid”，值为 “1234567890”。指令
proxy_cookie_value sessionid 1234567890 abcdefghij;
会将 Cookie 值改写为 “abcdefghij”。
cookie、cookie_value 和 replacement 字符串可以包含变量和正则表达式。cookie 也可以通过正则表达式指定。当 cookie_value 使用正则表达式时，支持命名和位置捕获，replacement 可以引用这些捕获。
多个 proxy_cookie_value 指令可以在同一层级指定，适用第一个匹配的指令。off 参数取消从上一配置层级继承的所有 proxy_cookie_value 指令的效果。
| 指令 | proxy_cookie_max_age |
|---|---|
| 语法 | proxy_cookie_max_age off; proxy_cookie_max_age cookie time; |
| 默认值 | proxy_cookie_max_age off; |
| 上下文 | http, server, location |
设置上游服务器响应中 “Set-Cookie” 头字段的 Cookie 最大有效期限。通过修改 “Max-Age” 或 “Expires” 属性来控制特定 Cookie 的过期时间。如果 “Max-Age” 或 “Expires” 属性未设置，则会向 Cookie 添加 “Max-Age”。
proxy_cookie_max_age SESSION 1h;
cookie 也可以通过正则表达式指定。多个 proxy_cookie_max_age 可以在同一层级指定，适用第一个匹配的指令。
| 指令 | proxy_hide_cookie |
|---|---|
| 语法 | proxy_hide_cookie cookie; |
| 默认值 | – |
| 上下文 | http, server, location |
设置按 Cookie 名称不传递的 “Set-Cookie” 字段。另请参阅 proxy_hide_header 指令。
fastcgi_hide_cookie、scgi_hide_cookie 和 uwsgi_hide_cookie 指令也可用。
增强上游缓存控制
引入一些新的缓存相关指令，以增强对上游缓存行为的控制。
| 指令 | proxy_ignore_cache_control |
|---|---|
| 语法 | proxy_ignore_cache_control field …; |
| 默认值 | – |
| 上下文 | http, server, location |
禁用处理上游响应中 Cache-Control 标头的某些字段。以下字段可以忽略：
- no-cache
- no-store
- private
- max-age
- s-maxage
- stale-while-revalidate
- stale-if-error
fastcgi_ignore_cache_control、scgi_ignore_cache_control 和 uwsgi_ignore_cache_control 指令也可用。
| 指令 | proxy_cache_min_age |
|---|---|
| 语法 | proxy_cache_min_age time; |
| 默认值 | proxy_cache_min_age 0s; |
| 上下文 | http, server, location |
如果从上游接收到的 Cache-Control 头中的 max-age/s-maxage 小于指定的最小年龄，则 max-age/s-maxage 值将设置为配置的最小年龄值。例如，如果收到的 HTTP 标头中的 max-age/s-maxage 值为 100 秒，且配置的最小年龄值为 200 秒，则有效缓存时间为 200 秒。此指令不会重写 Cache-Control 标头。此指令的值支持变量。
fastcgi_cache_min_age、scgi_cache_min_age 和 uwsgi_cache_min_age 指令也可用。
| 指令 | proxy_cache_stale_if_error |
|---|---|
| 语法 | proxy_cache_stale_if_error time; |
| 默认值 | proxy_cache_stale_if_error 0s; |
| 上下文 | http, server, location |
Cache-Control 标头字段的 stale-if-error 扩展允许在发生错误时使用过时的缓存响应。当 Cache-Control 头中缺少 stale-if-error 时，此指令将取代 Cache-Control 头中的 stale-if-error 扩展指令生效。此指令的优先级低于使用 proxy_cache_use_stale 指令参数。此指令的值支持变量。
fastcgi_cache_stale_if_error、scgi_cache_stale_if_error 和 uwsgi_cache_stale_if_error 指令也可用。
| 指令 | proxy_cache_stale_while_revalidate |
|---|---|
| 语法 | proxy_cache_stale_while_revalidate time; |
| 默认值 | proxy_cache_stale_while_revalidate 0s; |
| 上下文 | http, server, location |
Cache-Control 头字段中的 stale-while-revalidate 扩展指令允许使用过时的缓存响应（如果当前正在更新）。当 Cache-Control 头中缺少 stale-while-revalidate 时，此指令将代替 Cache-Control 头中的 stale-while-revalidate 扩展生效。此指令的优先级低于使用 proxy_cache_use_stale 指令参数。该指令的值支持变量。
fastcgi_cache_stale_while_revalidate、scgi_cache_stale_while_revalidate 和 uwsgi_cache_stale_while_revalidate 指令也可用。
| 指令 | proxy_cache_types |
|---|---|
| 语法 | proxy_cache_types mime-type …; |
| 默认值 | proxy_cache_types text/html; |
| 上下文 | http, server, location |
除了”text/html”之外，还启用指定 MIME 类型的上游缓存。特殊值”*”可匹配任何 MIME 类型。
fastcgi_cache_types、scgi_cache_types 和 uwsgi_cache_types 指令也可用。
| 指令 | proxy_cache_valid |
|---|---|
| 语法 | proxy_cache_valid [code …] time; |
| 默认值 | – |
| 上下文 | http, server, location |
请参阅 proxy_cache_valid。
此指令已更改为支持将缓存时间配置为变量。其他行为保持不变。
| 指令 | proxy_cache_vary |
|---|---|
| 语法 | proxy_cache_vary bypass | clear | string; |
| 默认值 | proxy_cache_vary bypass; |
| 上下文 | http, server, location |
控制上游缓存的 Vary 头处理。
示例：
proxy_cache_vary Test-Header;
如果客户端请求包含 Test-Header 头，则不同值的缓存将区分对待。
proxy_cache_vary "Test-Header-A, Test-Header-B";
缓存将根据请求头 Test-Header-A 和 Test-Header-B 的值进行区分。
bypass 用于禁用 Vary 头处理。此外，如果参数值为空，行为与 bypass 一致。clear 用于清除所有 Vary 头。参数值可以包含变量。
此指令仅影响上游缓存，不影响发送给客户端的响应头。如需同时修改响应给客户端的 Vary 头，请使用 proxy_hide_header 和 add_header 指令。
fastcgi_cache_vary、scgi_cache_vary 和 uwsgi_cache_vary 指令也可用。
| 指令 | proxy_cache_force_invalidate |
|---|---|
| 语法 | proxy_cache_force_invalidate string …; |
| 默认值 | – |
| 上下文 | http, server, location |
定义强制使缓存响应失效的条件。如果字符串参数中至少有一个值不为空且不等于”0″，则相应的缓存条目将被标记为无效。后续匹配该缓存键的请求将绕过已失效的条目，从上游获取内容。失效的缓存条目将获得 MISS 状态，这会触发立即从上游拉取，同时绕过缓存重新验证。
主要用于解决在缓存清除操作（基于模式匹配）完成之前请求可能命中缓存条目的场景。
fastcgi_cache_force_invalidate、scgi_cache_force_invalidate、uwsgi_cache_force_invalidate 指令也可用。
| 指令 | proxy_cache_force_expire |
|---|---|
| 语法 | proxy_cache_force_expire string …; |
| 默认值 | – |
| 上下文 | http, server, location |
定义强制使缓存响应过期的条件。如果字符串参数中至少有一个值不为空且不等于”0″，则相应的缓存条目将被标记为已过期。后续匹配该缓存键的请求将从上游获取新内容。已过期的缓存条目将获得 EXPIRED 状态。如果启用了 proxy_cache_revalidate 指令，则可以执行缓存重新验证。
fastcgi_cache_force_expire、scgi_cache_force_expire、uwsgi_cache_force_expire 指令也可用。
| 指令 | proxy_cache_min_length |
|---|---|
| 语法 | proxy_cache_min_length size; |
| 默认值 | proxy_cache_min_length 0; |
| 上下文 | http, server, location |
指定可缓存的最小响应长度。仅检查 Content-Length 头的大小。对于分块响应或既没有 Content-Length 头也没有 Transfer-Encoding 头的响应，此指令将被忽略。
fastcgi_cache_min_length、scgi_cache_min_length、uwsgi_cache_min_length 指令也可用。
| 指令 | proxy_cache_max_length |
|---|---|
| 语法 | proxy_cache_max_length size; |
| 默认值 | proxy_cache_max_length 0; |
| 上下文 | http, server, location |
指定可缓存的最大响应长度。仅检查 Content-Length 头的大小。对于分块响应或既没有 Content-Length 头也没有 Transfer-Encoding 头的响应，此指令将被忽略。值为 0 表示不设上限。
fastcgi_cache_max_length、scgi_cache_max_length、uwsgi_cache_max_length 指令也可用。
ngx_http_upstream_module
用于上游信息的额外变量
必须编译模块 ngx_http_extra_variables_module 才能使用这些变量。
| 变量 | 描述 |
|---|---|
| $upstream_method | 上游方法，通常为”GET”或”POST”。 |
| $upstream_start_msec | 保存上游启动的时间戳；时间以秒为单位，精度为毫秒。多个响应的时间用逗号和冒号分隔，就像 $upstream_addr 变量中的地址一样。 |
| $upstream_last_start_msec | 保存最近上游启动的时间戳；时间以秒为单位，精度为毫秒。 |
| $upstream_ssl_start_msec | 保存上游 SSL 握手开始的时间戳；该时间以秒为单位，精度为毫秒。多个响应的时间像 $upstream_addr 变量中的地址一样，用逗号和冒号分隔。 |
| $upstream_last_ssl_start_msec | 保存最新的上游 SSL 握手开始的时间戳；该时间以秒为单位，精度为毫秒。 |
| $upstream_send_start_msec | 保存上游请求发送开始的时间戳；该时间以秒为单位，精度为毫秒。多个响应的时间像 $upstream_addr 变量中的地址一样，用逗号和冒号分隔。 |
| $upstream_last_send_start_msec | 保存最新的上游请求发送开始的时间戳；该时间以秒为单位，精度为毫秒。 |
| $upstream_send_end_msec | 保存上游请求发送结束的时间戳；时间以秒为单位，精度为毫秒。多个响应的时间像 $upstream_addr 变量中的地址一样，用逗号和冒号分隔。 |
| $upstream_last_send_end_msec | 保存最新上游请求发送结束的时间戳；时间以秒为单位，精度为毫秒。 |
| $upstream_header_msec | 保存发送上游响应头的时间戳；时间以秒为单位，精度为毫秒。多个响应的时间像 $upstream_addr 变量中的地址一样，用逗号和冒号分隔。 |
| $upstream_last_header_msec | 保存发送最新上游响应头的时间戳；时间以秒为单位，精度为毫秒。 |
| $upstream_end_msec | 保存发送上游响应或异常中断的时间戳；时间以秒为单位，精度为毫秒。多个响应的时间像 $upstream_addr 变量中的地址一样，用逗号和冒号分隔。 |
| $upstream_last_end_msec | 保存最新发送的上游响应或异常中断的时间戳；时间以秒为单位，精度为毫秒。 |
| $upstream_transport_connect_time | 保存与上游服务器建立连接所花费的时间；时间以秒为单位，精度为毫秒。对于 SSL，不包括握手所花费的时间。多个连接的时间像 $upstream_addr 变量中的地址一样，用逗号和冒号分隔。 |
| $upstream_last_transport_connect_time | 保存与上游服务器建立连接所花费的时间；时间以秒为单位，精度为毫秒。对于 SSL，不包括握手所花费的时间。 |
| $upstream_ssl_time | 保存上游 SSL 握手所花费的时间；时间以秒为单位，精度为毫秒。请注意，此计时仅在收到上游请求标头后开始。多个 SSL 连接的时间以逗号和冒号分隔，就像 $upstream_addr 变量中的地址一样。 |
| $upstream_last_ssl_time | 保存最新上游 SSL 握手所花费的时间；时间以秒为单位，精度为毫秒。请注意，此计时仅在收到上游请求标头后开始。 |
| $upstream_send_time | 保存向上游服务器发送请求所花费的时间；时间以秒为单位，精度为毫秒。多个发送请求的时间以逗号和冒号分隔，就像 $upstream_addr 变量中的地址一样。 |
| $upstream_last_send_time | 保存向最新上游服务器发送请求所花费的时间；时间以秒为单位，精度为毫秒。 |
| $upstream_read_time | 保存从上游服务器读取响应所花费的时间；时间以秒为单位，精度为毫秒。请注意，此计时仅在收到上游请求标头后开始。多个响应的时间用逗号和冒号分隔，就像 $upstream_addr 变量中的地址一样。 |
| $upstream_last_read_time | 记录从最新上游服务器读取响应所花费的时间；该时间以秒为单位，精度为毫秒。请注意，此计时仅在收到上游请求标头后开始。 |
ngx_http_realip_module
使用多个请求标头配置真实客户端 IP
| 指令 | real_ip_header |
|---|---|
| 语法 | real_ip_header field | X-Real-IP | X-Forwarded-For | proxy_protocol; |
| 默认值 | real_ip_header X-Real-IP; |
| 上下文 | http, server, location |
定义将使用其值替换客户端地址的请求标头字段。
如果定义了多个请求字段，则将按照配置中定义的顺序检查标头值，并使用第一个具有有效值的标头：
real_ip_header X-Real-IP Cdn-Src-Ip X-Forwarded-For;
将依次检查上述标头的值，直到找到有效值。
包含可选端口的请求标头字段值也用于替换客户端端口。地址和端口应根据 RFC 3986 指定。
proxy_protocol 参数会将客户端地址更改为 PROXY 协议标头中的地址。必须事先通过设置 listen 指令中的 proxy_protocol 参数来启用 PROXY 协议。
ngx_http_rewrite_module
扩展了原重写模块的”if”指令。它具有以下功能：
为”if”指令添加更多运算符
除了原有的”if”条件运算符外，还支持：
* <
* >
* !< 或 >=
* !> 或 <=
* ^~（开头为）或 !^~（开头不为）
比较符号支持小数和负数。非数字输入将始终返回负数结果。
带有多个条件的”if”
| 指令 | if |
|---|---|
| 语法 | if (conditions) {…} |
| 默认值 | – |
| 上下文 | server, location |
支持在 if 语句中使用&&和||运算符。
支持基于括号的子条件。
示例：
if ($remote_addr = 192.168.1.1 && ($http_user_agent ~ 'Mozilla' || $server_port > 808)) {
return 404;
}
已知限制 1：
使用基于括号的条件分组时，条件语句的最后一个字符不能是”)”，即使它被引号括起来。例如，以下表达式将导致配置测试错误。
if (($test_var = "test)" && $http_user_agent ~ 'Mozilla') || $server_port > 808) {
return 404
}
如果必须使用以 ‘)’ 结尾的字符串，可以考虑使用变量来支持它。
set $value "test)";
if (($test_var = $value && $http_user_agent ~ 'Mozilla') || $server_port > 808) {
return 404
}
如果是正则表达式，可以通过多种方式避免在末尾使用 ‘)’。
已知限制 2：
所有子条件都会先求值，然后再计算表达式结果。这与一般编程语言的子条件处理逻辑不同。
已知限制 3：
由于 nginx 脚本引擎的限制，如果使用正则捕获，则只能获取最后一个匹配的正则表达式的捕获组。
支持”elif”和”else”指令
| 指令 | elif |
|---|---|
| 语法 | elif (condition) {…} |
| 默认值 | – |
| 上下文 | server, location |
与 if 类似，但如果此指令前面没有 if/elif 指令，或者前面的 if/elif 指令的结果为 true，则不会生效。
此指令将创建一个新的 location，就像 if 指令一样，请参阅 if is evil
| 指令 | else |
|---|---|
| 语法 | else {…} |
| 默认值 | – |
| 上下文 | server, location |
与 if 和 elif 类似，但不包含任何条件表达式，因此始终为 true。如果此指令前面没有 if/elif 指令，或者前面的 if/elif 指令的结果为 true，则此指令不会生效。
此指令将像 if 一样创建一个新的 location，请参考 if is evil
ngx_http_gunzip_module
支持强制 gzip 解压
这是一个简单的补丁，修改了 NGINX gunzip 过滤器模块，以强制对压缩的响应进行 inflate 操作。对于发送 gzip 压缩响应的上游源，此功能是理想的选择。请阅读”其他评论”部分，了解这将解压所有内容，因此您需要尽可能具体地指定其用途，以避免解压您原本不想修改的内容。
此功能有多种用途：
- 在上游服务器和 nginx 之间维持 gzip 压缩传输，减少网络带宽占用。
- 某些模块需要上游内容解压才能正常工作。
- 允许 nginx 在将数据发送到客户端之前重新压缩数据（例如 brotli）。
此功能已成功测试到 1.20.0 版本（截至撰写本文时的最新版本）。gunzip 模块代码变化不大（如果有的话），所以它应该可以完美地针对旧版本/未来版本进行补丁。
原始补丁来自强制 gunzip 过滤器模块工作的补丁。原作者是姚伟斌。
默认情况下不构建 gunzip 模块，您必须在编译 nginx 时指定 –with-http_gunzip_module 选项。
| 指令 | gunzip_force |
|---|---|
| 语法 | gunzip_force string …; |
| 默认值 | – |
| 上下文 | http, server, location |
定义强制 gzip 解压的条件。如果字符串参数中至少有一个值不为空且不等于”0″，则执行强制 gzip 解压。但它不会尝试解压缩不包含响应头 Content-Encoding: gzip 的响应。
ngx_http_gzip_filter_module
gzip_max_length
| 指令 | gzip_max_length |
|---|---|
| 语法 | gzip_max_length length; |
| 默认值 | gzip_max_length 0; |
| 上下文 | http, server, location |
设置将被 gzip 压缩的响应的最大长度。该长度仅由”Content-Length”响应头字段决定。值为 0 表示无上限。
gzip_bypass
| 指令 | gzip_bypass |
|---|---|
| 语法 | gzip_bypass string …; |
| 默认值 | – |
| 上下文 | http, server, location |
定义响应不会被 gzip 压缩的条件。如果字符串参数中至少有一个值不为空且不等于”0″，则响应不会被 gzip 压缩。
ngx_http_log_module
access_log 指令支持反向条件
| 指令 | access_log |
|---|---|
| 语法 | access_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition | if!=condition]]; access_log off; |
| 默认值 | access_log logs/access.log combined; |
| 上下文 | http, server, location, if in location, limit_except* |
参考 access_log
在原有 if= 参数的基础上，你可以将 if= 改为 if!= 来实现相反的效果。
ngx_http_waf_module（第三方模块）
请参阅 ngx_waf。
此补丁对该模块进行了一些更改，主要添加了更多开关，用于对 WAF 行为进行细粒度控制。此外，它还更改了默认质询或错误页面的外观以及配置文件的读取路径。
waf_bypass
| 指令 | waf_bypass |
|---|---|
| 语法 | waf_bypass string …; |
| 默认值 | – |
| 上下文 | http, server, location |
定义 waf 是否会检查请求的条件。如果字符串参数中至少有一个值不为空且不等于”0″，则 waf 将检查该请求。
waf_cc_deny_bypass
| 指令 | waf_cc_deny_bypass |
|---|---|
| 语法 | waf_cc_deny_bypass string …; |
| 默认值 | – |
| 上下文 | http, server, location |
定义请求在何种条件下会被 waf cc 拒绝函数检查。如果字符串参数中至少有一个值不为空且不等于”0″，则该请求将被 waf cc 拒绝函数检查。
waf_under_attack_bypass
| 指令 | waf_under_attack_bypass |
|---|---|
| 语法 | waf_under_attack_bypass string …; |
| 默认值 | – |
| 上下文 | http, server, location |
定义请求在何种条件下会被 waf under attack 函数检查。如果字符串参数中至少有一个值不为空且不等于”0″，则该请求将被 waf under attack 函数检查。
waf_captcha_bypass
| 指令 | waf_captcha_bypass |
|---|---|
| 语法 | waf_captcha_bypass string …; |
| 默认值 | – |
| 上下文 | http, server, location |
定义 waf captcha 函数在何种条件下会检查请求。如果字符串参数中至少有一个值不为空且不等于”0″，则 waf captcha 函数会检查该请求。
waf_modsecurity_bypass
| 指令 | waf_modsecurity_bypass |
|---|---|
| 语法 | waf_modsecurity_bypass string …; |
| 默认值 | – |
| 上下文 | http, server, location |
定义 waf modsecurity 函数在何种条件下会检查请求。如果字符串参数中至少有一个值不为空且不等于”0″，则 waf modsecurity 函数会检查该请求。
ngx_http_headers_more_filter_module（第三方模块）
此模块包含在 OpenResty 官方软件包中。
more_set_headers
| 指令 | more_set_headers |
|---|---|
| 语法 | more_set_headers [-t \ |
| 默认值 | – |
| 上下文 | http, server, location, location if |
请参阅 more_set_headers。仅添加了 if 参数，其他参数保持不变。您也可以通过将 if= 更改为 if!= 来实现相反的效果。
more_clear_headers
| 指令 | more_clear_headers |
|---|---|
| 语法 | more_clear_headers [-t \ |
| 默认值 | – |
| 上下文 | http, server, location, location if |
请参阅 more_clear_headers。仅添加了 if 参数，其他参数保持不变。您也可以通过将 if= 更改为 if!= 来实现相反的效果。
more_set_input_headers
| 指令 | more_set_input_headers |
|---|---|
| 语法 | more_set_input_headers [-r] [-t \ |
| 默认值 | – |
| 上下文 | http, server, location, location if |
请参阅 more_set_input_headers。仅添加了 if 参数，其他参数保持不变。您也可以通过将 if= 更改为 if!= 来实现相反的效果。
more_clear_input_headers
| 指令 | more_clear_input_headers |
|---|---|
| 语法 | more_clear_input_headers [-t \ |
| 默认值 | – |
| 上下文 | http, server, location, location if |
请参阅 more_clear_input_headers。仅添加了 if 参数，其他参数保持不变。您也可以通过将 if= 更改为 if!= 来实现相反的效果。
ngx_stream_ssl_module
关于 SSL 握手时间戳和耗时变量
在 Stream 子系统中，引入了新的变量来获取 SSL 握手的开始时间戳、结束时间戳和耗时。必须编译模块 ngx_stream_extra_variables_module 才能使用这些变量。
| 变量 | 描述 |
|---|---|
| $ssl_handshake_start_msec | SSL 握手开始时间戳（以秒为单位，精度为毫秒）。 |
| $ssl_handshake_end_msec | SSL 握手结束时间戳（以秒为单位，精度为毫秒）。 |
| $ssl_handshake_time | 以毫秒为单位记录 SSL 握手耗时。 |
ngx_stream_upstream_module
用于上游信息的额外变量
| 变量 | 描述 |
|---|---|
| $upstream_status | 保存上游连接的状态。对于多次连接尝试，值用逗号和冒号分隔，就像 $upstream_addr 变量中的地址一样。如果没有可用的状态，则显示短横线（”-“）。 |
LuaRocks
LuaRocks 是 Lua 模块的包管理器。
它允许您创建并安装 Lua 模块，并将其作为名为 rocks 的独立包。
LuaRocks 是一款免费软件，使用与 Lua 相同的许可证。
coreruleset
OWASP CRS 是一组通用的攻击检测规则，可与 ModSecurity 或兼容的 Web 应用程序防火墙配合使用。CRS 旨在保护 Web 应用程序免受各种攻击（包括 OWASP 十大攻击）的侵害，并将误报率降至最低。
Copyright (c) 2006-2020 Trustwave and contributors. All rights reserved.
Copyright (c) 2021-2025 CRS project. All rights reserved.
OWASP CRS 根据 Apache 软件许可证 (ASL) 版本 2 分发。请参阅 LICENSE 以了解完整详细信息。
版权与许可
此软件包本身遵循 2-clause BSD 许可证。
NGINX 是 F5 NETWORKS, INC. 的注册商标。
OpenResty® 是 OpenResty Inc. 的注册商标。
此定制软件包的维护者 (Hanada) 并非由 OpenResty Inc. 或 NGINX Official/F5 NETWORKS, INC. 赞助或与其有任何关联。
详情请参阅许可证。
更新频率居然比我的网站还低