Nginx转发配置实战：从反向代理到常见报错排查

先交代一下我自己的情况我手里的服务器上有不少业务系统有的跑在Tomcat上有的挂在Docker容器里还有一个是同事自己用Node.js起的服务端口五花八门。要让人记住每个端口号根本不现实所以我基本都用nginx转发来统一入口让所有请求都先打到nginx再由它转发到各自后端的“可以正常访问的网站”。这篇文章不会讲什么花哨的负载均衡、灰度发布就聚焦在最实用的场景nginx转发指向一个可以正常访问的网站。我会把从安装、配置到排错的完整链路都过一遍尤其会讲清楚那些搜索引擎里不太好找到的细节坑。不管你是刚开始接触nginx还是已经配过几次但总被各种报错折磨这篇文章应该都能给你一些参考。1. 转发方案选型先想清楚你要哪种“转发”1.1 反向代理转发最常用的那种nginx转发核心其实是反向代理。我们先搞清楚概念正向代理是替客户端去访问服务器比如你通过代理访问外网反向代理则是替服务器接收请求客户端只知道nginx的地址并不知道背后真实服务器的位置。举个生活化的例子公司前台就是反向代理。外部访客不需要知道你要找的张三坐在哪个工位直接跟前台说“我找张三”前台帮你转达。nginx就扮演这个前台角色外部请求只需要访问nginxnginx再根据配置把请求转给真正干活的网站。为什么这种方案最常用因为它对客户端完全透明。用户访问的还是原来的域名或IP浏览器地址栏不会变但实际响应内容来自后端那个“可以正常访问的网站”。这就带来几个实际好处可以隐藏后端真实地址、可以在nginx层统一做缓存和访问控制、还可以随时切换后端而不影响用户。1.2 转发和重定向是两码事很多人会混淆“转发”和“重定向”。转发是nginx帮客户端把请求拿过来自己作为中间人去访问后端再把结果返回给客户端全程客户端和后端没有直接对话。重定向则是nginx告诉客户端“你要找的东西在另一个地址”客户端浏览器会自动跳转到新地址。举个例子如果你配置了return 302 http://example.com/用户访问你的域名时浏览器会直接跳转到example.com地址栏会变。这在很多场景下并不适用尤其是你希望用户无感知地访问后端服务时。所以要实现真正的“转发”效果必须用proxy_pass而不是return或rewrite。我把三者的核心差异整理成一个对照表方便你选型实现方式核心指令用户地址栏变化适用场景反向代理转发proxy_pass不变透传请求隐藏后端统一入口HTTP重定向return 302会变临时搬家、强制跳转HTTPS、旧链接迁移URL重写rewrite通常不变但会改变请求URI美化URL、调整路径结构一句话总结如果只是想让请求到达那个“可以正常访问的网站”并把内容原样返回那就用proxy_pass。这是后续所有配置的基础。2. 先把nginx装好不同环境下的安装与验证2.1 Linux系统安装三条路可以走在国内服务器市场CentOS、Ubuntu、Debian是主力。nginx安装方式大致分三类包管理器安装、官方源安装、源码编译安装。包管理器安装最省事。Ubuntu/Debian上执行sudo apt update sudo apt install nginx -yCentOS/RHEL/AlmaLinux上执行sudo yum install nginx -y不过有些系统默认源里的nginx版本偏老这就得用官方源。比如Ubuntu可以添加nginx官方仓库sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring curl -fsSL https://nginx.org/keys/nginx_signing.key | sudo gpg --dearmor -o /usr/share/keyrings/nginx-archive-keyring.gpg echo deb [signed-by/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/ubuntu $(lsb_release -cs) nginx | sudo tee /etc/apt/sources.list.d/nginx.list sudo apt update sudo apt install nginx -y源码编译安装适合有特殊需求的场景比如需要编译第三方模块。基本流程是wget http://nginx.org/download/nginx-1.24.0.tar.gz tar -zxvf nginx-1.24.0.tar.gz cd nginx-1.24.0 ./configure --prefix/usr/local/nginx --with-http_ssl_module --with-stream make make install如果是arm架构且纯内网环境热搜词里提到的“aarch64离线安装nginx”也很常见。思路是找一台能联网的同架构机器把nginx的rpm包或deb包下载下来拷贝到内网机器上用rpm -ivh或dpkg -i安装。如果连包都拿不进去就只能在能联网的机器上编译好再把整个安装目录打包拷进内网。2.2 用Docker或Windows快速跑起来如果你只是测试或者不想污染宿主机环境Docker是很好的选择docker run -d --name nginx-proxy -p 80:80 -v /path/to/conf:/etc/nginx/conf.d nginx:alpine把配置文件目录挂载进去改完配置直接docker exec nginx-proxy nginx -s reload就生效。Windows环境很多人以为nginx用不了其实官方一直有Windows版本。去nginx.org下载Windows压缩包解压后目录里直接start nginx就能启动。Windows版的坑在于没有优雅的reload机制改动配置后需要nginx -s reload或者干脆nginx -s stop再start nginx重启。2.3 验证nginx是否真的跑起来了安装完成后别急着写配置先验证nginx本身工作正常nginx -t这条命令会检查配置文件语法输出syntax is ok和test is successful就说明基础没问题。然后启动服务sudo systemctl start nginx sudo systemctl enable nginx在浏览器访问服务器IP看到Welcome to nginx!页面就说明安装成功。这一步花不了两分钟却能把很多后续问题提前排除掉。3. 核心配置把请求转发到一个可以正常访问的网站3.1 最简配置长这样逐行拆解配一个最基础的转发其实只需要几行配置。假设你本机8080端口跑着一个能正常访问的网站你想让用户直接访问80端口就能看到它server { listen 80; server_name demo.example.com; location / { proxy_pass http://127.0.0.1:8080; } }拆开看每一部分的作用。listen 80是让nginx监听80端口server_name声明这个配置块匹配哪个域名多个域名用空格隔开location /匹配所有以根路径开头的请求然后proxy_pass把请求转给指定后端。这里必须说清楚一个很多人忽略的前提proxy_pass后面那个地址必须是“可以正常访问”的。这意味着nginx这台机器能够通过网络访问到那个地址端口要通、服务要正常响应。很多人配完发现502排查半天才发现后端服务根本没启动或者服务器防火墙把8080端口拦了。3.2 让后端网站“认识”你本地端口和转发目标拆分实际项目中nginx和后端往往不在同一台机器上。比如nginx在10.0.0.10后端网站跑在10.0.0.20的3000端口那配置就是server { listen 80; server_name demo.example.com; location / { proxy_pass http://10.0.0.20:3000; } }但问题来了后端服务如果做了域名校验或者需要知道客户端真实来源此时它看到的请求来自nginx而不是真实用户。如果不加透传参数后端IP全是nginx服务器的IP。所以完整配置需要带上这几个headerserver { listen 80; server_name demo.example.com; location / { proxy_pass http://10.0.0.20:3000; 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; } }Host一定要带上很多Web服务会根据Host头来生成绝对链接或做虚拟主机路由。X-Real-IP和X-Forwarded-For是让后端知道真实访问者的IP否则后端日志里的IP全是nginx的IP排查问题会非常难。X-Forwarded-Proto则在后端需要判断请求是http还是https时特别重要不然nginx用https接收请求、向后端转发时用http后端以为访问者全程都是http生成的回跳链接就会出错。3.3 转发相关参数速查与调优proxy_pass只是入口真正决定转发稳定性的是一堆proxy_*参数。很多线上问题比如“页面打开要等半天才报错”“大文件下载总是中断”都是这些参数没调好。参数默认值作用与建议proxy_connect_timeout60s与后端建立连接的超时时间内网转发建议5-10s不用太长proxy_read_timeout60s等待后端响应的时间。后端处理慢逻辑时建议调大到120s或更长proxy_send_timeout60snginx向后端发送请求的超时时间一般保持默认即可proxy_bufferingon是否缓冲后端响应。需要实时输出如SSE时应设为offproxy_buffer_size4k/8k响应头缓冲区大小后端返回响应头过大时可调大proxy_set_header Connection空长连接场景需要特殊处理后面WebSocket部分细说从实际经验看80%的转发问题集中在proxy_connect_timeout和proxy_read_timeout上。连接超时多半是网络不通或后端没监听读超时则是后端处理太慢或者后端本身有长时间不返回数据的逻辑。3.4 location路径与proxy_pass末尾斜杠的坑还有一个高频坑区location和proxy_pass的路径匹配规则。直接看两个例子location /api/ { proxy_pass http://127.0.0.1:8080/; }当请求是/api/user时nginx会把/api/替换成/转发给后端的路径变成/user。这里的斜杠起到了“重写路径”的作用。再看这个location /api/ { proxy_pass http://127.0.0.1:8080; }注意proxy_pass后面没有斜杠此时nginx不会替换/api/前缀转发给后端的路径还是/api/user。这个区别如果没搞清楚配置出来的转发行为会跟预期差很远。专门说这个是因为很多博客甚至网上教程都在这里含糊带过。实战中我踩过最狠的一次坑是后端接口路径其实是/inner/user但前端请求路径是/api/user我照抄了一个带斜杠的配置结果所有接口都404。后来改成不带斜杠的proxy_pass http://127.0.0.1:8080再用rewrite处理前缀才恢复正常。4. 进阶玩法https、负载均衡、长连接与纯端口转发4.1 给转发加上https自签名证书的交互式配置很多场景下转发链路需要加密。尤其是后端网站本身是https的而nginx用http去连接后端这中间就是明文传输。解决方法是拿自签名证书配到nginx上让nginx对客户端提供https服务。生成自签名证书的命令mkdir -p /etc/nginx/ssl cd /etc/nginx/ssl openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout server.key -out server.crt执行过程中会交互式地询问国家、省份、组织等信息直接一路回车跳过也行关键是Common Name那一项要填你的域名或IP。然后配置server { listen 443 ssl; server_name demo.example.com; ssl_certificate /etc/nginx/ssl/server.crt; ssl_certificate_key /etc/nginx/ssl/server.key; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; } }配置完后访问https://demo.example.com浏览器会提示证书不受信任因为这是自签名的。个人测试或内网使用可以直接忽略警告如果对外提供服务还是建议用Lets Encrypt之类的正规证书。4.2 upstream负载均衡和多节点转发如果那个“可以正常访问的网站”不止一台而是多台实例组成集群用upstream定义一组后端再让proxy_pass指向这组后端upstream backend_servers { server 10.0.0.21:8080 weight3; server 10.0.0.22:8080 weight1; server 10.0.0.23:8080 backup; } server { listen 80; server_name demo.example.com; location / { proxy_pass http://backend_servers; proxy_set_header Host $host; } }weight控制权重3比1意味着前者分担大约三倍流量backup标记备用节点只有其他节点都挂了才会启用。这是最简单的负载均衡无需额外组件。但这里有一个关键的常识upstream里的server如果不做健康检查nginx转发时发现某台后端挂了只会把请求转到下一个节点不会主动把故障节点剔除。如果多台后端一起挂用户就会看到502。所以生产环境建议加上健康检查模块或者用nginx plus的动态解析能力再或者使用外部健康检查脚本定期检测并动态调整upstream配置。4.3 转发WebSocket和长连接场景WebSocket连接和普通http不同它需要一个从http升级到WebSocket协议的握手过程。如果直接用普通的proxy_pass握手会失败前端控制台会报WebSocket connection failed。关键在于设置Upgrade头部location /ws/ { proxy_pass http://127.0.0.1:8080/ws/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; }proxy_http_version设为1.1是因为http/1.0不支持Upgrade头。Connection upgrade告诉后端这次连接要升级成WebSocket协议。这两行缺一不可网上不少人只加了Upgrade没加Connection照样连不上。顺便提一句流媒体转发也是类似逻辑。RTSP流如果要通过nginx转发通常得用nginx的rtmp模块或者stream模块普通的http代理配置是搞不定的。4.4 纯端口转发不想用域名怎么办有些场景你手里只有一个IP没有域名但想把外网的某个端口转发到内网某台机器的某个端口。这时候不用listen 80 server_name那种http配置而是用nginx的stream模块stream { server { listen 3306; proxy_pass 10.0.0.20:3306; } }上面这段配置会把nginx的3306端口流量原样转发给内网的3306端口适合MySQL等非HTTP协议。配合刚才说的反向代理nginx就能同时处理四层转发和七层转发。注意stream模块在源码编译时需要--with-stream参数否则配置了也不会生效。5. 常见问题与排查实录5.1 502 Bad Gateway后端访问不通502在所有转发问题里出现频率最高。原因基本可以归纳为三类后端服务没启动、nginx无法连接到后端地址、后端响应太慢被nginx判定为无响应。排查顺序很关键。第一先确认后端服务本身能访问直接在nginx服务器上执行curl http://127.0.0.1:8080/如果这里都失败问题在nginx配置和后端之间。第二看nginx错误日志默认在/var/log/nginx/error.logtail -f /var/log/nginx/error.log看到类似connect() failed (111: Connection refused)就说明后端端口没监听看到Connection timed out则说明网络不通或防火墙拦截。按这两个方向去查基本能定位。5.2 504 Gateway Timeout后端处理不过来504表示nginx把请求转发给了后端但等太久没等到响应。现实中常见于后端接口本身要执行很久的SQL或调用外部API。处理办法有两种一是上调proxy_read_timeout比如改成300s二是优化后端逻辑让接口尽快返回。很多时候这两种要同时做。我遇到过一台上线半年的服务某天突然大量504看了后端日志发现是有用户导出了超大报表。后来不仅把proxy_read_timeout调大还把导出改成了异步任务问题才算根治。5.3 转发后页面样式丢失、接口404这是转发配置中非常典型的一类问题。页面能打开但CSS、JS、图片全部加载失败或者接口路径不对。根因基本都是路径问题。它分两种情况如果页面里的静态资源路径是绝对路径比如/static/css/style.css而这些资源只在后端8000端口的/static/目录下那前端页面被转发后浏览器请求的却是nginx的/static/css/style.cssnginx没有这个目录就返回404。解决办法有两个思路一是给nginx增加静态资源的location直接代理到后端location /static/ { proxy_pass http://127.0.0.1:8080/static/; }二是给页面里所有资源路径加上前缀让它们经过nginx时也能匹配到正确的location。第一种改法简单直接推荐优先尝试。5.4 reload失败或配置不生效改了配置执行nginx -s reload结果提示nginx: [emerg] unknown directive这种情况最常发生在配置文件语法错误。解决办法永远先跑一遍nginx -t检查。还有一个容易被忽略的情况你改了/etc/nginx/conf.d/下的文件但nginx主配置里根本没有include /etc/nginx/conf.d/*.conf;这行自然不生效。另外要留意配置文件的行尾在Windows上编辑过的文件如果行尾是CRLFnginx会报unknown directive。用dos2unix工具转换一下就好。5.5 页面反复跳转或无限重定向循环最后说一个藏得比较深的坑。如果后端网站本身是https的而nginx用http转发后端生成的重定向链接就会是http://...浏览器访问后又跳回https来回反复最终报“重定向次数过多”。解决办法是显式传递X-Forwarded-Protoproxy_set_header X-Forwarded-Proto $scheme;同时确认后端框架能识别这个header并据此生成正确的重定向协议。比如Spring Boot需要设置server.forward-headers-strategyframeworkNginx后面挂的Web应用各有各的配置方法但核心都是让后端知道真实协议。5.6 问题速查表把上面这些整理成一张速查表方便日常排错现象可能原因排查手段解决方案502 Bad Gateway后端未启动/端口不通/防火墙拦截curl直接访问后端查看error.log启动后端、放通防火墙504 Gateway Timeout后端响应超时看后端访问日志确认哪个接口慢调大proxy_read_timeout或优化后端404 Not Foundlocation路径匹配错误/静态资源缺失对比实际请求路径和后端真实路径调整location或补充静态资源配置样式丢失静态资源路径不匹配浏览器F12看加载失败的URL增加static的location代理重定向循环X-Forwarded-Proto未传递/后端生成错误链接浏览器开发者工具看响应头Location设置X-Forwarded-Proto并调整后端配置reload失败配置语法错误/extra文件未包含nginx -t逐行检查报错修复语法正确写法这套排查方法我用了很久几乎每次都能在十分钟内定位问题。秘诀就是别瞎猜一步一个脚印地按链路排查先看后端正不正常再看nginx日志最后分析配置细节。顺序反了容易把自己绕进去。结尾一些个人体会做运维和开发这些年nginx转发是我用得最频繁的功能之一。每次新上线一个内部系统我第一件事就是把它的入口收敛到nginx上统一域名、统一证书、统一日志。哪怕有些系统刚开始只是临时测试我也会先把nginx转发配好因为后期再补往往要面对各种路径和跳转问题反而更费劲。最后分享一个小习惯任何配置改动前先把原来的配置复制一份备份然后nginx -t检查再nginx -s reload。这条流程花不了十秒钟但能避免大量手滑导致的线上事故。nginx转发本身不复杂复杂的是它背后那些关于路径、协议、超时和网络中来回的细节把这些细节吃透你就能把那个“可以正常访问的网站”稳稳地藏在nginx后面让用户永远只看到统一的入口。