Nginx 反向代理常用配置解析

理解代理头、超时、缓冲和静态缓存，构建稳定的 Web 入口。

核心思路

正确传递 Host、客户端地址与协议头；连接、读取和发送超时应按业务特征设置。上传接口与流式响应不要沿用普通页面的缓冲策略。

落地步骤

静态资源使用版本化文件名和长期缓存，HTML 保持较短缓存。修改配置前先校验语法，再平滑重载并观察错误率。

验证清单

实施后不要只确认“能运行”，还应检查错误率、延迟、资源占用和异常路径。把验证命令、预期结果和回滚方式写进变更记录，后续维护会轻松很多。

小结

好的工程实践不是堆叠工具，而是用清晰边界、可观察结果和可逆变更降低长期成本。先解决最重要的问题，再逐步自动化。

可执行实践

为上游传递 Host、X-Forwarded-For 和 X-Forwarded-Proto，按接口特性设置 connect/read/send timeout。HTML 使用短缓存，带内容哈希的静态资源使用长期缓存。

验证与退出条件

每次修改先执行 nginx -t，再平滑 reload。通过访问日志、上游响应时间和 499/502/504 比例验证，流式接口要关闭不适用的缓冲。

实践场景

以“为两个后端实例提供反向代理”为例。实施前先保存当前版本、配置和关键指标基线，写明成功条件与停止条件；涉及生产数据或外部写入时，先在隔离环境验证。

分步实施

显式设置上游超时、请求体限制和转发头；健康检查与应用就绪语义一致，TLS 终止和真实客户端地址有可信代理边界。每完成一步都记录可观察结果，不把命令返回零等同于业务正确。

故障演练

关闭一个上游、制造慢响应和超大请求，确认重试不会重复非幂等动作且错误码清晰。演练应使用可清理的测试数据，并验证告警、日志和恢复路径，而不只是确认系统最终又能访问。

观测与回滚

观察 upstream 响应时间、502/504 和连接数；配置检查通过后再 reload，异常恢复旧配置。变更单中应写清负责人、观察窗口、阈值和回滚触发器，避免故障发生后再临时争论。

完成后把使用的版本、关键命令、观测窗口和结果写入变更记录。没有验证证据的“已完成”不能作为上线结论。

第二轮实践复核

可复用交付物： 可校验配置、上游故障矩阵和回退文件。复用时先固定软件版本、依赖锁文件、测试数据规模和运行环境；文章中的命令包含占位符，必须替换成自己的非生产目标后再执行。

最低验证： nginx -t && nginx -T > nginx-effective.conf

执行记录要保存命令、退出码、关键输出、观察窗口和回滚结果。若验证会产生写入，先使用隔离环境或 dry-run；任何失败都不能通过扩大权限、关闭校验或跳过测试来“解决”。

完整实战：带超时边界的 API 代理

反向代理要明确客户端、Nginx 和上游三段连接的超时与信任边界。下面是一个起点，不是通用最优配置：

upstream api_backend {
    zone api_backend 64k;
    keepalive 64;
    server 10.0.1.10:8080 max_fails=3 fail_timeout=10s;
    server 10.0.1.11:8080 max_fails=3 fail_timeout=10s;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

    location /api/ {
        proxy_pass http://api_backend;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Request-ID $request_id;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";

        proxy_connect_timeout 2s;
        proxy_send_timeout 10s;
        proxy_read_timeout 30s;
        client_max_body_size 10m;
    }
}

只有代理处于受信网络边界时才转发或重写 X-Forwarded-*；外部客户端自带的同名头不能直接信任。proxy_read_timeout 是相邻读取间隔，不是完整业务 deadline，应用仍需自己的截止时间和取消传播。

重试不是默认安全

GET 等幂等请求可以在连接失败时有限重试，POST 写操作除非具有稳定幂等键且业务明确支持，否则不能自动转发到第二个上游。代理重试、客户端重试和服务内部重试叠加会形成放大，必须只在一层主导并设置总预算。

验收场景	预期证据
单上游退出	新请求转到健康节点，在途请求行为可解释
上游延迟	到达超时后返回明确状态，无无限连接
大请求体	在代理层受控拒绝，不耗尽临时磁盘
客户伪造转发头	应用看到代理生成的可信链
WebSocket/SSE	单独 location 配置并验证长连接

变更前执行配置语法检查，再 reload 而非粗暴重启；从外部入口验证状态、证书、响应头和 request ID。观察各 upstream 的连接、响应时间、状态码、重试次数和活动连接。回滚使用上一版完整配置文件并再次语法检查，不能在生产机上临时手改后丢失差异。

一手资料

资料与版本边界复核日期：2026-08-22。工具行为可能演进，实施前以锁定版本对应的官方文档为准。