Nginx 高性能配置：反向代理、负载均衡与缓存优化

2.1.2 worker 进程与连接数配置

# /etc/nginx/nginx.conf - 主配置文件全局段
user nginx;
# auto 自动检测 CPU 核心数，等价于手动写核心数
# 绑定 worker 到具体 CPU 核心可减少上下文切换，8 核机器写 auto
worker_processes auto;
worker_cpu_affinity auto;
# 单个 worker 可打开的最大文件描述符数
# 必须 >= worker_connections * 2（每个连接占用 2 个 fd：客户端 + 上游）
worker_rlimit_nofile 65536;
# 错误日志级别：生产用 warn，调试用 debug（debug 会产生大量日志，影响性能）
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;
# 动态模块加载（如需要）
load_module modules/ngx_http_geoip_module.so;

events {
    # 单 worker 最大并发连接数
    # 总并发 = worker_processes * worker_connections
    # 4 核机器设 16384，总并发约 65536
    worker_connections 16384;
    # 使用 epoll（Linux 最高效的 I/O 多路复用）
    use epoll;
    # 允许 worker 一次性接受所有新连接，而非逐个接受
    # 高并发场景下减少系统调用次数，低流量场景意义不大
    multi_accept on;
}

2.1.3 内核参数调优

Nginx 性能上限受内核参数约束，应用层配置再好也无法突破内核限制。

# /etc/sysctl.d/99-nginx-tuning.conf - 内核参数调优
# 修改后执行 sysctl -p /etc/sysctl.d/99-nginx-tuning.conf 生效
# TCP 连接队列长度，默认 128 远不够用，高并发场景必须调大
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
# 允许 TIME_WAIT 状态的 socket 被新连接复用
# 反向代理场景下大量短连接会产生 TIME_WAIT，不开启会导致端口耗尽
net.ipv4.tcp_tw_reuse = 1
# 系统最大文件描述符数，必须大于 worker_rlimit_nofile * worker_processes
fs.file-max = 1000000
# 网卡接收队列长度，10Gbps 网卡建议调大
net.core.netdev_max_backlog = 65535
# TCP 接收/发送缓冲区，影响大文件传输和高延迟链路性能
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216
# 本地端口范围，反向代理向上游发起连接时使用
# 默认 32768-60999，约 28000 个端口，高并发场景可能不够
net.ipv4.ip_local_port_range = 10000 65535

# 应用内核参数并验证
sysctl -p /etc/sysctl.d/99-nginx-tuning.conf
# 验证关键参数
sysctl net.core.somaxconn
sysctl net.ipv4.tcp_tw_reuse
sysctl fs.file-max
# 设置系统级文件描述符限制（/etc/security/limits.conf）
echo "nginx soft nofile 65536" >> /etc/security/limits.conf
echo "nginx hard nofile 65536" >> /etc/security/limits.conf

2.2 反向代理配置

2.2.1 upstream 配置与健康检查

# /etc/nginx/conf.d/upstream.conf - upstream 定义文件
upstream backend_api {
    # keepalive 保持与上游的长连接池，避免每次请求重新建立 TCP 连接
    # 值为连接池中保持的空闲连接数，不是最大连接数上限
    # 后端是 HTTP/1.1 应用时，32-64 是合理起点
    keepalive 64;
    # keepalive_requests：单个长连接最多处理的请求数，防止连接老化
    keepalive_requests 1000;
    # keepalive_timeout：空闲连接保持时间
    keepalive_timeout 60s;
    server 10.0.1.11:8080 weight=3 max_fails=3 fail_timeout=30s;
    server 10.0.1.12:8080 weight=3 max_fails=3 fail_timeout=30s;
    server 10.0.1.13:8080 weight=2 max_fails=3 fail_timeout=30s;
    # backup 服务器：仅在所有主服务器不可用时启用
    server 10.0.1.14:8080 backup;
}
upstream backend_static {
    # 静态资源服务器，使用最少连接策略
    least_conn;
    keepalive 32;
    server 10.0.1.21:80 weight=1;
    server 10.0.1.22:80 weight=1;
}

2.2.2 proxy_pass 细节

proxy_pass 的 trailing slash 是最常见的配置错误来源。proxy_pass http://backend/ 和 proxy_pass http://backend 行为完全不同：前者会截断 location 前缀，后者保留完整 URI。

# /etc/nginx/conf.d/proxy-detail.conf
server {
    listen 80;
    server_name api.example.com;
    location /api/ {
        # 末尾有斜杠：/api/users -> http://backend/users（截断 /api 前缀）
        # 末尾无斜杠：/api/users -> http://backend/api/users（保留完整路径）
        proxy_pass http://backend_api/;
        # 必须传递 Host，否则后端无法识别虚拟主机
        proxy_set_header Host $host;
        # 传递真实客户端 IP，后端日志和业务逻辑依赖此值
        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;
        # 使用 HTTP/1.1 与上游通信，keepalive 必须配合此设置
        proxy_http_version 1.1;
        # 清除 Connection 头，防止 keep-alive 信息传递到上游导致连接管理混乱
        proxy_set_header Connection "";
        # 连接超时：Nginx 与上游建立 TCP 连接的超时时间
        # 内网服务设 5s 足够，超过说明上游有问题
        proxy_connect_timeout 5s;
        # 读取超时：等待上游响应的超时时间（两次读操作之间的间隔）
        # 根据业务最慢接口设定，不是总响应时间
        proxy_read_timeout 60s;
        # 发送超时：向上游发送请求的超时时间
        proxy_send_timeout 60s;
        # 缓冲区配置：响应先缓冲到 Nginx，再发给客户端
        # 关闭缓冲（proxy_buffering off）适合 SSE/流式响应
        proxy_buffering on;
        proxy_buffer_size 16k;      # 响应头缓冲区，通常 4k-16k 足够
        proxy_buffers 8 32k;        # 响应体缓冲区数量和大小
        proxy_busy_buffers_size 64k; # 同时向客户端发送的最大缓冲量
    }
}

