Web 服务器与网关 / 知识点
Nginx 操作与排障指南
基础与配置生效
确认实际运行的 Nginx 二进制、版本、编译能力、主配置路径和最终加载的 include 文件。
确认 Nginx 环境与生效配置
新接手服务器、修改配置前,或怀疑“改错 Nginx / 改错配置文件”时先做这一步。
1. 确认二进制与编译信息
command -v nginx
nginx -V 2>&1重点读取 nginx version、--conf-path、--prefix、--modules-path 以及所需模块开关。
2. 确认服务启动参数
systemd 环境:
systemctl cat nginx | grep -E '^[[:space:]]*ExecStart='如果 ExecStart 带 -c <PATH> 或 -p <PATH>,后续检查必须使用同一套参数。
3. 查看实际加载的配置文件
sudo nginx -T 2>&1 | sed -n 's/^# configuration file \(.*\):$/\1/p'预期能看到主配置和实际命中的 include 文件,例如:
/etc/nginx/nginx.conf
/etc/nginx/conf.d/default.confnginx -T 会输出完整配置,可能包含内部地址、鉴权头或证书路径;共享结果前先脱敏。
按“语法检查 → 平滑 reload → 请求验证”的顺序安全应用 Nginx 配置。
安全检查并重载配置
任何配置修改都优先使用“先检查、再重载”,不要把 restart 当作常规生效方式。
执行
systemd 环境推荐:
sudo nginx -t && sudo systemctl reload nginx
systemctl is-active nginx预期:
nginx: configuration file <PATH> syntax is ok
nginx: configuration file <PATH> test is successful
active非 systemd 环境可在检查成功后执行:
sudo nginx -t && sudo nginx -s reload验证
reload 成功只表示新配置被尝试加载,不代表业务路由、证书或上游一定正确。随后使用真实 Host 做本机请求验证:
curl -i http://127.0.0.1/ -H 'Host: <DOMAIN>'失败时优先修复第一条 [emerg],不要连续重复 reload。
启动、停止或重启 Nginx,并确认 master、worker、监听端口和连接状态。
管理服务并检查运行状态
服务未启动、端口未监听或需要维护 Nginx 时使用。
查看服务状态
systemctl status nginx --no-pager -l
systemctl is-active nginx正常应看到:
active查看进程与监听
ps -eo pid,ppid,user,stat,cmd | grep '[n]ginx:'
sudo ss -lntp | grep -E ':(80|443)[[:space:]]'应能看到 master、worker,以及预期的 80/443 监听。
启停
sudo systemctl start nginx
sudo systemctl restart nginx
sudo systemctl stop nginx普通配置变更不要使用 restart;它会重新创建主进程并可能中断现有连接。生产环境停止服务前先从负载均衡摘流并排空连接。
确认修改文件是否真的被加载、reload 是否发给正确 master,以及请求是否命中正确实例。
排查配置重载未生效
reload 没报错,但请求行为仍旧不变时按下面顺序处理。
1. 确认运行实例
MASTER_PID=$(pgrep -o nginx)
ps -o pid=,ppid=,lstart=,args= -p "$MASTER_PID"
nginx -V 2>&1 | tr ' ' '\n' | grep -E '^--(prefix|conf-path|pid-path)='2. 确认目标文件已加载
sudo nginx -T 2>&1 | grep '^# configuration file'
sudo nginx -T 2>&1 | grep -nF 'server_name <DOMAIN>'没有结果通常表示文件未被 include、软链接不对、扩展名不匹配或使用了另一套配置。
3. 重新测试并验证请求
sudo nginx -t && sudo systemctl reload nginx
ps -o pid,ppid,lstart,stat,args -C nginx
curl -i http://127.0.0.1/ -H 'Host: <DOMAIN>'master PID 应保持不变,新 worker 的启动时间应接近本次 reload。若本机正确而外部仍旧,继续检查其他节点、容器副本、DNS、CDN 或代理缓存。
高风险变更前备份可恢复配置,失败时快速回滚,并在维护时排空连接后优雅退出。
安全回滚与优雅下线
用于高风险配置发布、紧急回退或服务器维护。
1. 变更前备份
STAMP=$(date +%Y%m%d-%H%M%S)
BACKUP_DIR=/var/backups/nginx
sudo install -d -m 700 "$BACKUP_DIR"
sudo tar -C /etc -czf "$BACKUP_DIR/etc-nginx-$STAMP.tgz" nginx
sudo nginx -t预期最后看到:
test is successful2. 发布失败时回滚
先解包到临时目录并 dry-run:
BACKUP=/var/backups/nginx/etc-nginx-<ID>.tgz
RESTORE_DIR=$(mktemp -d)
sudo tar -C "$RESTORE_DIR" -xzf "$BACKUP"
sudo rsync -a --delete --dry-run "$RESTORE_DIR/nginx/" /etc/nginx/确认无误后再执行实际 rsync,然后 nginx -t && reload。
3. 优雅下线
先从负载均衡摘除节点并等待连接下降,再执行:
sudo nginx -s quit
pgrep -a nginx || trueQUIT 会停止接收新连接并等待现有请求完成。不要直接使用 KILL,除非业务明确接受连接中断。
站点与路由
为多个域名配置独立 server,并为未知域名设置明确的默认处理。
配置虚拟主机与域名匹配
多个站点共用一个 Nginx 时,通过 listen + server_name 决定请求进入哪个 server。
配置
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _;
return 404;
}
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
root /srv/www/example.com;
index index.html;
}同一 address:port 只能有一个 default_server。server_name _; 只是占位,真正决定默认服务器的是 default_server。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -i http://127.0.0.1/ -H 'Host: example.com'
curl -i http://127.0.0.1/ -H 'Host: unknown.invalid'预期目标域名命中业务站点,未知域名进入默认服务器。HTTPS 验证应使用 curl --resolve,同时校验 SNI 和域名。
明确配置 HTTP、HTTPS、IPv4、IPv6 监听地址,并验证实际套接字。
配置监听端口与 IPv6
双栈部署建议显式声明 IPv4 与 IPv6,不依赖系统双栈套接字差异。
配置
server {
listen 80;
listen [::]:80;
server_name example.com;
}
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name example.com;
ssl_certificate /etc/nginx/tls/example.crt;
ssl_certificate_key /etc/nginx/tls/example.key;
}验证
sudo nginx -t && sudo systemctl reload nginx
sudo ss -lntp | grep -E ':(80|443)\b'
curl -sS -H 'Host: example.com' http://127.0.0.1/
curl -g -6 -sS -H 'Host: example.com' http://[::1]/预期能看到 IPv4、IPv6 对应端口处于 LISTEN。监听 0.0.0.0 或 [::] 会暴露到所有对应接口,管理端或测试服务应绑定明确的内网/回环地址。
在多个 location 同时可能命中时,确定真正处理请求的配置块。
判断 location 匹配优先级
URI 命中错误 location 时,按匹配规则判断,不要按配置文件从上到下猜。
核心顺序
location = /path精确匹配,命中后结束。- 普通前缀和
^~中先记录最长前缀。 - 最长前缀是
^~时跳过当前层级正则。 - 否则按书写顺序检查
~/~*,第一个命中正则获胜。 - 没有正则命中时使用最长前缀。
快速验证
临时让候选 location 返回不同文本:
location = /health { return 200 "exact"; }
location ^~ /static/ { return 200 "static"; }
location /api/ { return 200 "api"; }
location ~ \.json$ { return 200 "json"; }
location / { return 200 "fallback"; }sudo nginx -t && sudo systemctl reload nginx
curl -sS http://127.0.0.1/health
curl -sS http://127.0.0.1/api/data.json验证完成后恢复业务配置。正则按出现顺序匹配,宽泛规则不要放在更具体规则之前。
根据 URI 到文件系统的映射方式正确选择 root 或 alias,避免 404 和路径重复。
配置静态资源路径
需要让 URI 映射到本地文件时,先判断是保留完整 URI,还是替换 location 前缀。
root
location /static/ {
root /srv/www;
}请求 /static/app.css 实际查找:
/srv/www/static/app.cssalias
location /assets/ {
alias /srv/cdn/;
}请求 /assets/app.css 实际查找:
/srv/cdn/app.css验证
sudo nginx -t && sudo systemctl reload nginx
curl -i http://127.0.0.1/static/app.css
curl -i http://127.0.0.1/assets/app.css目录型 alias 建议让 location 和 alias 都以 / 结尾。遇到 404 时优先从 error.log 的 open() "<PATH>" failed 读取 Nginx 实际尝试的路径。
为静态站点设置首页和文件查找规则,并为单页应用回退到 index.html。
配置首页、try_files 与 SPA 回退
普通静态站点与 Vue/React 等 SPA 的关键区别是“资源不存在时怎么处理”。
普通静态站点
server {
root /srv/www/site;
index index.html;
location / {
try_files $uri $uri/ =404;
}
}SPA
server {
root /srv/www/app;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
}静态资源目录仍建议真实不存在就返回 404,不要全部回退 HTML。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -i http://127.0.0.1/
curl -i http://127.0.0.1/nonexistent-routeSPA 路由应返回 index.html;真实静态资源缺失应继续返回 404。出现 403 时检查目录权限和首页文件。
为带版本指纹的静态资源配置长期浏览器缓存,并避免缓存 HTML 入口。
设置静态资源缓存
适用于 CSS、JS、字体和图片等可版本化资源。
配置
location ~* \.(?:css|js|png|jpg|jpeg|gif|svg|woff2?)$ {
expires 30d;
add_header Cache-Control "public";
}如果资源文件名包含内容哈希,可进一步使用更长缓存;index.html 等入口文件通常不应设置长期不可变缓存。
验证
sudo nginx -t && sudo systemctl reload nginx
curl -I http://127.0.0.1/static/app.<ID>.js重点检查:
Expires: ...
Cache-Control: ...缓存策略必须与发布方式一致。文件内容会覆盖但文件名不变时,过长缓存会让客户端持续读取旧资源。
为常见 HTTP 错误提供统一静态页面,并避免错误页再次触发业务代理。
配置自定义错误页
希望 404、50x 返回统一页面时使用。
配置
server {
error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;
location = /404.html {
root /srv/www/errors;
internal;
}
location = /50x.html {
root /srv/www/errors;
internal;
}
}验证
sudo nginx -t && sudo systemctl reload nginx
curl -i http://127.0.0.1/not-found预期状态码仍保持原错误状态,只替换响应页面。错误页应使用本地静态文件,避免再代理到已经故障的上游。
使用 return 处理 HTTP→HTTPS、旧路径迁移和域名规范化,并验证不会形成循环。
配置跳转与 URL 规范化
简单重定向优先使用 return,规则更直观。
HTTP 跳转 HTTPS
server {
listen 80;
server_name example.com www.example.com;
return 301 https://example.com$request_uri;
}路径迁移
location = /old-login {
return 301 /login;
}验证
sudo nginx -t && sudo systemctl reload nginx
curl -I http://example.com/old-login
curl -IL --max-redirs 10 http://example.com/预期 Location 指向目标地址,并能在有限跳转次数内结束。Nginx 前有 TLS 终止代理时,必须正确识别原始协议,否则容易出现 HTTP/HTTPS 重定向循环。
反向代理与负载均衡
把请求代理到后端服务,并正确处理 proxy_pass 的路径前缀与尾斜杠。
配置反向代理与路径映射
后端服务部署在本机或内网端口时,通过 proxy_pass 对外提供统一入口。
保留原 URI
location /api/ {
proxy_pass http://127.0.0.1:8080;
}/api/users 会转发为上游 /api/users。
去掉 /api/ 前缀
location /api/ {
proxy_pass http://127.0.0.1:8080/;
}/api/users 会转发为上游 /users。
常用请求头
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;验证
sudo nginx -t && sudo systemctl reload nginx
curl -i http://127.0.0.1/api/health -H 'Host: <DOMAIN>'出现 404 时先确认请求到达了哪个上游 URI,不要只检查后端是否存在该接口。
在反向代理链中传递原始 Host、客户端 IP 和协议,并只信任明确的前置代理。
传递真实 IP 与 Host
后端需要记录真实客户端、生成绝对 URL 或按 Host 路由时使用。
代理到应用
location / {
proxy_pass http://app_backend;
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;
}Nginx 前还有可信负载均衡
在 http 级只信任真实代理网段:
set_real_ip_from 10.0.0.10;
real_ip_header X-Forwarded-For;
real_ip_recursive on;验证
sudo nginx -t && sudo systemctl reload nginx
curl -i http://127.0.0.1/ -H 'Host: <DOMAIN>'同时检查后端日志中的 Host 与客户端地址。不要对任意来源信任 X-Forwarded-For,否则客户端可以伪造真实 IP。
正确转发 WebSocket Upgrade 头并为长连接设置合适超时。
代理 WebSocket
WebSocket 需要 HTTP/1.1 和 Upgrade 头,普通 HTTP 代理配置不够。
配置
在 http 级:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}在目标 location:
location /ws/ {
proxy_pass http://app_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 60s;
}验证
sudo nginx -t && sudo systemctl reload nginx
curl --http1.1 -i -N \
-H 'Connection: Upgrade' \
-H 'Upgrade: websocket' \
http://127.0.0.1/ws/正常握手通常返回 101 Switching Protocols。连接固定时间断开时,再检查前置负载均衡和应用端空闲超时。
使用 upstream 分发请求,并限制故障节点切换的条件、次数和总时间。
配置负载均衡与失败切换
多个后端节点提供同一服务时使用。
配置
upstream app_backend {
server 10.0.0.11:8080 max_fails=2 fail_timeout=10s;
server 10.0.0.12:8080 max_fails=2 fail_timeout=10s;
}
location / {
proxy_connect_timeout 1s;
proxy_read_timeout 5s;
proxy_next_upstream error timeout invalid_header
http_502 http_503 http_504;
proxy_next_upstream_tries 2;
proxy_next_upstream_timeout 6s;
proxy_pass http://app_backend;
}默认使用加权轮询;也可按场景使用 least_conn 或 ip_hash。
验证
sudo nginx -t && sudo systemctl reload nginx
for i in $(seq 1 4); do curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1/; done停止一个节点后,请求应能切换到其他节点。非幂等请求不要为了提高成功率盲目开启重试,否则可能造成重复下单、扣款或写入。
根据后端响应特征设置连接、发送、读取超时,并为普通响应或流式响应选择缓冲策略。
调整代理超时与缓冲
后端慢、响应较大、SSE/流式输出异常时使用。
普通 API
location /api/ {
proxy_pass http://app_backend;
proxy_connect_timeout 3s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;
proxy_buffering on;
proxy_buffer_size 8k;
proxy_buffers 8 16k;
}流式响应
location /events/ {
proxy_pass http://app_backend;
proxy_buffering off;
proxy_read_timeout 60s;
}验证
sudo nginx -t && sudo systemctl reload nginx
curl -N -i http://127.0.0.1/events/超时过短会把正常慢请求误判为故障;过长会放大资源占用和客户端等待。按真实延迟分位值调整,不要用无限增大 timeout 解决应用性能问题。
定位请求体超过 Nginx 限制的问题,并把上传上限与前置代理、应用层保持一致。
解决上传 413
客户端上传文件时返回 413 Request Entity Too Large,先确认 Nginx 是否记录了请求体过大。
查看错误日志
sudo grep -F 'client intended to send too large body' /var/log/nginx/error.log | tail设置上限
在合适的 http、server 或 location 中:
client_max_body_size 50m;生效并验证
sudo nginx -t && sudo systemctl reload nginx
curl -i -F 'file=@<PATH>' http://127.0.0.1/upload如果仍然失败,继续检查 CDN、Ingress、负载均衡器和应用服务器的上传限制。不要无上限放大请求体;应按真实业务最大文件大小设置。
按明确来源白名单返回 CORS 响应头,并正确处理 OPTIONS 预检请求。
配置跨域响应
只有确实需要浏览器跨域访问时才配置 CORS。
白名单示例
map $http_origin $cors_origin {
default "";
"https://app.example.com" $http_origin;
}
server {
location /api/ {
if ($request_method = OPTIONS) {
add_header Access-Control-Allow-Origin $cors_origin always;
add_header Access-Control-Allow-Methods "GET,POST,PUT,DELETE,OPTIONS" always;
add_header Access-Control-Allow-Headers "Content-Type,Authorization" always;
return 204;
}
add_header Access-Control-Allow-Origin $cors_origin always;
proxy_pass http://app_backend;
}
}验证
sudo nginx -t && sudo systemctl reload nginx
curl -i -X OPTIONS \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: POST' \
http://127.0.0.1/api/不要把带凭据的接口配置成任意来源。CORS 只控制浏览器跨域读取,不是服务端鉴权。