Nginx:从事件驱动内核到云原生网关

举报
lapis 发表于 2026/11/17 13:49:01 2026/11/17
【摘要】 引言Nginx 诞生于 2004 年,最初的目标非常明确:解决 C10K 问题——如何用一台服务器同时承载上万个并发连接。二十多年过去,这一目标早已成为基本功,但 Nginx 并没有停留在"高性能静态文件服务器 + 反向代理"的定位上。它通过稳定的核心架构、持续的协议演进和可控的扩展机制,成为了现代基础设施中少数几个几乎无处不在的组件:CDN 边缘节点、API 网关、Kubernetes ...

引言

Nginx 诞生于 2004 年,最初的目标非常明确:解决 C10K 问题——如何用一台服务器同时承载上万个并发连接。二十多年过去,这一目标早已成为基本功,但 Nginx 并没有停留在"高性能静态文件服务器 + 反向代理"的定位上。它通过稳定的核心架构、持续的协议演进和可控的扩展机制,成为了现代基础设施中少数几个几乎无处不在的组件:CDN 边缘节点、API 网关、Kubernetes 入口、Service Mesh 的数据面旁路、流媒体分发、gRPC 与 HTTP/3 的接入层,都能看到它的身影。

本文面向已经了解基本反向代理配置、希望系统化理解"现代 Nginx"的工程人员。内容覆盖运行时架构、近年新增的关键能力、负载均衡与缓存策略、TLS 与 HTTP/3、可观测性、安全加固、脚本化扩展,以及生产环境中的常见陷阱。文中不提供任何外部地址,所有配置片段均可直接作为起点进行改造。


一、现代 Nginx 的运行时架构

1.1 Master–Worker 模型

Nginx 启动后会分裂为两类进程:

  • master 进程:以 root 身份运行,负责读取配置、绑定监听端口、创建共享内存区、管理 worker 进程的生命周期,自身不处理任何请求。
  • worker 进程:以非特权用户运行,每个 worker 都是单线程的事件循环,独立处理连接。worker 数量由 worker_processes 决定,生产环境通常设为 auto,即等于可用 CPU 核心数。

这种设计带来三个直接好处:

  1. 故障隔离:单个 worker 崩溃不影响整体服务,master 会立即拉起新进程。
  2. 无锁化:worker 之间不共享连接状态,仅在共享内存中共享缓存元数据、限流计数器、upstream 健康状态等少量数据,避免了用户态锁竞争。
  3. 平滑升级:master 支持二进制热替换,新旧 worker 可短暂共存,连接不中断。

自 1.9.1 起支持 worker_cpu_affinity auto,可将 worker 绑定到 CPU 核,减少上下文切换与缓存失效。在高 PPS 场景(如四层转发、TLS 终结)中,这一项带来的收益往往比调整缓冲区更明显。

1.2 事件驱动与多路复用

worker 的核心是一个事件循环,在 Linux 上使用 epoll,在 BSD 系使用 kqueue,在 Solaris 系使用 eventport,Windows 上则退化为 select。配置项 use 在现代版本中几乎不需要显式指定,构建时会自动选择最优机制。

关键点在于:一个连接在等待网络 I/O 时不占用线程。因此单 worker 的并发能力主要受限于 worker_connections(默认 512,生产常设为 1024 到 65535)以及文件描述符上限。需要注意,反向代理场景下每个客户端连接会消耗两个连接(客户端侧 + 上游侧),所以理论并发约为 worker_connections / 2。

worker_processes auto;
worker_rlimit_nofile 65535;

events {
    worker_connections 16384;
    multi_accept on;
}

multi_accept 让 worker 在一次唤醒中尽可能多地 accept 新连接,在突发流量下能降低延迟抖动;但在极高并发下可能造成连接在 worker 间分布不均,需结合实际压测决定。

1.3 连接复用与 listen 优化

自 1.9.1 起支持 listen ... reuseport,由内核在多个 worker 之间分流新连接。相比默认的"惊群"唤醒机制,SO_REUSEPORT 能把连接哈希到不同 worker 的独立 accept 队列,显著降低高并发下的调度开销。从 1.15.3 起还支持 BPF 形式的 reuseport,可在四层做基于地址与端口的稳定分流,避免内核哈希在 worker 重启后导致连接重分布。

listen 80 reuseport;
listen 443 ssl reuseport;
listen 443 quic reuseport;

