NGINX · 反向代理 / 流量入口
Nginx速查
从配置层级、location 匹配规则到反向代理、负载均衡，再到 HTTPS 加固与 502 排错，运维与生产方向最常用的 41 条配置要点一张表收齐，随查随用。
41条配置要点
6大场景
∞持续更新
📖 速查表
点击展开各小节
⚙️ 核心配置结构
| 配置层级 / 指令 | 说明 | 示例 |
|---|---|---|
| main 全局块 | 最外层全局配置区：运行用户、工作进程数、错误日志、PID 文件路径，作用于整个 Nginx | user www-data; error_log /var/log/nginx/error.log; |
| events 块 | 事件驱动模型配置区（全局只能有一个）：每个 worker 的最大连接数、IO 多路复用模型 | events { worker_connections 10240; use epoll; } |
| http 块 | HTTP 服务全局区：MIME 类型、日志格式、gzip、keepalive 等通用指令，所有 server 都定义在其中 | http { include mime.types; gzip on; } |
| server 块 | 虚拟主机：监听端口与域名，一台机器可配多个 server，按域名/端口分流 | server { listen 80; server_name example.com; } |
| location 块 | server 内的路由单元：按 URI 规则匹配请求，转给后端代理或返回静态文件 | location /api/ { proxy_pass http://backend; } |
| worker_processes | 工作进程数，auto 自动等于 CPU 核数；IO 密集场景可略调高 | worker_processes auto; |
| worker_connections | 单个 worker 的最大并发连接数；反向代理场景一个请求占用 2 个连接（客户端 + 后端） | worker_connections 10240; 理论并发 ≈ worker × connections |
| systemctl 常用命令 | 启动/停止/重启/平滑重载；改完配置先用 nginx -t 校验语法再重载，避免带病上线 | systemctl start nginx nginx -t && nginx -s reload 平滑重载不断连接 |
📍 location 匹配规则
| 匹配符号 | 说明 | 示例 |
|---|---|---|
| = 精确匹配 | URI 完全相等才命中，命中后立即停止匹配，性能最好，适合健康检查等固定路径 | location = /health { return 200 "ok"; } 优先级最高 |
| ^~ 前缀匹配 | 按前缀匹配后不再检查后面的正则，适合静态资源目录的确定性路由 | location ^~ /static/ { root /data/www; } |
| ~ 正则（区分大小写） | 按配置书写顺序依次尝试正则，首个命中即生效 | location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; } |
| ~* 正则（忽略大小写） | 与 ~ 相同但不区分大小写，常用于图片等静态后缀 | location ~* \.(jpg|png|gif)$ { expires 7d; } |
| 无符号 普通前缀 | 最长前缀优先；命中普通前缀后仍可能被正则覆盖，需配合 ^~ 阻断 | location /api/ { proxy_pass http://backend; } |
| 优先级总览 | = > ^~ > 正则（~ / ~* 按书写顺序）> 普通前缀（最长优先） | 口诀：精确最优先，正则压前缀 |
🔀 反向代理
| 配置项 | 说明 | 示例（前提 location /api/） |
|---|---|---|
| proxy_pass 不带路径 | 原样透传完整 URI：/api/user → http://backend/api/user | proxy_pass http://backend; 最常用 |
| proxy_pass 带 / | 去掉 location 匹配前缀再转发：/api/user → http://backend/user | proxy_pass http://backend/; |
| proxy_pass 带路径 | 把 location 前缀替换为指定路径：/api/user → http://backend/v2/user | proxy_pass http://backend/v2/; |
| proxy_pass 带变量 | 按变量动态决定后端，此时 URI 不再自动替换，且需 resolver 解析域名 | resolver 114.114.114.114; proxy_pass http://$upstream_host; |
| 传递真实 IP | 让后端拿到客户端真实 IP 而不是 Nginx 地址，Host 头也要一并透传 | proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Host $host; |
| WebSocket 代理 | 必须升级到 HTTP/1.1 并透传 Upgrade/Connection 头，同时拉长读超时防止长连接被断 | proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 300s; 长连接必备 |
⚖️ 负载均衡
| 策略 / 参数 | 说明 | 示例 |
|---|---|---|
| 轮询（默认） | 请求依次分发到各后端节点，无需任何额外配置 | upstream app { server 10.0.0.1:8080; server 10.0.0.2:8080; } |
| weight 权重轮询 | 按权重分配流量，性能强的机器多分担 | server 10.0.0.1:8080 weight=3; |
| ip_hash | 同一客户端 IP 固定打到同一后端，最简单的会话保持方案 | ip_hash; 会话保持 |
| least_conn | 把新请求分给当前连接数最少的后端，适合请求耗时不均的场景 | least_conn; |
| hash 一致性哈希 | 按指定 key 哈希分片，增删节点时影响面小；配合 consistent 参数更平滑 | hash $cookie_jsessionid consistent; |
| backup 备用节点 | 平时不接流量，主节点全部不可用时自动顶上；可配合 max_fails/fail_timeout 做被动健康检查 | server 10.0.0.3:8080 backup; |
| down 摘除节点 | 标记后不再接收新请求，常用于发布前先摘流量、观察期后上线 | server 10.0.0.2:8080 down; 发布摘流量 |
🔐 HTTPS 与安全
| 配置场景 | 说明 | 示例 |
|---|---|---|
| SSL 证书配置 | 443 端口加 ssl 标记，指定证书与私钥文件，并限制只允许安全的 TLS 版本 | listen 443 ssl; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; |
| HTTP 强制跳转 HTTPS | 单独用一个 server 监听 80 端口，301 永久跳转并保留原始 URI 与参数 | return 301 https://$host$request_uri; |
| Gzip 压缩 | 文本类资源压缩传输，省带宽、加快首屏；注意补上 JSON/JS 等 MIME 类型 | gzip on; gzip_min_length 1k; gzip_comp_level 5; gzip_types text/css application/json application/javascript; |
| limit_req 限流 | 按 IP 限制请求速率：limit_req_zone 定义必须写在 http 上下文，limit_req 在 server/location 中引用；burst 允许突发排队，nodelay 不排队直接处理超额请求 | limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s; limit_req zone=perip burst=20 nodelay; 防刷防爬 |
| limit_conn 并发限连 | 限制单个 IP 的同时连接数，压制大文件盗刷与长连接占用 | limit_conn_zone $binary_remote_addr zone=perconn:10m; limit_conn perconn 20; |
| 防盗链 | 校验 Referer 合法性，放行本站与指定域名，非法来源直接拒绝 | valid_referers none blocked server_names *.example.com; if ($invalid_referer) { return 403; } |
🩺 排错与性能
| 主题 / 指令 | 说明 | 示例 |
|---|---|---|
| root | 实际路径 = root + 完整 URI，location 与 root 各写各的、互不影响 | location /img/ { root /data/www; } # /img/a.png → /data/www/img/a.png |
| alias | 实际路径 = alias 直接替换 location 匹配部分，两端斜杠必须一致，是最易踩坑的指令 | location /img/ { alias /data/images/; } # /img/a.png → /data/images/a.png ⚠ 易错：斜杠一致 |
| 502 Bad Gateway | 后端连不上或返回非法响应：进程挂了、端口写错、防火墙拦截 | curl 10.0.0.1:8080 验证后端存活 grep "connect() failed" error.log |
| 504 Gateway Timeout | 后端处理超过读超时：慢 SQL、下游接口卡死、线程池打满 | proxy_read_timeout 300s; proxy_connect_timeout 10s; 同时排查后端耗时 |
| 日志格式与排查 | 自定义 log_format 加入 $request_time 与 $upstream_response_time，一眼定位慢在哪一层 | tail -f error.log awk '{print $1}' access.log | sort | uniq -c | sort -rn | head Top IP |
| 配置校验与重载 | 任何修改先校验语法再平滑重载，master 进程热加载新配置、旧 worker 处理完再退出 | nginx -t && nginx -s reload |
| 静态文件性能 | sendfile 内核态直接发送文件不落用户态，tcp_nopush 攒满包再发 | sendfile on; tcp_nopush on; 大文件传输 |
| keepalive 复用连接 | 客户端到 Nginx 的长连接超时；对上游 upstream 也配 keepalive，减少反复建连开销 | keepalive_timeout 65; upstream app { keepalive 32; } |