ENGINEERING PLAYBOOK

Nginx 反向代理配置与验证

反向代理配置要区分客户端到 Nginx 和 Nginx 到上游两段连接。URI 拼接、Host 传递和可信代理边界应通过实际请求验证。

适用人群：需要定位 Nginx 502、上游连接和转发头问题的服务维护人员

排查路径

  1. 明确公开入口、上游地址和 URI 映射。
  2. 配置必要请求头并限制可信来源。
  3. 分别设置连接、发送和读取超时。
  4. 用状态码、上游耗时和请求标识验收。

执行步骤

  1. 先用 curl 直接访问上游确认服务可用。
  2. 使用 nginx -T 检查最终合并配置。
  3. 核对 proxy_pass 是否带尾部斜线。
  4. 只在可信代理链中接受转发客户端地址。
  5. nginx -t 通过后再 reload。

可复制命令与示例

基础代理位置

location /api/ {
    proxy_pass http://127.0.0.1:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Request-ID $request_id;
}

验证配置与响应

sudo nginx -t && curl -sS -D - https://example.test/api/health

可复现任务记录

具体错误或任务

代理返回 502，但上游本机端口可访问，需要比较连接地址、协议和 Host。

失败信号：Nginx error log 出现 connect() failed 或 upstream prematurely closed connection。

最小输入

server/location 配置、上游地址、请求 Host、失败时间和直接访问上游的结果。

验证命令或步骤

nginx -t && curl -sS -D - -o /dev/null -H 'Host: example.test' 'http://127.0.0.1:8080/health'

预期输出

nginx -t 显示 syntax is ok；上游 health 返回预期 2xx 和正确 Content-Type。

失败输出

connection refused、协议不匹配、Host 路由错误或上游提前关闭连接。

成功判据

代理与直连使用可解释的头和协议，目标路径返回同一业务结果，错误日志不再出现对应失败。

本任务常见错误

  • 只改超时掩盖连接错误
  • 混用 http 与 https 上游
  • 未传递或误写 Host 导致路由错误

资料与适用边界

指令行为依据 Nginx 官方 proxy 模块文档；上游健康和业务响应由目标服务自身证据验证。

证据块复核日期：2026-09-04

相关站内页面

资料依据与复核边界

资料复核日期：2026-08-29