Nginx请求转发实战：从proxy_pass到负载均衡与故障排查

只用一条 proxy_pass 就能让后端接口跑起来，但真正上了生产环境才发现，请求转发这个事，水比想象中深得多。我最早接触 Nginx 是因为前后端分离项目联调，前端打包完扔到 Nginx 里，后端接口一联调就 404，后来发现是 location 匹配规则和 proxy_pass 结尾斜杠的问题。这篇文章就把我这些年折腾 Nginx 请求转发的经验完整写出来，从核心概念到常见场景配置，再到故障排查，一次性讲透，适合刚接触 Nginx 的运维新手，也适合给写过简单配置但没系统捋过转发原理的后端和前端同学查漏补缺。

1. 先想清楚：请求转发到底在解决什么问题

很多人把 Nginx 请求转发和反向代理混着叫，其实在日常使用场景里，这俩基本是同一件事。所谓请求转发，就是 Nginx 接收到客户端的 HTTP 请求之后，根据我们配置好的规则，把请求转给另一台服务器去处理，然后把处理结果原样返回给客户端。这个过程对客户端完全透明，客户端始终只跟 Nginx 打交道。

1.1 明明可以直接访问后端，为什么要多一层转发

这是新手最容易困惑的点。我做个简单类比：Nginx 就像一个公司前台。来访者不需要知道研发部在几楼哪个工位，只需要跟前台说“我要找技术部的张工”，前台自己知道张工坐在哪，帮你把人带过去，再把张工的答复带回来。

对应到实际项目里，好处非常实在。第一是解决了端口和跨域问题，后端服务可能跑在 8080、9090 这种端口上，直接暴露给外部既不好记也不安全，通过 Nginx 统一从 80 或 443 端口进入，按域名或路径分发到不同后端；第二是能实现多服务共存，一台服务器上跑着好几个 Web 应用，Nginx 根据请求的域名或 URL 路径，把流量分给对应的应用；第三是能做负载均衡，后端拆成多台实例后，Nginx 按策略把请求分发到不同实例上，避免单台压力过大。除此之外，Nginx 还能顺带做静态资源缓存、HTTPS 证书卸载、请求日志记录，这些都是后端服务不太方便自己处理的事情。

1.2 转发与重定向的本质区别

这里必须重点强调一下，Nginx 里的 proxy_pass 是“代理转发”，跟 return 302 这类“重定向”完全是两码事。转发是 Nginx 替客户端去访问后端，浏览器地址栏的 URL 不会变，整个请求对用户来说还是停留在 Nginx 的域名上；重定向则是服务器告诉客户端“你要的资源在另一个地址，你自己去访问吧”，浏览器地址栏会发生变化，多了一次往返。

实际排查问题时，经常有人把这两者搞混。比如配置完发现浏览器跳到了后端地址、端口暴露出来了，那多半是后端返回了重定向响应，或者是 proxy_pass 配置触发了一些特殊行为。理解了这层区别，后面很多诡异问题都能找到一个合理的排查方向。

1.3 什么场景下必须用 Nginx 转发

从我的实践经验来看，下面几类场景基本离不开 Nginx 请求转发：

• 前后端分离项目部署，前端静态文件放在 Nginx，API 请求转发到后端服务
• 同一台服务器部署多个不同域名的站点，或多个不同路径的 Web 应用
• WebSocket 长连接服务，需要 Nginx 转发并正确设置 Upgrade 头
• 后端服务需要隐藏真实 IP 和端口，或需要统一入口做 HTTPS 卸载
• 多个后端实例组成的集群，需要 Nginx 做负载均衡

搞清楚“为什么要转发”，再去看配置语法，很多细节就都能对上号了。比如为什么要设置 Host 头，为什么要配 X-Forwarded-For，这些不是凭空冒出来的规则，而是为了解决真实存在的问题。

2. 配置语法拆解：location、proxy_pass 与请求头的那些坑

请求转发的核心配置其实就那么几行，但真正决定配置对不对的，是几个容易忽略的细节。我先从一个最简单的完整配置说起，然后逐个拆解重点参数。

2.1 一份最基础的转发配置长什么样

