Web 服务器与网关 / 知识点
Nginx 配置指令速查手册
压缩与协议
指定除默认文本类型外还应压缩的 MIME 类型。
gzip_types
指定除默认文本类型外还应压缩的 MIME 类型。是否启用以及参数取值都应结合响应类型、CPU、带宽和客户端协议能力验证。
语法
gzip_types mime-type ...;上下文: http、server、location
推荐配置
gzip_types text/css application/json application/javascript image/svg+xml;关键行为
不要用文件扩展名替代 MIME 类型;已压缩的图片、视频等通常收益很低。
验证
sudo nginx -t相关指令: gzip
启用或关闭 HTTP/2。
http2
HTTPS 站点需要启用 HTTP/2 时查这个指令。现代 Nginx 推荐独立使用 http2 on;,不要继续新增已弃用的 listen ... http2 写法。
语法
http2 on | off;上下文: http、server
推荐配置
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name example.com;
ssl_certificate /etc/nginx/tls/example.com/fullchain.pem;
ssl_certificate_key /etc/nginx/tls/example.com/privkey.pem;
}关键行为
- HTTP/2 通常通过 TLS ALPN 协商。
- 是否真正使用 HTTP/2 要从客户端协议结果验证,不能只看配置文件。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -I --http2 https://example.com/常见问题
- 客户端仍使用 HTTP/1.1:检查 Nginx 版本、TLS/ALPN 和前置 CDN/LB 是否终止连接。
相关指令: listen、ssl_protocols
TLS 与访问安全
指定 TLS 服务器证书链文件。
ssl_certificate
HTTPS 站点部署或续期证书时查这个指令。生产站点通常应指向包含中间证书链的 fullchain,而不是只放叶子证书。
语法
ssl_certificate file;上下文: http、server
推荐配置
server {
listen 443 ssl;
http2 on;
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
}关键行为
- 证书文件需要 Nginx master 能读取。
- 多域名/SNI 环境要确认请求命中的 server 与证书 SAN 一致。
- 证书内容更新后需要 reload 才会被新连接使用。
验证
sudo nginx -t && sudo systemctl reload nginx
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null |
openssl x509 -noout -subject -issuer -dates常见问题
- 浏览器仍看到旧证书:检查 CDN/LB、多节点和 reload 是否完成。
- 链不完整:确认 ssl_certificate 指向 fullchain。
相关指令: ssl_certificate_key
指定与服务器证书匹配的私钥文件。
ssl_certificate_key
配置 HTTPS 私钥路径或排查证书/私钥不匹配时查这个指令。
语法
ssl_certificate_key file;上下文: http、server
推荐配置
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;关键行为
- 私钥权限应尽可能收紧,并确保 Nginx 运行方式仍能读取。
- 不要把私钥内容直接写进普通配置变量或日志可见位置。
验证
sudo nginx -t
openssl pkey -in /etc/letsencrypt/live/example.com/privkey.pem -check -noout常见问题
key values mismatch:恢复与证书对应的私钥,不要随意重新生成后直接替换。
相关指令: ssl_certificate
限制 TLS 允许使用的协议版本。
ssl_protocols
需要限定客户端允许使用的 TLS 版本时查这个指令。现代公网服务通常以 TLS 1.2 + TLS 1.3 作为兼容起点。
语法
ssl_protocols protocol ...;上下文: http、server
推荐配置
ssl_protocols TLSv1.2 TLSv1.3;关键行为
- 当前 Nginx 官方默认已是 TLSv1.2 TLSv1.3,但显式声明有利于配置审计和跨版本一致性。
- TLS 1.3 需要 Nginx 实际链接的 OpenSSL 支持。
验证
sudo nginx -t && sudo systemctl reload nginx
openssl s_client -brief -connect example.com:443 -servername example.com -tls1_2 </dev/null
openssl s_client -brief -connect example.com:443 -servername example.com -tls1_3 </dev/null常见问题
- 部分旧客户端失败:评估客户端分布,不要为了兼容轻易重新启用 TLS 1.0/1.1。
相关指令: ssl_ciphers
配置 TLS 密码套件列表,主要控制 TLS 1.2 及更早协议的套件。
ssl_ciphers
需要约束 TLS 1.2 及更早协议的密码套件时查这个指令。不要机械复制多年以前的“安全套件清单”,应与证书类型、OpenSSL 和客户端兼容性一起验证。
语法
ssl_ciphers ciphers;上下文: http、server
推荐配置
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers off;关键行为
ssl_ciphers主要控制 TLS 1.2 及更早版本;TLS 1.3 套件由 OpenSSL 的 TLS 1.3 配置机制控制。- 套件过度收紧会导致
no shared cipher。
验证
sudo nginx -t && sudo systemctl reload nginx
openssl ciphers 'HIGH:!aNULL:!MD5'
openssl s_client -brief -connect example.com:443 -servername example.com -tls1_2 </dev/null常见问题
- RSA/ECDSA 证书与允许套件不匹配会导致握手失败。
相关指令: ssl_protocols、ssl_conf_command
控制 SSLv3/TLS1.0–1.2 握手时是否优先按服务端套件顺序选择。
ssl_prefer_server_ciphers
控制 SSLv3/TLS1.0–1.2 握手时是否优先按服务端套件顺序选择。安全相关配置应先明确可信边界、证书来源和客户端兼容范围,再决定是否放宽。
语法
ssl_prefer_server_ciphers on | off;上下文: http、server
推荐配置
ssl_prefer_server_ciphers off;关键行为
现代部署通常优先依赖现代协议和客户端选择;修改前应按兼容性测试。
验证
sudo nginx -t相关指令: ssl_ciphers
通过 OpenSSL 配置接口设置额外 SSL 参数。
ssl_conf_command
通过 OpenSSL 配置接口设置额外 SSL 参数。安全相关配置应先明确可信边界、证书来源和客户端兼容范围,再决定是否放宽。
语法
ssl_conf_command name value;上下文: http、server
推荐配置
ssl_conf_command Ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384;关键行为
属于高级能力,直接改变 OpenSSL 行为;仅在明确合规要求和版本支持下使用。
验证
sudo nginx -t相关指令: ssl_ciphers
声明哪些代理来源可信,可用其传入的地址替换客户端地址。
set_real_ip_from
Nginx 前面存在可信 CDN、负载均衡器或反向代理,需要恢复真实客户端 IP 时查这个指令。最重要的原则是:只信任明确的代理网段。
语法
set_real_ip_from address | CIDR | unix:;上下文: http、server、location
推荐配置
set_real_ip_from 10.0.0.0/8;
set_real_ip_from 192.168.0.0/16;
real_ip_header X-Forwarded-For;
real_ip_recursive on;关键行为
- 只有来自
set_real_ip_from声明地址的代理头才应被信任。 - 把
0.0.0.0/0设为可信会允许普通客户端伪造来源 IP,影响日志、限流和访问控制。
验证
sudo nginx -t
sudo nginx -T 2>/dev/null | grep -nE 'set_real_ip_from|real_ip_header|real_ip_recursive'常见问题
- 恢复后的 IP 不对:检查代理实际写入的是 X-Forwarded-For、X-Real-IP 还是 PROXY protocol。
相关指令: real_ip_header、real_ip_recursive
指定从哪个头或 PROXY protocol 中读取真实客户端地址。
real_ip_header
可信代理已经确定后,用这个指令选择从哪个头或 PROXY protocol 中读取客户端地址。
语法
real_ip_header field | X-Real-IP | X-Forwarded-For | proxy_protocol;上下文: http、server、location
推荐配置
set_real_ip_from 10.0.0.0/8;
real_ip_header X-Forwarded-For;
real_ip_recursive on;关键行为
- 默认头是
X-Real-IP;多级代理链常用X-Forwarded-For配合 recursive。 - 使用
proxy_protocol前,监听 socket 必须同时启用 PROXY protocol。
验证
sudo nginx -t
curl -H 'X-Forwarded-For: 203.0.113.10' http://127.0.0.1/常见问题
- 本地手工伪造头不应改变真实 IP,除非请求来源本身位于可信代理网段。
相关指令: set_real_ip_from
控制在代理地址链中是否递归寻找最后一个非可信地址。
real_ip_recursive
控制在代理地址链中是否递归寻找最后一个非可信地址。安全相关配置应先明确可信边界、证书来源和客户端兼容范围,再决定是否放宽。
语法
real_ip_recursive on | off;上下文: http、server、location
推荐配置
real_ip_recursive on;关键行为
多层可信代理场景常用;可信代理边界配置错误会得到错误客户端 IP。
验证
sudo nginx -t相关指令: real_ip_header、set_real_ip_from
允许指定地址或网段访问当前资源。
allow
允许指定地址或网段访问当前资源。安全相关配置应先明确可信边界、证书来源和客户端兼容范围,再决定是否放宽。
语法
allow address | CIDR | unix: | all;上下文: http、server、location、limit_except
推荐配置
allow 10.0.0.0/8;
deny all;关键行为
allow/deny 按配置顺序检查到第一个匹配规则即停止。
验证
sudo nginx -t相关指令: deny、satisfy
拒绝指定地址或网段访问当前资源。
deny
拒绝指定地址或网段访问当前资源。安全相关配置应先明确可信边界、证书来源和客户端兼容范围,再决定是否放宽。
语法
deny address | CIDR | unix: | all;上下文: http、server、location、limit_except
推荐配置
deny 192.0.2.10;关键行为
规则按顺序匹配;大量复杂地址规则更适合专门的地址映射方案。
验证
sudo nginx -t相关指令: allow
控制 IP 访问控制和认证等多个访问模块是全部满足还是任一满足。
satisfy
控制 IP 访问控制和认证等多个访问模块是全部满足还是任一满足。安全相关配置应先明确可信边界、证书来源和客户端兼容范围,再决定是否放宽。
语法
satisfy all | any;上下文: http、server、location
推荐配置
satisfy any;
allow 10.0.0.0/8;
deny all;
auth_basic "Restricted";关键行为
any 常用于“内网免密、外网认证”;需要同时确认 IP 判断基于可信真实地址。
验证
sudo nginx -t相关指令: allow、deny、auth_basic
启用 HTTP Basic Authentication,并设置认证 realm。
auth_basic
启用 HTTP Basic Authentication,并设置认证 realm。安全相关配置应先明确可信边界、证书来源和客户端兼容范围,再决定是否放宽。
语法
auth_basic string | off;上下文: http、server、location、limit_except
推荐配置
auth_basic "Restricted";关键行为
Basic Auth 只是编码而非加密,公网使用必须配合 HTTPS。
验证
sudo nginx -t相关指令: auth_basic_user_file
指定 Basic Auth 用户名和密码哈希文件。
auth_basic_user_file
指定 Basic Auth 用户名和密码哈希文件。安全相关配置应先明确可信边界、证书来源和客户端兼容范围,再决定是否放宽。
语法
auth_basic_user_file file;上下文: http、server、location、limit_except
推荐配置
auth_basic_user_file /etc/nginx/.htpasswd;关键行为
文件应限制权限并使用受支持的密码哈希格式,不要存放明文密码。
验证
sudo nginx -t相关指令: auth_basic
限流与容量
创建请求速率限制共享内存区域并定义统计 key 与平均速率。
limit_req_zone
需要按客户端 IP、用户或其他变量建立共享请求速率状态时查这个指令。它只定义“计数区和平均速率”,真正执行限制还需要 limit_req。
语法
limit_req_zone key zone=name:size rate=rate;上下文: http
推荐配置
http {
limit_req_zone $binary_remote_addr zone=api_per_ip:10m rate=10r/s;
server {
listen 80;
location /api/ {
limit_req zone=api_per_ip burst=20 nodelay;
limit_req_status 429;
proxy_pass http://app_backend;
}
}
}关键行为
$binary_remote_addr比字符串形式 IP 更节省共享内存。- zone 大小决定可保存多少状态;耗尽时会直接影响后续请求。
- rate 是平均速率,不等于固定时间窗计数器。
验证
sudo nginx -t && sudo systemctl reload nginx
for i in $(seq 1 40); do
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/api/health
done | sort | uniq -c常见问题
- 全都 503/429:检查 zone 是否过小、key 是否过度集中。
- 真实用户共用一个出口 IP 时,按 IP 限流可能误伤。
相关指令: limit_req
把请求速率限制区域应用到具体请求范围。
limit_req
共享限流区已经定义后,用它设置 burst、延迟或拒绝行为。
语法
limit_req zone=name [burst=number] [nodelay | delay=number];上下文: http、server、location
推荐配置
limit_req_zone $binary_remote_addr zone=api_per_ip:10m rate=10r/s;
server {
location /api/ {
limit_req zone=api_per_ip burst=20 nodelay;
limit_req_status 429;
proxy_pass http://app_backend;
}
}关键行为
- 不写
nodelay时,超出平均速率但仍在 burst 内的请求会被延迟处理。 nodelay允许 burst 内请求立即通过,但长期平均速率仍受 zone 控制。- 对登录、短信、验证码等接口,应结合业务账号维度,而不只按 IP。
验证
sudo nginx -t && sudo systemctl reload nginx
for i in $(seq 1 40); do curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/api/; done常见问题
- 状态码默认可能是 503;对 API 通常显式设置
limit_req_status 429更易理解。
相关指令: limit_req_zone、limit_req_status
设置请求因速率限制被拒绝时返回的状态码。
limit_req_status
设置请求因速率限制被拒绝时返回的状态码。限流和容量参数应从真实流量基线出发,并为突发流量、共享出口 IP 和返回状态码预留明确策略。
语法
limit_req_status code;上下文: http、server、location
推荐配置
limit_req_status 429;关键行为
默认值并不一定符合 API 语义;面向 API 时常显式使用 429。
验证
sudo nginx -t相关指令: limit_req
创建并发连接限制的共享内存区域。
limit_conn_zone
需要按 IP、虚拟主机或其他键记录并发连接状态时查这个指令。它定义共享状态区,真正限制数量还要配合 limit_conn。
语法
limit_conn_zone key zone=name:size;上下文: http
推荐配置
http {
limit_conn_zone $binary_remote_addr zone=perip:10m;
server {
location /download/ {
limit_conn perip 2;
limit_conn_status 429;
}
}
}关键行为
- 状态区耗尽会导致新请求被拒绝,因此不能只关注限制数字,也要规划 zone 大小。
- HTTP/2/HTTP/3 中并发请求的计数语义与传统单连接多请求直觉不同,需按实际协议压测。
验证
sudo nginx -t
sudo nginx -T 2>/dev/null | grep -n 'limit_conn_zone'常见问题
- 误伤 NAT 用户:按 IP 的连接限制需要结合用户群网络特征。
相关指令: limit_conn