06-生产排障高可用与运维体系

1. 阶段定位

第六阶段的目标是从“会配置 Nginx”进入“能守住生产 Nginx”。前五个阶段关注部署、配置、代理、HTTPS、安全、缓存和性能；本阶段关注真实流量下的稳定性、可观测性、故障定位、高可用、灰度发布、变更回滚和运维治理。

生产环境中，Nginx 往往位于客户端、DNS、CDN、云负载均衡、后端应用之间。它可能是真正的故障点，也可能只是故障暴露点。大量 499、502、504、慢请求、上传失败、证书异常、连接耗尽、灰度不生效等问题，表面发生在 Nginx，根因却可能在客户端、网络、系统内核、后端服务、数据库、缓存或发布流程中。

本阶段建立的核心闭环是：

1

日志可观测 -> 指标可告警 -> 故障可定位 -> 变更可回滚 -> 节点可切换 -> 发布可灰度 -> 问题可复盘

完成本阶段后，你应该能回答：为什么 499 激增、502 和 504 如何区分、reload 是否会中断请求、如何设计 access log 字段、如何搭建 Keepalived + VIP、如何做 Header/Cookie/IP 灰度、如何写生产变更和回滚 SOP。

2. 学习边界

本阶段重点学习生产运维和故障治理，不深入源码实现。源码中 master/worker、事件模型、upstream、filter、内存池、模块开发等内容留到第七阶段。

本阶段必须掌握：

• access log 字段设计、JSON 日志、请求 ID 和 upstream 观测。
• error log 级别、典型错误含义和排障方法。
• $request_time、$upstream_connect_time、$upstream_header_time、$upstream_response_time 的含义。
• 400、403、404、405、408、413、414、429、499 等 4xx 排查。
• 500、502、503、504 等 5xx 排查。
• stub_status、连接状态、系统指标、网络抓包和日志采集。
• 平滑 reload、优雅退出、日志重开、二进制热升级和回滚。
• logrotate、日志归档、磁盘治理和审计留存。
• Keepalived + VIP、云负载均衡、Ingress Controller、API Gateway 的职责边界。
• 灰度发布、蓝绿发布、按 Header/Cookie/IP/比例分流。
• 配置变更评审、发布窗口、发布后观察、故障复盘。

3. 生产环境中的 Nginx 角色

排障前必须先判断 Nginx 在架构中的角色，因为不同角色关注的指标和风险完全不同。

第一句话要先问：这台 Nginx 是入口层、静态层、缓存层、代理层、灰度层，还是高可用节点？角色明确后，排障证据才有方向。

4. 生产排障方法论

生产排障不要靠猜，建议固定流程。

1
2
3
4
5
6
7
8

1. 确认影响面：全站、单域名、单接口、单地区、单用户群还是单节点。
2. 确认故障类型：4xx、5xx、超时、慢请求、连接失败、TLS 失败、静态资源异常。
3. 确认时间窗口：是否与发布、配置变更、证书续期、流量突增、云厂商变更有关。
4. 确认入口表现：access log、error log、Nginx 进程、连接数、系统资源。
5. 确认 upstream 表现：upstream 地址、状态码、连接耗时、首包耗时、响应耗时。
6. 确认系统网络：CPU、内存、磁盘、IO、文件描述符、端口、丢包、DNS、路由。
7. 临时止血：回滚、摘除异常节点、扩容、降级、限流、切流。
8. 根因复盘：写清楚原因、影响、处理过程、改进项和监控补齐。

排障时优先回答三个问题：谁报错、哪里慢、影响是否扩大。不要一上来就改配置，正确顺序是：观察证据 > 快速止血 > 小步验证 > 最小变更 > 保留现场 > 复盘固化。

5. 生产日志体系设计

默认 access log 不够支撑生产排障，建议使用 JSON 日志并记录请求 ID、upstream 信息和耗时字段。

生产日志至少应该包含：客户端 IP、真实 IP、X-Forwarded-For、请求 ID、Host、server_name、方法、URI、原始 request_uri、状态码、响应大小、请求体大小、总耗时、upstream 地址、upstream 状态码、upstream 连接耗时、upstream 首包耗时、upstream 响应耗时、缓存状态、Referer、User-Agent。

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