nginx复制server {
    listen 80;
    server_name demo.example.com;

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

这段配置的意思是：当客户端访问 http://demo.example.com/api/xxx 时，Nginx 把请求转发给 http://192.168.1.10:8080/xxx。注意 proxy_pass 的地址末尾带了斜杠，这是关键之一，我后面单独说。

proxy_set_header 这三行是转发的标配。Host 头不改的话，后端收到的 Host 是 Nginx 的地址，但很多时候后端需要知道客户端原本访问的是哪个域名；X-Real-IP 和 X-Forwarded-For 则是把客户端真实 IP 传给后端，否则后端看到的 IP 全是 Nginx 的，做访问控制或日志分析时就抓瞎了。

2.2 location 匹配规则：优先级决定了请求去哪

location 是 Nginx 里最常用的块，它负责决定“这个请求该由哪段配置处理”。刚开始配置的人最容易在这里犯迷糊，因为 location 的匹配规则有好几种，优先级还容易混。

nginx复制# 精确匹配，优先级最高
location = /login {
    proxy_pass http://192.168.1.10:8080/login;
}

# 前缀匹配，^~ 开头表示一旦匹配则不再看正则
location ^~ /static/ {
    alias /var/www/static/;
}

# 正则匹配，按书写顺序匹配，区分大小写
location ~ \.php$ {
    proxy_pass http://192.168.1.10:8080;
}

# 正则匹配，不区分大小写
location ~* \.(jpg|png|css|js)$ {
    expires 30d;
}

# 普通前缀匹配，如果没命中上面的规则，按最长前缀匹配
location /api/ {
    proxy_pass http://192.168.1.10:8080/;
}

# 兜底规则
location / {
    root /var/www/html;
    index index.html;
}

Nginx 匹配 location 的顺序是这样的：先检查精确匹配 =，命中就结束；再检查普通前缀匹配（包括 ^~），记录最长匹配的那个，如果这个最长匹配是 ^~ 开头，就直接结束；否则继续按顺序检查正则匹配 ~ 和 ~*，一旦命中就使用这个正则结果；如果没有正则命中，则使用之前记录的最长前缀匹配结果。

这个优先级顺序务必记清楚。我见过一个真实案例，后端接口路径是 /api/user/info，但项目里同时还有个静态资源目录 /api/docs，结果正则匹配把 /api/docs 下面的请求也转给后端了，导致文档页面打不开。排查到最后就是匹配优先级没理清楚。

2.3 proxy_pass 带不带斜杠，结果天差地别

这是 Nginx 转发里最容易踩的坑，没有之一。proxy_pass 后面是否带 URI，决定了转发时是否替换原请求的路径。很多人配完发现路径不对，基本都是这个问题。

nginx复制# 情况一：proxy_pass 不带 URI（不带斜杠后面的路径部分）
location /api/ {
    proxy_pass http://192.168.1.10:8080;
}
# 请求 /api/user 会被转发为 http://192.168.1.10:8080/api/user
# 原路径原样保留

# 情况二：proxy_pass 带 URI（带了斜杠和路径）
location /api/ {
    proxy_pass http://192.168.1.10:8080/;
}
# 请求 /api/user 会被转发为 http://192.168.1.10:8080/user
# 匹配 location 的部分被替换成 proxy_pass 的 URI

# 情况三：proxy_pass 带了具体路径
location /api/ {
    proxy_pass http://192.168.1.10:8080/v2/;
}
# 请求 /api/user 会被转发为 http://192.168.1.10:8080/v2/user

记住一个规律：proxy_pass 里如果不写 URI 部分，Nginx 会把原始请求 URI 完整传给后端；如果写了 URI（哪怕只是一个 /），匹配到 location 的那一段前缀就会被替换掉。我的建议是：除非你明确需要路径重写，否则不要乱加 URI，保持行为可预期。

这个细节最容易出问题的地方是 WebSocket 或某些对接第三方接口的场景。比如对方接口路径是 /ws/chat，你的前端请求是 /api/ws/chat，配置时如果没有注意斜杠，转发过去的路径就会莫名多一层或少一层，对方直接返回 404，日志里怎么查都发现不了问题。

2.4 Host 头与客户端 IP 传递

为什么 proxy_set_header Host $host 要单独拎出来说？因为很多框架和应用会根据 Host 头来生成跳转链接或校验域名白名单。如果你后端有个功能是“用户修改资料后跳转回个人中心”，返回的是 302 加一个 Location，如果 Host 头不对，这个 Location 可能就指向了内网地址，用户一点就报错。

nginx复制proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

前面三行比较常规，第四行 X-Forwarded-Proto 也很重要。当 Nginx 做 HTTPS 卸载时（即外部走 HTTPS，内部 Nginx 到后端走 HTTP），后端拿 $scheme 是 http，但客户端实际用的是 https。如果后端要根据协议生成绝对链接（典型的比如某些支付回调、OAuth 授权跳转），拿到的协议不对就会校验失败。所以转发时把原始协议也传给后端，让后端知道真实情况。

从这里能看出来，Nginx 转发不仅仅是把流量导过去，还要做好“信息传递”。哪些头要保留，哪些信息要补充，都要根据后端服务的实际需求来定。不同的框架和业务，对头的依赖不一样，配好之后一定要用 curl 验证。

2.5 proxy_set_header 与 proxy_redirect 的配合

还有一种常见情况：后端返回的 Location 或 Refresh 头里带了后端地址（比如 http://192.168.1.10:8080/login），客户端收到后直接访问内网地址，自然就失败了。这时需要 proxy_redirect 把响应头里的地址改写成对外地址。

nginx复制location /api/ {
    proxy_pass http://192.168.1.10:8080/;
    proxy_redirect http://192.168.1.10:8080/ http://demo.example.com/api/;
}

proxy_redirect 默认行为是，如果后端返回的 Location 头跟 proxy_pass 的地址能对上，就自动改写为当前的请求地址。但当后端返回的地址跟 proxy_pass 不一致时，就需要手动指定了。我在对接第三方登录时经常遇到这种问题，对方回调地址写死成了内网 IP，前端拿到跳转地址就懵了。遇到这种问题，先看响应头，再用 proxy_redirect 修正，比让后端改代码要快得多。

3. 实操现场：一次前后端分离项目的完整转发配置

理论说再多，不如完整走一遍真实场景。我拿最常见的“Vue3 前端 + Spring Boot 后端”项目来演示，这套配置几乎能覆盖 90% 以上前后端分离项目的转发需求。

3.1 需求梳理与目录规划

假设服务器是 CentOS 7 或 Ubuntu 20.04，Nginx 已经装好（不会装的后面我会附个快速指引）。项目情况如下：

• 前端：Vue3 项目，npm run build 后生成 dist 目录
• 后端：Spring Boot 项目，运行在 127.0.0.1:8080
• 域名：demo.example.com
• 需求：访问 http://demo.example.com/ 打开前端页面，访问 http://demo.example.com/api/ 时请求转发到后端

这里有个决策点：是前后端都放在同一个 server 块里，还是分开两个 server？我建议前后端分离项目放同一个 server 块，通过 location 区分，这样只需要配一个域名和一个证书，管理成本最低。如果前端和后端各自有独立域名，那就开两个 server 块，各自监听。

3.2 Nginx 配置文件的组织方式

Nginx 的配置文件默认在 /etc/nginx/nginx.conf，主配置文件里通过 include 引入了 conf.d 或 sites-enabled 目录下的子配置。我习惯每个项目单独建一个配置文件，比如 /etc/nginx/conf.d/demo.conf，这样多个项目互不干扰，改配置也只影响对应站点。

bash复制mkdir -p /var/www/demo
# 把前端 dist 目录内容上传到 /var/www/demo 下

编辑配置文件：

nginx复制server {
    listen 80;
    server_name demo.example.com;

    # 前端静态资源
    root /var/www/demo;
    index index.html;

    # 静态资源缓存策略
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 30d;
        add_header Cache-Control "public, no-transform";
    }

    # Vue Router history 模式支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 请求转发到后端
    location /api/ {
        proxy_pass http://127.0.0.1:8080/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 后端处理时间较长时，调大超时时间
        proxy_connect_timeout 60s;
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
    }
}

