一、起源

1.1 后端直接暴露的三个问题

  • 地址与拓扑泄露:客户端必须知道后端实例的地址与端口,扩容、迁移与故障替换都会导致客户端侧变更。
  • 横切能力无处安放:TLS 终止、域名路由、限流、访问控制、灰度分流属于所有后端共有的需求,若在每个服务内实现,会造成重复且不一致。
  • 流量入口缺少统一观测点:请求量、状态码分布、响应时间与来源分布需要一个集中的采集位置。

1.2 代理层承担的四类职责

反向代理把上述问题收拢到入口层,同时承担四类职责:

职责 具体内容 依赖的机制
路由 按域名与路径把请求分发到不同后端 server_name、location
负载均衡 在同一后端的多个实例之间分配请求 upstream 与调度算法
上下文传递 把客户端真实信息传给后端 proxy_set_header
治理 TLS、限流、访问控制、缓存、日志 各阶段模块

1.3 七层与四层的分工

代理可以工作在应用层或传输层,两者的能力边界不同:

维度 七层(http 块 + proxy_pass) 四层(stream 块 + proxy_pass)
处理对象 HTTP 请求与响应 TCP 或 UDP 字节流
路由依据 域名、路径、请求头、方法 目标端口,可选按来源地址分流
可做的处理 改写 URI、改请求头、缓存、限流、压缩 只能转发与调度,无法感知应用协议
适用对象 Web 应用、API、WebSocket、gRPC 数据库、缓存、消息队列、任意 TCP 服务
代价 需要解析协议,开销略高 开销低,但对协议内容不可见

选择依据是"是否需要按协议内容做决策":需要则用七层,不需要且希望低开销地用四层。

二、原理

2.1 反向代理的请求路径

一次被代理的请求在 Nginx 内经历三段时间:

  1. 与客户端建连并读取请求,耗时计入 $request_time 的前段。
  2. 与后端建连、发送请求、读取响应,耗时由 $upstream_* 变量单独记录。
  3. 向客户端发送响应,慢客户端会拉长 $request_time 但不影响 $upstream_response_time。

这两个时间分开记录的意义在于:$request_time 明显大于 $upstream_response_time 时,瓶颈在客户端侧或 Nginx 自身;两者接近且都很大时,瓶颈在后端。日志字段定义见 nginx 访问日志分析与在线监控 第二章。

2.2 URI 传递规则

proxy_pass 是否带路径决定了转发给后端的 URI 如何构造,这是配置中最容易出错的部分。

