Nginx反向代理实战：让后台管理系统从IP:端口变成干净域名

接手一个后台管理系统时最烦的事就是大家访问的时候还得记一堆端口号比如192.168.1.20:8080这种。今天这篇就专门聊怎么用 Nginx 给后台管理系统配一个域名访问入口把你原来的IP:端口变成admin.example.local这种干净地址顺便把 Nginx 反向代理里最容易踩的坑都捋一遍。这套配置几乎适用于所有 Web 后台管理系统不管你是本地开发想模拟线上域名还是服务器上部署完系统要隐藏端口看完都能直接上手。1. 先搞明白域名访问后台管理系统到底做了什么1.1 直接用 IP 加端口访问的痛点在哪里很多项目初期图省事后端服务启动后直接在浏览器输http://192.168.1.20:8080/login进去。这个方式在单机环境凑合能用但用着用着你就会发现几件事。第一个麻烦是记不住。8080、8888、9090 这类端口号本来就没什么规律你告诉别人“访问后台啊地址是 192.168.1.20端口 8080不对是 8081”对方一脸懵。第二个麻烦是端口暴露在外面你也不知道会不会被乱扫。第三个麻烦出现在前后端分离的项目里前端页面调接口的时候接口地址写http://192.168.1.20:8080/api万一后端换了台机器或者换了个端口前端代码里所有写死的地方全得跟着改。域名访问最大的价值就是把这些麻烦收敛掉。用户只需要记住admin.example.local后面不管是内网 IP 变了、端口换了、还是从 HTTP 升级到 HTTPS对外始终是这一个域名。Nginx 在中间做一层代理转发后端服务地址只存在于 Nginx 配置里改起来就一个文件的事。1.2 从浏览器输入域名到看到后台页面的完整链路这一小节不用把它们想象得很玄乎拆开看就是一个请求转发的过程。你输入http://admin.example.local浏览器会先做 DNS 解析把这个域名翻译成对应的 IP 地址。生产环境里这个 IP 是云服务器或内网服务器地址本地开发或者内网测试时通常你会在hosts文件里手动加一行把域名指到127.0.0.1或者内网某台机器地址。浏览器拿到 IP 后发起 HTTP 请求到这台机器的 80 端口。这台机器上运行着 NginxNginx 一看请求头里的Host是admin.example.local就知道这个请求应该交给配置文件里对应的那个 server 块来处理。这个 server 块里配置了proxy_passNginx 就把请求原封不动地转发给后面真正的后台服务进程比如监听在 8080 端口的 Java 服务或 Node 服务。后台服务处理完把响应沿原路返回给 NginxNginx 再交给浏览器渲染。整个过程对用户来说就跟访问一个普通网站一样完全感知不到后端还有个 8080 端口。这类比成公司前台所有客户统一从前门进来前台看了对方找谁再转接到对应的部门。客户永远不用知道某个部门的具体房间号。1.3 为什么选型首选 Nginx市面上能做反向代理的东西不少但我用下来Nginx 在这个场景里基本是标准答案。有人可能会问直接把后端服务的监听端口改回 80 不就行了不行。80 端口只有一个后台管理系统往往还有别的应用要共用这台机器可能是另一个管理端、一套对外 API甚至一个前端静态站点。它们都抢 80 端口就撞车了。Nginx 靠不同的域名区分不同应用80 端口只留给 Nginx其他服务都监听在各自的内网端口上。还有人提过用应用自带的网关功能像某些后端框架自带的转发能力。可用在 Nginx 上的好处是稳定、可控、不侵入业务代码而且对后端服务完全透明。你的后台服务不用做任何改动该监听 8080 就监听 8080对外换域名、换端口全都由 Nginx 这一层搞定。加上 Nginx 社区极其活跃各种问题基本搜一下都有答案团队里随便谁都能看懂配置出问题排查起来成本很低。2. 动手必懂Nginx 反向代理的三个核心概念2.1 listen 端口与 server_nameNginx 怎么知道这个域名是给谁的Nginx 的一个 server 块本质上就是一条规则监听什么端口、匹配什么域名、匹配到了干什么。最常见的一段配置长这样server { listen 80; server_name admin.example.local; location / { proxy_pass http://127.0.0.1:8080; } }listen 80表示让 Nginx 监听 80 端口。server_name admin.example.local表示当请求头里的 Host 是这个域名时这个 server 块生效。如果一台机器上同时挂着多个域名比如admin.example.local和api.example.local就写两个 server 块都监听 80但server_name不同Nginx 会自动根据浏览器带给它的 Host 字段来分配。这里有个新手容易迷糊的点域名解析到 IP 后从网络层看请求确实是发到这台机器的 80 端口了但一台机器上可能有多个域名对应同一个 IP怎么区分靠的就是 HTTP 请求头里的 Host。浏览器访问http://admin.example.local时请求头里自带Host: admin.example.localNginx 拿这个值跟配置里的server_name比对命中哪个就交给哪个。所以多个网站共用一台服务器同一个端口在 Nginx 这里是完全没问题的。如果你只有一个域名其实可以不写server_name但强烈建议写。写了以后配置含义一眼就能看明白以后加第二个域名的时候也有个参照。另外还有一个细节如果请求 Host 跟所有 server_name 都匹配不上Nginx 会默认给第一个 server 块处理。所以通常把默认入口或者一条默认 404 规则放在第一个位置避免乱七八糟的请求落到业务 server 上。2.2 proxy_pass 的转发逻辑斜杠到底怎么加proxy_pass是这个配置里最关键的一行。它的作用就是把匹配到的请求转发给后端服务。最简单的写法就是proxy_pass http://127.0.0.1:8080;不带任何路径Nginx 会保留请求的原始 URI 原封不动转发过去。我用一个例子说清楚斜杠带来的差异。假设你有一个后台管理系统后端服务的所有接口都带/admin前缀你在 Nginx 里写了location /admin/ { proxy_pass http://127.0.0.1:8080; }用户访问http://admin.example.local/admin/loginNginx 会把整个路径/admin/login原封不动地转发给后端后端收到的是/admin/login。这种写法适合后端本身就用这些路径来路由的场景。但如果你写的是location /admin/ { proxy_pass http://127.0.0.1:8080/; }注意这个结尾加了个/。此时 Nginx 就会把匹配到的/admin/前缀去掉再把剩下的部分往后端转。用户访问/admin/login后端收到的就是/login。这个差异非常隐蔽很多人排查了半天发现后端老是 404结果就是proxy_pass结尾多了个斜杠导致的。我个人的习惯是尽量让 Nginx 只做转发、不改路径也就是proxy_pass不写路径只写到端口为止。除非后端服务的路由和前端访问路径确实对不上才考虑用斜杠来重写。原因也很简单少一层路径改写就少一个出错点排查问题的时候更容易想清楚到底是谁改的路径。2.3 location 路径匹配的优先级location的匹配规则其实有几种但后台管理系统场景里你 90% 的情况只需要用前缀匹配也就是写location /这种。要注意的是Nginx 在同一个 server 块里找 location 时不是从上往下按顺序找而是先找出所有前缀匹配里最长的那一个。比如一个后台管理系统既有静态资源又有接口转发你可能会写两个 locationlocation / { proxy_pass http://127.0.0.1:8080; } location /static/ { proxy_pass http://127.0.0.1:8081; }用户访问/static/app.js时Nginx 会匹配第二个 location因为/static/比/更长、更具体。访问/login时只有/能匹配上就走到第一个。这个逻辑其实挺符合直觉的就是“越长越具体越优先”你只要记住这点日常配置基本不会出大问题。还有一种比较特殊的情况是正则匹配用~或~*开头优先级别比普通前缀匹配更高。但后台管理系统里接口路径大多是固定前缀用不到正则。真遇到需要的话知道有这个机制就行真用到的时候再去查官方文档也不迟。在生产环境里我还见过有人把location /写成location / {}中间啥也不加的这种写法会导致所有请求直接返回 200 空白页。所以哪怕只有一个 location也一定要写全proxy_pass这是配置里最容易漏掉的一环。3. 实操全记录一步步配好域名访问3.1 第一步准备域名并确定解析方式这一步根据你的部署环境分两种情况。如果是本地开发或者内网环境通常不用真的去注册域名改一下本机的hosts文件就行。Windows 上编辑C:\Windows\System32\drivers\etc\hostsmacOS 和 Linux 编辑/etc/hosts加一行127.0.0.1 admin.example.local如果后端服务部署在另一台机器上就把127.0.0.1换成那台机器的内网 IP。改完之后在命令行里执行ping admin.example.local能通说明 hosts 生效了。如果是生产环境需要到域名服务商的控制台里配置一条 A 记录把admin这个子域名解析到服务器的公网 IP。这里有一点值得提醒如果你的 Nginx 是放在某台云服务器上要确认安全组和防火墙规则允许外部访问 80 端口。我见过好多回域名配好了 Nginx 也启动了从服务器本机 curl 域名一切正常但外部浏览器就是打不开查到最后都是云厂商安全组里没放行 80 端口。不管哪种方式最终的目标都是让这个域名能解析到运行 Nginx 的那台机器上。至于解析的 IP 是公网还是内网取决于你的访问场景不要搞混。3.2 第二步确认后台服务到底监听在哪个地址Nginx 配置里的proxy_pass要写对前提是你得知道后端服务监听的 IP 和端口。以常见的 Java 后台管理系统为例Spring Boot 默认监听8080而且默认是监听在所有网卡上的。如果你的后端服务启动时设置了server.address127.0.0.1那就只有本机能访问Nginx 转发过去没问题但外网直连后端端口就不通。所以在配 Nginx 之前我一般会先在服务器本机验证一下后端服务是不是活着。执行curl -I http://127.0.0.1:8080/login如果返回了 HTTP 状态码说明后端服务正常。如果连接被拒绝先回头看服务有没有启动端口是不是被占了。也可以通过ss -lntp或者netstat -lntp看端口监听状态。这一步花不了两分钟但能帮你把后面排查范围缩小很多。还有一个小坑要提醒有些后台管理系统为了安全后端服务刻意只绑定127.0.0.1这种情况下 Nginx 在同一台机器上转发没问题。但如果你的 Nginx 装在另一台机器上转发到后端时就必须把监听地址放开到内网网卡或者在防火墙上做精确放行否则转发过去也是连接拒绝。3.3 第三步编写 Nginx 配置文件Nginx 的配置目录在不同系统上略有差别但思路一致。以主流 Linux 发行版为例通常/etc/nginx/nginx.conf是主配置文件里面通过include引入了/etc/nginx/conf.d/目录下所有.conf文件。我们新建一个独立的配置文件来管理后台系统这样结构清晰以后改动也不会影响别的站点。在/etc/nginx/conf.d/下新建一个admin.confserver { listen 80; server_name admin.example.local; # 日志分开记好排查 access_log /var/log/nginx/admin_access.log; error_log /var/log/nginx/admin_error.log; 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_set_header新手可能不太理解为什么需要它们。原理是这样的请求从浏览器到 Nginx 再到后端服务后端服务看到的客户端 IP 来源如果不是做特殊处理看到的永远是 Nginx 的 IP也就是127.0.0.1。那后端如果要记录用户 IP、做访问控制拿到的数据就是错误的。所以 Nginx 通过X-Real-IP和X-Forwarded-For这两个请求头把真实客户端 IP 传下去。Host头也是很关键的有些后端框架在做 URL 拼接时依赖 Host 字段你不传或传错生成的链接可能就异常。如果你的后台管理系统里有文件上传或者 WebSocket 功能还需要额外处理请求体大小和连接升级。上传场景加一行client_max_body_size 100m;放在 server 或 location 里限制的是上传文件最大值不配的话 Nginx 默认只允许 1MB传个稍大点的图片就会 413。WebSocket 场景要加proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;不配这段的话WebSocket 会建立失败页面里某些基于长连接的功能就会异常而且控制台报错不直观排查起来比较费劲。3.4 第四步校验配置并让 Nginx 生效配置写完不要急着重启 Nginx先做配置语法检查。执行nginx -t这个命令会检查所有配置文件里的语法问题。如果看到syntax is ok和test is successful说明配置没问题。如果有报错它会告诉你具体是哪个文件哪一行出错比你自己瞎子摸象快得多。确认没问题后执行systemctl reload nginx这里我用的是reload而不是restart。两者的区别在于reload是平滑重载Nginx 会重新读取配置文件但已经建立的连接不会中断restart则是先停后启所有连接都会断开。对于后台管理系统这种需要持续在线的服务reload是更安全的操作。如果 Nginx 是源码编译安装的也可以通过nginx -s reload达到同样效果。每次改完配置都养成nginx -t先检查再reload的习惯能避免很多生产事故。我之前有次改完配置直接 reload结果配置里写错了一个分号没检查出来一瞬间整个站点全挂了。从那以后凡是涉及 Nginx 配置变更我一定先过一遍语法检查。3.5 第五步验证效果与查看转发日志配置生效后先从服务器本机验证一下curl -I http://admin.example.local/login如果返回状态码 200说明 Nginx 已经正确把请求转发给了后端服务。如果返回 404 或 502对照第 4 章排查。本机没问题后再回到你日常用的电脑上浏览器打开http://admin.example.local正常的话就能看到后台登录页了。登录一次操作几个菜单页面重点看两件事页面样式有没有丢接口返回数据正不正常。如果样式全乱或者接口 404多半是资源路径匹配的问题具体解法看 4.3 节。排查问题时Nginx 的访问日志和错误日志是最直接的线索。我通常在access_log里看请求进来后返回的状态码在error_log里看 Nginx 转发时到底报了什么错。像connect() failed这种提示一看就知道是 Nginx 连接后端的地址不通。4. 常见问题与排查技巧实录4.1 502 Bad Gateway八成是后端没对上打开域名后如果浏览器直接刷出 502说明 Nginx 自己活着但它转发请求给后端的时候失败了。最常见的两个原因后端服务没启动或者proxy_pass指向的地址和端口不对。排查的顺序我一般是这样先在服务器本机执行curl -I http://127.0.0.1:8080/login如果能通说明后端正常不通就先去把后端服务拉起来。后端正常但 Nginx 还是 502就看error.log里面会写类似connect() failed (111: Connection refused) while connecting to upstream的报错这个报错的意思就是 Nginx 尝试连接127.0.0.1:8080时被拒绝了。再看一眼你配置里的端口和实际监听端口是否一致别把 8080 写成 8081 这种低级错误。还有一种隐蔽的情况后端服务绑定在127.0.0.1但proxy_pass写的是内网 IP比如http://192.168.1.20:8080这时候 Nginx 从内网 IP 去连接后端大概率会超时或拒绝。解决方法是让后端监听地址和 Nginx 访问地址保持一致最简单就是 Nginx 写127.0.0.1后端也绑127.0.0.1前提是 Nginx 和后端在同一个台机器上。4.2 404 Not Found路径在转发过程中丢了404 的发生场景比 502 更多样。一种情况是proxy_pass写的是带斜杠的地址导致路径前缀被 Nginx 剥掉了后端收到一个根本不存在的路由。遇到 404 先把你配置里proxy_pass末尾的斜杠去掉试试很多问题就此解决。另一种情况是后端服务本身配置了 context-path比如 Spring Boot 里设置了server.servlet.context-path/admin。此时后端实际能响应的路径是/admin/login而你 Nginx 转发过来的是/login后端当然返回 404。这种情况有两个处理思路一是 Nginx 的 location 里把/改成/admin/这样转发时保留完整路径二是让前端访问时本身就带/admin前缀Nginx 不做路径改动。我个人偏好第一种因为入口更干净用户访问根路径就能进入后台不需要记前缀。排查 404 时还有个很实用的技巧把 Nginx 的location临时改成直接返回 JSON比如location / { return 200 {msg:ok}; }访问域名看看能不能返回这段 JSON。能返回说明 Nginx 配置没问题问题出在转发链路或后端路由不能返回说明 Nginx 层面的路径匹配就有问题。这个自测方法我屡试不爽能帮助快速缩小排查范围。4.3 页面能开但样式全乱、接口全崩资源路径失配问题这种情况非常典型登录页面能出来但样式全丢打开开发者工具一看CSS 文件全部 404。原因也简单很多前端框架构建出来的 HTML 里资源路径写的是绝对路径比如/static/css/app.css。浏览器解析时它会把路径拼在当前域名下也就是http://admin.example.local/static/css/app.css。如果 Nginx 只对/做了转发而后端拿到的路径又对不上加载自然失败。解决的思路有三个。第一如果后端服务本身能处理这些静态资源比如 Spring Boot 能提供/static路径下的资源那 Nginx 只要保证转发路径正确即可。第二如果静态资源和接口不在同一个服务上可以单独加一个 locationlocation /static/ { proxy_pass http://127.0.0.1:8081; }专门把静态资源指到另一个服务。第三如果前端是独立构建的纯静态资源可以直接让 Nginx 直接托管文件目录不经过后端location /static/ { alias /opt/admin-frontend/dist/static/; }alias的意思是把/static/映射到服务器磁盘上的某个真实目录。这种方式效率更高因为 Nginx 处理静态文件本身非常快不需要经过后端的业务逻辑。判断是路径问题还是服务问题打开浏览器开发者工具的 Network 面板找一个失败的资源请求看它的 URL 长什么样再问自己一个问题这个 URL 对应到后端服务里应该是什么路径。只要前后端的路径对上了问题自然解决。4.4 403 Forbidden 与端口冲突的隐蔽小坑403 出现的情况没有 502 和 404 那么频繁但一旦遇到也很头疼。最容易发生在用alias托管静态资源时Nginx 对目录里的文件没有读取权限。Nginx 进程默认以nginx用户运行而你前端构建出来的文件可能是root用户创建的权限是 700 或 600Nginx 读不了就会返回 403。解决方法是把资源目录的权限至少调整为 755或者用chown把文件属主改成 nginx 用户chown -R nginx:nginx /opt/admin-frontend/dist/另外一个和权限无关但很隐蔽的坑是端口冲突。如果之前有别的服务占用了 80 端口Nginx 启动时会直接失败。这时候执行ss -lntp | grep :80看是谁在占用。常见的是有些系统自带的 Apache 或者其他 Web 服务被开机自启了关掉它再启动 Nginx 即可。4.5 一个容易忽略的细节Cookie 和重定向的域名问题后台管理系统登录之后通常会写 Cookie某些后端的 Cookie 域配置是限定在具体 IP 上的比如Set-Cookie: JSESSIONIDxxx; Domain192.168.1.20。你用域名访问时浏览器发现 Cookie 的 Domain 和当前访问域名不一致就不会保存或不会发送这个 Cookie最直接的表现就是登录成功后跳转回登录页甚至陷入死循环。遇到这类问题优先在后端应用的配置文件里把 Cookie 的 Domain 改成你的域名比如admin.example.local或者干脆不设置 Domain只设置 Path这样浏览器就会按当前请求域来带 Cookie。改完后端配置后重启服务再试。这种情况在老的 Java 后台系统里比较常见新版框架大多已经自动适配请求头里的 Host 了但如果你在维护的恰好是历史遗留项目这一条基本上是必踩的坑。还有一个关联问题是重定向地址。很多后端框架在登录成功后会返回302并带上Location字段如果这个字段里的地址是内网 IP浏览器看到后就会往那个地址跳转那你前面做了半天的域名访问等于白做。排查方法是看浏览器地址栏跳到了哪里如果跳回到 IP 加端口就去后端的配置里把服务地址或重定向地址改成域名。这类问题本质上都是后端生成的 URL 用了硬编码地址没有使用请求头里的 Host 信息属于应用层需要修的问题Nginx 层只能通过proxy_set_header Host $host辅助配合。5. 一些扩展建议从域名访问到 HTTPS再到多环境切换域名访问这件事本身不算复杂但它是整个后台系统对外暴露的入口值得你多花一点心思做得更完整。第一个建议是顺手把 HTTPS 加上。域名已经绑定了申请一个 SSL 证书配上让后台走 HTTPS 访问一方面登录密码等敏感信息传输过程中加密了安全性提升一个级别另一方面现在很多浏览器对 HTTP 页面的特性限制越来越多比如某些浏览器 API 在非安全上下文里根本不能用。Nginx 配置 HTTPS 并不复杂核心就是证书路径和listen 443 ssl两件事。从域名访问跨到 HTTPS整个链路就更接近生产环境的真实形态。第二个建议是同一套 Nginx 配置可以复用到多个环境。开发环境、测试环境、生产环境往往只是域名不同、后端地址不同其他结构都一样。我在实际项目里会为每个环境维护一个独立的配置文件比如admin-dev.conf、admin-test.conf、admin-prod.conf内容和结构完全一致只有少数几行参数不同。这样团队里任何人接手都知道去哪找对应环境的配置不会出现改了一个环境把另一个环境也带崩的情况。第三个建议是一定要把配置纳入版本管理。Nginx 配置虽然是运维的事但它本质上跟代码一样应该进入 Git 仓库方便回溯和评审。我在实际工作中维护的好几个后台系统Nginx 配置就跟项目代码放在同一个仓库里改动有记录出错能回滚比一个人在服务器上直接改文件要靠谱得多。这条链路里最核心的还是把listen、server_name、proxy_pass这三个概念吃透。很多摸不着头脑的问题最后往回追溯基本都是这三样里面某一样没配置准确。你把它们理解了不管是配后台管理系统还是以后配一个静态站点、一个 API 网关你会发现思路是通用的。