跳到主要内容

Nginx 配置速查

日常配置的高频指令和可直接抄的片段，随用随查。环境口径 Ubuntu 22.04 + nginx 1.24，改完一律 nginx -t && nginx -s reload。

常用指令速查​

指令作用示例
worker_processesworker 进程数，按 CPU 核数worker_processes auto;
worker_rlimit_nofileworker 可打开的 fd 上限worker_rlimit_nofile 65535;
worker_connections单 worker 最大连接数（events 层）worker_connections 10240;
use事件模型，Linux 默认 epolluse epoll;
multi_accept一次事件循环接多个新连接multi_accept on;
include引入其他配置文件include /etc/nginx/conf.d/*.conf;
listen监听地址与端口listen 443 ssl http2;
server_name虚拟主机域名，空格分隔多个server_name example.com www.example.com;
root站点根目录，拼完整 URIroot /var/www/html;
alias用指定路径替换 location 前缀alias /data/files/;
index目录默认文件index index.html index.htm;
try_files依次尝试文件，末位兜底try_files $uri $uri/ /index.html;
locationURI 匹配规则location ^~ /static/ { ... }
proxy_pass转发到上游，尾斜杠决定是否改写 URIproxy_pass http://backend/;
proxy_set_header设置转发请求头proxy_set_header Host $host;
proxy_http_version转发使用的 HTTP 版本proxy_http_version 1.1;
proxy_connect_timeout连接上游超时proxy_connect_timeout 5s;
proxy_read_timeout读上游响应超时（504 的来源）proxy_read_timeout 60s;
proxy_send_timeout向上游发送超时proxy_send_timeout 60s;
proxy_buffering是否缓冲上游响应proxy_buffering off;
proxy_cache_path定义缓存目录与 zone（http 层）proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=c:100m;
proxy_cache引用缓存 zoneproxy_cache c;
client_max_body_size请求体大小上限（413 的来源）client_max_body_size 20m;
client_header_timeout读请求头超时client_header_timeout 15s;
keepalive_timeout客户端长连接空闲超时keepalive_timeout 65s;
keepalive_requests单连接最多复用次数keepalive_requests 1000;
sendfile零拷贝发送静态文件sendfile on;
tcp_nopush攒满包再发，配合 sendfiletcp_nopush on;
tcp_nodelay小包立即发，降低延迟tcp_nodelay on;
gzip开启压缩gzip on;
gzip_types哪些 MIME 类型压缩gzip_types text/css application/json;
gzip_comp_level压缩级别 1-9gzip_comp_level 5;
expires浏览器缓存时长expires 30d;
add_header加响应头add_header Cache-Control "no-store" always;
rewriteURI 改写rewrite ^/old/(.*)$ /new/$1 permanent;
return直接返回状态码或跳转return 301 https://$host$request_uri;
limit_req_zone限流 zone（http 层）limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req在 location 应用限流limit_req zone=api burst=20 nodelay;
stub_status状态页stub_status;
access_log访问日志access_log /var/log/nginx/access.log main;
error_log错误日志与级别error_log /var/log/nginx/error.log warn;
server_tokens是否显示版本号server_tokens off;
resolverDNS 服务器，proxy_pass 用域名时必需resolver 223.5.5.5 valid=30s;

location 匹配规则​

写法类型优先级说明
= /path精确匹配1（最高）命中即返回，不再匹配
^~ /prefix/前缀匹配2命中后跳过正则检查
~ pattern正则，区分大小写3按配置出现顺序，先匹配者胜
~* pattern正则，不区分大小写4同上
/prefix/普通前缀5（最低）取最长前缀

常用组合：

server {
    listen 80;
    server_name example.com;

    # 健康检查：最短链路
    location = /health {
        access_log off;
        return 200 "ok\n";
    }

    # 静态目录：^~ 防止被下面的正则抢走
    location ^~ /static/ {
        root /var/www;
        expires 30d;
    }

    # 图片：正则
    location ~* \.(jpg|jpeg|png|webp|svg)$ {
        root /var/www/images;
        expires 7d;
    }

    # API：前缀转发
    location /api/ {
        proxy_pass http://app_backend/;
    }

    # 兜底
    location / {
        root /var/www/html;
        try_files $uri $uri/ /index.html;
    }
}

反向代理片段​

upstream app_backend {
    server 10.0.0.11:8080 weight=5 max_fails=3 fail_timeout=10s;
    server 10.0.0.12:8080 weight=1;
    keepalive 64;
}

server {
    listen 80;
    server_name app.example.com;

    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_set_header X-Request-ID      $request_id;

        proxy_connect_timeout 5s;
        proxy_send_timeout    60s;
        proxy_read_timeout    60s;
    }

    # SSE / WebSocket / 流式输出：关缓冲、拉长超时
    location /stream/ {
        proxy_pass http://app_backend;
        proxy_buffering off;
        proxy_read_timeout 3600s;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

HTTPS 片段​

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name example.com;

    ssl_certificate     /etc/nginx/certs/example.com.pem;
    ssl_certificate_key /etc/nginx/certs/example.com.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

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

    add_header Strict-Transport-Security "max-age=31536000" always;

    location / {
        proxy_pass http://app_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

gzip 与缓存片段​

# gzip 放 http 层
gzip on;
gzip_vary on;
gzip_comp_level 5;
gzip_min_length 1k;
gzip_proxied any;
gzip_types
    text/plain
    text/css
    text/xml
    application/javascript
    application/json
    application/xml
    image/svg+xml;

# 服务端缓存
proxy_cache_path /var/cache/nginx/data
                 levels=1:2
                 keys_zone=api_cache:100m
                 max_size=10g
                 inactive=60m
                 use_temp_path=off;

server {
    location /api/public/ {
        proxy_pass http://app_backend;
        proxy_cache api_cache;
        proxy_cache_key "$scheme$host$request_uri";
        proxy_cache_valid 200 302 10m;
        proxy_cache_use_stale error timeout http_502 http_503;
        proxy_cache_lock on;
        add_header X-Cache-Status $upstream_cache_status always;
    }

    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

日志格式片段​

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 urt=$upstream_response_time '
                'uht=$upstream_header_time upstream=$upstream_addr '
                'request_id=$request_id';

校验与信号​

操作命令说明
语法检查nginx -t只读检查，不生效
打印生效配置nginx -T展开所有 include，排查「改了不生效」
平滑重载nginx -s reload新 worker 接新连接，老 worker 处理完退出
重开日志nginx -s reopen等价 kill -USR1，配合 logrotate
优雅停机nginx -s quit处理完存量请求再退
快速停机nginx -s stop立即退出
平滑升级kill -USR2 $(cat /var/run/nginx.pid)起新 master
关闭老 workerkill -WINCH $(cat /var/run/nginx.pid.oldbin)升级流程第 6 步

排障命令​

目的命令
看实时访问日志tail -f /var/log/nginx/access.log
看错误tail -n 100 /var/log/nginx/error.log
找慢请求（按 rt 排序）grep -o 'rt=[0-9.]*' access.log | cut -d= -f2 | sort -n | tail
统计状态码分布awk '{print $9}' access.log | sort | uniq -c | sort -rn
端口监听ss -lntp | grep nginx
进程与 workerps -ef | grep nginx
连接状态ss -s
压力测试wrk -t4 -c400 -d60s --latency http://127.0.0.1/
测后端连通curl -sv --connect-timeout 3 http://10.0.0.11:8080/health
状态页curl http://127.0.0.1:8081/stub_status