注意:同一组地址端口上启用 reuseport 时,必须所有监听该端口的指令都带上该参数,否则 Nginx 会拒绝启动。

1.4 内存管理与零拷贝

Nginx 自行实现了内存池(pool),按请求生命周期批量分配与释放,避免频繁调用 malloc。这让它在长连接、大并发下依然保持稳定的内存曲线。

数据路径上,静态文件通过 sendfile on 走内核零拷贝,绕过用户态缓冲区;配合 tcp_nopush on 让响应头与文件首段在同一次发送中发出,减少小包数量。对于大文件或高延迟链路,tcp_nodelay on 则用于抑制 Nagle 算法造成的额外延迟。Nginx 默认开启该指令,但只在长连接(keepalive)上设置该选项,短连接不受影响。

当磁盘 I/O 可能阻塞事件循环时(例如读取大静态文件、执行代理缓存写入),应启用线程池:

aio threads;
directio 4m;
output_buffers 4 256k;

aio threads 会把阻塞型文件操作卸载到独立线程池(由 thread_pool 指令定义),使 worker 的事件循环不被磁盘拖慢。directio 对超过阈值的文件绕过页缓存,适合一次性大文件分发;但对于会被反复访问的资源应保持关闭,否则会破坏缓存命中。


二、现代版本带来的关键能力

2.1 HTTP/3 与 QUIC

自 1.25.0 起,Nginx 提供了 HTTP/3 的实验性实现,1.25.1 将其拆分并持续完善。启用方式分为两步:在 UDP 端口上开启 quic,并在 HTTP 层启用 http3。

server {
    listen 443 ssl;
    listen 443 quic reuseport;
    server_name _;

    ssl_certificate     /etc/nginx/ssl/site.crt;
    ssl_certificate_key /etc/nginx/ssl/site.key;
    ssl_protocols       TLSv1.2 TLSv1.3;

    add_header Alt-Svc 'h3=":443"; ma=86400' always;

    http3 on;
    quic_retry on;

    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
    }
}

几个实践要点:

  • HTTP/3 强制要求 TLS 1.3,ssl_protocols 中若不包含 TLSv1.3,UDP 监听会失效。
  • Alt-Svc 响应头是浏览器发现 HTTP/3 的主要途径,ma 建议不小于 86400 秒,always 保证错误响应也携带该头。
  • quic_retry on 启用地址验证,可有效缓解 UDP 反射放大攻击。
  • 回退机制天然存在:客户端若无法建立 QUIC 连接,会自动回落到 TCP 上的 HTTP/2 或 HTTP/1.1,因此灰度上线风险较低。
  • 观察指标应关注 UDP 丢包率与 quic_* 相关连接统计,而不是简单沿用 HTTP/1.1 的 QPS 曲线。

2.2 上游域名的动态解析

长期以来,upstream 块中的 server 名称只在启动或重载时解析一次,容器环境中后端 IP 变化后必须 reload。1.27.3 引入了在 upstream 内直接使用 resolve 参数的能力:

resolver 127.0.0.53 valid=10s ipv6=off;

upstream app_backend {
    zone app_backend 64k;
    server app-backend:8080 resolve;
    keepalive 64;
}

zone 是必需的前提,因为解析结果需要保存在共享内存中,供所有 worker 一致使用。这一特性让 Nginx 在动态环境中不再强依赖"配置模板 + reload",与 Consul、DNS SRV、Kubernetes Headless Service 等发现机制配合时更为自然。

需要注意的是,resolve 使用的是 Nginx 自身的解析器,不复用系统 glibc 的解析路径,因此 resolver 指令必须显式配置。该解析器默认同时查询 A 与 AAAA 记录,若后端仅监听 IPv4,建议显式设置 ipv6=off,避免上游拿到不可达的 AAAA 地址后再触发重试。

2.3 主动健康检查的替代方案

开源版本仅提供被动健康检查(max_fails + fail_timeout),以及 proxy_next_upstream 触发的重试。现代实践中通常用三种方式补齐:

  1. 被动标记 + 快速摘除:设置较小的 max_fails 与 fail_timeout,并让上游在健康时返回真实状态码,避免把 5xx 全部归因为上游故障(可用 proxy_next_upstream 精确控制哪些状态码触发重试)。
  2. 共享内存 zone + 一致性:upstream 的 zone 让所有 worker 共享失败计数,否则每个 worker 独立计数会导致摘除行为不一致。
  3. 外部控制器:由编排系统在探测失败时改写 upstream 成员或调用配置重载接口。动态解析能力的引入,使这条路线的收敛时间从"分钟级"降到"秒级"。