2.2.3 WebSocket 代理与长连接保持

# /etc/nginx/conf.d/websocket.conf
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''     close;
    # 当客户端不发送 Upgrade 头时，Connection 设为 close
    # 避免普通 HTTP 请求被错误地保持为长连接
}
server {
    listen 443 ssl;
    server_name ws.example.com;
    location /ws/ {
        proxy_pass http://backend_ws;
        # WebSocket 升级握手必须的头
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        # WebSocket 连接通常长时间保持，读取超时需要设长
        # 或设为 0（永不超时），但要配合心跳机制
        proxy_read_timeout 3600s;
        # 关闭缓冲，WebSocket 消息需要实时传递
        proxy_buffering off;
    }
}

2.2.4 gRPC 反向代理配置

# /etc/nginx/conf.d/grpc.conf
upstream grpc_backend {
    server 10.0.1.11:50051;
    server 10.0.1.12:50051;
    keepalive 32;
}
server {
    listen 443 ssl http2;  # gRPC 依赖 HTTP/2
    server_name grpc.example.com;
    ssl_certificate /etc/nginx/ssl/grpc.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/grpc.example.com.key;
    location / {
        # grpc_pass 替代 proxy_pass，专用于 gRPC 协议
        grpc_pass grpc://grpc_backend;
        # gRPC 错误处理
        error_page 502 = /error502grpc;
    }
    location = /error502grpc {
        internal;
        default_type application/grpc;
        # gRPC 状态码：14 = UNAVAILABLE
        add_header grpc-status 14;
        add_header content-length 0;
        return 204;
    }
}

2.3 负载均衡策略

2.3.1 轮询、加权轮询与 ip_hash

# /etc/nginx/conf.d/lb-strategies.conf
# 默认轮询：请求依次分发到每个 server，适合无状态服务
upstream rr_backend {
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
    server 10.0.1.13:8080;
}
# 加权轮询：按 weight 比例分发，适合服务器配置不均的场景
# 下例中 .11 处理 50% 流量，.12 和 .13 各处理 25%
upstream weighted_backend {
    server 10.0.1.11:8080 weight=2;
    server 10.0.1.12:8080 weight=1;
    server 10.0.1.13:8080 weight=1;
}
# ip_hash：同一客户端 IP 始终路由到同一后端
# 实现简单的会话保持，但存在热点问题（大量用户来自同一 NAT IP）
# 不支持与 weight 同时使用（1.26.x 已支持，但行为需验证）
upstream iphash_backend {
    ip_hash;
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
    server 10.0.1.13:8080;
}

2.3.2 least_conn 与一致性哈希

# /etc/nginx/conf.d/lb-advanced.conf
# least_conn：将请求发送到当前活跃连接数最少的 server
# 适合请求处理时间差异大的场景（如混合快慢接口）
# 比轮询更能避免慢请求堆积在某个 server 上
upstream leastconn_backend {
    least_conn;
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
    server 10.0.1.13:8080;
    keepalive 32;
}
# hash：基于自定义 key 的一致性哈希
# 适合缓存场景：相同 URL 始终路由到同一后端，提高后端缓存命中率
# consistent 参数启用一致性哈希，server 增减时只有少量请求重新分配
upstream hash_backend {
    hash $request_uri consistent;
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
    server 10.0.1.13:8080;
}
# 基于请求头的哈希（适合 API 网关按用户 ID 路由）
upstream user_hash_backend {
    hash $http_x_user_id consistent;
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;
}

2.3.3 被动健康检查与主动健康检查

开源版 Nginx 只支持被动健康检查（请求失败后标记 server 不可用），主动健康检查是商业版 Nginx Plus 的功能。开源替代方案是 nginx_upstream_check_module 第三方模块。

# /etc/nginx/conf.d/health-check.conf
upstream backend_with_check {
    server 10.0.1.11:8080 max_fails=3 fail_timeout=30s;
    server 10.0.1.12:8080 max_fails=3 fail_timeout=30s;
    server 10.0.1.13:8080 max_fails=3 fail_timeout=30s;
    # max_fails：在 fail_timeout 时间窗口内，失败次数达到此值则标记为不可用
    # fail_timeout：不可用状态持续时间，同时也是统计失败次数的时间窗口
    # 上例：30 秒内失败 3 次，则该 server 被下线 30 秒后重新尝试
    keepalive 32;
}
# 如果编译了 nginx_upstream_check_module，可配置主动健康检查
# upstream backend_active_check {
#     server 10.0.1.11:8080;
#     server 10.0.1.12:8080;
#     check interval=3000 rise=2 fall=3 timeout=1000 type=http;
#     check_http_send "HEAD /health HTTP/1.0\r\n\r\n";
#     check_http_expect_alive http_2xx http_3xx;
# }

2.3.4 会话保持方案对比

2.4 缓存优化

2.4.1 proxy_cache 配置