log_format main_json escape=json
    '{'
    '"time":"$time_iso8601",'
    '"remote_addr":"$remote_addr",'
    '"xff":"$http_x_forwarded_for",'
    '"request_id":"$request_id",'
    '"host":"$host",'
    '"method":"$request_method",'
    '"request_uri":"$request_uri",'
    '"status":$status,'
    '"body_bytes_sent":$body_bytes_sent,'
    '"request_length":$request_length,'
    '"request_time":$request_time,'
    '"upstream_addr":"$upstream_addr",'
    '"upstream_status":"$upstream_status",'
    '"upstream_connect_time":"$upstream_connect_time",'
    '"upstream_header_time":"$upstream_header_time",'
    '"upstream_response_time":"$upstream_response_time",'
    '"upstream_cache_status":"$upstream_cache_status",'
    '"referer":"$http_referer",'
    '"user_agent":"$http_user_agent"'
    '}';
access_log /var/log/nginx/access.log main_json;

如果业务已经有链路 ID，应优先透传：

1
2
3
4
5
6

map $http_x_request_id $trace_id {
    default $http_x_request_id;
    ""      $request_id;
}
proxy_set_header X-Request-Id $trace_id;
add_header X-Request-Id $trace_id always;

6.1 $request_time

从读取客户端第一个字节到日志写入的总耗时，包含客户端上传、Nginx 处理、upstream 连接和响应、Nginx 回传客户端。

判断要点：高且 upstream 高：后端慢；高但 upstream 低：客户端接收慢、响应体大或网络慢；高且无 upstream：静态、本地处理或客户端上传慢。

6.2 $upstream_connect_time

Nginx 与 upstream 建立 TCP 连接的耗时。

判断要点：升高时检查后端端口、连接队列、网络丢包、防火墙、安全组、upstream keepalive 和后端 CPU。

6.3 $upstream_header_time

Nginx 连接 upstream 后到收到响应头的耗时。

判断要点：通常代表后端开始返回前的业务处理时间；升高时检查慢 SQL、线程池、连接池、GC、外部依赖。

6.4 $upstream_response_time

Nginx 从 upstream 接收完整响应的耗时。

判断要点：header 低但 response 高：响应体大、后端发送慢或网络慢；多个值说明发生 upstream 重试。

6.5 $upstream_status

upstream 返回给 Nginx 的状态码，不一定等于最终 $status。

判断要点：status=200 upstream_status="502, 200" 表示第一次失败，重试后成功。

6.6 $upstream_addr

实际访问的后端地址。

判断要点：用于定位哪台后端错误率高、响应慢、未摘除，或灰度流量是否进入预期节点。

7. error log 核心用法

access log 看请求结果，error log 看内部原因。生产环境常用 warn，排障可短时间调到 info，debug 需要编译 --with-debug 且日志量极大，不应长期打开。

error log 是定位 502、504、权限、上传限制、文件句柄和 buffer 问题的关键证据。

8. 4xx 状态码生产排查

8.1 400 Bad Request

请求行/Header 格式错误、Header 太大、Host 不合法、HTTPS 打到 HTTP 端口。检查 large_client_header_buffers、curl -v 和客户端代理行为。

8.2 401 Unauthorized

auth_basic、上游鉴权、Authorization Header 未透传。检查认证配置和 proxy_set_header Authorization $http_authorization;。

8.3 403 Forbidden

文件权限、deny、目录无 index、SELinux/AppArmor、防盗链、root/alias 权限错误。用 namei -l 和 error log 定位。

8.4 404 Not Found

文件不存在、root/alias 配错、try_files 回退错误、SPA 路由未回 index、命中错误 server/location。

8.5 405 Method Not Allowed

静态 location 收到 POST/PUT/DELETE、limit_except、后端不支持、OPTIONS 预检未处理。

8.6 408 Request Timeout

客户端发送请求头或请求体太慢、网络差、上传中断。检查 client_header_timeout 和 client_body_timeout。

