Nginx 配置参数详解

分类详解 Nginx 常用核心配置参数（worker 进程、HTTP、gzip、SSL、upstream 负载均衡、stub_status 监控），并给出生产级配置模板。参数均结合 Ubuntu 22.04 实测默认值说明

Nginxnginxnginx编译Web 服务器与反向代理Web 服务器反向代理2026/09/27

Nginx 配置参数详解

目标：分类详解 Nginx 常用核心配置参数（worker 进程、HTTP、gzip、SSL、upstream 负载均衡、stub_status 监控），并给出生产级配置模板。参数均结合 Ubuntu 22.04 实测默认值说明。

环境信息

  • 操作系统：Ubuntu 22.04.5 LTS
  • Nginx：1.18.0（Ubuntu）
  • 主配置：/etc/nginx/nginx.conf
  • 实测默认：worker_processes auto、worker_connections 768、gzip on

参数查看与修改方式

  • 编译安装时用的参数：nginx -V（查看 configure arguments）。
  • 运行期指令：编辑 /etc/nginx/nginx.conf 或分站点配置。
  • 查看最终合并配置：nginx -T。
  • 校验语法：nginx -t；生效：nginx -s reload。

参数总览

参数所属上下文默认值说明
worker_processes主autoworker 进程数，auto=CPU 核数
worker_connectionsevents768单个 worker 最大并发连接数
keepalive_timeouthttp/server65保持连接超时（Ubuntu 默认 65s）
sendfilehttpon高效零拷贝文件发送
tcp_nopushhttpon拼包后再发送（配合 sendfile）
tcp_nodelayhttpon关闭 Nagle 算法
types_hash_max_sizehttp2048MIME 哈希表大小
default_typehttpapplication/octet-stream未匹配 MIME 的类型
gziphttpon是否开启压缩
ssl_protocolshttp/serverTLSv1..TLSv1.3允许的 TLS 版本
worker_rlimit_nofile主内核上限worker 可打开文件数上限

核心参数分类详解

一、进程与性能参数

user www-data;              # worker 运行身份（影响文件访问权限）
worker_processes auto;      # worker 数=CPU 核数
worker_rlimit_nofile 65535; # 进程可打开文件描述符上限
pid /run/nginx.pid;         # master 进程 PID 文件

events {
    worker_connections 1024;  # 每 worker 最大连接数，需压力测试校准
    multi_accept on;          # 一次 accept 多个连接
}

💡 说明：worker_connections 太高会耗尽内存、太低并发不够，生产建议经压测后设定。

二、HTTP 基础参数

http {
    sendfile on;                    # 零拷贝
    tcp_nopush on;                  # 攒满包再发，减少网络包数
    tcp_nodelay on;                 # 数据及时发送（配合 keepalive）
    keepalive_timeout 65;           # 保持连接时长，过长耗资源、过短对 http1.1 不利
    types_hash_max_size 4096;       # MIME 哈希表
    include /etc/nginx/mime.types;  # 加载文件类型映射
    default_type application/octet-stream;  # 未识别的按下载处理
}

三、gzip 压缩参数（实测通过）

gzip on;
gzip_comp_level 5;                     # 压缩比 1-9，测 6 已默认注释，生产常用 5-6
gzip_min_length 1k;                    # 小于 1k 不压缩
gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript;
gzip_vary on;                          # 响应加 Vary: Accept-Encoding
gzip_disable "MSIE [1-6]\.";           # 屏蔽老 IE

实测：开启压缩并 reload 后，curl -sI --compressed http://localhost/test.html 返回 Content-Encoding: gzip 与 Vary: Accept-Encoding。

四、SSL/HTTPS 参数

server {
    listen 443 ssl;
    ssl_certificate     /etc/ssl/certs/example.crt;  # 证书链文件
    ssl_certificate_key /etc/ssl/private/example.key;# 私钥
    ssl_protocols TLSv1.2 TLSv1.3;           # 禁旧协议
    ssl_session_cache shared:SSL:10m;        # 共享会话缓存，1M≈4000 会话
    ssl_session_timeout 10m;                 # 会话缓存有效期
    ssl_prefer_server_ciphers on;
}

⚠️ 说明：ssl on 指令已在 1.15.0 废弃，用 listen 443 ssl; 替代；升级到新版 nginx 时若仍写 ssl on; 会出 [warn] the "ssl" directive is deprecated 警告。

五、upstream 负载均衡三大模式

  1. 轮询（默认）