# /etc/nginx/nginx.conf - http 段缓存路径定义
http {
    # 缓存路径配置
    # levels=1:2：两级目录结构，避免单目录文件过多影响文件系统性能
    # keys_zone=cache_main:100m：共享内存区名称和大小，100m 约存储 80 万个 key
    # max_size=10g：缓存文件总大小上限，超出时 LRU 淘汰
    # inactive=60m：60 分钟内未被访问的缓存自动删除
    # use_temp_path=off：直接写入缓存目录，避免跨文件系统 rename 操作
    proxy_cache_path /data/nginx/cache
        levels=1:2
        keys_zone=cache_main:100m
        max_size=10g
        inactive=60m
        use_temp_path=off;
    # 第二个缓存区，用于静态资源（更大的 inactive 时间）
    proxy_cache_path /data/nginx/cache_static
        levels=1:2
        keys_zone=cache_static:50m
        max_size=20g
        inactive=7d
        use_temp_path=off;
}

2.4.2 缓存策略

# /etc/nginx/conf.d/cache-policy.conf
server {
    listen 80;
    server_name www.example.com;
    # API 接口缓存
    location /api/ {
        proxy_pass http://backend_api/;
        proxy_cache cache_main;
        # 缓存 key 设计：包含 scheme、host、URI 和查询参数
        # 如果接口有用户态，需要加入 Cookie 或 Authorization 头
        proxy_cache_key "$scheme$host$request_uri";
        # 不同响应码的缓存时间
        proxy_cache_valid 200 302 10m;  # 成功响应缓存 10 分钟
        proxy_cache_valid 404 1m;      # 404 缓存 1 分钟，防止穿透攻击
        proxy_cache_valid any 30s;     # 其他响应码缓存 30 秒
        # 绕过缓存的条件：有 Cookie 或特定请求头时不使用缓存
        # $cookie_session 非空时，认为是登录用户，不走缓存
        proxy_cache_bypass $cookie_session $http_authorization;
        proxy_no_cache $cookie_session $http_authorization;
        # stale 配置：上游故障时，允许使用过期缓存响应
        # 这是提升可用性的关键配置，避免上游抖动直接影响用户
        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
        # 防止缓存击穿：同一 key 只允许一个请求回源，其他请求等待
        proxy_cache_lock on;
        proxy_cache_lock_timeout 5s;
        # 在响应头中暴露缓存状态，便于调试（生产可关闭）
        add_header X-Cache-Status $upstream_cache_status;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
    }
}

2.4.3 静态文件缓存与 expires/Cache-Control

# /etc/nginx/conf.d/static-cache.conf
server {
    listen 80;
    server_name static.example.com;
    root /var/www/static;
    # 带哈希指纹的静态资源（如 app.a1b2c3d4.js）可永久缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        # 浏览器缓存 1 年，CDN 缓存 1 年
        expires 1y;
        add_header Cache-Control "public, immutable";
        # 开启 gzip 静态压缩（需要预先生成 .gz 文件）
        gzip_static on;
        # sendfile 零拷贝传输，静态文件服务必开
        sendfile on;
        tcp_nopush on;  # 配合 sendfile，批量发送响应头和文件内容
    }
    # HTML 文件不缓存或短时缓存（内容会更新）
    location ~* \.html$ {
        expires -1;
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }
    # API 响应：私有缓存，不允许 CDN 缓存
    location /api/ {
        proxy_pass http://backend_api;
        add_header Cache-Control "private, no-cache";
    }
}

2.4.4 缓存预热与清理

# /opt/scripts/cache-warm.sh - 缓存预热脚本
#!/bin/bash
set -euo pipefail
NGINX_HOST="http://127.0.0.1"
URL_LIST="/opt/scripts/warm-urls.txt"
CONCURRENCY=10  # 并发预热请求数
warm_cache() {
    local url="$1"
    # 通过 curl 访问触发缓存，-s 静默，-o /dev/null 丢弃响应体
    curl -s -o /dev/null -w "%{http_code} %{url_effective}\n" \
        -H "Host: www.example.com" \
        "${NGINX_HOST}${url}"
}
export -f warm_cache
# 使用 xargs 并发执行预热
cat "${URL_LIST}" | xargs -P "${CONCURRENCY}" -I{} bash -c 'warm_cache "$@"' _ {}
echo "Cache warm-up completed"

# /etc/nginx/conf.d/cache-purge.conf
# 需要编译 ngx_cache_purge 模块
server {
    listen 80;
    server_name cache-admin.internal;
    # 限制只有内网可以访问清理接口
    allow 10.0.0.0/8;
    allow 192.168.0.0/16;
    deny all;
    location ~ /purge(/.*) {
        proxy_cache_purge cache_main "$scheme$host$1";
    }
}

2.5 SSL/TLS 优化

2.5.1 TLS 1.3 配置与密码套件选择

# /etc/nginx/conf.d/ssl-base.conf - SSL 基础配置（include 到各 server 块）
# 只启用 TLS 1.2 和 1.3，TLS 1.0/1.1 已被 RFC 8996 废弃
ssl_protocols TLSv1.2 TLSv1.3;
# TLS 1.2 密码套件：优先 ECDHE（前向保密），禁用 RC4、3DES、MD5
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
# 服务端优先选择密码套件（TLS 1.3 中此设置被忽略）
ssl_prefer_server_ciphers off;
# DH 参数文件，防止 Logjam 攻击
# 生成命令：openssl dhparam -out /etc/nginx/ssl/dhparam.pem 2048
ssl_dhparam /etc/nginx/ssl/dhparam.pem;
# 椭圆曲线选择：X25519 性能最好，P-256 兼容性最广
ssl_ecdh_curve X25519:prime256v1:secp384r1;