对于要求严格的场景,可通过 health_check 相关模块(商业版内置,社区版需第三方模块)实现基于 HTTP 状态、URI、匹配规则与间隔的主动探测;不具备条件时,用外部探针 + 动态解析是更易维护的等价方案。

2.4 OpenTelemetry 原生接入

自 1.25.3 起随源码提供 OpenTelemetry 模块(需在编译时显式启用,1.27.0 起可作为动态模块编译加载)。此前接入链路追踪普遍依赖第三方模块或 Lua,配置复杂且与版本强耦合。原生模块的典型用法:

load_module modules/ngx_otel_module.so;

http {
    otel_exporter {
        endpoint 127.0.0.1:4317;
    }
    otel_trace on;
    otel_trace_context propagate;

    server {
        location /api/ {
            otel_span_name api_gateway;
            otel_span_attr service.name api-gateway;
            proxy_pass http://app_backend;
        }
    }
}

默认使用 OTLP/gRPC 导出。otel_trace 的取值可以是变量,因此可与 map 结合实现按路径或按租户的采样策略;otel_trace_context 负责决定是否沿用上游传入的追踪上下文,从而保持父子链路关系。这对只在上游应用内埋点的团队尤其有价值——网关层的耗时(排队、TLS 握手、上游首字节)终于能被拆开归因。

2.5 更细粒度的 TLS 控制

除 TLS 1.3 之外,近年的几个小改动在生产中价值很高:

  • ssl_reject_handshake on(1.19.4):对未匹配任何 server_name 的 SNI 直接拒绝握手,替代了过去"返回默认站点证书"的做法,能减少证书信息泄露与扫描面。
  • ssl_conf_command(1.19.4):直接向 OpenSSL 传递底层参数,例如关闭会话票据、启用特定曲线,而不必等待 Nginx 暴露对应指令。
  • ssl_early_data on:启用 TLS 1.3 的 0-RTT,配合上游的幂等性约束使用,可显著降低重连延迟;必须在应用侧防御重放。
  • ssl_session_cache shared:SSL:10m 与 ssl_session_timeout 的合理配置,比盲目关闭会话复用更能兼顾安全与性能。
server {
    listen 443 ssl;
    server_name _;
    ssl_reject_handshake on;
}

server {
    listen 443 ssl;
    server_name app;

    ssl_certificate     /etc/nginx/ssl/app.crt;
    ssl_certificate_key /etc/nginx/ssl/app.key;
    ssl_protocols       TLSv1.3;
    ssl_ciphers         TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;
    ssl_prefer_server_ciphers off;

    ssl_session_cache   shared:SSL:20m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/nginx/ssl/ca.pem;
    resolver 127.0.0.53 valid=300s;
}

说明:TLS 1.3 的套件选择由 ssl_ciphers 中的 TLS 1.3 段控制(该用法需要 1.19.4 及以上版本),且顺序不再影响协商结果(客户端偏好优先),因此 ssl_prefer_server_ciphers 在纯 TLS 1.3 环境下应设为 off。若要兼容只支持 TLS 1.2 的客户端,需在 ssl_protocols 中保留 TLSv1.2,并同时提供对应的 ECDHE 套件,否则该部分客户端会因无可用套件而握手失败。OCSP 装订的验证依赖 ssl_trusted_certificate 指向的 CA 证书,并需要可用的 resolver;在离线或内网环境中应确保解析可达,否则装订会静默失败。

2.6 流量镜像与灰度

mirror 指令(1.13.4)把生产请求复制到影子后端,用于新版本验证、压测或数据比对:

location /order/ {
    mirror /mirror;
    mirror_request_body on;
    proxy_pass http://order_v1;
}

location = /mirror {
    internal;
    proxy_pass http://order_v2$request_uri;
    proxy_pass_request_body on;
}

镜像请求的响应被丢弃,不影响主链路,但会真实消耗后端资源,因此需要为影子服务单独限流,或在 mirror 目标上关闭日志与缓存写。

灰度发布则常用 split_clients 做稳定的按比例分流:

split_clients "${remote_addr}${http_user_agent}" $variant {
    5%     v2;
    *      v1;
}

upstream order_v1 { server 10.0.1.11:8080; }
upstream order_v2 { server 10.0.2.11:8080; }