配置写法 请求 URI 转发到后端的 URI 规则
proxy_pass http://backend; /api/user /api/user 不带 URI 时原样传递
proxy_pass http://backend/; /api/user /user 带 URI 时用该 URI 替换 location 匹配到的前缀
proxy_pass http://backend/v1; /api/user /v1user 替换后直接拼接剩余部分,缺少斜杠会造成路径粘连
location /api/ { proxy_pass http://backend/; } /api/user /user location 前缀被替换为 /

容易出错的两种情况:

  • 需要去掉前缀时,proxy_pass 末尾必须带斜杠,且 location 前缀的斜杠位置要与预期替换范围一致。
  • 使用正则 location(~、~*)时不允许在 proxy_pass 中带 URI,否则 nginx -t 报错。

2.3 请求头的传递

默认情况下,Nginx 转发时会改写部分请求头:Host 被替换为 proxy_pass 中的主机名(未使用变量时),连接相关头按 HTTP 版本调整。因此客户端真实信息需要显式传递。

请求头 传递内容 后端用途
Host $host 虚拟主机路由、生成绝对链接
X-Real-IP $remote_addr 记录直接对端地址
X-Forwarded-For $proxy_add_x_forwarded_for 记录完整链路地址
X-Forwarded-Proto $scheme 判断原始协议,用于重定向与安全策略
X-Forwarded-Host $host 保留原始域名

$proxy_add_x_forwarded_for 的行为是"若请求已带该头则在其后追加 $remote_addr,否则等于 $remote_addr"。由此产生两个必须处理的问题:

  • 多级代理下该头会不断变长,后端取真实客户端地址时应按约定位置解析(通常是第一个地址),而不是取最后一个。
  • 客户端可以自行伪造该头。只有当请求必须经过可信代理时该值才可信,因此入口层应当覆盖而不是追加该头,例如直接使用 proxy_set_header X-Forwarded-For $remote_addr;,同时通过 real_ip 模块在入口可信来源范围内还原地址。

2.4 负载均衡算法

算法 配置方式 决策依据 适用条件
轮询 默认 依次分配 后端实例性能一致、请求开销相近
加权轮询 weight=n 按权重比例分配 实例规格不一致
ip_hash ip_hash; 客户端地址哈希 需要简单会话保持且客户端地址稳定
hash hash $key [consistent]; 任意变量哈希 按业务键分流,如按用户或租户
least_conn least_conn; 当前活跃连接数最少 请求耗时差异大,长连接与短请求混合
random random [two]; 随机选择,two 为二选一取较优 实例数量多,避免固定顺序带来的偏斜

选择顺序:

  1. 先确认后端是否无状态。无状态时优先轮询或 least_conn,把会话保持交给应用层或外部存储解决。
  2. 存在长耗时请求时选 least_conn,避免请求堆积在恰好被轮到的实例上。
  3. 必须按业务键稳定分流时才用 hash,并在实例扩缩容时评估重分布范围;需要减少重分布时使用 consistent 一致性哈希。
  4. ip_hash 只解决地址维度的粘滞,客户端切换网络或经多层 NAT 时分布会失真,通常不作为首选。

2.5 健康检查

Nginx 开源版只提供被动健康检查,判断时机是转发结果:

计数事件 是否计入失败 说明
连接后端失败(拒绝、超时) 计入 由 proxy_connect_timeout 与连接结果决定
读取响应超时 计入 由 proxy_read_timeout 决定
后端返回响应 不计入失败计数 即使是 5xx,也说明后端在响应
  • 失败计数达到 max_fails 后,该实例在 fail_timeout 时间内被标记为不可用,不再接收新请求;超时后重新纳入。
  • fail_timeout 同时是统计窗口,计数会随时间推移重置,因此单次抖动不一定触发下线。
  • 返回 5xx 不会让实例下线,需要通过 proxy_next_upstream 显式声明把哪些响应视为可重试,例如 proxy_next_upstream error timeout http_502 http_504;。
  • 主动健康检查需要 Nginx Plus 或第三方模块,开源版可借助外部探活脚本配合配置变更实现,代价是引入配置动态化。

2.6 超时与重试

三个超时的作用位置不同,混用会导致归因错误:

指令 覆盖的动作 触发后的表现
proxy_connect_timeout 与后端建立 TCP 连接 后端未监听或网络不可达时触发,通常很快失败
proxy_send_timeout 向后端发送请求 两次写操作之间的间隔超时,请求体大或后端接收慢时触发
proxy_read_timeout 读取后端响应 后端处理耗时超过该值时触发,接口变慢的主要表现

重试相关约定:

  • proxy_next_upstream_tries 与 proxy_next_upstream_timeout 限制重试次数与总时长,避免在后端大面积故障时反复重试放大压力。
  • 只有幂等请求(GET、HEAD 等)可以安全重试;POST 重试可能造成重复提交,因此不应把 non_idempotent 加入重试条件,除非后端本身具备幂等性。
  • 重试会增加整体延迟,因为客户端等待的是所有尝试的累计时间。

2.7 会话保持

会话保持有三种实现路径:

  • 代理层粘滞:ip_hash 或 hash $cookie_xxx,实现简单但把实例与客户端绑定,实例故障时会话丢失且负载分布易偏斜。
  • 应用层外置:会话数据放 Redis 等共享存储,后端无状态,扩缩容不影响会话(共享存储的可靠性见 Redis 高可用与集群)。
  • 令牌化:会话状态编码进客户端令牌,服务端只做校验,适合多端场景。

选择依据是实例故障时"会话丢失是否可接受":不可接受时优先外置存储,可接受时再考虑代理层粘滞。

2.8 到后端的长连接

默认情况下 Nginx 与后端使用短连接,每次转发都要重新握手;后端在高并发下会因大量 TIME_WAIT 与握手开销受损。开启长连接需要同时满足三个条件:

  1. upstream 块中声明 keepalive,指定每个 worker 与后端保持的空闲连接数。
  2. proxy_http_version 1.1;,HTTP/1.0 不支持连接复用。
  3. proxy_set_header Connection "";,清空客户端传来的关闭指令,否则连接无法复用。

四个条件缺一不可,缺少前两个中的任意一个都会退化为短连接。注意 keepalive 的值是"每 worker 的空闲连接上限",不是总连接数上限。

2.9 四层转发(stream 模块)

stream 块提供 TCP 与 UDP 转发,结构与 http 块类似,但可用指令是其子集。

  • 与 http 的区别:无法按路径或请求头路由,没有 location、proxy_set_header、proxy_cache;转发单位是连接或数据报。
  • 适用对象:数据库、缓存、消息队列,以及需要保留客户端源 IP 的 TCP 服务。
  • UDP 需要显式声明 listen ... udp;,且不适用连接保持类的语义。
  • 健康检查同样只有被动形式,通过 max_fails、fail_timeout 与 proxy_next_upstream 控制。

2.10 代理层自身的高可用

代理层成为新的入口后,自身也必须避免单点:

  • 多实例加 DNS 轮询:实现简单,但故障切换依赖客户端与 DNS 缓存,切换时间不可控。
  • VIP 加 keepalived:由 VRRP 探测决定 VIP 归属,切换时间在秒级,配置方式与健康检查脚本见 linux: 高可用与集群。
  • 上游负载均衡器:由云负载均衡或硬件设备承接入口,Nginx 作为下一层,适合多机房场景。

三、实现

3.1 基础反向代理

upstream backend {
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
}

server {
    listen 80;
    server_name api.example.com;

    location /api/ {
        # 末尾不带斜杠,保留 /api 前缀转发
        proxy_pass http://backend;

        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 3s;
        proxy_send_timeout    30s;
        proxy_read_timeout    30s;

        proxy_next_upstream error timeout http_502 http_504;
        proxy_next_upstream_tries 2;
    }
}

3.2 到后端的长连接池

upstream backend {
    server 10.0.0.11:8080 max_fails=3 fail_timeout=10s;
    server 10.0.0.12:8080 max_fails=3 fail_timeout=10s backup;

    keepalive 64;                       # 每个 worker 保持的空闲连接数
    keepalive_requests 1000;            # 单条连接最大请求数
    keepalive_timeout 60s;              # 空闲连接保持时间
}

server {
    location /api/ {
        proxy_pass http://backend;
        proxy_http_version 1.1;         # 复用要求 HTTP/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 $remote_addr;
    }
}

3.3 按业务键分流与最少连接

upstream tenant_backend {
    least_conn;                         # 活跃连接数优先
    hash $cookie_tenant consistent;     # 按租户稳定分流并减少重分布
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
}

同一个 upstream 中声明多个调度算法时,后声明的覆盖先声明的,nginx -t 会给出 load balancing method redefined 警告;因此需要按连接数调度时,不要在同一个 upstream 中同时写入 hash 与 least_conn。

3.4 WebSocket 与 gRPC 代理

# WebSocket:需要协议升级,读超时按业务空闲时间设置
location /ws/ {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

# gRPC:需要 HTTP/2,且不要改写 Host 与 Connection
location /pkg.Service/ {
    grpc_pass grpc://backend;
    grpc_read_timeout 60s;
    grpc_send_timeout 60s;
}

WebSocket 与 gRPC 都属于长连接,会把连接长期绑定到某个后端实例;此时 least_conn 比轮询更合适,同时需要放宽 proxy_read_timeout。

3.5 灰度发布

# 按请求头分流
map $http_x_release $release_pool {
    default      "backend_stable";
    "canary"     "backend_canary";
}

upstream backend_stable { server 10.0.0.11:8080; }
upstream backend_canary { server 10.0.0.21:8080; }

server {
    location /api/ {
        proxy_pass http://$release_pool;
        proxy_set_header Host            $host;
        proxy_set_header X-Real-IP       $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

要点:proxy_pass 使用变量时不再按 location 前缀替换 URI,若变量结果指向域名而非 upstream 名称,还需要显式声明 resolver 才能解析;按权重灰度则通过在 upstream 中组合新旧实例的 weight 实现,粒度更粗但无需客户端配合。

3.6 四层转发

stream {
    upstream mysql_backend {
        server 10.0.0.31:3306 max_fails=3 fail_timeout=10s;
        server 10.0.0.32:3306 backup;
    }

    upstream redis_backend {
        least_conn;
        server 10.0.0.41:6379;
        server 10.0.0.42:6379;
    }

    server {
        listen 3306;
        proxy_pass mysql_backend;
        proxy_connect_timeout 3s;
        proxy_timeout 600s;             # 空闲超时,需覆盖长事务与连接池空闲期
    }

    server {
        listen 6379;
        proxy_pass redis_backend;
        proxy_timeout 300s;
    }
}

四层转发的 proxy_timeout 覆盖的是连接空闲时间,设置过短会切断连接池中的空闲连接,表现为后端偶发的连接中断。

3.7 验证与核对

# 语法与转发目标核对
nginx -t
nginx -T | sed -n '/upstream/,/}/p'

# 确认请求最终转发到哪个后端(需日志中包含 $upstream_addr)
curl -s -o /dev/null -w "%{http_code}\n" http://api.example.com/api/ping
tail -n 5 /var/log/nginx/access.log

# 连续请求观察负载分布是否均匀
for i in $(seq 1 20); do curl -s http://api.example.com/api/whoami; echo; done

# 验证 URI 替换是否符合预期(在后端日志中核对收到的路径)
curl -s http://api.example.com/api/user/1

# 验证请求头传递
curl -s -H 'X-Forwarded-For: 1.2.3.4' http://api.example.com/api/echo

# 验证长连接是否复用(观察客户端到 nginx 的复用)
curl -sv http://api.example.com/api/ping 2>&1 | grep -i 're-using\|connection'

# 验证 WebSocket 升级
curl -s -i -N -H 'Connection: Upgrade' -H 'Upgrade: websocket' http://api.example.com/ws/ | head -5

# 验证四层转发连通性
nc -vz 10.0.0.11 3306

3.8 常见问题归因

现象 常见原因 核对手段
后端收到的路径多出或缺少前缀 proxy_pass 末尾斜杠与 location 前缀不匹配 后端日志中的请求路径与 nginx -T 的配置
后端获取不到真实客户端地址 未传递 X-Real-IP 与 X-Forwarded-For,或入口未覆盖伪造值 在后端回显请求头
后端日志中的地址是代理地址 未传递或未被后端信任 核对请求头传递与后端的可信代理配置
后端频繁出现 TIME_WAIT 未开启到后端的长连接,或缺少三个前提中的任意一个 nginx -T 检查 upstream 与 proxy 头
部分请求 502 后端实例不可用但未从 upstream 摘除,或响应头超过缓冲区 error_log 中的具体原因与 $upstream_addr 分布
请求集中在少数实例 使用了 ip_hash 且来源经过 NAT,或权重配置不一致 统计 $upstream_addr 分布
重试后出现重复写入 proxy_next_upstream 允许非幂等请求重试 检查重试条件与后端幂等性
长连接被提前断开 四层 proxy_timeout 短于连接池空闲时间 对比 proxy_timeout 与客户端连接池配置

四、总结

  1. 反向代理的价值在于把路由、负载均衡、上下文传递与横切治理集中到入口层,代价是增加一次连接并需要显式传递上下文。
  2. 七层与四层的选择依据是"是否需要按协议内容做决策",四层开销更低但对协议不可见。
  3. proxy_pass 的 URI 替换由末尾斜杠与 location 前缀共同决定,正则 location 不允许带 URI,这是路径错乱类问题的根源。
  4. Host 与 X-Forwarded-* 必须显式传递;X-Forwarded-For 可被伪造,入口层应覆盖而非追加。
  5. 负载均衡算法按后端是否有状态、请求耗时是否均匀、是否需要按业务键分流依次选择,无状态优先于粘滞。
  6. 开源版只有被动健康检查,5xx 不计入失败计数,需要 proxy_next_upstream 显式声明可重试的响应;非幂等请求不应重试。
  7. 到后端的长连接需要 upstream keepalive、proxy_http_version 1.1、清空 Connection 三个条件同时满足。
  8. 代理层自身是入口单点,需要多实例加 DNS、VIP 加 keepalived 或上游负载均衡承担接管。