1. 反向代理到底解决了什么问题三个最典型的业务场景很多朋友一开始接触Nginx反向代理配置时容易把它理解成端口转发我有一个服务跑在8080端口用Nginx把80端口的请求转发过去就完事了。这个理解没错但格局小了。反向代理真正解决的是服务架构层面的三个刚需。第一个场景是统一入口。假设你手上有三个服务前端静态页面占一个端口、后端API占一个端口、内网管理系统再占一个端口全部直接对外暴露。先不说端口号好不好记的问题——这等于把内部拓扑直接公开给所有人看安全上就很被动。用Nginx做反向代理之后所有流量都先打到80端口Nginx根据域名或URL路径把请求路由到对应的内部服务。对外只有一个入口内部结构被完全隐藏同时还能在入口层做访问控制、限流、日志审计。我见过不少团队把服务直接裸奔在公网端口上被扫描器盯上之后才开始补反向代理每次都心力交瘁。第二个场景是负载均衡。单台服务扛不住流量时方案是把请求分散到多台后端服务器上。Nginx作为反向代理的核心优势就在这里——它能用几行配置把请求按权重、按IP哈希、按最少连接数等策略分发给上游服务器组而且后端服务器宕机时还能自动摘除。这个能力在架构演进中几乎是从单机走向集群的第一道坎也是Nginx能常青十几年的根本原因。第三个场景是SSL证书集中管理。在没有反向代理之前每台业务服务器都要单独配置证书、单独处理加密证书更新时那叫一个痛苦。把Nginx放在最前端之后HTTPS加密在反向代理这一层统一终结内部服务之间继续走HTTP明文通讯不增加业务代码的复杂度。证书换一次只动Nginx配置背后的机器完全无感。顺带说清楚一个概念正向代理代理的是客户端——我想访问某个网站先请求代理服务器由它帮我取回内容反向代理代理的是服务端——用户表面上只跟代理打交道根本不知道真正的响应来自哪台机器。理解这个区别之后再看配置很多参数就对了。2. 环境准备Linux和Windows两种常见路径的注意事项2.1 Linux下安装选对安装方式比版本更新更重要生产环境我强烈建议用系统包管理器安装。Ubuntu和Debian用aptCentOS和Rocky Linux用yum或dnf一条命令就能装完而且会注册成系统服务开机自启、日志轮转、目录规范都替你安排好了。# Ubuntu / Debian sudo apt update sudo apt install nginx -y # CentOS / Rocky Linux sudo yum install nginx -y装完后的标准检查动作有三个看一眼服务状态、确认监听端口、查看版本号。systemctl status nginx ss -lntp | grep :80 nginx -v这里有一个容易忽略的坑apt安装的Nginx默认站点配置文件在/etc/nginx/sites-available/和/etc/nginx/sites-enabled/而yum安装的版本配置文件直接摆在/etc/nginx/conf.d/下。很多人从CentOS切到Ubuntu后找不到自己的子配置文件翻半天才明白是目录结构不同。如果你需要定制编译参数比如要加特定的第三方模块那就得走源码编译这条路。先安装依赖再下载源码然后configure、make、install三步走# 依赖安装以Ubuntu为例 sudo apt install build-essential libpcre3-dev libssl-dev zlib1g-dev -y # 下载源码并编译 wget http://nginx.org/download/nginx-1.27.0.tar.gz tar -zxf nginx-1.27.0.tar.gz cd nginx-1.27.0 ./configure --prefix/usr/local/nginx --with-http_ssl_module --with-stream make sudo make install编译安装的Nginx是另一个故事的开始其实大多数场景用系统自带的版本就够了——默认版本往往包含了ssl模块和gzip模块日常反代完全够用。真正需要编译的是那些要加载第三方模块的场景后文讲平滑升级时会专门说。2.2 Windows下安装调试方便但别当成生产方案Windows装Nginx非常简单去官网下载Windows版本的zip压缩包解压到合适目录双击nginx.exe就启动了。没有安装器、不写注册表、不动系统服务一切都在那个目录里。# 进入解压后的目录执行 start nginx # 启动 nginx.exe -t # 检查配置文件语法 nginx.exe -s reload # 平滑重载配置 nginx.exe -s stop # 停止服务Windows版的坑在于进程管理不够透明经常出现关不干净的问题。你在任务管理器里能看到的进程名称都叫nginx.exe停掉一个还留一个——主进程和worker进程混在一起。我的建议是Windows环境只用来本地开发和功能验证生产环境还是老老实实放Linux上。还有一个细节Windows下配置文件的路径写法要注意server块里的静态资源路径如果用了Linux风格会直接404。2.3 安装完成后的验证清单不管哪种安装方式装完之后先做这三步用浏览器或curl访问服务器IP能看到Nginx的默认欢迎页。看不到的话先查防火墙和安全组放行了没有。执行nginx -t确认配置语法没问题。这一步应该养成肌肉记忆每次改完配置都先过一遍。打开/var/log/nginx/error.logLinux看看有没有异常warning。我见过很多部署完成后服务异常的情况最后都能从error log里找到真正的导火索。3. 第一份真实可用的反向代理配置拆开每个指令的用途3.1 最小配置长什么样新建一个配置文件比如/etc/nginx/conf.d/reverse-proxy.conf写入最基础的反向代理配置server { listen 80; server_name 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; } }这份配置的作用是把所有访问example.com的HTTP请求原封不动交给本机8080端口上的后端应用处理。就这么几行已经涵盖了反向代理最核心的五个指令。listen声明监听端口server_name是虚拟主机匹配的域名这两个合在一起确定了什么样的请求进这个server块。location /表示匹配所有以/开头的URL路径。proxy_pass是最关键的一行它告诉Nginx把请求转发到哪里。后面三个proxy_set_header的作用很多人会忽略但实际影响很大——后面专门讲。3.2 proxy_pass的两副面孔带不带URI是两种行为这是反向代理配置里最坑的一个细节没有之一。同一个指令写法差一个斜杠行为天差地别。# 第一种不带URI保留完整的原始URL location /api/ { proxy_pass http://127.0.0.1:8080; } # 第二种带URI把匹配部分替换成新地址 location /api/ { proxy_pass http://127.0.0.1:8080/; }第一种写法下请求/api/login会被转发成上游的/api/login路径原样传递。第二种写法下location匹配到的/api/部分会被替换成/于是请求/api/login到达上游时变成了/login。迁移服务或者把老接口路径做重映射时这个特性用得好是神器用错了就是生产事故。我的建议是平时配置就按不带URI的方式写保持行为直觉可预期真要改路径时再显式加URI并且用nginx -t加上访问日志双重确认。3.3 请求头处理为什么必须设置Host和相关头默认情况下Nginx转发请求时会带着它从客户端收到的原始请求头。但Host头有特殊情况——如果你不做任何设置转发后上游服务器收到的Host还是客户端原始请求里的那个域名。这本身不算错但反向代理场景下通常你希望统一控制。反代场景中我几乎总是加这三行proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;$host取的是server_name匹配到的域名这样多域名共用一个反代时上游能正确分辨请求来自哪个站点。X-Real-IP直接透传真实的客户端IP。X-Forwarded-For负责在链路中追加IP信息——如果前面还有一层CDN或负载均衡$proxy_add_x_forwarded_for会自动保留已有的X-Forwarded-For并追加当前连接来源IP不会覆盖历史IP链这是排查真实用户来源时的关键依据。后端Java应用拿getHeader(X-Real-IP)就能拿到真实IP这在做用户行为分析、封禁恶意IP时非常实用不然所有请求的IP都是Nginx服务器的IP等于瞎了。3.4 配置完成后的三件事写完配置之后顺序执行下面三步每步都有意义nginx -t # 1. 语法检查有错会指出具体文件行号 nginx -s reload # 2. 平滑重载不断开已有连接 curl -I http://example.com/test # 3. 用curl验证请求头是否符合预期nginx -s reload的原理要稍微讲一下它不是重启而是向master进程发送信号master会重新读取配置文件并创建新的worker进程之后慢慢把旧worker进程里的连接处理完再回收。这意味着线上业务不会因为配置变更而中断哪怕一秒。我见过有人图省事用restart代替reload直接把所有连接掐断这在低峰期可能感受不明显高峰期等于主动制造一次小规模故障。4. 从单服务到多服务location匹配规则与多域名配置实战4.1 location匹配优先级一张表讲清楚单个server里复杂路由往往要多个location块配合。很多人只写过location /就觉得自己会了业务一复杂就抓瞎。Nginx的location匹配有一套严格优先级从上往下的顺序是写法含义匹配优先级location /path精确匹配最高location ^~ /path普通前缀匹配匹配后不再检查正则次高location ~ /path或location ~* /path正则匹配~*忽略大小写中location /path普通前缀匹配取最长匹配项低location /兜底匹配最低规则看似复杂记忆口诀就一句精确匹配优先其次带^~的前缀再其次正则这些都没命中才看普通前缀和兜底。实际开发中最容易出问题的点是写了正则location之后原本能命中的普通前缀突然失效了因为正则的优先级高于普通前缀。遇到这种情况要么改成正则也没问题要么在普通前缀上明确加^~让它不再下探到正则。4.2 一个典型的多路由反代配置拿一个常见的前后端分离项目举例前端是Vue打包出来的静态文件后端是Java服务还有一个图片上传服务独立部署。配置文件可以这么写server { listen 80; server_name example.com; # 静态资源直接由Nginx处理不往后端转发 location /static/ { alias /var/www/example/static/; expires 7d; } # API请求统一转发到Java后端 location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # 图片服务单独转发到另一台机器 location /images/ { proxy_pass http://192.168.1.20:8090; } # 剩下的路径兜底转发给前端静态入口 location / { root /var/www/example/dist; try_files $uri $uri/ /index.html; } }这个配置里静态资源不经过后端Java处理减少了后端压力/api/独立走Java接口图片服务则甩给内网另一台专用服务器。try_files $uri $uri/ /index.html是前端路由的经典写法如果请求的路径找不到对应文件就一律返回index.html让前端路由自己接管。这个思路能直接照抄进大部分前后端分离项目里。4.3 主域名与二级域名的配置技巧一个Nginx实例同时代理多个站点靠的是多个server块。这里注意每个server_name各不相同Nginx收到请求后按域名选块处理。比如主域名和二级域名走不同的后端# 主域名 server { listen 80; server_name example.com www.example.com; location / { proxy_pass http://127.0.0.1:3000; } } # 二级域名独立服务 server { listen 80; server_name blog.example.com; location / { proxy_pass http://127.0.0.1:4000; } } # 未匹配任何域名的请求直接拒绝 server { listen 80 default_server; server_name _; return 444; }第三个server块是很多人没意识到的安全门槛。不加它的话任何直接访问服务器IP的请求都可能被路由到第一个server块造成配置泄露或非预期暴露。default_server把所有没匹配上的流量接住return 444直接断开连接不带任何响应。这个习惯能让Nginx在公网上干净很多。多域名还有一个高级玩法是泛解析——server_name *.example.com可以匹配所有子域名在证书是通配符证书时配合得非常顺。但如果不同子域名要转发到不同后端就老老实实写多个server块清晰可控别为了少写点配置搞一堆if判断维护成本会直线上升。5. 给反向代理加SSL证书从HTTP平滑切到HTTPS5.1 证书文件从哪里来、放在哪里生产环境的证书来源有两种主流方式一是云厂商申请的免费证书二是Lets Encrypt的免费证书。证书拿到手通常是一堆文件其中最关键的是证书文件.crt或.pem和私钥文件.key还有部分场景需要的证书链文件.ca-bundle。我习惯把证书统一放在/etc/nginx/ssl/目录下按域名建子目录sudo mkdir -p /etc/nginx/ssl/example.com sudo cp example.com.crt /etc/nginx/ssl/example.com/ sudo cp example.com.key /etc/nginx/ssl/example.com/ sudo chmod 600 /etc/nginx/ssl/example.com/example.com.key最后一行chmod 600非常关键。Nginx的master进程以root权限启动之后会降权运行worker进程证书私钥文件如果权限过于开放Nginx会在重载配置时直接报错拒绝启动。我遇到过好几次明明证书能打开、配置看着也对reload就失败的情况最后都是权限问题。5.2 配置HTTPS监听一份完整的SSL反代配置server { listen 443 ssl; server_name example.com; ssl_certificate /etc/nginx/ssl/example.com/example.com.crt; ssl_certificate_key /etc/nginx/ssl/example.com/example.com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; 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; } }几个参数值得逐一说明。ssl_protocols现在主流只保留TLSv1.2和TLSv1.3TLSv1.0和TLSv1.1已经进了安全黑洞不建议再开。ssl_session_cache shared:SSL:10m允许SSL会话在worker进程间共享缓存10MB大致能缓存几万个会话对性能提升很直观尤其是大量短连接场景。X-Forwarded-Proto $scheme这个头在反向代理后面还有一个后端框架时特别重要——后端要判断请求是HTTP还是HTTPS以生成正确的重定向和资源链接时它就是唯一线索。5.3 HTTP自动跳转HTTPSreturn 301是首选通常你需要把老用户的HTTP请求自动带到HTTPS避免他们访问了一个毫无响应的80端口。实现方式有两种# 方式一推荐简单明确 server { listen 80; server_name example.com; return 301 https://$host$request_uri; } # 方式二通过rewrite实现效果类似但显得绕 server { listen 80; server_name example.com; rewrite ^(.*)$ https://$host$1 permanent; }方式一里的return 301比方式二直观得多而且不涉及正则匹配性能更好。有人可能关心301会不会影响SEO这个属于预期行为——HTTP跳HTTPS本来就该用301搜索引擎会把权重平滑迁移过去。还有一个细节$host$request_uri保留了原始域名和完整请求路径这样用户从http://example.com/article?id1跳过去之后落地地址是https://example.com/article?id1不会丢失参数。5.4 证书到期前的一个提醒免费证书有效期通常只有3个月一定要设置到期提醒。我踩过一次证书过期的亏——用户访问直接提示不安全连接业务受损不说排查还花了半天。推荐用crontab配合curl或openssl做定期检查# 每月1号检查证书剩余天数 0 0 1 * * /usr/bin/openssl s_client -connect example.com:443 -servername example.com /dev/null 2/dev/null | openssl x509 -noout -enddate把输出重定向到一个监控脚本里有效期少于30天就告警彻底告别证书怎么又过期了的尴尬。6. 平滑升级与常用运维操作别再用停服重启了6.1 reload、restart、stop的区别很多人命令没搞清就上来操作后果很不愉快。三者的本质区别nginx -s reload平滑重载配置不中断现有连接新配置对新连接生效。nginx -s restart先停再启如果你是通过start nginx启动的restart就是stop加start所有连接全部断开生产环境禁用。nginx -s stop立即停止快但是暴力正在处理的请求会被直接掐断非维护窗口不要用。reload看似简单背后Nginx内部其实做了一整套优雅的交接master进程解析新配置成功就fork新worker旧worker处理完手上所有连接后自动退出。如果新配置有语法错误reload会失败但旧进程照常运行——这也是为什么我们反复强调先nginx -t再reload的原因等于给操作上了一道双保险。另外注意如果你改了配置文件但忘了reloadNginx不会自动感知配置变更这点跟很多动态加载的应用不一样别以为改了文件就生效了。6.2 平滑升级Nginx版本的完整流程线上Nginx需要升级版本时最稳妥的方案是利用信号机制做无缝迁移不用停服。步骤记录在这里属于运维必背技能# 1. 先看当前版本和编译参数 nginx -V # 2. 下载新版本源码编译参数尽量保持和原来一致 wget http://nginx.org/download/nginx-1.26.0.tar.gz tar -zxf nginx-1.26.0.tar.gz cd nginx-1.26.0 ./configure --prefix/usr/local/nginx --with-http_ssl_module make # 3. 备份旧版可执行文件 mv /usr/local/nginx/sbin/nginx /usr/local/nginx/sbin/nginx.old # 4. 替换为新编译出的二进制 cp objs/nginx /usr/local/nginx/sbin/nginx # 5. 向master进程发送USR2信号让它启动新master和新的worker进程 kill -USR2 cat /usr/local/nginx/logs/nginx.pid # 6. 发送WINCH信号让旧master逐渐停掉旧的worker进程 kill -WINCH cat /usr/local/nginx/logs/nginx.pid.oldbin整个过程不需要执行nginx -s stop客户端完全无感知。升级完成后把新进程测试稳定再考虑清理旧二进制。这个流程在任何生产环境都能直接套用也建议在测试环境完整演练一遍再去线上操作毕竟信号量操作一旦弄错进程号后果是不可逆的。6.3 日常运维的常用命令清单整理一份我平时最常用的Nginx运维命令按使用频率排序nginx -t # 检查配置语法改完必跑 nginx -s reload # 平滑重载配置 nginx -s quit # 优雅退出处理完所有请求再停 systemctl status nginx # 查看服务状态 systemctl enable nginx # 设置开机自启 tail -f /var/log/nginx/access.log # 实时查看访问日志 tail -f /var/log/nginx/error.log # 实时查看错误日志日志这块值得多说几句。我调试反向代理问题时没有一次是离开日志能定位的。上游服务报502或504时error.log里通常会留下connect() failed或upstream timed out这样的关键线索顺藤摸瓜比瞎猜配置高效得多。7. 高频故障排查502、504、404出现的真正原因7.1 502 Bad Gateway连不上后端502是全流程中最常见的问题含义是Nginx向上游转发请求时连接失败了。触发原因大概三种后端服务根本没启动——先确认Java、Node或PHP的进程活着。端口写错——proxy_pass里写的端口和后端实际监听端口不一致。防火墙拦了——Nginx和后端不在同一台机时需要确认后端机器的防火墙放行对应端口。排查顺序建议是先看后端进程再核对配置文件和端口最后telnet一下端口连通性。ps aux | grep java nginx -t curl -v http://127.0.0.1:8080/health7.2 504 Gateway Timeout后端是慢不是挂504的含义完全不同它表示Nginx成功连接上了后端但等待响应的时间超过了阈值。默认超时时间是60秒有些慢接口本来就超了需要显式调大location /api/ { proxy_pass http://127.0.0.1:8080; proxy_connect_timeout 10s; proxy_read_timeout 120s; }proxy_connect_timeout控制建立连接的超时proxy_read_timeout控制等待响应正文的超时。写接口尤其要注意把proxy_read_timeout调大否则用户上传大文件或者后端处理耗时较长时Nginx不等后端返回就直接回了504。真实案例有一次一个报表导出接口需要90秒才能响应默认60秒超时用户反复报错调完超时参数之后问题直接消失。7.3 404 Not Found多半是路径改写逻辑错了反代场景导致404的最常见原因就是前文说的proxy_pass带URI引起的路径改写。举个例子后端接口实际路径是/user/info你的location匹配的是/api/如果proxy_pass带了/请求就变成了/info后端自然找不到路由。排查方法很简单看后端的访问日志对比收到的URL和预期URL的差异。如果后端日志显示缺了某一段路径基本就是proxy_pass的URI行为在作怪调整location匹配范围或去掉proxy_pass里的URI即可。7.4 一个综合排障思路做减法我总结了一套排障顺序可以当成条件反射来练先nginx -t排除配置语法问题再看error.log拿到第一手错误信息然后确认上游服务健康最后才怀疑Nginx配置本身逻辑。这个顺序在绝大多数场景都能快速收敛问题范围。反向代理配置出错不丢人谁都是从几个常见错误里摸爬滚打过来的关键是掌握一套可复用的排查路径下次遇到同样问题十分钟内就能搞定。实际执行时还有一个技巧临时把后端服务直接暴露到另一个端口比如直接访问8080绕过Nginx直接访问后端看是否正常。这一步能把后端问题和Nginx问题一刀切开省去大量猜测时间。验证完再改回原状即可。我自己写反向代理配置这多年最大的体会是不要把Nginx当黑盒它每个指令都遵循一套很朴素的逻辑——匹配、转发、改写、返回。把这四个环节拆开理解再复杂的配置也能拆成一个个能解释、能验证的小块。希望这份配置经验能帮你少走几步我之前走过的弯路。
1. 反向代理到底解决了什么问题三个最典型的业务场景很多朋友一开始接触Nginx反向代理配置时容易把它理解成端口转发我有一个服务跑在8080端口用Nginx把80端口的请求转发过去就完事了。这个理解没错但格局小了。反向代理真正解决的是服务架构层面的三个刚需。第一个场景是统一入口。假设你手上有三个服务前端静态页面占一个端口、后端API占一个端口、内网管理系统再占一个端口全部直接对外暴露。先不说端口号好不好记的问题——这等于把内部拓扑直接公开给所有人看安全上就很被动。用Nginx做反向代理之后所有流量都先打到80端口Nginx根据域名或URL路径把请求路由到对应的内部服务。对外只有一个入口内部结构被完全隐藏同时还能在入口层做访问控制、限流、日志审计。我见过不少团队把服务直接裸奔在公网端口上被扫描器盯上之后才开始补反向代理每次都心力交瘁。第二个场景是负载均衡。单台服务扛不住流量时方案是把请求分散到多台后端服务器上。Nginx作为反向代理的核心优势就在这里——它能用几行配置把请求按权重、按IP哈希、按最少连接数等策略分发给上游服务器组而且后端服务器宕机时还能自动摘除。这个能力在架构演进中几乎是从单机走向集群的第一道坎也是Nginx能常青十几年的根本原因。第三个场景是SSL证书集中管理。在没有反向代理之前每台业务服务器都要单独配置证书、单独处理加密证书更新时那叫一个痛苦。把Nginx放在最前端之后HTTPS加密在反向代理这一层统一终结内部服务之间继续走HTTP明文通讯不增加业务代码的复杂度。证书换一次只动Nginx配置背后的机器完全无感。顺带说清楚一个概念正向代理代理的是客户端——我想访问某个网站先请求代理服务器由它帮我取回内容反向代理代理的是服务端——用户表面上只跟代理打交道根本不知道真正的响应来自哪台机器。理解这个区别之后再看配置很多参数就对了。2. 环境准备Linux和Windows两种常见路径的注意事项2.1 Linux下安装选对安装方式比版本更新更重要生产环境我强烈建议用系统包管理器安装。Ubuntu和Debian用aptCentOS和Rocky Linux用yum或dnf一条命令就能装完而且会注册成系统服务开机自启、日志轮转、目录规范都替你安排好了。# Ubuntu / Debian sudo apt update sudo apt install nginx -y # CentOS / Rocky Linux sudo yum install nginx -y装完后的标准检查动作有三个看一眼服务状态、确认监听端口、查看版本号。systemctl status nginx ss -lntp | grep :80 nginx -v这里有一个容易忽略的坑apt安装的Nginx默认站点配置文件在/etc/nginx/sites-available/和/etc/nginx/sites-enabled/而yum安装的版本配置文件直接摆在/etc/nginx/conf.d/下。很多人从CentOS切到Ubuntu后找不到自己的子配置文件翻半天才明白是目录结构不同。如果你需要定制编译参数比如要加特定的第三方模块那就得走源码编译这条路。先安装依赖再下载源码然后configure、make、install三步走# 依赖安装以Ubuntu为例 sudo apt install build-essential libpcre3-dev libssl-dev zlib1g-dev -y # 下载源码并编译 wget http://nginx.org/download/nginx-1.27.0.tar.gz tar -zxf nginx-1.27.0.tar.gz cd nginx-1.27.0 ./configure --prefix/usr/local/nginx --with-http_ssl_module --with-stream make sudo make install编译安装的Nginx是另一个故事的开始其实大多数场景用系统自带的版本就够了——默认版本往往包含了ssl模块和gzip模块日常反代完全够用。真正需要编译的是那些要加载第三方模块的场景后文讲平滑升级时会专门说。2.2 Windows下安装调试方便但别当成生产方案Windows装Nginx非常简单去官网下载Windows版本的zip压缩包解压到合适目录双击nginx.exe就启动了。没有安装器、不写注册表、不动系统服务一切都在那个目录里。# 进入解压后的目录执行 start nginx # 启动 nginx.exe -t # 检查配置文件语法 nginx.exe -s reload # 平滑重载配置 nginx.exe -s stop # 停止服务Windows版的坑在于进程管理不够透明经常出现关不干净的问题。你在任务管理器里能看到的进程名称都叫nginx.exe停掉一个还留一个——主进程和worker进程混在一起。我的建议是Windows环境只用来本地开发和功能验证生产环境还是老老实实放Linux上。还有一个细节Windows下配置文件的路径写法要注意server块里的静态资源路径如果用了Linux风格会直接404。2.3 安装完成后的验证清单不管哪种安装方式装完之后先做这三步用浏览器或curl访问服务器IP能看到Nginx的默认欢迎页。看不到的话先查防火墙和安全组放行了没有。执行nginx -t确认配置语法没问题。这一步应该养成肌肉记忆每次改完配置都先过一遍。打开/var/log/nginx/error.logLinux看看有没有异常warning。我见过很多部署完成后服务异常的情况最后都能从error log里找到真正的导火索。3. 第一份真实可用的反向代理配置拆开每个指令的用途3.1 最小配置长什么样新建一个配置文件比如/etc/nginx/conf.d/reverse-proxy.conf写入最基础的反向代理配置server { listen 80; server_name 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; } }这份配置的作用是把所有访问example.com的HTTP请求原封不动交给本机8080端口上的后端应用处理。就这么几行已经涵盖了反向代理最核心的五个指令。listen声明监听端口server_name是虚拟主机匹配的域名这两个合在一起确定了什么样的请求进这个server块。location /表示匹配所有以/开头的URL路径。proxy_pass是最关键的一行它告诉Nginx把请求转发到哪里。后面三个proxy_set_header的作用很多人会忽略但实际影响很大——后面专门讲。3.2 proxy_pass的两副面孔带不带URI是两种行为这是反向代理配置里最坑的一个细节没有之一。同一个指令写法差一个斜杠行为天差地别。# 第一种不带URI保留完整的原始URL location /api/ { proxy_pass http://127.0.0.1:8080; } # 第二种带URI把匹配部分替换成新地址 location /api/ { proxy_pass http://127.0.0.1:8080/; }第一种写法下请求/api/login会被转发成上游的/api/login路径原样传递。第二种写法下location匹配到的/api/部分会被替换成/于是请求/api/login到达上游时变成了/login。迁移服务或者把老接口路径做重映射时这个特性用得好是神器用错了就是生产事故。我的建议是平时配置就按不带URI的方式写保持行为直觉可预期真要改路径时再显式加URI并且用nginx -t加上访问日志双重确认。3.3 请求头处理为什么必须设置Host和相关头默认情况下Nginx转发请求时会带着它从客户端收到的原始请求头。但Host头有特殊情况——如果你不做任何设置转发后上游服务器收到的Host还是客户端原始请求里的那个域名。这本身不算错但反向代理场景下通常你希望统一控制。反代场景中我几乎总是加这三行proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;$host取的是server_name匹配到的域名这样多域名共用一个反代时上游能正确分辨请求来自哪个站点。X-Real-IP直接透传真实的客户端IP。X-Forwarded-For负责在链路中追加IP信息——如果前面还有一层CDN或负载均衡$proxy_add_x_forwarded_for会自动保留已有的X-Forwarded-For并追加当前连接来源IP不会覆盖历史IP链这是排查真实用户来源时的关键依据。后端Java应用拿getHeader(X-Real-IP)就能拿到真实IP这在做用户行为分析、封禁恶意IP时非常实用不然所有请求的IP都是Nginx服务器的IP等于瞎了。3.4 配置完成后的三件事写完配置之后顺序执行下面三步每步都有意义nginx -t # 1. 语法检查有错会指出具体文件行号 nginx -s reload # 2. 平滑重载不断开已有连接 curl -I http://example.com/test # 3. 用curl验证请求头是否符合预期nginx -s reload的原理要稍微讲一下它不是重启而是向master进程发送信号master会重新读取配置文件并创建新的worker进程之后慢慢把旧worker进程里的连接处理完再回收。这意味着线上业务不会因为配置变更而中断哪怕一秒。我见过有人图省事用restart代替reload直接把所有连接掐断这在低峰期可能感受不明显高峰期等于主动制造一次小规模故障。4. 从单服务到多服务location匹配规则与多域名配置实战4.1 location匹配优先级一张表讲清楚单个server里复杂路由往往要多个location块配合。很多人只写过location /就觉得自己会了业务一复杂就抓瞎。Nginx的location匹配有一套严格优先级从上往下的顺序是写法含义匹配优先级location /path精确匹配最高location ^~ /path普通前缀匹配匹配后不再检查正则次高location ~ /path或location ~* /path正则匹配~*忽略大小写中location /path普通前缀匹配取最长匹配项低location /兜底匹配最低规则看似复杂记忆口诀就一句精确匹配优先其次带^~的前缀再其次正则这些都没命中才看普通前缀和兜底。实际开发中最容易出问题的点是写了正则location之后原本能命中的普通前缀突然失效了因为正则的优先级高于普通前缀。遇到这种情况要么改成正则也没问题要么在普通前缀上明确加^~让它不再下探到正则。4.2 一个典型的多路由反代配置拿一个常见的前后端分离项目举例前端是Vue打包出来的静态文件后端是Java服务还有一个图片上传服务独立部署。配置文件可以这么写server { listen 80; server_name example.com; # 静态资源直接由Nginx处理不往后端转发 location /static/ { alias /var/www/example/static/; expires 7d; } # API请求统一转发到Java后端 location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # 图片服务单独转发到另一台机器 location /images/ { proxy_pass http://192.168.1.20:8090; } # 剩下的路径兜底转发给前端静态入口 location / { root /var/www/example/dist; try_files $uri $uri/ /index.html; } }这个配置里静态资源不经过后端Java处理减少了后端压力/api/独立走Java接口图片服务则甩给内网另一台专用服务器。try_files $uri $uri/ /index.html是前端路由的经典写法如果请求的路径找不到对应文件就一律返回index.html让前端路由自己接管。这个思路能直接照抄进大部分前后端分离项目里。4.3 主域名与二级域名的配置技巧一个Nginx实例同时代理多个站点靠的是多个server块。这里注意每个server_name各不相同Nginx收到请求后按域名选块处理。比如主域名和二级域名走不同的后端# 主域名 server { listen 80; server_name example.com www.example.com; location / { proxy_pass http://127.0.0.1:3000; } } # 二级域名独立服务 server { listen 80; server_name blog.example.com; location / { proxy_pass http://127.0.0.1:4000; } } # 未匹配任何域名的请求直接拒绝 server { listen 80 default_server; server_name _; return 444; }第三个server块是很多人没意识到的安全门槛。不加它的话任何直接访问服务器IP的请求都可能被路由到第一个server块造成配置泄露或非预期暴露。default_server把所有没匹配上的流量接住return 444直接断开连接不带任何响应。这个习惯能让Nginx在公网上干净很多。多域名还有一个高级玩法是泛解析——server_name *.example.com可以匹配所有子域名在证书是通配符证书时配合得非常顺。但如果不同子域名要转发到不同后端就老老实实写多个server块清晰可控别为了少写点配置搞一堆if判断维护成本会直线上升。5. 给反向代理加SSL证书从HTTP平滑切到HTTPS5.1 证书文件从哪里来、放在哪里生产环境的证书来源有两种主流方式一是云厂商申请的免费证书二是Lets Encrypt的免费证书。证书拿到手通常是一堆文件其中最关键的是证书文件.crt或.pem和私钥文件.key还有部分场景需要的证书链文件.ca-bundle。我习惯把证书统一放在/etc/nginx/ssl/目录下按域名建子目录sudo mkdir -p /etc/nginx/ssl/example.com sudo cp example.com.crt /etc/nginx/ssl/example.com/ sudo cp example.com.key /etc/nginx/ssl/example.com/ sudo chmod 600 /etc/nginx/ssl/example.com/example.com.key最后一行chmod 600非常关键。Nginx的master进程以root权限启动之后会降权运行worker进程证书私钥文件如果权限过于开放Nginx会在重载配置时直接报错拒绝启动。我遇到过好几次明明证书能打开、配置看着也对reload就失败的情况最后都是权限问题。5.2 配置HTTPS监听一份完整的SSL反代配置server { listen 443 ssl; server_name example.com; ssl_certificate /etc/nginx/ssl/example.com/example.com.crt; ssl_certificate_key /etc/nginx/ssl/example.com/example.com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; 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; } }几个参数值得逐一说明。ssl_protocols现在主流只保留TLSv1.2和TLSv1.3TLSv1.0和TLSv1.1已经进了安全黑洞不建议再开。ssl_session_cache shared:SSL:10m允许SSL会话在worker进程间共享缓存10MB大致能缓存几万个会话对性能提升很直观尤其是大量短连接场景。X-Forwarded-Proto $scheme这个头在反向代理后面还有一个后端框架时特别重要——后端要判断请求是HTTP还是HTTPS以生成正确的重定向和资源链接时它就是唯一线索。5.3 HTTP自动跳转HTTPSreturn 301是首选通常你需要把老用户的HTTP请求自动带到HTTPS避免他们访问了一个毫无响应的80端口。实现方式有两种# 方式一推荐简单明确 server { listen 80; server_name example.com; return 301 https://$host$request_uri; } # 方式二通过rewrite实现效果类似但显得绕 server { listen 80; server_name example.com; rewrite ^(.*)$ https://$host$1 permanent; }方式一里的return 301比方式二直观得多而且不涉及正则匹配性能更好。有人可能关心301会不会影响SEO这个属于预期行为——HTTP跳HTTPS本来就该用301搜索引擎会把权重平滑迁移过去。还有一个细节$host$request_uri保留了原始域名和完整请求路径这样用户从http://example.com/article?id1跳过去之后落地地址是https://example.com/article?id1不会丢失参数。5.4 证书到期前的一个提醒免费证书有效期通常只有3个月一定要设置到期提醒。我踩过一次证书过期的亏——用户访问直接提示不安全连接业务受损不说排查还花了半天。推荐用crontab配合curl或openssl做定期检查# 每月1号检查证书剩余天数 0 0 1 * * /usr/bin/openssl s_client -connect example.com:443 -servername example.com /dev/null 2/dev/null | openssl x509 -noout -enddate把输出重定向到一个监控脚本里有效期少于30天就告警彻底告别证书怎么又过期了的尴尬。6. 平滑升级与常用运维操作别再用停服重启了6.1 reload、restart、stop的区别很多人命令没搞清就上来操作后果很不愉快。三者的本质区别nginx -s reload平滑重载配置不中断现有连接新配置对新连接生效。nginx -s restart先停再启如果你是通过start nginx启动的restart就是stop加start所有连接全部断开生产环境禁用。nginx -s stop立即停止快但是暴力正在处理的请求会被直接掐断非维护窗口不要用。reload看似简单背后Nginx内部其实做了一整套优雅的交接master进程解析新配置成功就fork新worker旧worker处理完手上所有连接后自动退出。如果新配置有语法错误reload会失败但旧进程照常运行——这也是为什么我们反复强调先nginx -t再reload的原因等于给操作上了一道双保险。另外注意如果你改了配置文件但忘了reloadNginx不会自动感知配置变更这点跟很多动态加载的应用不一样别以为改了文件就生效了。6.2 平滑升级Nginx版本的完整流程线上Nginx需要升级版本时最稳妥的方案是利用信号机制做无缝迁移不用停服。步骤记录在这里属于运维必背技能# 1. 先看当前版本和编译参数 nginx -V # 2. 下载新版本源码编译参数尽量保持和原来一致 wget http://nginx.org/download/nginx-1.26.0.tar.gz tar -zxf nginx-1.26.0.tar.gz cd nginx-1.26.0 ./configure --prefix/usr/local/nginx --with-http_ssl_module make # 3. 备份旧版可执行文件 mv /usr/local/nginx/sbin/nginx /usr/local/nginx/sbin/nginx.old # 4. 替换为新编译出的二进制 cp objs/nginx /usr/local/nginx/sbin/nginx # 5. 向master进程发送USR2信号让它启动新master和新的worker进程 kill -USR2 cat /usr/local/nginx/logs/nginx.pid # 6. 发送WINCH信号让旧master逐渐停掉旧的worker进程 kill -WINCH cat /usr/local/nginx/logs/nginx.pid.oldbin整个过程不需要执行nginx -s stop客户端完全无感知。升级完成后把新进程测试稳定再考虑清理旧二进制。这个流程在任何生产环境都能直接套用也建议在测试环境完整演练一遍再去线上操作毕竟信号量操作一旦弄错进程号后果是不可逆的。6.3 日常运维的常用命令清单整理一份我平时最常用的Nginx运维命令按使用频率排序nginx -t # 检查配置语法改完必跑 nginx -s reload # 平滑重载配置 nginx -s quit # 优雅退出处理完所有请求再停 systemctl status nginx # 查看服务状态 systemctl enable nginx # 设置开机自启 tail -f /var/log/nginx/access.log # 实时查看访问日志 tail -f /var/log/nginx/error.log # 实时查看错误日志日志这块值得多说几句。我调试反向代理问题时没有一次是离开日志能定位的。上游服务报502或504时error.log里通常会留下connect() failed或upstream timed out这样的关键线索顺藤摸瓜比瞎猜配置高效得多。7. 高频故障排查502、504、404出现的真正原因7.1 502 Bad Gateway连不上后端502是全流程中最常见的问题含义是Nginx向上游转发请求时连接失败了。触发原因大概三种后端服务根本没启动——先确认Java、Node或PHP的进程活着。端口写错——proxy_pass里写的端口和后端实际监听端口不一致。防火墙拦了——Nginx和后端不在同一台机时需要确认后端机器的防火墙放行对应端口。排查顺序建议是先看后端进程再核对配置文件和端口最后telnet一下端口连通性。ps aux | grep java nginx -t curl -v http://127.0.0.1:8080/health7.2 504 Gateway Timeout后端是慢不是挂504的含义完全不同它表示Nginx成功连接上了后端但等待响应的时间超过了阈值。默认超时时间是60秒有些慢接口本来就超了需要显式调大location /api/ { proxy_pass http://127.0.0.1:8080; proxy_connect_timeout 10s; proxy_read_timeout 120s; }proxy_connect_timeout控制建立连接的超时proxy_read_timeout控制等待响应正文的超时。写接口尤其要注意把proxy_read_timeout调大否则用户上传大文件或者后端处理耗时较长时Nginx不等后端返回就直接回了504。真实案例有一次一个报表导出接口需要90秒才能响应默认60秒超时用户反复报错调完超时参数之后问题直接消失。7.3 404 Not Found多半是路径改写逻辑错了反代场景导致404的最常见原因就是前文说的proxy_pass带URI引起的路径改写。举个例子后端接口实际路径是/user/info你的location匹配的是/api/如果proxy_pass带了/请求就变成了/info后端自然找不到路由。排查方法很简单看后端的访问日志对比收到的URL和预期URL的差异。如果后端日志显示缺了某一段路径基本就是proxy_pass的URI行为在作怪调整location匹配范围或去掉proxy_pass里的URI即可。7.4 一个综合排障思路做减法我总结了一套排障顺序可以当成条件反射来练先nginx -t排除配置语法问题再看error.log拿到第一手错误信息然后确认上游服务健康最后才怀疑Nginx配置本身逻辑。这个顺序在绝大多数场景都能快速收敛问题范围。反向代理配置出错不丢人谁都是从几个常见错误里摸爬滚打过来的关键是掌握一套可复用的排查路径下次遇到同样问题十分钟内就能搞定。实际执行时还有一个技巧临时把后端服务直接暴露到另一个端口比如直接访问8080绕过Nginx直接访问后端看是否正常。这一步能把后端问题和Nginx问题一刀切开省去大量猜测时间。验证完再改回原状即可。我自己写反向代理配置这多年最大的体会是不要把Nginx当黑盒它每个指令都遵循一套很朴素的逻辑——匹配、转发、改写、返回。把这四个环节拆开理解再复杂的配置也能拆成一个个能解释、能验证的小块。希望这份配置经验能帮你少走几步我之前走过的弯路。