location /order/ {
    proxy_pass http://order_$variant;
}

与随机数相比,基于客户端特征做哈希能保证同一用户在多次请求中落到同一版本,避免会话割裂。若需要按租户精确控制,用 map 从请求头或 Cookie 中提取标识即可。


三、配置模型与组织方式

3.1 上下文与继承规则

Nginx 配置是树形结构,指令在特定上下文中生效:main、events、http、server、location、upstream、stream。继承规则有两个容易踩坑的特点:

  • 数组型指令(如 add_header、proxy_set_header)在子级出现任意一条时,会完全覆盖父级的所有取值,而不是追加。
  • if 在 location 中是"重写阶段"指令,其内部只能安全地放置少数指令(return、rewrite、set 等)。试图在 if 中放 proxy_pass 会得到难以预测的行为,这是官方明确警告的反模式。

因此现代配置更倾向于用 map 表达条件逻辑,把分支从控制流转移为变量求值。

3.2 map、geo 与变量

map 在请求处理早期构建变量,惰性求值,性能开销极低,是实现"配置即逻辑"的核心工具:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

map $request_uri $cache_bypass {
    ~^/api/     1;
    ~^/admin/   1;
    default     0;
}

map $status $loggable {
    ~^[23]  0;
    default 1;
}

geo 则专用于按客户端地址归类,支持 CIDR 与区间,常用于内网识别、地域分流与访问控制:

geo $is_internal {
    default         0;
    10.0.0.0/8      1;
    172.16.0.0/12   1;
    192.168.0.0/16  1;
}

配合 map 与 split_clients,绝大多数过去需要 if 的场景都能被改写为声明式配置,既提升可读性,也避免了重写阶段与内容阶段的执行顺序陷阱。

3.3 include 与配置分层

生产环境的配置通常按职责拆分为若干片段:conf.d 放站点定义、snippets 放通用片段(TLS 参数、安全头、代理头)、upstreams 放后端定义。include 支持通配符且按字典序加载,因此命名前缀(如 10-、20-)可以用来控制覆盖顺序。

需要强调的是:配置分层的目的不是减少行数,而是让变更的影响面可预测。一个常见的反模式是把 add_header 拆到多个 include 中,结果子级片段里的任意一条头设置把父级的全部头覆盖掉,导致安全头在某条路由上静默消失。正确做法是把同一 server 内所有 add_header 集中在最靠近 server 的位置,或统一在 location 内重复声明。


四、反向代理与负载均衡

4.1 代理的基础要点

upstream app_backend {
    zone app_backend 64k;
    least_conn;
    server 10.0.1.11:8080 weight=3 max_fails=3 fail_timeout=10s;
    server 10.0.1.12:8080 weight=1;
    server 10.0.1.13:8080 backup;
    keepalive 64;
    keepalive_requests 1000;
    keepalive_timeout 60s;
}

server {
    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 3s;
        proxy_send_timeout 30s;
        proxy_read_timeout 60s;

        proxy_next_upstream error timeout http_502 http_503;
        proxy_next_upstream_tries 2;
    }
}