这里 location /api/ 我特意让 proxy_pass 带上了 /api/，也就是说转发后路径不变，后端接口本身有 /api 这个前缀。如果后端接口没有 /api 前缀，proxy_pass 就要写成 http://127.0.0.1:8080，让 Nginx 把 /api 前缀剥掉再转发。这个选择要看后端的具体设计，没有绝对的对错，但一定得跟后端约定清楚。

3.3 语法定校验与优雅重载

配置文件改完别急着重启，先用命令检查语法：

bash复制nginx -t

出现 syntax is ok 和 test is successful 再重载。重载用 nginx -s reload，它会让 Nginx 平滑加载新配置，不会中断现有连接。我见过有人直接 systemctl restart nginx，虽然也能生效，但如果配置文件有问题，重启就直接挂了，而且正在处理的请求会被强制断开。尽量养成 nginx -t 加 reload 的习惯。

3.4 验证配置是否生效

配置完成后的验证，我一般按下面几步走：

bash复制# 1. 验证前端页面是否能访问
curl -I http://demo.example.com/

# 2. 验证 API 转发是否正常
curl -X GET http://demo.example.com/api/user/info

# 3. 验证请求头是否传递正确
curl -I -H "Host: demo.example.com" http://127.0.0.1/api/user/info

第三步是为了模拟完整链路，同时在 Nginx 日志和后端日志里确认：后端收到的请求路径是什么、Host 头对不对、客户端 IP 是否透传成功。如果后端能看到真实客户端 IP 和正确的 Host，那配置基本就没问题了。