upstream backend {
    server 127.0.0.1:8080;
    server 127.0.0.1:8081;
}
server { location / { proxy_pass http://backend; } }
  1. 权重
upstream backend {
    server 127.0.0.1:8080 weight=1;
    server 127.0.0.1:8081 weight=4;   # 分配 4/5 流量
}
  1. IP 哈希（会话保持）
upstream backend {
    ip_hash;
    server 127.0.0.1:8080 weight=1;
    server 127.0.0.1:8081 weight=4;
}

六、stub_status 监控参数

server {
    location /status {
        stub_status on;
        access_log off;
        # allow 127.0.0.1;   # 限制来源，生产强烈建议
        # deny all;
    }
}

reload 后访问 http://localhost/status 实测输出：

Active connections: 1
server accepts handled requests
 2 2 2
Reading: 0 Writing: 1 Waiting: 0

upstream 失败策略与代理缓存（实测）

失败重试 / 健康检查参数

在 upstream 中给每台后端配置失败判定与备份，缓解单点：

upstream backend {
    # max_fails 连续失败 N 次 / fail_timeout 秒内即标记不可用
    server 127.0.0.1:9001 max_fails=2 fail_timeout=5s;   # 活跃后端
    server 127.0.0.1:9002 weight=4 backup;               # backup：活跃全挂后才启用
    # 其他常用：down(不参与)、max_conns=N(限最大并发)、backup(仅兜底)
}
参数作用
max_failsfail_timeout 窗口内最大失败次数，超过标记不可用
fail_timeout失败计数窗口 + 不可用后的恢复探测周期（默认 10s）
backup标记为备份节点，其余活跃节点全部不可用后才启用
down手动将节点下线（维护用）
max_conns该节点最大并发连接数，超限转其他节点

容器实测：active 节点 9001 存活时请求全部返回 backend-9001；kill 掉 9001 后（fail_timeout 窗口内探测到失败），新的缓存旁路请求自动落到 backup 节点 9002，返回 backend-9002 —— 证明备份接管生效。

⚠️ 说明：若配合 proxy_cache，命中的缓存请求不经过 upstream，杀掉 active 后端后仍会从缓存响应，需留意（可用 X-Cache-Status 头区分）。

代理缓存 proxy_cache（实测）

proxy_cache_path /var/cache/nginx/upcache levels=1:2 \
  keys_zone=upcache:10m max_size=100m inactive=10m use_temp_path=off;  # http 块

server {
    location /proxy/ {
        proxy_pass http://backend/;
        proxy_cache upcache;
        proxy_cache_key $request_uri;
        proxy_cache_valid 200 1m;                 # 必须显式声明，否则默认不缓存
        add_header X-Cache-Status $upstream_cache_status;   # MISS/HIT 观测
    }
}

容器实测：首次 X-Cache-Status: MISS，第二次起 HIT；去掉 proxy_cache_valid 后恒为 MISS。

四层负载均衡 stream（TCP/UDP 转发）

stream 模块做四层（非 HTTP 头）转发，编译需 --with-stream；apt 默认已以动态模块加载（/usr/lib/nginx/modules/ngx_stream_module.so）：

# 与 http 平级的顶层块，需确认已 load_module
load_module modules/ngx_stream_module.so;
stream {
    upstream tcp_backend {
        server 127.0.0.1:3306;
        server 127.0.0.1:3307 backup;
    }
    server {
        listen 3306;
        proxy_pass tcp_backend;   # 四层转发 MySQL 等
    }
}

💡 说明：stream 主要用于数据库、Redis、MQ 等 TCP/UDP 服务的高可用与负载，HTTP 场景不适用。

生产配置模板（Nginx 首段）

适用：≥8GB 内存、SSD、OLTP/Web 服务多站点网关：

user www-data;
worker_processes auto;
worker_rlimit_nofile 65535;
pid /run/nginx.pid;

events {
    worker_connections 2048;
    multi_accept on;
    use epoll;
}

http {
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    server_tokens off;              # 隐藏版本号
    client_max_body_size 20m;       # 接口上传限制
    types_hash_max_size 2048;
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    gzip on;
    gzip_comp_level 5;
    gzip_min_length 1k;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript;
    gzip_vary on;

    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';
    access_log /var/log/nginx/access.log main;

    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

常见问题

  • [warn] the "ssl" directive is deprecated：新版 nginx 用 listen 443 ssl;，去掉 ssl on;。
  • gzip 没生效：curl -I --compressed 无 Content-Encoding: gzip，确认 gzip on; 且在 http 块内，且响应类型在 gzip_types 中。
  • worker_connections 超并发：压测后按需加大，同时关注 worker_rlimit_nofile 与系统 ulimit -n。

参考链接