反向代理陷阱

proxy_pass URL

• proxy_pass http://backend（无斜杠）— 保留路径 /api/users → /api/users
• proxy_pass http://backend/（有斜杠）— 替换路径 /api/users → /users
• location /api/ 搭配 proxy_pass http://x/v1 = 路径不符合预期
• proxy_pass 中使用变量（$uri）会完全改变行为

请求头

• proxy_set_header Host $host — 不加这个，后端收到的是代理 IP 作为 Host
• Host $http_host 包含端口 — Host $host 不包含
• X-Forwarded-For 会被覆盖而非追加 — 使用 $proxy_add_x_forwarded_for
• 带下划线 _ 的请求头默认被忽略 — 需要 underscores_in_headers on

WebSocket

• 缺少 proxy_http_version 1.1 = WebSocket 静默失败
• Connection "upgrade" 必须是字面量字符串，不是变量
• 默认超时 60s 会杀死空闲 WebSocket 连接 — 增大 proxy_read_timeout
• 多级代理链中每一级都需要 upgrade 头

缓冲

• proxy_buffering on（默认）— 完整接收响应后再发送给客户端
• 开启缓冲时，流式响应不工作 — SSE、chunked encoding 会坏掉
• 后端返回 X-Accel-Buffering: no 头可以关闭 — 但不一定有效
• 缓冲区太小 + 大响应 = 写入临时文件

超时

• proxy_connect_timeout 默认 60s — 检测后端宕机太长
• 后端慢 + proxy_read_timeout 低 = 频繁 504
• nginx 超时不会取消后端请求 — 后端仍在处理

上游服务器

• upstream server 不指定端口 = 隐式使用 80 端口
• max_fails=0 禁用健康检查 — 服务器永远不会被标记为下线
• fail_timeout 是双重含义：失败计数周期 + 禁用时长
• 只有一台 server 在线时，轮询忽略权重