3.5 Windows 服务器上的 Nginx 部署差异

看到热搜词里有人问“win server 修改 nginx 端口号”和“windows server 部署 vue3 项目”，这里顺带说一嘴。Windows 下 Nginx 的配置逻辑跟 Linux 完全一样，只是没有 systemd 那套服务管理，启动是双击 nginx.exe，停止用 nginx -s stop，重载是 nginx -s reload。另外 Windows 下 Nginx 在 run 时会开两个进程，一个是主进程一个是 worker 进程，如果改完配置发现没生效，确认是不是把旧的 nginx.exe 关了又重复启动了。端口修改就在 server 块的 listen 里直接改，改成 8081 或别的端口都行，但要记得 Windows 防火墙放行对应端口，不然外部访问不到。

Windows 上还有个常见问题：前端项目如果用了 history 路由模式，刷新某个子页面会 404。原因很简单，Nginx 找不到对应的物理文件，落到 location / 后如果没有 try_files 兜底，就直接 404 了。所以 try_files $uri $uri/ /index.html; 这一行在 Vue3 项目里是必须的。

4. 转发之外的进阶玩法：负载均衡、多站点与可视化配置

请求转发只是基础能力，把它延展开，就能玩出不少花活。这一节我挑三个跟热搜词关联度最高的方向来讲：负载均衡、多项目部署、可视化配置工具。

4.1 upstream 与负载均衡策略

当后端服务是多个实例时，就需要用 upstream 定义一个后端服务器组，然后在 proxy_pass 里引用它。

nginx复制upstream backend_cluster {
    server 192.168.1.10:8080 weight=3;
    server 192.168.1.11:8080 weight=1;
    server 192.168.1.12:8080 backup;
}

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

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

这个配置里，第一台服务器权重是 3，第二台权重是 1，意思是每 4 个请求里大约有 3 个打到第一台、1 个打到第二台。第三台标了 backup，平时不参与服务，只有前两台都挂了才顶上。

默认情况下 upstream 的负载均衡算法是轮询（round-robin），可以按需切换：

• ip_hash：按客户端 IP 做哈希，同一 IP 每次都打到同一台后端，适合需要保持会话的场景
• least_conn：优先分给当前连接数最少的后端，适合请求处理时间差异比较大的情况
• hash $request_uri：按请求 URI 哈希，适合做缓存场景，同一个接口固定打到同一台机器

会话保持是负载均衡里特别容易踩坑的地方。如果后端没有做 session 共享，用户第一次请求打到 A 服务器，登录状态存在 A 上，第二次请求被轮询到 B，登录就丢了。解决方案要么是后端 session 入库或 Redis 共享，要么前端用 token 鉴权，纯靠 Nginx 的 ip_hash 只能缓解不能根治，因为它把同一个 IP 固定到一台机器，但是 NAT 环境下多个用户可能共享同一个出口 IP，反而会放大单台压力。

4.2 Nginx 部署多个 Web 项目的三种姿势

“Nginx 部署多个 web 项目”也是高频需求。我总结下来无非三种做法，按场景选就行。

第一种是不同域名、同一端口，靠 server_name 区分。这种最省事，每个项目一个 server 块，互不干扰。

nginx复制server {
    listen 80;
    server_name a.example.com;
    root /var/www/a;
}

server {
    listen 80;
    server_name b.example.com;
    root /var/www/b;
}

第二种是同一域名、不同路径，靠 location 区分。注意路径前缀要规划好，别让两个 location 的匹配范围重叠。

