Web 服务器与网关 / 知识点
Nginx 操作与排障指南
HTTPS 与访问安全
安装证书与私钥,验证证书链和域名,续期后安全 reload 并确认线上证书已更新。
部署、验证与续期 HTTPS 证书
证书上线应完成“文件检查 → Nginx 配置 → reload → 线上验证”。
1. 配置 HTTPS
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/nginx/tls/example.com/fullchain.pem;
ssl_certificate_key /etc/nginx/tls/example.com/privkey.pem;
}2. 生效
sudo nginx -t && sudo systemctl reload nginx3. 验证线上证书
openssl s_client -connect example.com:443 -servername example.com </dev/null并检查证书:
openssl x509 -in /etc/nginx/tls/example.com/fullchain.pem \
-noout -subject -issuer -dates -ext subjectAltName重点确认有效期、SAN 域名和证书链。续期后再次执行 nginx -t、reload,并比较线上证书序列号或指纹。
不要用 curl -k 或忽略 OpenSSL 验证错误作为验收依据。
只开放现代 TLS 协议,并逐步启用 HSTS 等安全响应头,兼顾客户端兼容性。
配置 TLS 与安全响应头
HTTPS 基础可用后,再逐步收紧协议和响应头。
TLS
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;如需自定义 TLS 1.2 套件,应与实际 RSA/ECDSA 证书类型匹配;不要为了兼容重新开放 TLS 1.0/1.1。
安全响应头
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Strict-Transport-Security "max-age=300" always;HSTS 初次上线建议先使用较短 max-age,确认所有子域和 HTTPS 路径都稳定后再逐步提高。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -I https://example.com/
openssl s_client -brief -connect example.com:443 -servername example.com -tls1_2 </dev/null修改 add_header 时注意继承规则:子级重新定义后可能不再继承父级头。
通过 IP 白名单和 HTTP Basic Auth 保护管理端或内部站点,并避免把它当作唯一业务认证。
配置访问控制与基础认证
适合内部管理页、临时运维入口等低复杂度保护场景。
IP 控制
location /admin/ {
allow 10.0.0.0/8;
deny all;
}Nginx 前有可信代理时,应先正确恢复真实客户端 IP,再使用 allow/deny。
Basic Auth
创建密码文件:
sudo htpasswd -c /etc/nginx/.htpasswd admin配置:
location /admin/ {
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
}验证
sudo nginx -t && sudo systemctl reload nginx
curl -i http://127.0.0.1/admin/
curl -i -u admin:<PASSWORD> http://127.0.0.1/admin/未认证应返回 401;允许用户应能访问。Basic Auth 应运行在 HTTPS 上,不应替代应用自身的权限体系。
分别限制单位时间请求速率和单客户端并发连接,避免突发流量耗尽后端资源。
配置请求与连接限流
请求速率和并发连接是两个不同维度,应分别控制。
请求速率
在 http 级:
limit_req_zone $binary_remote_addr zone=req_per_ip:10m rate=10r/s;在目标 location:
limit_req zone=req_per_ip burst=20 nodelay;并发连接
limit_conn_zone $binary_remote_addr zone=conn_per_ip:10m;
server {
limit_conn conn_per_ip 20;
}验证
sudo nginx -t && sudo systemctl reload nginx
for i in $(seq 1 30); do
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1/api/ &
done
wait限流阈值应基于真实流量和上游容量;不要把单一 IP 限制直接用于大量用户共享 NAT 的场景。
性能与可观测性
为文本类响应启用 Gzip,并验证客户端实际收到 Content-Encoding。
启用 Gzip 压缩
适合 HTML、CSS、JavaScript、JSON 等文本响应。
配置
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types
text/plain
text/css
application/json
application/javascript
application/xml;验证
sudo nginx -t && sudo systemctl reload nginx
curl -I -H 'Accept-Encoding: gzip' https://<DOMAIN>/<PATH>预期响应包含:
Content-Encoding: gzip不要重复压缩图片、视频、ZIP 等已经压缩的数据。压缩级别和类型越激进,CPU 开销越高,应结合实际流量测试。
确认构建能力并在 HTTPS 监听上启用 HTTP/2,再通过客户端协议结果验证。
启用 HTTP/2
需要 HTTPS 站点使用 HTTP/2 时,先确认当前 Nginx 构建支持对应能力。
检查
nginx -V 2>&1 | grep -- '--with-http_v2_module'配置
根据当前 Nginx 配置方式启用 HTTP/2,并保留现有 TLS 证书配置。完成后执行:
sudo nginx -t && sudo systemctl reload nginx验证
curl -I --http2 https://<DOMAIN>/客户端应能协商 HTTP/2。若前面还有 CDN 或负载均衡,外部看到的协议可能由前置组件终止,应区分边缘和源站分别验证。
根据 CPU、文件描述符和上下游连接需求调整 worker_connections 与长连接复用。
调整 Worker、连接容量与 Keepalive
高并发或连接数达到上限时,先确认真正瓶颈,再调整 Nginx 和系统限制。
基线配置
worker_processes auto;
events {
worker_connections 4096;
}
http {
keepalive_timeout 30s;
keepalive_requests 1000;
upstream app_backend {
server 127.0.0.1:8080;
keepalive 32;
}
}反向代理复用上游连接时:
proxy_http_version 1.1;
proxy_set_header Connection "";验证
sudo nginx -t
sudo ss -s
cat /proc/$(pgrep -o nginx)/limits | grep -i 'open files'出现 worker_connections are not enough 或 too many open files 时,同时检查 Nginx、生效的系统文件描述符上限和 systemd 单元。不要只不断放大连接数;CPU、上游连接池和内核网络队列也可能是瓶颈。
定义便于排障的 access_log 字段和请求 ID,并确认最终日志路径与错误级别。
配置并读取 Nginx 日志
需要串联客户端、Nginx 和上游问题时,先让日志包含请求、上游和耗时信息。
配置
log_format main
'$remote_addr [$time_local] "$request" $status '
'request_id=$request_id '
'upstream=$upstream_addr upstream_status=$upstream_status '
'rt=$request_time urt=$upstream_response_time';
access_log /var/log/nginx/access.log main;
error_log /var/log/nginx/error.log warn;确认生效位置
sudo nginx -T 2>&1 | grep -nE 'access_log|error_log|log_format'读取
sudo tail -f /var/log/nginx/access.log
sudo tail -n 100 /var/log/nginx/error.log共享日志前脱敏 Cookie、Authorization、查询参数和内部地址。不要长期把生产 error_log 调到 debug。
使用 logrotate 控制 Nginx 日志保留和压缩,并让进程重新打开日志文件。
配置日志轮转
避免 access/error log 长期增长占满磁盘。
logrotate 示例
/var/log/nginx/*.log {
daily
rotate 14
compress
delaycompress
missingok
notifempty
create 0640 root adm
sharedscripts
postrotate
[ ! -f /run/nginx.pid ] || kill -USR1 $(cat /run/nginx.pid)
endscript
}验证
sudo nginx -t
sudo logrotate -d /etc/logrotate.d/nginx确认规则正确后再按系统方式执行实际轮转。USR1 用于让 Nginx 重新打开日志文件;只重命名日志而不重新打开,会让进程继续写旧文件。
故障排查
区分 Nginx 访问规则、目录首页、Unix 权限和 SELinux/AppArmor 导致的 403。
排查 403 与文件权限问题
403 表示请求到达了服务,但访问被拒绝。不要直接 chmod -R 777。
1. 看错误日志
sudo tail -n 50 /var/log/nginx/error.log2. 核对路径映射和权限
sudo nginx -T 2>&1 | grep -nE '^user |root |alias |deny |allow |auth_basic'
namei -l <PATH>重点确认 Nginx worker 用户对父目录有执行权限、对目标文件有读取权限。
3. SELinux
ls -Zd <PATH>静态站点目录需要正确的 Web 内容安全上下文;不要用 setenforce 0 作为长期修复。
修正后:
sudo nginx -t && sudo systemctl reload nginx
curl -i http://127.0.0.1/<PATH>如果是目录请求,还要检查是否存在 index 文件或是否明确允许目录列表。
判断 404 来自 Nginx 本地文件还是上游应用,并还原 server、location 和文件/代理路径。
排查 404 Not Found
先确定请求命中了哪个 server/location,以及 404 是 Nginx 还是上游返回。
快速定位
curl -i http://127.0.0.1/<PATH> -H 'Host: <DOMAIN>'
sudo nginx -T 2>&1 | grep -nE 'listen|server_name|location|root|alias|try_files|proxy_pass'
sudo tail -n 30 /var/log/nginx/error.log如果日志出现:
open() "<PATH>" failed (2: No such file or directory)说明 Nginx 本地文件路径不存在;继续检查 root/alias/try_files。
如果请求走 proxy_pass,直接请求上游对应 URI,确认应用本身是否返回 404。
修正后执行:
sudo nginx -t && sudo systemctl reload nginx
curl -i http://127.0.0.1/<PATH> -H 'Host: <DOMAIN>'区分无效 HTTP 请求与 Cookie、URL、请求头超过缓冲区限制导致的 400/414。
排查 400 与请求头过大
只在携带登录态、大 Cookie 或超长 URL 时失败,优先检查请求头大小。
对比请求
curl -sS -o /dev/null -w 'status=%{http_code} bytes=%{size_request}\n' \
-H 'Host: <DOMAIN>' http://127.0.0.1/按实际峰值调整
http {
client_header_buffer_size 2k;
large_client_header_buffers 4 16k;
}以上数值只是配置示例,不是通用推荐值。
生效
sudo nginx -t && sudo systemctl reload nginx单个请求行或单个头字段仍不能超过单个大缓冲区。先清理重复 Cookie、缩短令牌或 URL,再考虑小幅放大缓冲;同时核对 CDN、Ingress 和应用服务器限制。
从 error.log 区分连接拒绝、地址错误、协议错误和 Unix socket 权限,再直接验证上游。
排查 502 与上游连接失败
502 通常表示 Nginx 已接到请求,但无法从上游获得有效响应。
1. 看错误日志
sudo tail -n 50 /var/log/nginx/error.log重点关注:
connect() failed
Connection refused
no live upstreams
upstream prematurely closed connection2. 直接检查上游
TCP:
curl -sv --max-time 5 http://127.0.0.1:8080/health -o /dev/null
sudo ss -lntp | grep ':8080'同时确认 Nginx 生效配置:
sudo nginx -T 2>/dev/null | grep -nE 'upstream |proxy_pass'如果使用 Unix socket,再检查 socket 路径和 Nginx worker 权限。容器环境不要把 127.0.0.1 误当成其他容器。
上游恢复后重新请求验证,不需要为了 502 反复 restart Nginx。
区分连接超时和响应超时,先直接测量上游耗时,再决定是否调整 proxy timeout。
排查 504 Gateway Timeout
504 表示 Nginx 等待上游超过了允许时间。
测量上游
curl -sS -o /dev/null --max-time 70 \
-w 'connect=%{time_connect}s starttransfer=%{time_starttransfer}s total=%{time_total}s code=%{http_code}\n' \
http://127.0.0.1:8080/<PATH>检查端口:
nc -vz -w 3 127.0.0.1 8080核对配置
proxy_connect_timeout 3s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;修改后:
sudo nginx -t && sudo systemctl reload nginx如果应用本身长期超过超时预算,应优先优化应用、数据库或外部依赖;单纯不断放大 proxy_read_timeout 只会让请求占用资源更久。
追踪 Location 链路,确认 HTTP/HTTPS、域名规范化和前置代理协议判断没有互相跳转。
排查重定向循环
浏览器提示重定向次数过多时,先查看完整跳转链。
追踪
curl -IL --max-redirs 10 http://<DOMAIN>/检查最终配置:
sudo nginx -T 2>&1 | grep -nE 'server_name|return 30[1278]|rewrite|X-Forwarded-Proto'常见问题:
- HTTP server 跳到 HTTPS,而前置代理回源时仍以 HTTP 告诉 Nginx。
www与裸域规则互相跳转。- Nginx 与应用同时做相反的规范化。
修正后:
sudo nginx -t && sudo systemctl reload nginx
curl -IL --max-redirs 10 http://<DOMAIN>/预期在有限次数内结束。前有负载均衡时,确保 Nginx/应用能正确识别原始协议。
检查 Nginx 配置、SNI、证书链、证书私钥匹配和 TLS 协议兼容性。
排查 SSL 握手错误
HTTPS 在返回 HTTP 状态码之前就失败时,从 TLS 层排查。
1. 测试配置
sudo nginx -t2. 直接握手
openssl s_client -connect <DOMAIN>:443 -servername <DOMAIN> </dev/null重点查看证书链、验证错误、协商协议和 SNI 命中的证书。
3. 检查证书与私钥
openssl x509 -in <CERT> -pubkey -noout | openssl pkey -pubin -outform DER | sha256sum
openssl pkey -in <KEY> -pubout -outform DER | sha256sum两边摘要应一致。
如果只有部分旧客户端失败,再检查 ssl_protocols、密码套件和 Nginx 实际链接的 OpenSSL 版本。不要用 curl -k 掩盖证书链或域名问题。
确认文件系统、Nginx 日志和临时目录占用,并识别已删除但仍被进程持有的文件。
排查磁盘占满与临时文件
磁盘接近 100%、日志无法写入或上传/代理缓存异常时使用。
快速定位
df -hT /
sudo du -xh /var/log/nginx /var/cache/nginx 2>/dev/null | sort -h | tail查看 Nginx 实际写入路径:
sudo nginx -T 2>&1 | grep -E 'access_log|error_log|client_body_temp_path|proxy_temp_path'查找已删除但仍占空间的文件:
sudo lsof +L1 | grep nginx如果是日志增长,优先修复 logrotate;如果是临时文件,先确认是否存在大上传、慢客户端、缓存或磁盘写入异常。
不要直接删除未知 temp 文件或整个缓存目录后重启,先确认对应进程和用途,避免破坏正在处理的请求。
结合 worker 资源、连接数、热点 URI 和上游耗时判断是流量增长还是单请求成本异常。
排查 CPU 或内存占用过高
先采样现场,再改配置或重启。
1. 查看 worker 与连接
date
ps -C nginx -o pid,ppid,%cpu,%mem,rss,vsz,stat,etime,cmd --sort=-%cpu | head
sudo ss -s2. 看访问日志热点
根据现有日志格式统计高频 URI、状态码和慢请求;如果已经记录 $request_time、$upstream_response_time,优先比较 Nginx 总耗时和上游耗时。
3. 判断方向
- 单个 worker 高 CPU、总请求量平稳:检查正则、压缩、TLS、热点请求。
- 全部 worker 同时升高且连接数增长:检查流量突增和容量。
- RSS 增长:同时看缓存、长连接、模块和系统 Swap。
- 上游耗时同步升高:先处理后端,不要只增加 Nginx worker。
重启会丢失现场,只在确认无法恢复或维护窗口内执行。