2.5.2 OCSP Stapling 与会话复用

# /etc/nginx/conf.d/ssl-performance.conf
# SSL 会话缓存：shared 在所有 worker 间共享，10m 约缓存 40000 个会话
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;  # 会话有效期 1 天，平衡安全性和性能
# TLS 1.3 会话票据（Session Tickets）
# 允许客户端恢复会话，避免完整握手，减少延迟
# 注意：多台 Nginx 需要共享相同的 ticket key，否则跨机器无法复用
ssl_session_tickets off;  # 单机可开启，集群环境需要同步 key 或关闭
# OCSP Stapling：Nginx 主动获取证书吊销状态并缓存
# 客户端无需单独查询 OCSP 服务器，减少握手延迟
ssl_stapling on;
ssl_stapling_verify on;
# 完整证书链（包含中间证书）
ssl_trusted_certificate /etc/nginx/ssl/chain.pem;
# DNS 解析器，用于 OCSP 查询
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;

2.5.3 HTTP/2 与 HTTP/3(QUIC) 启用

# /etc/nginx/conf.d/http2-http3.conf
server {
    # HTTP/2：在 listen 指令中添加 http2 参数（Nginx 1.25.1+ 语法）
    listen 443 ssl;
    http2 on;
    # HTTP/3 / QUIC：基于 UDP，需要 1.25.0+ 且编译了 --with-http_v3_module
    listen 443 quic reuseport;
    server_name www.example.com;
    ssl_certificate /etc/nginx/ssl/www.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/www.example.com.key;
    include /etc/nginx/conf.d/ssl-base.conf;
    include /etc/nginx/conf.d/ssl-performance.conf;
    # 告知客户端支持 HTTP/3，浏览器下次请求会尝试 QUIC
    add_header Alt-Svc 'h3=":443"; ma=86400';
    # HSTS：强制浏览器使用 HTTPS，max-age 建议至少 6 个月
    add_header Strict-Transport-Security "max-age=15768000; includeSubDomains" always;
    location / {
        proxy_pass http://backend_api;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
    }
}
# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name www.example.com;
    return 301 https://$host$request_uri;
}

三、示例代码和配置

3.1 完整的生产级 nginx.conf