nginx复制server {
    listen 80;
    server_name demo.example.com;

    location /a/ {
        proxy_pass http://127.0.0.1:8081/;
    }

    location /b/ {
        proxy_pass http://127.0.0.1:8082/;
    }
}

这里有个非常关键的细节，跟前面说的 proxy_pass 带不带斜杠有关。如果 location /a/ 里 proxy_pass http://127.0.0.1:8081/，那么请求 /a/login 转发到后端就是 /login，后端不需要知道有 /a 这层前缀。如果 proxy_pass http://127.0.0.1:8081 不带末尾斜杠，转发过去就是 /a/login。所以多项目部署时，这层“前缀剥离”全靠斜杠控制，务必跟后端同学确认清楚。

第三种是不同端口，靠 listen 区分。适合临时服务、管理后台这类不需要 80 端口暴露的场景，生产环境用得少，但调试时很方便。

4.3 可视化配置工具值不值得用

热词里出现了“nginx 可视化配置工具”，很多人问要不要装。我的看法是：能用命令行配好的，别急着上工具。Nginx 的配置本身就是一个纯文本文件，掌握了语法之后，用 VS Code 加 Nginx 语法高亮插件已经很好用了。图形化工具适合以下几种人：完全不熟悉命令行的新手、需要给非技术人员展示配置的场合、管理大量 Nginx 实例的场景。

如果确实需要可视化，可以了解下 Nginx GUI 这类开源项目，它提供了浏览器界面来编辑配置和测试。但要注意，这类工具只是帮你生成文本，最终还是要落地到配置文件里，所以核心语法该学还是得学，千万别指望工具帮你解决所有问题。我的建议是：先用命令行把基础概念摸熟，再去考虑工具化，否则出了问题你连日志都找不到。

4.4 简要说一下负载均衡与多项目组合的注意事项

如果多个项目共用一个 Nginx，日志文件、缓存目录、临时文件最好都按项目隔离，避免排查问题时日志混在一起。比如访问日志按域名拆：

nginx复制access_log /var/log/nginx/a.access.log;
access_log /var/log/nginx/b.access.log;

在同一 server 块里没法直接用 server_name 变量当文件名（某些版本有变量注入问题），所以一般是每个 server 块单独指定日志路径。多项目共用 Nginx 时，还要注意 client_max_body_size 这个参数，默认是 1m，如果你某个项目有文件上传需求，不调大这个值，上传稍微大点的文件就会被 Nginx 直接拒掉，报 413 Request Entity Too Large。这个坑我踩过好多次，印象太深了。

5. 高频故障排查与避坑实录

配置 Nginx 转发，大概率会遇到下面这些问题。我把最常见的几类汇总一下，附带排查思路和解决办法，方便你直接按图索骥。

5.1 502 Bad Gateway

这是转发配置里最经典的报错。502 的意思是 Nginx 成功接收了客户端请求，但转发给后端时后端没有正常响应。

排查步骤：

1. 先确认后端进程是不是活着：ps aux | grep java 或 systemctl status 后端服务名
2. 确认后端监听的端口是否有变化
3. 在后端服务器上本地 curl 一下，排除后端自身的问题
4. 检查 Nginx 错误日志：tail -f /var/log/nginx/error.log

常见原因就几类：后端服务没启动、后端端口写错、后端启动慢但 Nginx 的 proxy_connect_timeout 太小、后端和 Nginx 之间有防火墙拦截。我遇到最多的是后端启动慢，JVM 启动要十几秒，Nginx 默认连接超时 60 秒其实一般够，但如果后端启动要两分钟，期间访问就是 502，这时候不是配置问题，等它起来就好。

5.2 504 Gateway Timeout

504 跟 502 的区别是：后端连接上了，但处理时间太长，超过 Nginx 超时时间。这个时候调大三个参数：

nginx复制proxy_connect_timeout 60s;
proxy_read_timeout 120s;
proxy_send_timeout 120s;

比如后端有一个导出报表的接口，正常要跑 90 秒，默认的 60 秒读超时就会导致 504。调大 proxy_read_timeout 就好了。要注意这三个超时是独立配置的，连接超时、发送超时、读取超时各管各的，别只调一个。还有一个思路是接口设计上做异步化，先返回“任务已提交”再轮询结果，但这是后端的改造活了，紧急情况下先调大超时顶上。

5.3 404 Not Found

转发后出现 404，排查路径基本围绕转发的路径对不对。