8.7 413 Request Entity Too Large

上传超过 client_max_body_size，还要检查 CDN、LB、Ingress、API Gateway 和后端框架限制。

8.8 414 URI Too Large

GET 参数过长、SSO 回调过长、URL 嵌套。根治通常是改 POST body 或服务端状态存储。

8.9 429 Too Many Requests

limit_req 或网关限流。重点检查限流 key、NAT 出口误伤、burst、白名单和健康检查。

8.10 499 Client Closed Request

客户端在 Nginx 返回前主动断开。若 upstream_response_time 高，多半后端慢导致客户端放弃；若 request_time 很短，多半客户端取消、探测或网络中断。

9. 5xx 状态码生产排查

9.1 500 Internal Server Error

如果 $upstream_status=500，通常是后端返回；如果无 upstream 信息，可能是 Nginx 本地处理、FastCGI、Lua、SSI 或脚本异常。排查顺序：access log -> error log -> 后端日志 -> 最近发布 -> request_id 复现。

9.2 502 Bad Gateway

表示 Nginx 作为代理时无法从 upstream 获得有效响应。常见原因：后端未启动、端口不监听、进程崩溃、主动 reset、协议错误、响应头过大、网络不通。第一证据通常是 error log。常用命令：curl -v http://10.0.0.11:8080/health、ss -lntp | grep 8080。

9.3 503 Service Unavailable

常见原因：upstream 无可用节点、维护页、限流、健康检查失败、max_fails/fail_timeout 过严、灰度 upstream 没有节点。重点看 no live upstreams、upstream 配置和健康检查。

9.4 504 Gateway Timeout

表示等待 upstream 超时。常见原因：后端处理慢、连接建立慢、线程池/连接池耗尽、数据库慢、外部依赖慢、网络丢包。根据 error log 中 while connecting、while sending request、while reading response header、while reading upstream 区分阶段。不要靠无限调大超时解决，应优化慢接口、异步化长任务、设置合理 SLA。

10. 502、503、504 对比

口诀：502 是连上或读到的东西不对；503 是没有可用服务；504 是等太久没有等到。

11. Nginx 状态观测 stub_status

开启方式：

1
2
3
4
5
6
7
8
9

server {
    listen 127.0.0.1:8088;
    location /nginx_status {
        stub_status;
        allow 127.0.0.1;
        allow 10.0.0.0/8;
        deny all;
    }
}

输出示例：

1
2
3
4

Active connections: 291
server accepts handled requests
 16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106

Active 是当前活跃连接，accepts 是已接受连接，handled 是已处理连接，requests 是请求数，Reading 是读请求头，Writing 是返回响应，Waiting 是 keepalive 空闲连接。Reading 高可能是慢客户端或攻击，Writing 高可能是后端慢、响应体大或客户端接收慢，Waiting 高通常代表 keepalive 多，不一定异常。

12. 监控告警体系

Nginx 监控不能只看进程存活，要覆盖可用性、性能、错误、资源、安全和变更。

典型告警：5xx 比例持续升高、502/504 激增、499 激增、P99 延迟超过基线、连接数接近上限、日志盘超过 80%、证书 15/30 天内过期、VIP 丢失或双主、reload 失败。

13. 日志采集、切割与分析

推荐链路：

1

Nginx access.log / error.log -> logrotate -> Fluent Bit / Vector / Filebeat / Promtail -> Kafka / Loki / Elasticsearch / ClickHouse / 对象存储 -> Grafana / Kibana / SQL / 告警

logrotate 示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

/var/log/nginx/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 nginx adm
    sharedscripts
    postrotate
        if [ -f /run/nginx.pid ]; then
            kill -USR1 `cat /run/nginx.pid`
        fi
    endscript
}

常用分析命令：

1
2
3
4
5

awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -nr
awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -nr | head
grep -E 'upstream|connect\(\)|timed out|reset' /var/log/nginx/error.log | tail -100
jq 'select(.status >= 500)' /var/log/nginx/access.log
jq -r 'select(.status == 502) | .upstream_addr' /var/log/nginx/access.log | sort | uniq -c | sort -nr