# /etc/nginx/nginx.conf - 生产级主配置文件
user nginx;
worker_processes auto;
worker_cpu_affinity auto;
worker_rlimit_nofile 65536;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;
events {
    worker_connections 16384;
    use epoll;
    multi_accept on;
}
http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    # 自定义日志格式，包含响应时间和上游信息，便于性能分析
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for" '
                    'rt=$request_time uct=$upstream_connect_time '
                    'uht=$upstream_header_time urt=$upstream_response_time';
    access_log /var/log/nginx/access.log main buffer=32k flush=5s;
    # 零拷贝文件传输，静态文件服务必开
    sendfile on;
    # sendfile 开启后才有效：将多个小包合并成一个 TCP 包发送，减少网络开销
    tcp_nopush on;
    # 禁用 Nagle 算法，减少小包延迟，对实时性要求高的场景有效
    tcp_nodelay on;
    # 客户端连接保持时间，65s 是经验值，CDN 场景可适当调长
    keepalive_timeout 65;
    keepalive_requests 1000;
    # 隐藏 Nginx 版本号，减少信息泄露
    server_tokens off;
    # 客户端请求体大小限制，防止大文件上传耗尽内存
    client_max_body_size 100m;
    client_body_buffer_size 128k;
    # 请求头缓冲区，大 Cookie 或 JWT Token 场景需要调大
    client_header_buffer_size 4k;
    large_client_header_buffers 4 16k;
    # Gzip 压缩配置
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;       # 1-9，6 是压缩率和 CPU 消耗的平衡点
    gzip_min_length 1024;    # 小于 1KB 的响应不压缩，压缩收益低于开销
    gzip_types text/plain text/css text/xml text/javascript
               application/json application/javascript application/xml
               application/rss+xml application/atom+xml image/svg+xml;
    # 线程池：将阻塞的文件 I/O 操作卸载到独立线程，避免阻塞 worker
    thread_pool default threads=32 max_queue=65536;
    # 缓存区域定义（供各 server 块引用）
    proxy_cache_path /data/nginx/cache
        levels=1:2
        keys_zone=cache_main:100m
        max_size=10g
        inactive=60m
        use_temp_path=off;
    include /etc/nginx/conf.d/*.conf;
}

3.2 多站点反向代理 + 负载均衡完整配置

# /etc/nginx/conf.d/production.conf - 生产多站点配置
# API 服务集群
upstream api_cluster {
    least_conn;
    keepalive 64;
    keepalive_requests 1000;
    keepalive_timeout 60s;
    server 10.0.1.11:8080 weight=3 max_fails=3 fail_timeout=30s;
    server 10.0.1.12:8080 weight=3 max_fails=3 fail_timeout=30s;
    server 10.0.1.13:8080 weight=2 max_fails=3 fail_timeout=30s;
    server 10.0.1.14:8080 backup;
}
# 静态资源服务器
upstream static_cluster {
    server 10.0.1.21:80;
    server 10.0.1.22:80;
    keepalive 32;
}
# API 网关
server {
    listen 443 ssl;
    http2 on;
    listen 443 quic reuseport;
    server_name api.example.com;
    ssl_certificate /etc/nginx/ssl/api.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/api.example.com.key;
    include /etc/nginx/conf.d/ssl-base.conf;
    include /etc/nginx/conf.d/ssl-performance.conf;
    add_header Alt-Svc 'h3=":443"; ma=86400';
    add_header Strict-Transport-Security "max-age=15768000; includeSubDomains" always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options DENY always;
    # 限流：每个 IP 每秒最多 100 个请求
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=100r/s;
    limit_req zone=api_limit burst=200 nodelay;
    location /api/v1/ {
        proxy_pass http://api_cluster/;
        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 5s;
        proxy_read_timeout 30s;
        proxy_send_timeout 30s;
        # 启用缓存（GET 请求）
        proxy_cache cache_main;
        proxy_cache_key "$scheme$host$request_uri";
        proxy_cache_valid 200 5m;
        proxy_cache_valid 404 1m;
        proxy_cache_bypass $http_cache_control;
        proxy_no_cache $http_pragma $http_authorization;
        # 缓存命中状态头，便于调试
        add_header X-Cache-Status $upstream_cache_status;
    }
    # 健康检查端点不缓存
    location /health {
        proxy_pass http://api_cluster;
        proxy_cache off;
        access_log off;
    }
}
# 静态资源站点
server {
    listen 443 ssl;
    http2 on;
    server_name static.example.com;
    ssl_certificate /etc/nginx/ssl/static.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/static.example.com.key;
    include /etc/nginx/conf.d/ssl-base.conf;
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff2|svg)$ {
        proxy_pass http://static_cluster;
        proxy_cache cache_main;
        proxy_cache_valid 200 7d;
        # 浏览器缓存：静态资源设置长期缓存，配合文件名哈希实现缓存破坏
        expires 30d;
        add_header Cache-Control "public, immutable";
        # 预压缩文件优先（需要 gzip_static 模块）
        gzip_static on;
    }
}

3.3 缓存集群配置示例

# /etc/nginx/conf.d/cache-cluster.conf - 多级缓存配置
# 定义多个缓存区域，按内容类型分离
proxy_cache_path /data/nginx/cache/api
    levels=1:2
    keys_zone=cache_api:50m
    max_size=5g
    inactive=30m
    use_temp_path=off;
proxy_cache_path /data/nginx/cache/static
    levels=1:2
    keys_zone=cache_static:100m
    max_size=20g
    inactive=7d
    use_temp_path=off;
# 缓存锁：防止缓存击穿（多个请求同时穿透到上游）
proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
proxy_cache_lock_age 5s;
# 后台更新：缓存过期时先返回旧内容，后台异步更新
# 避免缓存过期瞬间大量请求打到上游
proxy_cache_background_update on;
# 上游不可用时使用过期缓存（降级策略）
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
server {
    listen 80;
    server_name cache.example.com;
    location /api/ {
        proxy_pass http://api_cluster;
        proxy_cache cache_api;
        proxy_cache_key "$scheme$host$uri$is_args$args";
        proxy_cache_valid 200 302 5m;
        proxy_cache_valid 404 1m;
        # 忽略上游的 Set-Cookie，防止带 Cookie 的响应被缓存
        proxy_ignore_headers Set-Cookie;
        proxy_hide_header Set-Cookie;
        add_header X-Cache-Status $upstream_cache_status;
        add_header X-Cache-Date $upstream_http_date;
    }
    location /static/ {
        proxy_pass http://static_cluster;
        proxy_cache cache_static;
        proxy_cache_key "$uri";  # 静态资源 key 不含 scheme/host，跨域共享缓存
        proxy_cache_valid 200 7d;
        proxy_cache_use_stale error timeout updating;
        expires 30d;
        add_header Cache-Control "public, max-age=2592000, immutable";
    }
}

四、最佳实践和注意事项

4.1 最佳实践

4.1.1 性能优化

# /etc/nginx/conf.d/performance.conf - 性能优化配置集合
http {
    # sendfile + tcp_nopush 组合：零拷贝传输 + 批量发送
    # sendfile 让内核直接将文件数据发送到网络，不经过用户态
    sendfile on;
    tcp_nopush on;
    # tcp_nodelay 禁用 Nagle 算法，减少小包延迟
    # 与 tcp_nopush 同时开启时，Nginx 会先积累数据（tcp_nopush），
    # 连接进入 keepalive 状态后再启用 tcp_nodelay 刷新剩余数据
    tcp_nodelay on;
    # 线程池异步文件 I/O，避免磁盘读写阻塞 worker 进程
    # 适合大文件下载场景，小文件场景收益不明显
    aio threads=default;
    aio_write on;
    # 直接 I/O：绕过操作系统页缓存，适合大文件且不需要重复读取的场景
    # 小文件或频繁访问的文件不要开启，会降低性能
    # directio 512;
    # open_file_cache：缓存文件描述符、文件大小和修改时间
    # 避免每次请求都调用 stat() 系统调用
    open_file_cache max=10000 inactive=30s;
    open_file_cache_valid 60s;
    open_file_cache_min_uses 2;
    open_file_cache_errors on;
    # Gzip 压缩：文本内容压缩率通常 60-80%，显著减少传输量
    gzip on;
    gzip_comp_level 6;
    gzip_min_length 1024;
    gzip_vary on;
    gzip_proxied any;
    gzip_types
        text/plain text/css text/xml text/javascript
        application/json application/javascript application/xml
        application/rss+xml application/atom+xml image/svg+xml
        font/truetype font/opentype application/vnd.ms-fontobject;
}

4.1.2 安全加固

# /etc/nginx/conf.d/security.conf - 安全加固配置
server {
    # 隐藏 Nginx 版本号，攻击者无法针对特定版本漏洞
    server_tokens off;
    # 限制请求方法，只允许 GET/POST/HEAD
    if ($request_method !~ ^(GET|POST|HEAD|PUT|DELETE|PATCH|OPTIONS)$) {
        return 405;
    }
    # 防止点击劫持
    add_header X-Frame-Options SAMEORIGIN always;
    # 禁止 MIME 类型嗅探，防止 XSS 攻击
    add_header X-Content-Type-Options nosniff always;
    # XSS 保护（现代浏览器已内置，但旧版浏览器需要此头）
    add_header X-XSS-Protection "1; mode=block" always;
    # 限制请求体大小，防止大文件上传耗尽内存
    client_max_body_size 10m;
    # 限制请求头大小，防止 Header 注入攻击
    large_client_header_buffers 4 8k;
    # 限流：防止暴力破解和 DDoS
    limit_req_zone $binary_remote_addr zone=login_limit:10m rate=5r/m;
    limit_conn_zone $binary_remote_addr zone=conn_limit:10m;
    location /login {
        limit_req zone=login_limit burst=10 nodelay;
        limit_conn conn_limit 5;
        proxy_pass http://backend_api;
    }
    # 禁止访问隐藏文件（.git、.env 等）
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }
    # 禁止访问备份文件
    location ~* \.(bak|conf|dist|fla|inc|ini|log|psd|sh|sql|swp)$ {
        deny all;
    }
}

4.1.3 高可用配置（Keepalived + Nginx 双主）

# /etc/keepalived/keepalived.conf - 主节点（192.168.1.11）配置
vrrp_script check_nginx {
    script "/opt/scripts/check-nginx.sh"
    interval 2   # 每 2 秒检查一次
    weight -20   # 检查失败时优先级降低 20，触发 VIP 漂移
    fall 2       # 连续失败 2 次才认为服务异常
    rise 2       # 连续成功 2 次才认为服务恢复
}
vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 100          # 主节点优先级高于备节点
    advert_int 1
    authentication {
        auth_type PASS
        auth_pass nginx_ha_2024
    }
    virtual_ipaddress {
        192.168.1.100/24  # VIP，对外提供服务的 IP
    }
    track_script {
        check_nginx
    }
}

# /opt/scripts/check-nginx.sh - Nginx 健康检查脚本
#!/bin/bash
set -euo pipefail
# 检查 Nginx 进程是否存在
if ! pgrep -x nginx > /dev/null; then
    # 尝试重启 Nginx
    systemctl start nginx
    sleep 2
    # 重启后再次检查，失败则退出非零状态触发 VIP 漂移
    pgrep -x nginx > /dev/null || exit 1
fi
# 检查 Nginx 是否能正常响应请求
http_code=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1/health)
if [ "${http_code}" != "200" ]; then
    exit 1
fi
exit 0

4.2 注意事项

4.2.1 配置注意事项

proxy_pass 末尾斜杠是最常见的配置错误：proxy_pass http://backend/ 会截断 location 前缀，proxy_pass http://backend 则保留完整 URI。在 location 使用正则表达式时，proxy_pass 不能带 URI 部分（即不能有斜杠后的路径），否则 Nginx 会拒绝启动。

worker_connections 设置的是单个 worker 的连接数上限，包含客户端连接和上游连接。作为反向代理时，每个客户端请求至少占用 2 个连接（客户端 + 上游），实际并发客户端数约为 worker_connections / 2。

proxy_cache_path 的 keys_zone 内存区只存储缓存 key 的索引，不存储缓存内容本身。100m 的 keys_zone 约能存储 80 万个 key，缓存内容存储在磁盘上。

4.2.2 常见错误

4.2.3 兼容性问题

HTTP/3 (QUIC) 需要防火墙放行 UDP 443 端口，许多企业网络默认封锁 UDP，导致 HTTP/3 降级到 HTTP/2。Alt-Svc 响应头告知浏览器支持 HTTP/3，浏览器会在后续请求中尝试 QUIC，失败后自动回退，不影响功能。

http2 on 指令是 1.25.1 引入的新语法，旧版本使用 listen 443 ssl http2。两种语法不能混用，升级 Nginx 版本后需要统一迁移。

五、故障排查和监控

5.1 故障排查

5.1.1 日志分析

# /etc/nginx/nginx.conf - 自定义日志格式
http {
    # 详细日志格式，包含所有关键性能指标
    log_format detailed '$remote_addr - $remote_user [$time_local] '
                        '"$request" $status $body_bytes_sent '
                        '"$http_referer" "$http_user_agent" '
                        'rt=$request_time '           # 总请求处理时间
                        'uct=$upstream_connect_time ' # 与上游建立连接时间
                        'uht=$upstream_header_time '  # 收到上游响应头时间
                        'urt=$upstream_response_time ' # 上游响应总时间
                        'cs=$upstream_cache_status '  # 缓存命中状态
                        'ua=$upstream_addr';          # 实际处理请求的上游地址
    # 生产环境使用缓冲写入，减少磁盘 I/O
    access_log /var/log/nginx/access.log detailed buffer=64k flush=10s;
    # 错误日志：warn 级别记录重要错误，不记录 notice/info 级别的噪音
    error_log /var/log/nginx/error.log warn;
}

# 常用日志分析命令
# 统计响应状态码分布
awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -rn
# 找出响应时间最慢的 10 个请求
awk '{print $NF, $7}' /var/log/nginx/access.log | sort -rn | head -10
# 统计每分钟请求量（流量趋势）
awk '{print $4}' /var/log/nginx/access.log | cut -d: -f1-3 | uniq -c
# 找出请求量最大的 IP（排查 DDoS）
awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head -20
# 实时监控错误日志
tail -f /var/log/nginx/error.log | grep -E "error|crit|alert|emerg"

5.1.2 常见问题排查

502 Bad Gateway 排查流程：

# 1. 确认上游服务是否存活
curl -v http://10.0.1.11:8080/health
# 2. 检查 Nginx 错误日志中的具体错误信息
tail -100 /var/log/nginx/error.log | grep "upstream"
# 3. 检查上游连接数是否耗尽
ss -s  # 查看 TCP 连接统计
ss -tn state established | grep :8080 | wc -l
# 4. 检查上游服务的文件描述符限制
cat /proc/$(pgrep -f "java")/limits | grep "open files"

连接数耗尽排查：

# 查看当前连接数
ss -s
# 查看 TIME_WAIT 连接数（过多说明短连接频繁）
ss -tn state time-wait | wc -l
# 查看 Nginx worker 打开的文件描述符数
ls /proc/$(pgrep nginx | head -1)/fd | wc -l
# 检查系统文件描述符使用情况
cat /proc/sys/fs/file-nr

5.1.3 调试模式

# /etc/nginx/conf.d/debug.conf - 临时调试配置（生产环境用完立即删除）
# 针对特定 IP 开启 debug 日志，避免全量 debug 影响性能
error_log /var/log/nginx/debug.log debug;
events {
    debug_connection 192.168.1.100;  # 只对此 IP 的连接输出 debug 日志
}

# 测试配置文件语法
nginx -t
# 查看编译参数和模块列表
nginx -V 2>&1 | tr ' ' '\n'
# 重载配置（不中断现有连接）
nginx -s reload
# 查看 Nginx 进程树
ps aux | grep nginx
# 实时查看连接状态（需要 stub_status 模块）
curl http://127.0.0.1/nginx_status

5.2 性能监控

5.2.1 stub_status 模块

# /etc/nginx/conf.d/status.conf - 监控状态页
server {
    listen 127.0.0.1:8080;  # 只监听本地，不对外暴露
    server_name localhost;
    location /nginx_status {
        stub_status;
        access_log off;
        # 只允许本机和监控服务器访问
        allow 127.0.0.1;
        allow 10.0.1.0/24;
        deny all;
    }
}

# stub_status 输出示例及含义
# Active connections: 291       # 当前活跃连接数
# server accepts handled requests
#  16630948 16630948 31070465   # 总接受连接数 / 总处理连接数 / 总请求数
# Reading: 6 Writing: 179 Waiting: 106
# Reading: 正在读取请求头的连接数
# Writing: 正在向客户端发送响应的连接数
# Waiting: keepalive 空闲连接数（等待下一个请求）

5.2.2 Prometheus + nginx-exporter 监控

# 安装 nginx-prometheus-exporter
wget https://github.com/nginxinc/nginx-prometheus-exporter/releases/download/v1.3.0/nginx-prometheus-exporter_1.3.0_linux_amd64.tar.gz
tar -xzf nginx-prometheus-exporter_1.3.0_linux_amd64.tar.gz
# 启动 exporter（读取 stub_status 并转换为 Prometheus 格式）
./nginx-prometheus-exporter \
    -nginx.scrape-uri=http://127.0.0.1:8080/nginx_status \
    -web.listen-address=:9113

# /etc/prometheus/rules/nginx.yml - Prometheus 告警规则
groups:
  - name: nginx
    rules:
      - alert: NginxHighActiveConnections
        expr: nginx_connections_active > 10000
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Nginx 活跃连接数过高"
          description: "当前活跃连接数 {{ $value }}，超过阈值 10000"
      - alert: NginxHighErrorRate
        # 5xx 错误率超过 5%
        expr: rate(nginx_http_requests_total{status=~"5.."}[5m]) / rate(nginx_http_requests_total[5m]) > 0.05
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Nginx 5xx 错误率过高"

5.2.3 关键指标与告警阈值

5.3 备份与恢复

5.3.1 配置备份脚本

# /opt/scripts/nginx-backup.sh - Nginx 配置备份脚本
#!/bin/bash
set -euo pipefail
BACKUP_DIR="/opt/backups/nginx"
NGINX_CONF_DIR="/etc/nginx"
RETENTION_DAYS=30
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/nginx_conf_${TIMESTAMP}.tar.gz"
backup_nginx_config() {
    mkdir -p "${BACKUP_DIR}"
    # 打包 Nginx 配置目录
    tar -czf "${BACKUP_FILE}" \
        --exclude="${NGINX_CONF_DIR}/ssl/*.key" \  # 私钥单独备份，不放在普通备份中
        "${NGINX_CONF_DIR}"
    echo "备份完成：${BACKUP_FILE}"
    echo "备份大小：$(du -sh "${BACKUP_FILE}" | cut -f1)"
}
cleanup_old_backups() {
    # 删除超过保留期的备份文件
    find "${BACKUP_DIR}" -name "nginx_conf_*.tar.gz" \
        -mtime "+${RETENTION_DAYS}" -delete
    echo "已清理 ${RETENTION_DAYS} 天前的备份"
}
verify_backup() {
    # 验证备份文件完整性
    if tar -tzf "${BACKUP_FILE}" > /dev/null 2>&1; then
        echo "备份验证通过"
    else
        echo "备份文件损坏！" >&2
        exit 1
    fi
}
backup_nginx_config verify_backup cleanup_old_backups

5.3.2 灰度发布与配置回滚

# /opt/scripts/nginx-deploy.sh - 配置灰度发布脚本
#!/bin/bash
set -euo pipefail
NGINX_CONF_DIR="/etc/nginx"
BACKUP_DIR="/opt/backups/nginx"
deploy_config() {
    local new_config_dir="$1"
    local timestamp
    timestamp=$(date +%Y%m%d_%H%M%S)
    # 备份当前配置
    cp -r "${NGINX_CONF_DIR}" "${BACKUP_DIR}/nginx_conf_before_deploy_${timestamp}"
    echo "当前配置已备份到：${BACKUP_DIR}/nginx_conf_before_deploy_${timestamp}"
    # 复制新配置
    rsync -av --delete "${new_config_dir}/" "${NGINX_CONF_DIR}/"
    # 测试新配置语法
    if ! nginx -t; then
        echo "新配置语法错误，回滚..." >&2
        rsync -av --delete "${BACKUP_DIR}/nginx_conf_before_deploy_${timestamp}/" "${NGINX_CONF_DIR}/"
        exit 1
    fi
    # 热重载（不中断现有连接）
    nginx -s reload
    echo "配置部署成功，已热重载"
}
rollback_config() {
    local backup_path="$1"
    if [ ! -d "${backup_path}" ]; then
        echo "备份目录不存在：${backup_path}" >&2
        exit 1
    fi
    rsync -av --delete "${backup_path}/" "${NGINX_CONF_DIR}/"
    if nginx -t && nginx -s reload; then
        echo "回滚成功"
    else
        echo "回滚失败，请手动检查配置" >&2
        exit 1
    fi
}
case "${1:-}" in
    deploy)   deploy_config "${2}" ;;
    rollback) rollback_config "${2}" ;;
    *)        echo "用法：$0 {deploy <config_dir>|rollback <backup_dir>}" ;;
esac

六、总结

6.1 技术要点回顾

• worker 配置：worker_processes auto + worker_cpu_affinity auto + worker_rlimit_nofile 65536，三者配合才能充分利用多核并支撑高并发
• 内核参数：somaxconn、tcp_tw_reuse、file-max 是必须调整的三个参数，不调整会在中等流量下触发瓶颈
• 反向代理：proxy_http_version 1.1 + proxy_set_header Connection "" + keepalive 是启用上游长连接的完整组合，缺一不可
• 缓存设计：proxy_cache_use_stale 配置上游降级策略，proxy_cache_lock 防止缓存击穿，proxy_cache_background_update 避免缓存过期时的流量尖刺
• TLS 优化：TLS 1.3 + OCSP Stapling + 会话缓存，三者叠加可将 TLS 握手延迟降低 50% 以上

6.2 进阶学习方向

1. OpenResty / njs：在 Nginx 中嵌入 Lua 或 JavaScript 逻辑，实现 JWT 验证、动态路由、A/B 测试等 API 网关功能，无需引入独立网关组件
2. Nginx Unit：Nginx 官方的应用服务器，支持动态配置（无需重载），可直接运行 Python/PHP/Node.js 应用，适合替代 uWSGI/Gunicorn
3. eBPF + Nginx：使用 eBPF 在内核层面监控 Nginx 的网络行为，实现零侵入的性能分析和安全审计

6.3 参考资料

• Nginx 官方文档 - 权威参考，指令说明以此为准
• Nginx 源码 - 理解内部实现的最直接途径
• nginx-prometheus-exporter - 官方 Prometheus 集成
• Mozilla SSL Configuration Generator - TLS 配置生成工具，覆盖主流浏览器兼容性

附录

A. 命令速查表

# 配置测试与重载
nginx -t                 # 测试配置文件语法
nginx -T                 # 测试并输出完整配置（含 include 文件）
nginx -s reload          # 热重载配置（不中断连接）
nginx -s reopen          # 重新打开日志文件（日志切割后使用）
nginx -s quit            # 优雅停止（等待现有请求完成）
nginx -s stop            # 立即停止
# 进程管理
systemctl start nginx    # 启动
systemctl stop nginx     # 停止
systemctl reload nginx   # 重载（等同于 nginx -s reload）
systemctl status nginx   # 查看状态
# 日志分析
tail -f /var/log/nginx/error.log  # 实时查看错误日志
nginx -V 2>&1 | tr ' ' '\n'       # 查看编译参数
# 连接状态
ss -tn state established dst :80  # 查看到 80 端口的连接
ss -s                            # 连接统计摘要
curl http://127.0.0.1/nginx_status # 查看 stub_status
# 缓存管理
find /data/nginx/cache -type f | wc -l  # 统计缓存文件数量
du -sh /data/nginx/cache                # 查看缓存占用空间

B. 配置参数详解

C. 术语表