Nginx反向代理到底怎么配?从零到上线,这份实操笔记帮你避掉90%的坑

很多站长在刚接触服务器运维时,都会遇到这样一个场景:明明买了两台云服务器,一台跑后端应用(比如 Node.js、Java 或者 Python),另一台想专门用来做流量分发和 SSL 证书卸载,结果卡在 Nginx 配置上,不是 502 就是 504,要么就是 WebSocket 连不上。说实话,笔者当初第一次配反向代理时,也是被 proxy_pass 后面那个斜杠折腾了大半天。

这篇文章不打算堆砌官方文档里那些晦涩的指令说明,而是站在一个过来人的角度,手把手带你走一遍完整的 Nginx 反向代理配置流程。从环境准备到具体配置,再到踩坑后的排查思路,尽量把每个步骤都讲透。如果你正准备给自己的项目加一层代理,或者想把多个服务统一到一个入口,那这篇内容应该能帮你省下不少查资料的时间。

一、动手之前,先把环境和思路理清楚

💡 推荐阅读:服务器卡成PPT?别再瞎猜了,top、htop、iotop三板斧教你揪出性能真凶

反向代理的本质,是让 Nginx 站在客户端和后端服务之间,客户端只跟 Nginx 打交道,Nginx 再把请求转发给内部服务。这样做的好处很明显:隐藏真实后端、方便做负载均衡、统一管理 SSL 证书、还能顺手加一层缓存或限流。

在开始配置之前,你需要准备好以下几样东西:

  • 一台带公网 IP 的云服务器:建议选择至少 1 核 2G 起步的配置,如果流量较大,带宽和 CPU 都要相应提升。笔者一般会优先考虑主流云厂商的轻量应用服务器,性价比高,网络也稳定。
  • 一个已经解析到该服务器的域名:域名注册建议走正规平台,后续备案和解析都省心。别贪便宜用那些来路不明的免费域名,后面出问题很麻烦。
  • 后端服务已经跑起来:比如你的 Java 应用监听在 8080 端口,或者 Node.js 服务跑在 3000 端口,确保在服务器内部用 curl 127.0.0.1:端口 能正常访问。
  • Nginx 已安装:如果还没装,Ubuntu/Debian 用 apt install nginx,CentOS 用 yum install nginx 即可。

这里笔者多嘴一句,服务器安全组或防火墙一定要提前放行 80 和 443 端口,否则配置写得再对,外面也访问不进来。

二、详细实操步骤:从零写出一份可用的反向代理配置

💡 延伸阅读:WordPress 打开慢到想砸键盘?我花了两天实测 Redis 缓存和页面加速,说点大实话

1. 确认 Nginx 配置目录结构

不同系统下 Nginx 的配置路径略有差异,但主配置文件通常都在 /etc/nginx/nginx.conf。笔者习惯把每个站点的配置单独拆到 /etc/nginx/conf.d/ 或 /etc/nginx/sites-available/ 下,这样管理起来清晰,也不容易改乱主配置。

# 查看 Nginx 主配置中是否包含 conf.d 目录
grep -r "include" /etc/nginx/nginx.conf

# 通常你会看到类似这样的行:
# include /etc/nginx/conf.d/*.conf;

如果确认有包含关系,我们就可以直接在 conf.d 下新建一个配置文件,比如 myapp.conf。

2. 编写最基础的反向代理配置

假设你的后端服务跑在本机 8080 端口,域名是 api.example.com,那么一个最简配置大概长这样:

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

    location / {
        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;
    }
}

这里有几个点需要特别注意:

  • proxy_pass 后面的地址:如果你写的是 http://127.0.0.1:8080,不带路径,Nginx 会把原始请求的 URI 原样转发过去。如果你写成 http://127.0.0.1:8080/,带了一个斜杠,那 Nginx 会把 location 匹配到的部分替换掉。这个细节非常容易搞混,后面避坑清单里会再展开。
  • proxy_set_header Host $host:这行很关键。如果不加,后端服务收到的 Host 头可能是 IP 地址,导致一些基于域名判断的逻辑出错,或者重定向时跳转到错误地址。
  • X-Real-IP 和 X-Forwarded-For:这两个头用来把真实客户端 IP 传给后端。否则后端日志里看到的全是 Nginx 的 IP,排查问题时很头疼。

3. 配置 HTTPS 并强制跳转

现在基本都要求 HTTPS 了,用 Let’s Encrypt 申请证书后,可以把上面的配置升级成这样:

server {
    listen 80;
    server_name api.example.com;
    # 强制跳转到 HTTPS
    return 301 https://$host$request_uri;
}

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

    ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    location / {
        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;
    }
}

证书路径根据你实际申请的位置调整即可。如果你用的是宝塔面板或者 acme.sh,路径会不太一样,但原理相通。

4. 处理 WebSocket 和长连接

很多现代应用都依赖 WebSocket,比如实时聊天、消息推送。如果只按上面的配置,WebSocket 握手可能会失败。需要额外加几行:

location /ws/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 3600s;
}

proxy_read_timeout 建议设大一点,否则连接空闲一会儿就被断开了,用户体验很差。

5. 检查配置并平滑重载

每次改完配置,不要急着重启,先用 nginx -t 测试语法:

# 测试配置文件语法
nginx -t

# 如果输出 syntax is ok 和 test is successful,就可以重载
nginx -s reload

重载不会中断现有连接,比直接 restart 更安全。笔者习惯每次改完都跑一遍测试,确认无误再重载,避免线上服务突然挂掉。

三、避坑清单:这些坑笔者几乎都踩过

💡 深度技术指南:Docker镜像动辄几个G?你可能从第一步就写错了

下面这些问题是反向代理配置中最常见的,提前了解能省下大量排查时间。

问题现象 可能原因 解决思路
502 Bad Gateway 后端服务没启动,或端口不对 在服务器上用 curl 测试后端端口是否可访问
504 Gateway Timeout 后端处理时间过长,Nginx 默认超时太短 适当调大 proxy_read_timeout 和 proxy_connect_timeout
静态资源 404 proxy_pass 路径斜杠导致 URI 被替换 检查 proxy_pass 末尾是否有多余斜杠,必要时用 rewrite
后端获取不到真实 IP 缺少 X-Real-IP 或 X-Forwarded-For 头 补上 proxy_set_header 相关配置
WebSocket 连接失败 没有设置 Upgrade 和 Connection 头 单独为 WebSocket 路径配置 proxy_http_version 1.1

另外还有一点容易被忽略:如果你在 Nginx 前面还套了 CDN 或负载均衡,那 X-Forwarded-For 里可能会有多个 IP,后端取第一个还是最后一个,要根据实际架构来定。笔者一般会在后端框架里配置信任的代理层数,避免 IP 伪造问题。

四、总结:反向代理不难,难的是细节

回过头来看,Nginx 反向代理的核心配置其实就那么几行,真正花时间的是理解每个指令背后的行为,以及遇到问题时的排查思路。笔者建议你在正式上线前,先在测试环境把各种场景都跑一遍,包括 HTTPS 跳转、WebSocket、大文件上传等,确认没问题再切到生产。

如果你还在选服务器阶段,记得优先考虑网络质量好、支持快照备份的云厂商,后期扩容和迁移都会轻松很多。域名也尽量选正规注册商,别为了省几块钱给自己埋雷。配置过程中遇到报错,多看看 Nginx 的 error.log,大部分答案都在里面。

希望这份笔记能帮你顺利把反向代理跑起来。如果后面遇到什么奇怪的问题,欢迎一起交流,笔者也会继续分享更多实战中总结出来的经验。

相关技术专题与延伸阅读

滚动至顶部