不要直接删除当前正在写入的日志文件。若删除了仍被进程占用的日志，磁盘空间可能不会释放，可用 lsof | grep deleted 检查。

14. 进程、信号与平滑 reload

常用信号：

reload 流程：master 收到 HUP -> 检查新配置 -> 打开新日志 -> 启动新 worker -> 通知旧 worker 优雅退出 -> 旧 worker 不再接新连接 -> 处理完已有请求后退出。reload 通常不中断请求，但长连接、WebSocket、大文件下载会让旧 worker 存活更久。

生产 reload SOP：备份配置 -> 测试环境验证 -> nginx -t -> 低峰分批 reload -> 观察 5xx、延迟、连接数、error log -> 异常则回滚并 reload。

15. 二进制热升级与回滚

热升级流程：保留旧二进制 -> 安装新二进制 -> nginx -t -> kill -USR2 $(cat /run/nginx.pid) -> 新 master/worker 启动 -> kill -WINCH $(cat /run/nginx.pid.oldbin) 关闭旧 worker -> 观察新版本 -> kill -QUIT $(cat /run/nginx.pid.oldbin) 退出旧 master。

如果新版本异常，可让旧 master 拉起 worker 并退出新 master：

1
2

kill -HUP $(cat /run/nginx.pid.oldbin)
kill -QUIT $(cat /run/nginx.pid)

热升级必须先在测试环境演练，确认模块和配置兼容，保留旧二进制并准备回滚。多数普通场景下，负载均衡摘流 + 滚动重启比手工热升级更可靠。

16. 系统层排障

常用命令：

1
2
3
4
5

top; uptime; free -h; df -h; iostat -x 1; vmstat 1
ss -s; ss -lntp; ss -antp | head
ulimit -n; cat /proc/$(cat /run/nginx.pid)/limits
lsof -p $(cat /run/nginx.pid) | wc -l
sar -n TCP,ETCP 1; sar -n DEV 1

常见瓶颈：CPU 高可能来自 TLS、gzip、日志或攻击；内存高可能来自连接、buffer、缓存和 page cache；磁盘满通常是日志、缓存或临时文件；IO 高可能是静态大文件、日志写入、缓存读写；文件描述符不足会导致连接失败；TIME_WAIT 多常见于短连接、keepalive 不合理或回源连接过多。

Nginx 配置要和系统限制配合：

1
2

worker_rlimit_nofile 65535;
events { worker_connections 16384; }

systemd 还要配置 LimitNOFILE=65535。

17. 网络层排障

常用命令：

1
2
3
4
5

dig example.com; nslookup example.com
curl -v http://10.0.0.11:8080/health
nc -vz 10.0.0.11 8080
ip route; traceroute 10.0.0.11; mtr 10.0.0.11
ss -ant | awk '{print $1}' | sort | uniq -c | sort -nr

抓包：

1
2

tcpdump -i eth0 host 10.0.0.11 and port 8080 -nn -s 0 -w upstream.pcap
tcpdump -i eth0 port 443 -nn -s 0 -w https.pcap

SYN 无响应通常是网络、防火墙、安全组或后端未监听；SYN 后 RST 通常是端口拒绝或应用主动拒绝；建连后无响应常见于后端处理慢；大量 retransmission 表示丢包或拥塞；后端发 RST 表示后端主动重置。

18. curl 与 openssl 排障

curl 分段耗时：

1
2
3
4
5
6
7
8
9

curl -o /dev/null -s -w '
namelookup: %{time_namelookup}
connect: %{time_connect}
appconnect: %{time_appconnect}
pretransfer: %{time_pretransfer}
starttransfer: %{time_starttransfer}
total: %{time_total}
http_code: %{http_code}
' https://www.example.com/

DNS 高看解析链路，connect 高看 TCP 建连和服务端 accept，appconnect 高看 TLS，starttransfer 高看后端处理或 Nginx 排队，total 高但 starttransfer 低看响应体下载和客户端网络。

证书检查：

1
2

