很多站长在刚接触服务器运维时,都会遇到这样一个场景:明明买了两台云服务器,一台跑后端应用(比如 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,大部分答案都在里面。
希望这份笔记能帮你顺利把反向代理跑起来。如果后面遇到什么奇怪的问题,欢迎一起交流,笔者也会继续分享更多实战中总结出来的经验。