先看 Nginx 请求日志，看实际转发的目标地址。我前面反复强调的 proxy_pass 带不带斜杠，就是 404 的第一大元凶。其次是 location 匹配到了错误的块，被静态文件处理逻辑接管了。还有一种是后端接口本来就没有这个路径，那就要跟后端对接口文档。

给一个通用的调试方法，在 location 里临时加上一行日志：

nginx复制location /api/ {
    proxy_pass http://127.0.0.1:8080/;
    access_log /var/log/nginx/api_access.log;
}

然后把请求打一遍，打开 api_access.log 看实际请求的 URL，基本就能定位问题。

5.4 刷新页面就 404（前端路由问题）

这个问题前面提过一次，但值得单独列出来。Vue3、React 这类 SPA 应用使用 history 路由时，URL 是真实路径，比如 /user/profile，但服务器上并没有 user 目录，刷新时 Nginx 去找这个物理路径，找不到就 404。

解决办法是在 location / 里加 try_files 兜底：

nginx复制location / {
    try_files $uri $uri/ /index.html;
}

这三个参数的意思是：先找该 URI 对应的文件，找不到就找对应目录下的索引文件，再找不到就返回 /index.html，由前端路由接管页面渲染。这个方法对所有 SPA 项目都适用。如果项目部署在子路径下，比如 http://example.com/app/，那 try_files 要写成 try_files $uri $uri/ /app/index.html;，同时前端项目里的 base 或 publicPath 也要改成 /app/，两边的路径必须对齐。

5.5 客户端真实 IP 丢失的问题

很多应用需要记录用户真实 IP，比如风控系统、投票系统、访问统计。如果通过 Nginx 转发，后端默认看到的 IP 是 Nginx 所在机器的 IP（比如 127.0.0.1），全是一模一样的，没法区分用户。

解决办法就是前面提过的 X-Forwarded-For 头：

nginx复制proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

$proxy_add_x_forwarded_for 这个变量会自动把客户端 IP 追加到已有的 X-Forwarded-For 链路后面。后端框架里要读取这个头而不是 remote_addr。有些框架还有专门的配置项来信任反向代理，比如 Spring Boot 的 server.forward-headers-strategy=native，Tomcat 的 RemoteIpValve，配好之后后端拿到的 getRemoteAddr() 就是真实 IP 了。

这里有个安全细节要注意：如果 Nginx 直接暴露在公网，客户端是可以伪造 X-Forwarded-For 头的。所以比较稳妥的做法是，Nginx 直接覆盖这个头，而不是追加：

nginx复制proxy_set_header X-Forwarded-For $remote_addr;

这样客户端传进来的旧值会被丢弃，后端信任的 IP 来源就是 Nginx 转发的、被 Nginx 验证过的连接 IP。当然，如果中间还有多层代理，怎么处理就得结合整个链路来设计，这里不展开。

5.6 日志切割与排错

日志是 Nginx 排错的命根子，但很多人不重视日志管理，导致日志文件越来越大，排查问题时又找不到关键记录。Nginx 默认不会自动切割日志，运行久了 access.log 可能几个 GB 甚至几十 GB，打开都费劲。我习惯用 logrotate 做日志切割，在 /etc/logrotate.d/nginx 里配置：

bash复制/var/log/nginx/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 640 nginx adm
    sharedscripts
    postrotate
        [ -f /var/run/nginx.pid ] && kill -USR1 `cat /var/run/nginx.pid`
    endscript
}

这段配置的意思是：每天切割一次，保留 14 天，切割后压缩，并且通过向 Nginx 发送 USR1 信号让它重新打开日志文件。配好之后基本不用管，日志会按天滚动存储，排错时按日期找文件就行。Nginx 的日志默认路径在 /var/log/nginx/ 下，access.log 记录请求日志，error.log 记录错误日志。遇到问题先看 error.log，它比 access.log 信息密度高得多，问题原因一般都能在里面找到。

5.7 配置常见问题速查表

这张表我给过不少人，排查效率提升很明显。遇到问题先别慌，对照表格定位方向，再结合日志逐层排查，大多数问题都能在半小时内解决。

6. 一个容易被忽略的点：版本和依赖，以及离线安装

热搜词里有“centos8 离线安装 nginx 下载相关依赖整合包”，还有一个“linux 中配置 dns 出现的问题”，都是部署阶段的拦路虎。这里把离线安装和后端依赖的问题一块聊聊。