openssl s_client -connect www.example.com:443 -servername www.example.com </dev/null
echo | openssl s_client -connect www.example.com:443 -servername www.example.com 2>/dev/null | openssl x509 -noout -dates -subject -issuer -ext subjectAltName

常见 HTTPS 问题包括证书过期、域名不匹配、证书链不完整、TLS 版本不兼容、HTTPS 请求打到 HTTP 端口、续期后忘记 reload 或访问到未更新节点。

19. upstream 排障与代理模板

生产代理配置要便于观测和控制：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

upstream app_backend {
    least_conn;
    server 10.0.0.11:8080 max_fails=3 fail_timeout=10s;
    server 10.0.0.12:8080 max_fails=3 fail_timeout=10s;
    keepalive 64;
}
server {
    location /api/ {
        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-Request-Id $request_id;
        proxy_connect_timeout 3s;
        proxy_send_timeout 30s;
        proxy_read_timeout 60s;
        proxy_next_upstream error timeout http_502 http_503 http_504;
        proxy_next_upstream_tries 2;
        proxy_pass http://app_backend;
    }
}

排查重点：是否命中预期 upstream、是否发生重试、哪台后端错误率最高、哪台响应最慢、连接是否复用、健康检查是否准确、超时是否符合业务 SLA。

20. 高可用架构

单台 Nginx 有机器宕机、进程异常、系统资源耗尽、网卡故障、配置误操作、证书异常、磁盘满等单点风险。

云上更推荐云 LB + 多 Nginx；传统机房可使用 Keepalived + VIP。

21. Keepalived + VIP

典型架构：VIP 10.0.0.100，Nginx-A 10.0.0.11 为 MASTER，Nginx-B 10.0.0.12 为 BACKUP。

主节点配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

vrrp_script chk_nginx {
    script "/etc/keepalived/check_nginx.sh"
    interval 2
    timeout 2
    fall 2
    rise 2
    weight -20
}
vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 100
    advert_int 1
    authentication { auth_type PASS; auth_pass nginx-ha; }
    virtual_ipaddress { 10.0.0.100/24 }
    track_script { chk_nginx }
}

备节点使用 state BACKUP 和较低 priority 90。健康检查不要只检查进程，还要检查 HTTP 响应：

1
2
3
4

#!/bin/bash
pgrep -x nginx >/dev/null || exit 1
curl -fsS http://127.0.0.1/nginx_health >/dev/null || exit 1
exit 0

生产注意：放通 VRRP、避免 virtual_router_id 冲突、监控 VIP 所在节点、防止脑裂、变更前演练切换，可考虑 nopreempt 减少频繁抢占。

22. 云 LB、Ingress、API Gateway 边界

多层入口常见链路：客户端 -> CDN -> 云 LB -> Nginx -> API Gateway/应用 -> 后端。看到 502 要先判断是谁返回的：CDN、云 LB、Nginx 还是应用。方法包括看响应 Header、查 Nginx access log 是否有请求、看云 LB/CDN 日志、用 curl --resolve 直接访问指定 Nginx 节点。

Kubernetes Ingress 中，Nginx 配置通常由 Ingress、ConfigMap、Annotation 生成，排障要看 Ingress 规则、Service Endpoints、Pod Ready、Controller 日志和 reload 结果。

Nginx 能做反向代理、TLS、路由、基础限流和简单安全控制，但不等于完整 API Gateway。复杂鉴权、多租户、配额、API 生命周期、控制台和动态插件治理，通常由 API Gateway 承担。

23. 灰度发布

灰度维度包括 Header、Cookie、IP、用户 ID、请求参数、比例随机、地域和渠道。

Header 灰度：

1
2
3
4

