一、起源
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 内经历三段时间:
- 与客户端建连并读取请求,耗时计入
$request_time的前段。 - 与后端建连、发送请求、读取响应,耗时由
$upstream_*变量单独记录。 - 向客户端发送响应,慢客户端会拉长
$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 为二选一取较优 | 实例数量多,避免固定顺序带来的偏斜 |
选择顺序:
- 先确认后端是否无状态。无状态时优先轮询或
least_conn,把会话保持交给应用层或外部存储解决。 - 存在长耗时请求时选
least_conn,避免请求堆积在恰好被轮到的实例上。 - 必须按业务键稳定分流时才用
hash,并在实例扩缩容时评估重分布范围;需要减少重分布时使用consistent一致性哈希。 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 与握手开销受损。开启长连接需要同时满足三个条件:
upstream块中声明keepalive,指定每个 worker 与后端保持的空闲连接数。proxy_http_version 1.1;,HTTP/1.0 不支持连接复用。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 与客户端连接池配置 |
四、总结
- 反向代理的价值在于把路由、负载均衡、上下文传递与横切治理集中到入口层,代价是增加一次连接并需要显式传递上下文。
- 七层与四层的选择依据是"是否需要按协议内容做决策",四层开销更低但对协议不可见。
proxy_pass的 URI 替换由末尾斜杠与 location 前缀共同决定,正则 location 不允许带 URI,这是路径错乱类问题的根源。Host与X-Forwarded-*必须显式传递;X-Forwarded-For可被伪造,入口层应覆盖而非追加。- 负载均衡算法按后端是否有状态、请求耗时是否均匀、是否需要按业务键分流依次选择,无状态优先于粘滞。
- 开源版只有被动健康检查,5xx 不计入失败计数,需要
proxy_next_upstream显式声明可重试的响应;非幂等请求不应重试。 - 到后端的长连接需要
upstream keepalive、proxy_http_version 1.1、清空Connection三个条件同时满足。 - 代理层自身是入口单点,需要多实例加 DNS、VIP 加 keepalived 或上游负载均衡承担接管。