6.1 离线安装 Nginx 的准备工作

内网环境不能联网，装 Nginx 是最痛苦的。首先确认服务器系统版本，然后找一台同系统的联网机器下载 Nginx 的 RPM 包和依赖：

bash复制# 在联网机器上执行
yum install --downloadonly --downloaddir=/tmp/nginx_rpm nginx

把 /tmp/nginx_rpm 下的文件拷到内网机器，然后用：

bash复制rpm -ivh *.rpm

或者用 yum localinstall 安装。如果系统是 Ubuntu/Debian，则用 apt-get download 下载 .deb 包再离线安装。离线安装过程中最常见的坑是依赖顺序，有些包之间有依赖关系，用 rpm 一个个装时注意顺序，用 yum localinstall 会自动处理依赖顺序，建议优先用后者。

6.2 Nginx 版本选择与安全更新

安装 Nginx 时版本选择也有讲究。系统自带的 Nginx 往往比较旧，可能带了一些已知的安全隐患。我的建议是使用 Nginx 官方源或维护较好的第三方源安装较新版本，不要贪图省事用系统自带的旧包。关于安全更新，大家平时多关注官方发布的安全公告，确定自己版本受影响后，及时升级到修复版本，这是最稳妥的做法。生产环境升级前，先在测试环境验证配置兼容性，再灰度发布，避免直接大版本跳跃导致配置失效。

6.3 SSL 证书与 HTTPS 转发

虽然标题是请求转发，但现实里 80 端口转发几乎已经不够用了，小程序、Web 安全规范都要求 HTTPS。配置 HTTPS 转发并不复杂：

nginx复制server {
    listen 443 ssl;
    server_name demo.example.com;

    ssl_certificate /etc/nginx/ssl/demo.example.com.pem;
    ssl_certificate_key /etc/nginx/ssl/demo.example.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    location /api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

这里面 X-Forwarded-Proto $scheme 在 HTTPS 场景下特别重要，后端需要用这个值来判断原始请求是 http 还是 https。另外注意配置 80 端口跳转到 443，用 return 301 https://$host$request_uri; 即可。

申请证书现在很方便，免费证书机构能用，有些云平台也有免费证书申请入口。但别忽略证书到期提醒，我见过好几次生产环境证书过期导致服务不可用的，都是因为没设提醒。证书到期前一个月左右就开始准备更换，千万别卡在到期当天再去操作。

6.4 简单说明几种常见编程环境下的部署配合

热搜词里很多是在问环境配置，比如“jdk 环境变量配置失败”、“maven 安装与配置”、“nodejs 安装及环境配置”，这些跟 Nginx 转发看着关系不大，但都是部署前后端项目的上游环节。后端服务跑不起来，Nginx 转发配得再好也是白搭。所以我在这里简单提醒几句。

• JDK 环境变量配好后，一定要在命令行执行 java -version 验证，因为经常出现配了 PATH 但新开的终端窗口没加载的问题，或者装了多个 JDK 导致版本不对的情况
• Maven 配置国内镜像源是加速依赖下载最有效的办法，不然拉依赖能等到怀疑人生
• Node.js 打包前端时，注意前端项目里 /api 请求前缀的配置要和 Nginx 的转发规则对得上，如果改了 Nginx 但前端没有同步修改代理前缀，接口一样不通

这些环境问题看着小，但实际部署链路里出 bug 的概率很高，建议部署前先逐项检查，别等 Nginx 配好了才发现后端根本起不来。

7. 我的一点实操体会

配置 Nginx 请求转发这件事，门槛不高，但坑是真的多。我整理这篇文章的时候，回想这些年踩过的雷，发现大多数问题都是三个原因引起的：一是对 location 匹配优先级不够熟，二是对 proxy_pass 的斜杠规则理解不透，三是排错时不会用日志定位。如果你能把这三样吃透，基本就超越了绝大多数“会配 Nginx 的人”。

最后再分享一个我自己的小习惯：每配完一个转发规则，我都会用 curl 加上 -v 参数把完整的请求和响应头打出来，确认转发路径、Host 头、响应状态码都符合预期才收工。转发链路里，眼见为实比什么都重要，别靠猜。配置文件我还会用 Git 管理起来，每次改动都留痕，万一改出问题，还能第一时间对比回滚。这个习惯帮我省了不知道多少回深夜救火的力气。