upstream app_stable { server 10.0.0.11:8080; server 10.0.0.12:8080; }
upstream app_gray { server 10.0.0.21:8080; }
map $http_x_gray $target_upstream { default app_stable; "true" app_gray; }
server { location /api/ { proxy_pass http://$target_upstream; } }

Cookie 灰度适合固定用户：

1

map $cookie_gray $target_upstream { default app_stable; "v2" app_gray; }

IP 灰度适合办公网和特定客户，但要处理 CDN/LB 后真实 IP：

1
2
3
4
5

geo $gray_ip { default 0; 10.10.0.0/16 1; }
map $gray_ip $target_upstream { 0 app_stable; 1 app_gray; }
set_real_ip_from 10.0.0.0/8;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

比例灰度使用 split_clients，分桶 key 必须稳定，优先使用用户 ID、设备 ID 或稳定 Cookie，不建议用每次都变化的 request_id。

灰度推进建议：1% 内部观察 -> 5% 小流量 -> 10% -> 30% -> 50% -> 100%。每一步都观察错误率、延迟、业务指标和日志，并准备一键切回稳定版本。

24. 蓝绿发布

蓝绿发布维护两套完整环境：Blue 为当前生产，Green 为新版本。流程是 Green 部署并冒烟验证，随后切流到 Green，保留 Blue 作为回滚环境。

Nginx 可以通过 upstream 或 map 切换，但生产中更推荐在云 LB、服务注册发现或发布平台切换，减少手工配置风险。蓝绿发布必须保证数据库结构、缓存 key、消息格式、静态资源版本兼容；如果数据库变更不可逆，回滚方案必须提前设计。

25. 生产变更与回滚 SOP

变更 SOP：

1
2
3
4
5
6
7
8
9
10

1. 需求确认：目的、域名、接口、时间、影响范围。
2. 方案评审：配置差异、风险点、验证方式、回滚方式。
3. 测试验证：相同 Nginx 版本和模块。
4. 配置检查：nginx -t 必须通过。
5. 备份当前配置：nginx.conf、conf.d、证书、upstream。
6. 发布窗口：低峰期，通知相关团队。
7. 分批发布：多节点逐台 reload，不同时全量变更。
8. 发布观察：5xx、延迟、error log、业务指标。
9. 异常回滚：恢复备份配置并 reload。
10. 记录归档：记录变更人、时间、内容、结果、问题。

没有回滚方案的发布不应进入生产。回滚对象包括配置、证书、upstream 节点、灰度比例、DNS/LB 切流、缓存策略和限流规则。故障中不要同时做多个不相关变更，否则会增加定位难度。

26. 容量评估与压测

容量评估关注峰值 QPS、并发连接数、平均响应大小、峰值带宽、TLS 握手比例、keepalive 数、upstream 连接数、worker 数、文件描述符、CPU、内存、磁盘 IO。

理论连接上限约等于：worker_processes × worker_connections，但实际还受文件描述符、CPU、内存、网卡、内核参数、upstream 能力、TLS/gzip、日志写入限制。

压测命令：

1
2
3

wrk -t4 -c200 -d60s http://example.com/
ab -n 10000 -c 200 http://example.com/
hey -n 10000 -c 200 http://example.com/

压测必须逐步加压，不要只看平均值，要记录 P50/P90/P95/P99、错误率、超时、Nginx 指标、后端指标和数据库指标。不要在生产高峰直接压测。

27. 安全运维与审计

安全巡检关注 TLS 证书有效期、弱协议和弱 cipher、管理路径暴露、敏感文件暴露、目录遍历、请求体限制、异常频率、扫描器、恶意 Header、Host 头攻击、日志敏感信息泄露。

禁止暴露敏感文件：

1
2
3
4
5
6
7
8
9
10

location ~* /(?:\.git|\.svn|\.hg|\.env|composer\.json|package-lock\.json) {
    deny all;
    access_log off;
    log_not_found off;
}
server {
    listen 80 default_server;
    server_name _;
    return 444;
}

生产建议：关闭 server_tokens、管理接口只允许内网、限制上传大小、对登录/短信/支付接口限流、定期扫描证书、审计配置变更、不在日志中记录完整敏感 Token。

28. 配置管理与目录规范

推荐目录：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

/etc/nginx/
  nginx.conf
  conf.d/
    00-base.conf
    10-log-format.conf
    20-upstream-app.conf
    30-server-www.conf
  snippets/
    proxy-headers.conf
    security-headers.conf
    gzip.conf
    ssl-params.conf
  certs/
  backup/
  sites-available/
  sites-enabled/

原则：通用 Header、SSL 参数、upstream、gzip、安全 Header 分开；每个域名一个 server 文件；生产配置纳入 Git；发布由 CI/CD 或配置管理工具执行；不要把所有内容堆在一个巨大 nginx.conf 中。

29. 生产故障案例

29.1 404 静态资源异常

确认 Host、URI、status；检查 server_name、location、root/alias、try_files、文件是否存在和 error log。常见根因是发布产物缺失、root 错误、alias 斜杠错误、旧 HTML 引用已删除 hash 文件、CDN 缓存旧入口。

29.2 413 上传失败

查 error log 的 client intended to send too large body；检查 Nginx、CDN、LB、Ingress、API Gateway、后端框架的大小限制。上传限制必须全链路一致。

29.3 499 激增

按 URI 统计，查看 request_time 和 upstream_response_time，结合后端耗时、客户端超时、移动端版本、地区运营商。499 是现象，不是根因。

29.4 502 后端拒绝连接

error log 常见 connect() failed (111: Connection refused)。根据 upstream_addr 找异常后端，curl health，查 ss 端口，查应用进程和崩溃日志，临时摘除异常节点。

29.5 504 后端处理慢

error log 常见 upstream timed out while reading response header。查 upstream_header_time、后端 request_id、慢 SQL、线程池、连接池、大查询或导出任务。长任务应异步化。

29.6 日志盘打满

查 df、du、日志目录和 lsof deleted。常见原因是未配置 logrotate、debug 长期开启、访问量突增、error log 高频打印、采集失败。

30. 必做实验清单

1. 自定义 JSON access log 并用 jq 查询 5xx、慢请求、upstream_addr。
2. 复现 404、403、413 并记录 access log、error log、配置项和修复动作。
3. 使用 curl --max-time 1 复现 499，观察 request_time 和 upstream 行为。
4. 让 upstream 指向不存在端口复现 502，让后端 sleep 超过 proxy_read_timeout 复现 504。
5. 开启 stub_status，配合 wrk 观察 Active、Reading、Writing、Waiting。
6. 请求慢接口过程中执行 nginx -t && nginx -s reload，验证请求是否中断。
7. 配置 logrotate，执行 dry-run 和强制切割，确认 USR1 后新日志继续写入。
8. 搭建 Keepalived + Nginx 双机 VIP，停止主节点验证漂移。
9. 配置 Header/Cookie/IP 灰度，验证 stable/gray 命中和快速回滚。

31. 故障排查 SOP 模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

故障标题：
故障时间：
影响范围：
发现方式：监控 / 用户反馈 / 巡检 / 其他
影响域名：
影响接口：
状态码：
错误比例：
峰值 QPS：

一、现象描述
- 客户端表现：
- Nginx access log：
- Nginx error log：
- upstream 表现：
- 系统指标：

二、时间线
- HH:MM 首次告警
- HH:MM 开始排查
- HH:MM 定位根因
- HH:MM 临时恢复
- HH:MM 完全恢复

三、根因分析
- 直接原因：
- 深层原因：
- 为什么监控没有提前发现：

四、处理过程
- 临时止血：
- 配置变更：
- 回滚动作：
- 后端处理：

五、改进项
- 监控补齐：
- 配置治理：
- 发布流程：
- 容量优化：
- 文档沉淀：

32. 生产巡检清单

每日：5xx、499、P95/P99、error log 高频错误、磁盘空间、证书剩余时间、节点健康。

每周：logrotate、线上配置与仓库一致性、upstream 长期异常节点、限流误伤、缓存目录增长、Keepalived 主备状态、告警阈值。

每月：证书续期演练、高可用切换演练、配置回滚演练、容量趋势分析、慢接口 Top、安全配置审计、依赖版本评估。

33. 常用命令速查表

1
2
3
4
5
6
7
8
9

nginx -t; nginx -T; nginx -V
systemctl status nginx; systemctl reload nginx; journalctl -u nginx -n 100 --no-pager
tail -f /var/log/nginx/access.log; tail -f /var/log/nginx/error.log
grep ' 502 ' /var/log/nginx/access.log
ss -s; ss -lntp; ss -antp | grep nginx
top; free -h; df -h; iostat -x 1; vmstat 1
curl -v http://example.com/; curl -vk https://example.com/
dig example.com; tcpdump -i eth0 port 443 -nn
openssl s_client -connect example.com:443 -servername example.com </dev/null

34. 常见误区

• 看到 502 就认为一定是 Nginx 问题。
• 看到 499 就完全归因于客户端，不分析后端耗时。
• 通过无限调大超时时间解决 504。
• 只看平均响应时间，不看 P95/P99。
• access log 没有 upstream 字段，故障时无法定位后端。
• debug 日志长期打开导致磁盘打满。
• 生产变更前不执行 nginx -t。
• 多节点同时 reload，没有分批和回滚。
• Keepalived 只检查进程，不检查真实 HTTP 响应。
• 高可用只关注 VIP 漂移，不监控脑裂。
• 灰度只做分流，不做指标观察和快速回滚。
• 日志只保存在本机，没有集中采集。
• 证书续期后忘记 reload。
• 把 CDN、云 LB、API Gateway 返回的错误误判为 Nginx 错误。

35. 学习检查清单

• 能设计生产 JSON access log。
• 能解释 request_time 和 upstream 三个时间字段。
• 能根据 access log 判断 upstream 重试。
• 能根据 error log 判断 502 直接原因。
• 能区分 502、503、504。
• 能解释 499 的常见原因。
• 能用 curl -w 分析分段耗时。
• 能用 ss、lsof、top、iostat、sar 排查系统瓶颈。
• 能用 tcpdump 分析连接异常。
• 能配置 stub_status 并解释字段。
• 能设计 Nginx 监控告警项。
• 能配置 logrotate 并理解 USR1。
• 能说明 reload 机制和风险。
• 能写变更与回滚 SOP。
• 能搭建 Keepalived + VIP。
• 能配置 Header/Cookie/IP/比例灰度。
• 能区分 Nginx、CDN、云 LB、Ingress、API Gateway、后端服务的问题边界。

36. 过关标准

达到下面标准，说明本阶段基本过关：

1
2
3
4
5
6
7

1. 能在 10 分钟内根据日志判断 502/504/499 的主要方向。
2. 能为生产域名设计完整 access log 字段。
3. 能搭建 stub_status 并接入基础监控。
4. 能写出发布、回滚、日志切割和故障排查 SOP。
5. 能独立完成 Keepalived + Nginx VIP 高可用实验。
6. 能设计按 Header/Cookie/IP/比例的灰度发布方案。
7. 能区分 Nginx、CDN、云 LB、Ingress、API Gateway、后端服务的问题边界。

如果只能写配置，但无法根据日志定位问题，说明还没有真正完成第六阶段。

37. 推荐练习顺序

1
2
3
4
5
6
7
8
9
10
11

自定义 JSON access log
  -> 理解 request_time 和 upstream 时间
  -> 复现 404/403/413/499/502/504
  -> 使用 error log 定位根因
  -> 开启 stub_status
  -> 接入日志切割
  -> 验证 reload 是否中断请求
  -> 使用 curl、ss、tcpdump 做链路排查
  -> 编写变更和回滚 SOP
  -> 搭建 Keepalived + VIP
  -> 实现 Header/Cookie/IP 灰度

不要先做高可用和灰度，必须先掌握日志和排障，否则系统复杂后问题会更难定位。

38. 阶段总结

第六阶段的核心是生产治理能力。Nginx 不再只是一个配置文件和代理进程，而是入口稳定性体系的一部分。你需要用日志还原现场，用指标发现异常，用 SOP 控制变更，用高可用避免单点，用灰度降低发布风险，用复盘减少重复故障。

完成本阶段后，再进入第七阶段源码学习，会更容易理解 Nginx 为什么能平滑 reload、为什么 master/worker 适合高并发、为什么 upstream 和 filter 机制会影响代理、缓存、日志和故障表现。