几个高频误区:

  • upstream 中的 keepalive 不会自动生效。必须在 location 中设置 proxy_http_version 1.1 并清空 Connection 头,否则每个请求都会新建 TCP 连接,连接复用形同虚设。
  • proxy_pass 的尾部斜杠语义不同。带 URI 的 proxy_pass(如 http://backend/api/)会替换匹配到的 location 前缀;不带 URI 的(如 http://backend)则保留完整原始 URI。混用两者是路径错乱的常见来源。
  • proxy_next_upstream 不应包含 http_500。500 通常意味着业务逻辑错误,重试只会放大问题;http_502、http_503、timeout 才是典型的连接层失败。
  • 超时链路要分层。proxy_connect_timeout 应远小于 proxy_read_timeout,前者用于快速剔除不可达节点,后者用于容忍长耗时接口。网关层的读超时若小于后端业务超时,会造成"后端仍在处理、前端已经重试"的重复副作用。

4.2 调度算法选择

算法 指令 适用场景
轮询 默认 后端同构、请求耗时均匀
加权轮询 weight 机器规格不同
最少连接 least_conn 请求耗时差异大
源地址哈希 ip_hash 有状态会话、无共享存储
通用哈希 hash $key consistent 缓存亲和、分片
随机 random 大规模节点池
最短响应时间 商业版 对尾延迟敏感

一致性哈希(hash $arg_tenant consistent)在缓存分片场景中尤为重要:节点增减时只有约 1/N 的键需要重新映射,而普通哈希几乎全部失效。

4.3 会话保持

如果没有集中式会话存储,可按以下顺序取舍:

  1. 优先改造应用,使用无状态令牌(JWT)或集中式会话存储,从根上消除亲和需求。
  2. 必须亲和时,用 hash 而非 ip_hash——以 Cookie 中的稳定标识作为哈希键,避免用户切换网络后会话漂移。
  3. 节点故障时会话必然丢失,因此需要上游具备快速故障转移能力,或用 sticky 类第三方模块实现基于 Cookie 的粘滞。

4.4 gRPC 与 WebSocket

gRPC 依赖 HTTP/2 端到端,配置上必须显式开启:

location /grpc. {
    grpc_pass grpc://grpc_backend;
    grpc_set_header X-Real-IP $remote_addr;
    grpc_read_timeout 300s;
    grpc_send_timeout 300s;
}

注意 gRPC 的流式调用需要较长的读写超时,且 grpc_pass 与 proxy_pass 不能混用于同一 location。客户端侧若使用 HTTP/2,1.25.1 起推荐写成 listen 443 ssl; 加独立的 http2 on;,而不是旧的 listen ... http2 形式;相应的 http2_max_concurrent_streams 等旧调优参数也已被逐步废弃,前后端的并发流容量应按实际承载能力评估。

WebSocket 只需正确处理升级头(下面的 map 与 3.2 节示例相同,实际配置中只需定义一次):

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

location /ws {
    proxy_pass http://ws_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 3600s;
}

proxy_read_timeout 对 WebSocket 而言是"空闲超时",应按心跳间隔设置为略大于心跳周期的值,否则会在无数据时被误断开。


五、缓存体系

5.1 代理缓存

proxy_cache_path /var/cache/nginx/data
                 levels=1:2
                 keys_zone=app_cache:100m
                 max_size=10g
                 inactive=60m
                 use_temp_path=off;

server {
    location /assets/ {
        proxy_cache app_cache;
        proxy_cache_valid 200 206 1h;
        proxy_cache_valid 404 1m;
        proxy_cache_key "$scheme$host$request_uri";
        proxy_cache_lock on;
        proxy_cache_lock_timeout 5s;
        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
        proxy_cache_background_update on;
        add_header X-Cache-Status $upstream_cache_status;
    }
}

关键参数的工程含义:

  • keys_zone 只存键与元数据,max_size 限制磁盘实体大小,两者需分别规划。
  • proxy_cache_lock on 在多请求同时未命中时只放行一个回源,其余等待,能有效防止缓存击穿导致的回源风暴。
  • proxy_cache_use_stale ... updating 允许在后台更新时继续返回旧内容,配合 proxy_cache_background_update on 实现"先响应、后刷新",对可用性提升明显。
  • proxy_cache_key 的默认值为 $scheme$proxy_host$request_uri;若存在 Host 混用或多协议入口,务必显式构造键,避免跨站点内容串味。缓存只对可安全复用的请求方法有意义,通常无需把 $request_method 放进键。
  • X-Cache-Status 便于快速判断 HIT、MISS、STALE、UPDATING、BYPASS,是最低成本的缓存观测手段。

5.2 缓存分片与范围请求

大文件(视频、安装包)缓存常遇到两个问题:单文件过大导致淘汰粒度粗糙;客户端使用 Range 请求时缓存命中率低。slice 模块可把响应切分为固定大小的块分别缓存:

location /media/ {
    slice 1m;
    proxy_cache media_cache;
    proxy_cache_key "$scheme$host$uri$slice_range";
    proxy_set_header Range $slice_range;
    proxy_cache_valid 200 206 1d;
    proxy_pass http://media_backend;
}

配合 proxy_force_ranges on,即使上游不支持 Range,Nginx 也能对缓存内容提供范围响应,显著改善播放器拖动进度条时的体验。

5.3 微缓存

对高并发、可容忍秒级陈旧的内容(如商品列表、新闻首页),"微缓存"是性价比极高的策略:把 proxy_cache_valid 设为 1 秒,并在响应头中显式声明 stale-while-revalidate 语义,让客户端与下游缓存接受短暂的陈旧值。它把瞬时洪峰从后端彻底剥离,而用户几乎感知不到延迟差异。

5.4 浏览器侧缓存

代理缓存解决的是"回源次数",浏览器缓存解决的是"请求次数",两者不可互相替代。对带内容指纹的静态资源设置长 max-age 与 immutable,对 HTML 入口设置 no-cache,是单页应用的标准组合:

location /static/ {
    add_header Cache-Control "public, max-age=31536000, immutable";
}

location = /index.html {
    add_header Cache-Control "no-cache";
}

这里刻意不使用 expires:该指令自身也会输出一条 Cache-Control: max-age=...,与手写的 add_header Cache-Control 同时出现时会产生重复响应头,二者选其一即可。


六、可观测性

6.1 结构化访问日志

默认的 combined 格式不利于机器解析。现代做法是输出 JSON,并利用 escape=json 保证字段安全:

log_format json_main escape=json
    '{'
      '"time":"$time_iso8601",'
      '"remote_addr":"$remote_addr",'
      '"method":"$request_method",'
      '"uri":"$request_uri",'
      '"status":$status,'
      '"bytes":$body_bytes_sent,'
      '"rt":$request_time,'
      '"upstream_rt":"$upstream_response_time",'
      '"upstream_addr":"$upstream_addr",'
      '"cache":"$upstream_cache_status",'
      '"trace_id":"$otel_trace_id",'
      '"ua":"$http_user_agent"'
    '}';

access_log /var/log/nginx/access.log json_main buffer=64k flush=5s;

几个细节值得注意:

  • $request_time 是端到端总耗时,$upstream_response_time 仅覆盖上游处理,两者之差反映排队、TLS 与传输开销。
  • $upstream_response_time 在多节点重试时是逗号分隔的列表,解析端需兼容多值。
  • buffer 与 flush 的配合可显著降低高 QPS 下的写放大;容器环境中应确保日志落盘位置支持日志采集器的 tail。
  • 若接入 OpenTelemetry,$otel_trace_id 能把访问日志与链路追踪直接关联,排查问题时无需再按时间窗猜。

6.2 指标采集

stub_status 提供最基础的连接与请求计数:

location = /basic_status {
    stub_status;
    allow 127.0.0.1;
    deny all;
}

输出仅包含 active 连接、accepts、handled、requests 四项,足以计算 QPS 与连接利用率,但缺少上游维度。要获得 upstream 级别的状态码分布、响应时间与健康度,通常依赖:

  1. 商业版的状态接口;
  2. 第三方指标模块(暴露 Prometheus 文本格式);
  3. 从结构化访问日志做离线聚合;
  4. OpenTelemetry 指标导出。

无论采用哪种,都应保证采集端点在内网可达、有访问控制,且不与业务 location 共享限流配额。

6.3 错误日志分级

error_log 支持 debug、info、notice、warn、error、crit、alert、emerg。生产环境设为 warn 能在保留关键信号的同时避免日志爆炸;排查特定问题时可按 location 单独开启 debug,但必须限制开启时长,因为 debug 级别会写大量文件,对高并发服务是可观的性能负担。


七、安全加固

7.1 限流与限连

limit_req_zone $binary_remote_addr zone=per_ip:20m rate=20r/s;
limit_conn_zone $binary_remote_addr zone=conn_per_ip:20m;

server {
    location /api/ {
        limit_req zone=per_ip burst=40 nodelay;
        limit_req_status 429;
        limit_conn conn_per_ip 20;
        limit_conn_status 429;
    }
}

rate 是平均速率,burst 允许的突发队列长度。nodelay 表示突发请求立即处理而不排队,适合延迟敏感的接口;若不使用 nodelay,请求会被整速排队,可能引入数百毫秒等待。limit_req 的 delay 参数(1.15.7)可对突发做部分延迟,是两者的折中。

在多实例网关中,限流必须是全局的,否则各实例独立计数会让实际阈值成倍放大。此时应借助相应模块把计数器下沉到共享存储(如 Redis + Lua),或在边缘层做粗粒度限流、在应用层做精细配额。

7.2 请求体与头部约束

client_max_body_size 10m;
client_body_timeout 12s;
client_header_timeout 10s;
large_client_header_buffers 4 8k;

这些指令常被忽略,但它们直接决定了慢速攻击(Slowloris、Slow POST)的成本。默认的 client_max_body_size 仅为 1m,上传功能异常时应优先检查此项,而不是怀疑上游。

7.3 安全响应头

add_header X-Content-Type-Options nosniff always;
add_header X-Frame-Options DENY always;
add_header Referrer-Policy strict-origin-when-cross-origin always;
add_header Content-Security-Policy "default-src 'self'; object-src 'none'; base-uri 'self'" always;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

always 让头在 4xx/5xx 响应中同样生效。再次提醒:同一 server 下若某个 location 设置了任何 add_header,父级的全部 add_header 在该 location 中失效,需重复声明或抽成 include 片段。

7.4 隐藏信息与访问控制

server_tokens off;
proxy_hide_header X-Powered-By;

location /admin/ {
    allow 10.0.0.0/8;
    deny all;
    satisfy all;
    auth_basic "restricted";
    auth_basic_user_file /etc/nginx/conf.d/admin.htpasswd;
}

satisfy all 要求访问控制与认证同时通过;默认的 satisfy any 只要任一通过即可放行,这在实际中被误解最多,务必显式声明。另外要区分两个指令的作用面:server_tokens off 只影响 Nginx 自身生成的 Server 头与错误页版本信息,而 proxy_hide_header 只能隐藏上游返回的头,无法隐藏 Nginx 自己的 Server 头。

7.5 应用层防护的边界

Nginx 可以做基础的请求校验(方法白名单、URI 规范化、请求体大小、头部数量),但不应期望它替代 WAF。$request_method 白名单、拒绝可疑路径与过滤明显畸形的头部是低成本高收益的,而 SQL 注入、XSS 等语义级攻击需要专用规则引擎或应用内防护。若需在 Nginx 层接入规则集,需引入相应模块并接受其性能与误报成本。


八、脚本化扩展:njs

njs 是 Nginx 官方的 JavaScript 子集运行时,定位介于"纯配置"与"Lua 编程"之间:足够表达请求级逻辑,又保持了接近配置的执行模型。它适合做签名校验、参数改写、A/B 分流、简单的响应加工,而不适合做重计算或复杂状态管理。

一个常见的鉴权示例:

function verify(r) {
    var token = r.headersIn['X-Request-Token'];
    if (!token) {
        r.return(401, 'missing token');
        return;
    }
    var ts = r.args.ts;
    if (!ts || Math.abs(Date.now() / 1000 - parseInt(ts, 10)) > 300) {
        r.return(401, 'expired');
        return;
    }
    r.return(200);
}

export default { verify };
js_import auth from /etc/nginx/njs/auth.js;

location /api/ {
    auth_request /_verify;
    proxy_pass http://app_backend;
}

location = /_verify {
    internal;
    js_content auth.verify;
}

实践要点:

  • njs 每请求执行,避免在其中做阻塞 I/O;需要外部依赖时应改为异步或前置到上游。
  • 复杂对象可在启动时用 js_preload_object 预加载,避免每次读取文件。
  • js_content 与 auth_request 的组合能在不改业务代码的前提下插入统一逻辑,比在每个 location 重复配置更易维护。
  • 与 Lua 相比,njs 的学习成本低、内存模型简单,但生态与可用的第三方库少得多;选择时应按"是否真的需要编程"来判断,而非按语言偏好。

九、现代部署形态

9.1 容器化

在容器环境中,Nginx 的运行方式有几点必须调整:

  • worker_processes auto 在限制了 CPU 配额但未设置 cpuset 的容器中可能读到宿主机核数,导致 worker 过多、上下文切换严重。必要时显式指定数量,或用启动脚本按 cgroup 配额计算。
  • 日志应输出到 stdout/stderr 由采集器处理,而非写入容器内文件系统。
  • 主进程需要能接收 SIGQUIT 实现优雅退出,worker_shutdown_timeout 控制最长等待时间,避免滚动更新时连接被硬切断。
  • 在只读根文件系统下,需把 pid 文件与临时目录指向可写路径,通常通过挂载空目录实现。

9.2 作为入口控制器

在 Kubernetes 中,Nginx 常以入口控制器的形式存在,通过监听集群资源变化动态生成 upstream 与路由。理解其工作方式有助于排查问题:

  • 配置由控制器渲染后整体 reload,reload 会触发新 worker 启动与旧 worker 优雅退出,高频变更会造成内存与连接抖动,因此应控制变更频率。
  • upstream 的成员变更依赖控制器感知端点变化,收敛时间由监听、渲染、reload 三段构成;这正是 resolve 动态解析与共享内存 zone 值得关注的原因。
  • 注解(annotation)是具体实现的扩展面而非标准配置语义,容易出现"配置看似生效但实际未渲染"的情况,排查时应先看渲染后的最终配置,而不是 CRD 原文。

9.3 配置验证与发布流程

任何配置变更都应遵循同一顺序:先用 nginx -t 做语法与语义校验,再用 nginx -T 打印合并后的完整配置并人工核对覆盖关系,最后用 nginx -s reload 平滑重载。

nginx -t
nginx -T
nginx -s reload

nginx -T 的价值常被低估:它与 -t 共用解析逻辑,能直接暴露 add_header 覆盖、include 顺序、变量拼写等问题,是代码评审中应附上的产物。重载失败时旧 worker 仍在服务,因此不会中断流量,但新配置未生效——这一点应在监控上做区分,避免"以为已发布"。


十、性能调优的次序

调优应按"瓶颈出现的位置"排序,而不是把常见参数抄一遍:

  1. 确认瓶颈类型:是 CPU、连接数、磁盘 I/O、上游耗时,还是 TLS 握手。可用 $request_time 与 $upstream_response_time 的差值快速区分。
  2. 连接层:worker_connections、worker_rlimit_nofile、reuseport、keepalive 复用(上游与客户端两侧)。
  3. 协议层:启用 HTTP/2 或 HTTP/3;对静态资源启用 gzip 或 brotli(需相应模块),注意压缩只对文本有效,对已压缩格式应关闭。
  4. 数据路径:sendfile、tcp_nopush、aio threads、open_file_cache。其中 open_file_cache 对大量小文件的场景收益明显:
open_file_cache max=10000 inactive=60s;
open_file_cache_valid 30s;
open_file_cache_min_uses 2;
open_file_cache_errors on;
  1. 缓存层:代理缓存命中率、proxy_cache_lock、stale 策略。缓存命中率每提升 10 个百分点,对后端的减负效果通常超过任何内核参数微调。
  2. 内核参数:somaxconn、tcp_max_syn_backlog、net.ipv4.tcp_tw_reuse 等,属于最后一步,且必须结合真实流量形态验证。

压缩策略的细节值得单独说明:gzip_vary on 保证缓存区分压缩与未压缩版本;gzip_min_length 避免对小响应做无谓压缩;gzip_types 默认只覆盖 text/html,需要显式补充 JSON、XML、SVG、字体文件等。对高并发场景,压缩的 CPU 成本不可忽略,可在边缘层开启、在内部层关闭。


十一、常见陷阱清单

  • if 中放 proxy_pass:行为不可预测,改用 map 或独立的 location。
  • add_header 被子级覆盖:安全头静默消失,需集中声明或重复声明。
  • upstream keepalive 未生效:缺少 proxy_http_version 1.1 与清空 Connection。
  • proxy_pass 尾部斜杠导致路径错乱:明确期望的 URI 重写语义。
  • 重载过于频繁:每次 reload 都新建 worker,短连接高峰时会造成端口与内存压力,应合并变更。
  • error_log debug 长期开启:磁盘与 CPU 双重开销。
  • 限流计数器落在本地:多实例场景阈值成倍放大。
  • 缓存键未包含必要的区分维度:多租户或多协议下出现内容串味。
  • TLS 证书链不完整:部分客户端(尤其移动端)握手失败,需拼接中间证书。
  • client_max_body_size 保持默认:上传接口在大文件时返回 413,容易被误判为应用错误。
  • 未设置 worker_shutdown_timeout:滚动发布时长连接被硬切断,表现为偶发 502。

十二、结语

现代 Nginx 的价值不在于"参数多",而在于它在保持核心模型稳定的前提下,持续补齐了云原生时代需要的能力:HTTP/3、动态上游解析、原生追踪、细粒度 TLS 控制、流量镜像与声明式分流。这些能力共同指向一个方向——把过去必须依赖自定义模块或外部组件才能完成的网关逻辑,收敛回配置本身。

理解其架构后,调优与排障会变得有迹可循:连接问题看事件循环与文件描述符,延迟问题看 $request_time 与 $upstream_response_time 的差值,容量问题看缓存命中率与上游承载,安全问题看限流、头部与访问控制的覆盖关系。配置本身只是表象,真正决定系统表现的,是对这些机制边界的准确判断。

【版权声明】本文为华为云社区用户翻译文章,如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容, 举报邮箱:cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。