内容摘要：Nginx 最常用的功能就是反向代理。配置写起来不复杂，但细节没注意，上线后就是 502、504 轮着来。我整理了一份实际项目中反复用到的配置模板，附带说明，直接抄改就能用。 先看一个基础的反向代理配

Nginx 最常用的理配功能就是反向代理。配置写起来不复杂，理配但细节没注意，理配上线后就是理配 502、504 轮着来。理配我整理了一份实际项目中反复用到的理配配置模板，附带说明，理配直接抄改就能用。理配

先看一个基础的理配反向代理配置：

server {  listen 80; server_name api.example.com; location / {  proxy_pass http://127.0.0.1:3000; 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; } }

这四行 proxy_set_header 几乎每个代理配置都得带上。少了 Host，理配后端拿到的理配域名就是 127.0.0.1，有些框架会因此生成错误的理配跳转链接。X-Real-IP 和 X-Forwarded-For 是理配给后端识别真实客户端 IP 用的——如果你后端日志里全是 127.0.0.1，就是理配这里没配。

超时设置是理配另一个坑。Nginx 默认代理超时是 60 秒，但很多后端接口跑个报表、导出数据动辄两三分钟。不改的话，用户等到 60 秒就收到 504。我的习惯是按业务场景分 location 设置：

location /api/report/ {  proxy_pass http://127.0.0.1:3000; proxy_read_timeout 300s; proxy_send_timeout 300s; proxy_connect_timeout 10s; } location /api/ {  proxy_pass http://127.0.0.1:3000; proxy_read_timeout 30s; }

proxy_connect_timeout 不用设太大，10 秒足够。它管的是 Nginx 跟后端建立 TCP 连接的时间，连不上就是连不上，等再久也没意义。真正要放宽的是 proxy_read_timeout，它管的是连接建立后等待后端响应的时间。

WebSocket 代理需要额外加两行：

location /ws {  proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; }

不加 Upgrade 和 Connection 头，WebSocket 握手直接失败，浏览器控制台会报 400。这个我踩过，排查了半天以为是后端问题，结果就是 Nginx 没配对。

负载均衡配置也不复杂。假设后端有三台机器：

upstream backend {  least_conn; server 10.0.1.10:8080 weight=3; server 10.0.1.11:8080; server 10.0.1.12:8080 backup; } server {  listen 80; location / {  proxy_pass http://backend; } }

least_conn 策略适合请求处理时间差异大的场景，谁连接少就往谁那发。默认的轮询在接口响应时间均匀时够用。weight=3 表示这台机器承担三倍流量，适合配置更高的机器。backup 标记的是备机，前面几台都挂了才启用。

健康检查用被动的就行：

upstream backend {  server 10.0.1.10:8080 max_fails=3 fail_timeout=30s; server 10.0.1.11:8080 max_fails=3 fail_timeout=30s; }

30 秒内失败 3 次就摘掉，再过 30 秒重新尝试。对大多数业务来说够用了，没必要上 Nginx Plus 的主动健康检查。

还有个容易忽略的点——proxy_buffering。默认是开的，Nginx 会先把后端响应缓冲下来再发给客户端。对普通接口没影响，但如果是 SSE（Server-Sent Events）或者流式输出，必须关掉：

location /api/stream {  proxy_pass http://127.0.0.1:3000; proxy_buffering off; proxy_cache off; }

不关的话，客户端会一直等，直到缓冲区满了或者连接结束才收到数据，流式效果完全没了。

最后提一下配置文件的组织。别把所有东西塞进 nginx.conf。在 conf.d/ 目录下按域名或业务拆成多个 .conf 文件，改哪个服务就动哪个文件，出问题也好回滚。我见过一个 nginx.conf 写了 2000 多行的，改一行配置得翻半天，纯给自己找麻烦。

配完记得 nginx -t 测一下语法，没问题再 nginx -s reload。reload 不会断现有连接，放心操作。