1. 为什么需要用 Nginx 反向代理 Nacos1.1 Nacos 的访问形态与 Nginx 的角色Nacos 作为注册中心和配置中心在微服务架构里的地位不用我多说。不管是 Spring Cloud Alibaba 还是 Dubbo只要上了规模基本都离不开它。而 Nacos 默认的访问方式是直接通过 IP 加端口访问控制台默认端口是 8848gRPC 端口是 9848客户端向服务端发起注册、订阅、配置拉取时走的也是这些端口。问题来了生产环境里你不可能让所有客户端都裸连 Nacos 的 8848 端口尤其是当你有多套环境、多个服务分组或者公司内部有统一的网关入口时。这个时候在 Nacos 前面加一层 Nginx 反向代理把所有进入 Nacos 的流量统一收敛到一个入口再由 Nginx 根据路径、域名、端口做转发是最常见也最稳的做法。我在实际项目中遇到最多的场景有三种第一种公司要求所有内部系统必须走统一域名访问Nacos 控制台也要挂在域名下面第二种Nacos 做了集群部署客户端需要统一入口做负载均衡而不是自己维护一堆节点列表第三种服务通过 Nginx 暴露到外部网络但不想直接把 Nacos 的真实 IP 和端口暴露出去。这三种场景本质上都是同一个诉求让 Nacos 的访问更可控、更安全、更统一。1.2 直接暴露端口的问题很多人一开始图省事直接把 Nacos 的 8848 端口开放出去客户端配置里写死 IP。短期看确实能用但长期来看问题一堆。首先是端口管理混乱。一个 Nacos 实例涉及 8848HTTP 主端口和 9848gRPC 端口如果你部署了多套环境每套环境至少占用两个端口再加上 Nacos 2.x 版本默认还会开放 9849 之类的端口端口一多防火墙规则、安全组配置、运维排障都会变得非常痛苦。其次是安全风险。Nacos 控制台默认的鉴权机制如果配置不当很容易出现未授权访问的问题。这一点在最近的漏洞通告里反复被提及比如/nacos/v1/core/cluster/nodes这类接口在没有鉴权的情况下可能泄露集群节点信息。把 Nacos 直接暴露在公网或者大内网里等于把风险敞口放大。用 Nginx 做一层代理至少可以在入口层做 IP 白名单、访问频率限制甚至统一加一层简单的 Basic Auth比裸奔强太多了。第三是升级维护困难。Nacos 版本升级、节点扩容、故障切换如果客户端都写着固定 IP你每次变更都要改一堆客户端配置而且客户端不会自动感知节点变化。有了 Nginx 这个统一入口后端节点怎么变客户端都不需要动。所以我的建议是不管你是单机测试还是生产集群只要条件允许就在 Nacos 前面加一层 Nginx。这层代理的成本极低但带来的灵活性和安全性提升非常明显。2. 配置前的环境准备与前置条件2.1 版本选型与兼容性确认我在配置之前永远会先确认三套环境的版本Nginx 版本、Nacos 版本、客户端版本。这三个版本之间可能存在兼容性问题尤其是 Nacos 2.x 之后引入了 gRPC 长连接对代理层的要求发生了根本性变化。Nacos 1.x 时代客户端和服务端之间走的是 HTTP 短连接Nginx 只需要做普通的 HTTP 反向代理就行。但 Nacos 2.x 开始客户端和服务端之间的核心通信改成了 gRPCgRPC 基于 HTTP/2而且是长连接。如果你还用老思路只代理 8848 端口会发现客户端能连接上但服务注册、配置订阅经常超时或者控制台看着正常实际服务列表一直拉不起来。这是因为 Nacos 2.x 的客户端会先通过 8848 端口做服务发现拿到服务端地址后再尝试和偏移量 1000 的端口建立 gRPC 长连接。也就是说服务端监听 8848gRPC 长连接端口就是 9848。如果你在 Nginx 层只代理了 8848gRPC 连接建立不了服务自然注册不上。我这边实际用的是 Nginx 1.24 和 Nacos 2.2.3这个组合在我维护的几个项目里跑了大概一年多整体非常稳定。如果你用的是 Nacos 2.1.x 和 Nginx 1.18 这类老版本也可以正常工作但要特别注意 HTTP/2 相关配置的差异。Nginx 原生支持 gRPC 反向代理是从 1.13.10 开始的所以理论上 1.14 以上都行但我还是建议用 1.20 以上的版本毕竟 bug 修复和稳定性都有保障。2.2 Nacos 部署形态确认动手配置 Nginx 之前先搞清楚你的 Nacos 是怎么部署的。单机模式、集群模式、还是容器化部署这几种形态对 Nginx 配置的影响完全不一样。单机模式下你只需要关注一个节点。集群模式下Nginx 要配置多个 upstream 节点做负载均衡并且需要开启 ip_hash 或者 least_conn 之类的负载策略因为 Nacos 的 gRPC 长连接需要保持会话粘滞不然客户端频繁切换节点会导致连接重建。容器化部署的情况更复杂。如果你是用 Docker 或者 Kubernetes 部署的 Nacos需要确认容器端口映射是否正确尤其是 9848 这个 gRPC 端口有没有映射出来。我踩过一个坑Kubernetes 里只暴露了 Service 的 8848 端口Nginx 代理也只写了 8848结果服务注册死活不成功。查了半天才发现是 gRPC 端口没有同步暴露Nginx 无法连接到后端的 9848 端口。还有一个细节需要确认Nacos 的 IP 地址绑定。在application.properties里Nacos 2.x 默认会0.0.0.0监听所有网卡。如果你改了绑定地址比如只绑定了内网 IP那么 Nginx 转发时使用的主机名解析可能会出问题。我建议是保持默认监听通过防火墙或安全组来控制访问来源这样 Nginx 配置也不用特殊处理。2.3 Nginx 安装与基础验证Nginx 的安装其实没什么难度CentOS 上用 yumUbuntu 上用 aptWindows 上直接下载二进制包解压就能用。但我还是想额外强调一点如果真的打算在生产环境用尽量别用系统自带的旧版本尤其是 CentOS 7 自带的 Nginx 1.12 之类年代过于久远对 HTTP/2 和 gRPC 的支持不够完善。我一般推荐用 Nginx 官方源安装或者直接用 OpenResty后者在扩展性上更强不过只是做反向代理的话原版 Nginx 就够了。安装完之后先别急着写代理配置。先用默认配置启动一下确认 Nginx 本身能正常工作然后再去改配置。很多新手一上来就写代理结果出了问题也不知道是 Nginx 的问题还是 Nacos 的问题。基础验证很简单启动 Nginx 后直接在浏览器访问服务器 IP能看到 Nginx 的欢迎页就说明基础服务没问题。另外别忘了测试配置文件的语法。Nginx 的配置语法很严格少一个分号、多一个空格都可能起不来。修改完配置后用nginx -t做一次语法检查通过了再执行nginx -s reload平滑重载。这个习惯我从入行就养成了帮我避免了很多低级错误。3. Nginx 反向代理 Nacos 的完整配置3.1 最基础的 HTTP 代理配置我们先从最基础的开始用 Nginx 代理 Nacos 的 HTTP 访问也就是控制台和客户端通过 HTTP 访问 8848 端口的场景。这个配置我给过很多同事几乎可以直接照抄。server { listen 80; server_name nacos.example.com; location / { proxy_pass http://127.0.0.1:8848; 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; } }把server_name换成你自己的域名proxy_pass换成 Nacos 的实际地址这个配置就能跑起来。访问http://nacos.example.com就能打开 Nacos 控制台客户端的 server-addr 也可以直接配成nacos.example.com:80。这里有几个细节需要解释一下。proxy_set_header Host $host这一行非常关键。Nacos 控制台在登录后会做重定向如果 Host 头不对重定向 URL 会指向内网地址导致你从浏览器访问的时候被跳转到127.0.0.1:8848看起来就是页面打不开或者一直在加载。server_name配置的域名会和浏览器地址栏的域名一致这样才能保证 Nacos 内部生成的回跳地址正确。X-Real-IP和X-Forwarded-For是给 Nacos 传递客户端真实 IP 的。这样 Nacos 的日志里能看到真正的客户端来源而不是所有请求都显示 Nginx 的 IP。如果你后续要做 IP 白名单控制这两个头是基础。3.2 路径代理配置的细节有些场景下Nacos 不是部署在独立域名下而是和其他服务共享一个域名通过路径来区分。比如http://example.com/nacos/访问 Nacoshttp://example.com/other/访问另一个服务。这种场景就需要对路径做处理。server { listen 80; server_name example.com; location /nacos/ { proxy_pass http://127.0.0.1:8848/nacos/; 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_pass后面路径写不写、带不带尾斜杠效果完全不一样。proxy_pass http://127.0.0.1:8848;—— 不带路径Nginx 会把原始 URI 原封不动地传给后端。访问/nacos/后端收到的也是/nacos/。proxy_pass http://127.0.0.1:8848/nacos/;—— 带路径且以斜杠结尾Nginx 会把 location 中匹配到的部分替换成代理路径。访问/nacos/后端收到的也是/nacos/但在某些正则和嵌套场景下行为会有差异。proxy_pass http://127.0.0.1:8848/;—— 后端收到的路径会去掉/nacos/前缀。访问/nacos/后端收到的是/。对于 Nacos 来说我强烈建议保持路径一致也就是第一种或者第二种方式。因为 Nacos 的很多接口和静态资源路径都是写死的比如登录接口是/nacos/v1/auth/login控制台页面资源是/nacos/console/...。如果你用第三种方式去掉了前缀Nacos 会认为客户端访问的是根路径但实际的接口路径里包含了/nacos这会导致页面能打开但接口全部 404。3.3 处理 Nacos 2.x 的 gRPC 端口前面反复提到 Nacos 2.x 和 gRPC 的关系这里专门展开说。Nacos 2.x 的客户端和服务器之间的核心通信改成了 gRPC而 gRPC 是长连接走的是专门的端口。Nacos 服务器在启动时会在主端口 8848 的基础上自动偏移创建 gRPC 端口主端口 1000也就是 9848。这个端口用于客户端向服务端发起的 gRPC 连接和基于 gRPC 的服务发现、配置监听。如果你只是用 Nginx 代理 8848而不处理 9848会看到的现象是控制台能打开登录也正常但服务列表是空的或者服务注册后很快被标记为不健康。客户端日志里会反复出现类似Connection refused或gRPC timeout的错误。解决办法有两种。第一种是在 Nginx 配置中显式增加对一个新端口的监听专门转发 gRPC 流量。Nginx 从 1.13.10 开始支持grpc_pass指令专门用于 gRPC 反向代理。但要注意gRPC 走的是 HTTP/2所以 Nginx 这边也必须开启 HTTP/2。server { listen 9848 http2; server_name nacos.example.com; location / { grpc_pass grpc://127.0.0.1:9848; } }这里的listen 9848 http2表示 Nginx 在 9848 端口监听并启用 HTTP/2 协议。grpc_pass grpc://127.0.0.1:9848把 gRPC 流量转发到后端的 Nacos gRPC 端口注意这个 URL 前缀是grpc://不是http://。第二种方式更简单粗暴直接用stream模块做 TCP 层转发不关心上层是不是 gRPC反正都是 TCP 长连接直接透传就行。stream { upstream nacos_grpc { server 127.0.0.1:9848; } server { listen 9848; proxy_pass nacos_grpc; proxy_timeout 600s; } }stream模块需要 Nginx 编译时包含了--with-stream参数。大多数发行版默认都带了这个模块你可以用nginx -V查看编译参数确认。如果没有需要重新编译或者安装对应的模块包。这两种方式我都用过个人更推荐第一种grpc_pass因为它在 Nginx 层还能做更多的 HTTP/2 层面的控制和日志记录。但如果你只是图省事第二种也是完全可行的性能上反而更好因为 TCP 转发不需要解析应用层协议。3.4 WebSocket 与长连接的超时设置Nacos 控制台页面和控制台本身有实时推送的机制在 Nacos 1.x 时代走的是 WebSocket2.x 之后主要走 gRPC。但不管哪种方式都存在长连接的问题。Nginx 默认的proxy_read_timeout是 60 秒也就是说如果后端在 60 秒内没有响应Nginx 会主动断开连接。对于 Nacos 这种需要长时间保持连接的场景这个默认值明显不够用。我一般会调整这几个参数proxy_connect_timeout 60s; proxy_send_timeout 600s; proxy_read_timeout 600s;proxy_connect_timeout是建立和后端 TCP 连接的超时时间一般默认就行。proxy_send_timeout和proxy_read_timeout是两次写操作和读操作之间的间隔超时不是总超时。设置成 600 秒是为了确保客户端长时间没有消息发送时连接不会被 Nginx 提前掐断。另外如果你还在用 Nacos 1.x并且控制台在 Firefox 或者某些特定浏览器上出现实时日志和配置发布不正常的情况很可能就是 WebSocket 连接被 Nginx 断了。这时候还需要加上 WebSocket 升级相关的 Header 配置proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;Nacos 2.x 的控制台虽然已经改用 gRPC 和 HTTP 轮询了但加上这行配置没有任何副作用反而能兼容一些特殊情况。4. 多环境与集群场景的配置方案4.1 按环境拆分域名或路径实际生产里很少有人只部署一套 Nacos。开发环境、测试环境、预发布环境、生产环境至少得有个两三套。如果每套都用独立域名Nginx 配置就很清晰每套一个 server 块就行。但如果公司域名资源不够也可以在一个域名下用路径区分利用 Nginx 的 location 匹配。我这边是开发环境、测试环境、生产环境三套 Nacos域名分别对应nacos-dev.example.com、nacos-test.example.com、nacos.example.com。每个环境在 Nginx 里配置独立的 server 块参数基本一致只是 upstream 指向不同的 Nacos 节点。这样配置的优点是逻辑清晰互不干扰排查问题的时候直接找到对应 server 块就行。如果用同一个域名不同路径的方式比如/dev-nacos/、/test-nacos/、/prod-nacos/配置上要注意 Nacos 内部回调路径的问题。前面提到过Nacos 控制台登录后会有跳转如果它不知道自己是挂在子路径下的跳转会出现路径丢失。虽然可以通过设置 Nacos 的server.servlet.context-path来解决但跨环境切换时还是容易搞混。我建议除非是临时演示生产环境尽量用不同域名区分省心很多。4.2 Nacos 集群的负载均衡Nacos 集群部署时一般会有三个或更多节点组成集群。这种情况下Nginx 的作用就从单点代理变成了负载均衡入口。客户端只需要配置 Nginx 的地址不需要知道后面到底有几个 Nacos 节点。upstream nacos_cluster { ip_hash; server 192.168.1.11:8848 weight1; server 192.168.1.12:8848 weight1; server 192.168.1.13:8848 weight1; } server { listen 80; server_name nacos.example.com; location / { proxy_pass http://nacos_cluster; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }注意我在 upstream 里使用了ip_hash负载均衡算法。为什么要用 ip_hash 而不是默认的轮询因为 Nacos 客户端的 gRPC 长连接机制是有状态的。如果客户端每次请求都被 Nginx 分发到不同的 Nacos 节点客户端就需要反复重建 gRPC 连接造成不必要的性能开销甚至可能导致服务注册状态不一致。ip_hash能保证同一个客户端 IP 的请求始终落在同一个 Nacos 节点上gRPC 长连接就能保持稳定。但 ip_hash 也有一个副作用如果客户端 IP 是动态变化的比如移动网络环境下hash 结果会变依然可能导致节点切换。不过对于大部分微服务场景客户端都是固定内网 IP 的服务器ip_hash 完全够用。如果你用的是least_conn或者默认的轮询我建议在 gRPC 入口的 stream 代理层改为 hash 一致性算法避免长连接频繁切换。4.3 使用域名和 HTTPS配置 HTTPS 是现在的主流要求尤其当 Nacos 控制台需要从公网或者公司办公网访问时明文 HTTP 传输账号密码真的很不安全。Nacos 控制台的登录接口走的虽然是 POST但如果没有 TLS 加密密码在网络里就是裸奔的抓包工具一抓一个准。Nginx 配置 HTTPS 很简单核心是证书文件和私钥文件。server { listen 80; server_name nacos.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name nacos.example.com; ssl_certificate /etc/nginx/certs/nacos.example.com.pem; ssl_certificate_key /etc/nginx/certs/nacos.example.com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; location / { proxy_pass http://127.0.0.1:8848; 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; } } server { listen 9848 http2; server_name nacos.example.com; location / { grpc_pass grpc://127.0.0.1:9848; } }HTTP 自动跳转到 HTTPS 那个 return 301 是最简单的做法把 80 端口的请求全部导到 443。$host可以保留原始请求的域名$request_uri保留原始路径和参数这样跳转后的链接不会丢失信息。ssl_protocols设置成 TLSv1.2 和 TLSv1.3 是当前的主流选择TLSv1.0 和 TLSv1.1 已经太老了不建议继续支持。还有一个细节要注意当 Nacos 域名走 HTTPS 时Nacos 控制台内部生成的重定向 URL 默认会使用https吗不一定。Nginx 需要通过X-Forwarded-Proto $scheme把原始协议告诉后端Nacos 接收到https后才会在页面跳转、Locator 生成等场景使用 HTTPS 链接。这行配置很多人容易漏掉导致 HTTPS 部署完成后页面能打开但登录后跳转回 HTTP或者某些接口回调地址变成 HTTP。5. 常见问题与排查技巧5.1 控制台访问 401 / 403这是配置 Nginx 代理 Nacos 后最常见的报错之一。场景是直接访问 Nacos 的 IP:8848 一切正常但从 Nginx 代理访问时登录接口返回 401 或者 403。排查思路先确认 Nacos 开启了鉴权。Nacos 2.2.3 及之后的版本默认开启鉴权的话需要设置nacos.core.auth.plugin.nacos.token.secret.key这些参数。如果直接 IP 访问没问题代理访问有问题问题大概率出在 Nginx 转发时改变了请求的一些特征比如 Host 头、User-Agent 或者请求来源 IP。我曾经遇到过一种情况Nacos 控制台从 Nginx 代理访问时登录一直报 401但查 Nacos 服务端日志却发现登录接口已经正常登录成功了。后来发现是 Nginx 做了重试第一次请求成功但响应超时Nginx 自动重发了一次第二次请求在 Nacos 侧导致 token 冲突返回了 401。解决方法是检查 Nginx 的proxy_next_upstream配置默认情况下 Nginx 只会对连接失败、超时之类的错误做重试一般不会对 HTTP 401 做重试所以这种情况比较少见。更常见的原因还是 Header 配置不完整导致 Nacos 的登录校验逻辑拿不到预期的参数。建议你按这个顺序排查先看 Nginx 配置里有没有加proxy_set_header Host $host再看 Nacos 服务端日志确认请求确实到达了 Nacos最后用 curl 直接模拟 Nginx 转发的请求逐步比对和直接访问的差异。5.2 访问跳转到内网 IP / 端口现象通过 Nginx 代理访问 Nacos 控制台地址栏先是显示了正确的域名但登录完成后突然跳转到http://192.168.x.x:8848/nacos/然后页面就打不开了。这个问题的根源是 Nacos 生成的跳转 URL 是基于服务器本身感知到的 Host 和端口。当你直接用 IP:8848 访问时Nacos 认为自己就在192.168.x.x:8848所以所有跳转都指向这个地址。代理访问时你必须通过 Header 告诉 Nacos外部访问的地址是域名不是内网 IP。解决方案就是前面反复强调的那行核心配置proxy_set_header Host $host;确保$host是浏览器地址栏的域名。另外还有几个 Header 也很重要proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Port $server_port;X-Forwarded-Port用来告诉 Nacos 外部访问的端口。尤其是 HTTPS 非标准端口比如 8443时少了这个 HeaderNacos 生成的跳转链接端口就会变成 443 或者 80导致跳转失败。5.3 服务注册成功但一直不健康这个问题的排查过程往往很折磨人。服务能注册到 Nacos控制台也能看到服务实例但实例状态长期是不健康或者反复在健康与不健康之间横跳。首先你需要理解 Nacos 2.x 的健康检查机制。临时实例ephemeraltrue默认通过 gRPC 长连接维持心跳。客户端会定期通过 gRPC 连接向服务端发送心跳服务端如果在preserved.heart.beat.timeout时间内没有收到心跳就会把实例标记为不健康。所以不健康的根因绝大多数情况下是 gRPC 长连接没有建立或者不稳定。而 gRPC 长连接不稳定最常见的原因就是 Nginx 只代理了 8848 端口9848 端口的流量没有正确转发或者转发超时时间设置得太短。客户端注册和心跳走的 9848 端口连接一旦被 Nginx 断开Nacos 服务端在超时后就会把实例标记为不健康直到客户端重新建立连接。解决步骤第一在 Nacos 服务端执行ss -lntp | grep 9848确认 gRPC 端口确实在监听第二在客户端所在服务器上执行nslookup nacos.example.com确认域名解析到了正确地址第三在客户端服务器上用telnet nacos.example.com 9848测试 gRPC 端口的连通性第四确认 Nginx 对 9848 端口的转发配置没有语法错误并且确实生效了。还有一个容易被忽略的点如果你在 Nginx 的 HTTP 代理里配置了proxy_read_timeout 60s而 gRPC 的连接也是通过这个代理走的那么 60 秒没有数据传输后连接会被掐断。这种问题很隐蔽因为服务注册和心跳不一定是持续不断的偶尔有一段时间没有通信连接就被断了接着就是一场心跳重连的大戏。所以把proxy_read_timeout调大或者对 gRPC 使用独立的 stream 代理配置能有效避免这个问题。5.4 大配置发布的时候超时Nacos 配置中心发布的配置如果特别大比如几百 KB 甚至几 MB 的配置文件客户端拉取时可能触发 Nginx 的响应超时。尤其在公司网络带宽受限或者跨地域访问时这个概率更高。我在一次客户现场遇到过他们的配置中心里放了一个接近 1MB 的 JSON 文件客户端通过 Nginx 拉取时频繁超时但直接访问 Nacos 节点就没问题。后来定位到是 Nginx 的proxy_read_timeout太短加上后端 Nacos 在生成响应时有点慢导致 Nginx 判定超时并主动断开。我把代理的超时时间适当调大并且加大了proxy_buffer_size和proxy_buffers因为默认的 buffer 对于大响应体来说不够用Nginx 会反复向上游读取增加了延迟。proxy_buffer_size 16k; proxy_buffers 8 32k; proxy_busy_buffers_size 64k; proxy_read_timeout 600s;如果你遇到的是大配置发布或者大量配置拉取的场景这几个参数一定要检查。特别是那些用 Nacos 作为统一配置中心、配置项非常多的项目很容易踩到这个坑。5.5 常见问题速查表问题现象根因排查方向控制台登录后跳转内网地址缺少 Host 头转发检查proxy_set_header Host $host登录接口 401/403鉴权配置或 Header 不完整对比直接访问与代理访问的请求差异服务注册成功但不健康gRPC 端口未代理或连接被断开测试 9848 端口连通性、调大超时时间控制台页面打开但接口 404路径代理时前缀被移除检查proxy_pass路径写法大配置拉取超时响应体太大、buffer 不足调整proxy_buffers和相关超时参数客户端连接频繁断开长连接超时设置过短调大proxy_read_timeout和proxy_send_timeout这张表可以贴在你自己的运维笔记里下次遇到问题直接对照排查能省下不少时间。6. 关于 gRPC 端口偏移的一个难点6.1 偏移规则与 Nginx 端口依赖Nacos 2.x 的 gRPC 端口不是独立配置的而是在主端口基础上自动加 1000。主端口是 8848gRPC 就是 9848主端口如果是 8849gRPC 就是 9849。这些端口必须保持一致且不能被防火墙拦截。Nginx 做代理时如果你用了 HTTP 代理方式并开启 HTTP/2 来转发 gRPC那么 Nginx 对外暴露的 gRPC 监听端口和后端 Nacos 的 gRPC 端口可以不一致Nginx 只需要在grpc_pass里指定后端实际端口即可。但客户端的server-addr配置必须指向 Nginx 监听的 gRPC 端口。举个例子Nacos 的 gRPC 端口是 9848Nginx 监听的对外 gRPC 端口也是 9848客户端配置server-addrnacos.example.com:80时客户端会自动尝试连接nacos.example.com:9848来建立 gRPC 连接。也就是说即使你通过 Nginx 代理了 8848 的 HTTP 请求客户端还是会在 9848 端口上找 gRPC 服务。这就意味着如果你用了 Nginx 代理80 端口代理 8848那你必须同时让 9848 端口也能访问到后端的 9848 端口。所以配置 Nginx 时必须记得在防火墙和安全组里放行 9848 端口否则客户端虽然能通过 80 端口正常访问 Nacos 的 HTTP 接口但 gRPC 连接会被防火墙拦截服务注册不健康。6.2 非标准端口的注意事项如果你因为端口冲突把 Nacos 的主端口改成了 8849比如通过server.port8849指定那么 gRPC 端口会自动变成 9849。Nginx 配置时两处都要相应调整。我之前有一次为了在一台服务器上跑两套 Nacos一套 8848/9848另一套 8849/9849结果 Nginx 配置时只改了 HTTP 代理忘了改 gRPC 端口第二套环境的所有服务注册全部失败。后来在配置里补上了对应的 9849 监听才恢复正常。这种端口偏移机制的设计初衷是让运维少配置一个端口但对使用反向代理的场景来说反而容易多出一个遗漏点。建议你画一张表格把每套 Nacos 的 HTTP 端口、gRPC 端口、Nginx 监听端口、客户端配置地址都列出来配置的时候对照着来基本不会出错。
Nginx反向代理Nacos完整指南：HTTP与gRPC端口配置及集群实践
1. 为什么需要用 Nginx 反向代理 Nacos1.1 Nacos 的访问形态与 Nginx 的角色Nacos 作为注册中心和配置中心在微服务架构里的地位不用我多说。不管是 Spring Cloud Alibaba 还是 Dubbo只要上了规模基本都离不开它。而 Nacos 默认的访问方式是直接通过 IP 加端口访问控制台默认端口是 8848gRPC 端口是 9848客户端向服务端发起注册、订阅、配置拉取时走的也是这些端口。问题来了生产环境里你不可能让所有客户端都裸连 Nacos 的 8848 端口尤其是当你有多套环境、多个服务分组或者公司内部有统一的网关入口时。这个时候在 Nacos 前面加一层 Nginx 反向代理把所有进入 Nacos 的流量统一收敛到一个入口再由 Nginx 根据路径、域名、端口做转发是最常见也最稳的做法。我在实际项目中遇到最多的场景有三种第一种公司要求所有内部系统必须走统一域名访问Nacos 控制台也要挂在域名下面第二种Nacos 做了集群部署客户端需要统一入口做负载均衡而不是自己维护一堆节点列表第三种服务通过 Nginx 暴露到外部网络但不想直接把 Nacos 的真实 IP 和端口暴露出去。这三种场景本质上都是同一个诉求让 Nacos 的访问更可控、更安全、更统一。1.2 直接暴露端口的问题很多人一开始图省事直接把 Nacos 的 8848 端口开放出去客户端配置里写死 IP。短期看确实能用但长期来看问题一堆。首先是端口管理混乱。一个 Nacos 实例涉及 8848HTTP 主端口和 9848gRPC 端口如果你部署了多套环境每套环境至少占用两个端口再加上 Nacos 2.x 版本默认还会开放 9849 之类的端口端口一多防火墙规则、安全组配置、运维排障都会变得非常痛苦。其次是安全风险。Nacos 控制台默认的鉴权机制如果配置不当很容易出现未授权访问的问题。这一点在最近的漏洞通告里反复被提及比如/nacos/v1/core/cluster/nodes这类接口在没有鉴权的情况下可能泄露集群节点信息。把 Nacos 直接暴露在公网或者大内网里等于把风险敞口放大。用 Nginx 做一层代理至少可以在入口层做 IP 白名单、访问频率限制甚至统一加一层简单的 Basic Auth比裸奔强太多了。第三是升级维护困难。Nacos 版本升级、节点扩容、故障切换如果客户端都写着固定 IP你每次变更都要改一堆客户端配置而且客户端不会自动感知节点变化。有了 Nginx 这个统一入口后端节点怎么变客户端都不需要动。所以我的建议是不管你是单机测试还是生产集群只要条件允许就在 Nacos 前面加一层 Nginx。这层代理的成本极低但带来的灵活性和安全性提升非常明显。2. 配置前的环境准备与前置条件2.1 版本选型与兼容性确认我在配置之前永远会先确认三套环境的版本Nginx 版本、Nacos 版本、客户端版本。这三个版本之间可能存在兼容性问题尤其是 Nacos 2.x 之后引入了 gRPC 长连接对代理层的要求发生了根本性变化。Nacos 1.x 时代客户端和服务端之间走的是 HTTP 短连接Nginx 只需要做普通的 HTTP 反向代理就行。但 Nacos 2.x 开始客户端和服务端之间的核心通信改成了 gRPCgRPC 基于 HTTP/2而且是长连接。如果你还用老思路只代理 8848 端口会发现客户端能连接上但服务注册、配置订阅经常超时或者控制台看着正常实际服务列表一直拉不起来。这是因为 Nacos 2.x 的客户端会先通过 8848 端口做服务发现拿到服务端地址后再尝试和偏移量 1000 的端口建立 gRPC 长连接。也就是说服务端监听 8848gRPC 长连接端口就是 9848。如果你在 Nginx 层只代理了 8848gRPC 连接建立不了服务自然注册不上。我这边实际用的是 Nginx 1.24 和 Nacos 2.2.3这个组合在我维护的几个项目里跑了大概一年多整体非常稳定。如果你用的是 Nacos 2.1.x 和 Nginx 1.18 这类老版本也可以正常工作但要特别注意 HTTP/2 相关配置的差异。Nginx 原生支持 gRPC 反向代理是从 1.13.10 开始的所以理论上 1.14 以上都行但我还是建议用 1.20 以上的版本毕竟 bug 修复和稳定性都有保障。2.2 Nacos 部署形态确认动手配置 Nginx 之前先搞清楚你的 Nacos 是怎么部署的。单机模式、集群模式、还是容器化部署这几种形态对 Nginx 配置的影响完全不一样。单机模式下你只需要关注一个节点。集群模式下Nginx 要配置多个 upstream 节点做负载均衡并且需要开启 ip_hash 或者 least_conn 之类的负载策略因为 Nacos 的 gRPC 长连接需要保持会话粘滞不然客户端频繁切换节点会导致连接重建。容器化部署的情况更复杂。如果你是用 Docker 或者 Kubernetes 部署的 Nacos需要确认容器端口映射是否正确尤其是 9848 这个 gRPC 端口有没有映射出来。我踩过一个坑Kubernetes 里只暴露了 Service 的 8848 端口Nginx 代理也只写了 8848结果服务注册死活不成功。查了半天才发现是 gRPC 端口没有同步暴露Nginx 无法连接到后端的 9848 端口。还有一个细节需要确认Nacos 的 IP 地址绑定。在application.properties里Nacos 2.x 默认会0.0.0.0监听所有网卡。如果你改了绑定地址比如只绑定了内网 IP那么 Nginx 转发时使用的主机名解析可能会出问题。我建议是保持默认监听通过防火墙或安全组来控制访问来源这样 Nginx 配置也不用特殊处理。2.3 Nginx 安装与基础验证Nginx 的安装其实没什么难度CentOS 上用 yumUbuntu 上用 aptWindows 上直接下载二进制包解压就能用。但我还是想额外强调一点如果真的打算在生产环境用尽量别用系统自带的旧版本尤其是 CentOS 7 自带的 Nginx 1.12 之类年代过于久远对 HTTP/2 和 gRPC 的支持不够完善。我一般推荐用 Nginx 官方源安装或者直接用 OpenResty后者在扩展性上更强不过只是做反向代理的话原版 Nginx 就够了。安装完之后先别急着写代理配置。先用默认配置启动一下确认 Nginx 本身能正常工作然后再去改配置。很多新手一上来就写代理结果出了问题也不知道是 Nginx 的问题还是 Nacos 的问题。基础验证很简单启动 Nginx 后直接在浏览器访问服务器 IP能看到 Nginx 的欢迎页就说明基础服务没问题。另外别忘了测试配置文件的语法。Nginx 的配置语法很严格少一个分号、多一个空格都可能起不来。修改完配置后用nginx -t做一次语法检查通过了再执行nginx -s reload平滑重载。这个习惯我从入行就养成了帮我避免了很多低级错误。3. Nginx 反向代理 Nacos 的完整配置3.1 最基础的 HTTP 代理配置我们先从最基础的开始用 Nginx 代理 Nacos 的 HTTP 访问也就是控制台和客户端通过 HTTP 访问 8848 端口的场景。这个配置我给过很多同事几乎可以直接照抄。server { listen 80; server_name nacos.example.com; location / { proxy_pass http://127.0.0.1:8848; 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; } }把server_name换成你自己的域名proxy_pass换成 Nacos 的实际地址这个配置就能跑起来。访问http://nacos.example.com就能打开 Nacos 控制台客户端的 server-addr 也可以直接配成nacos.example.com:80。这里有几个细节需要解释一下。proxy_set_header Host $host这一行非常关键。Nacos 控制台在登录后会做重定向如果 Host 头不对重定向 URL 会指向内网地址导致你从浏览器访问的时候被跳转到127.0.0.1:8848看起来就是页面打不开或者一直在加载。server_name配置的域名会和浏览器地址栏的域名一致这样才能保证 Nacos 内部生成的回跳地址正确。X-Real-IP和X-Forwarded-For是给 Nacos 传递客户端真实 IP 的。这样 Nacos 的日志里能看到真正的客户端来源而不是所有请求都显示 Nginx 的 IP。如果你后续要做 IP 白名单控制这两个头是基础。3.2 路径代理配置的细节有些场景下Nacos 不是部署在独立域名下而是和其他服务共享一个域名通过路径来区分。比如http://example.com/nacos/访问 Nacoshttp://example.com/other/访问另一个服务。这种场景就需要对路径做处理。server { listen 80; server_name example.com; location /nacos/ { proxy_pass http://127.0.0.1:8848/nacos/; 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_pass后面路径写不写、带不带尾斜杠效果完全不一样。proxy_pass http://127.0.0.1:8848;—— 不带路径Nginx 会把原始 URI 原封不动地传给后端。访问/nacos/后端收到的也是/nacos/。proxy_pass http://127.0.0.1:8848/nacos/;—— 带路径且以斜杠结尾Nginx 会把 location 中匹配到的部分替换成代理路径。访问/nacos/后端收到的也是/nacos/但在某些正则和嵌套场景下行为会有差异。proxy_pass http://127.0.0.1:8848/;—— 后端收到的路径会去掉/nacos/前缀。访问/nacos/后端收到的是/。对于 Nacos 来说我强烈建议保持路径一致也就是第一种或者第二种方式。因为 Nacos 的很多接口和静态资源路径都是写死的比如登录接口是/nacos/v1/auth/login控制台页面资源是/nacos/console/...。如果你用第三种方式去掉了前缀Nacos 会认为客户端访问的是根路径但实际的接口路径里包含了/nacos这会导致页面能打开但接口全部 404。3.3 处理 Nacos 2.x 的 gRPC 端口前面反复提到 Nacos 2.x 和 gRPC 的关系这里专门展开说。Nacos 2.x 的客户端和服务器之间的核心通信改成了 gRPC而 gRPC 是长连接走的是专门的端口。Nacos 服务器在启动时会在主端口 8848 的基础上自动偏移创建 gRPC 端口主端口 1000也就是 9848。这个端口用于客户端向服务端发起的 gRPC 连接和基于 gRPC 的服务发现、配置监听。如果你只是用 Nginx 代理 8848而不处理 9848会看到的现象是控制台能打开登录也正常但服务列表是空的或者服务注册后很快被标记为不健康。客户端日志里会反复出现类似Connection refused或gRPC timeout的错误。解决办法有两种。第一种是在 Nginx 配置中显式增加对一个新端口的监听专门转发 gRPC 流量。Nginx 从 1.13.10 开始支持grpc_pass指令专门用于 gRPC 反向代理。但要注意gRPC 走的是 HTTP/2所以 Nginx 这边也必须开启 HTTP/2。server { listen 9848 http2; server_name nacos.example.com; location / { grpc_pass grpc://127.0.0.1:9848; } }这里的listen 9848 http2表示 Nginx 在 9848 端口监听并启用 HTTP/2 协议。grpc_pass grpc://127.0.0.1:9848把 gRPC 流量转发到后端的 Nacos gRPC 端口注意这个 URL 前缀是grpc://不是http://。第二种方式更简单粗暴直接用stream模块做 TCP 层转发不关心上层是不是 gRPC反正都是 TCP 长连接直接透传就行。stream { upstream nacos_grpc { server 127.0.0.1:9848; } server { listen 9848; proxy_pass nacos_grpc; proxy_timeout 600s; } }stream模块需要 Nginx 编译时包含了--with-stream参数。大多数发行版默认都带了这个模块你可以用nginx -V查看编译参数确认。如果没有需要重新编译或者安装对应的模块包。这两种方式我都用过个人更推荐第一种grpc_pass因为它在 Nginx 层还能做更多的 HTTP/2 层面的控制和日志记录。但如果你只是图省事第二种也是完全可行的性能上反而更好因为 TCP 转发不需要解析应用层协议。3.4 WebSocket 与长连接的超时设置Nacos 控制台页面和控制台本身有实时推送的机制在 Nacos 1.x 时代走的是 WebSocket2.x 之后主要走 gRPC。但不管哪种方式都存在长连接的问题。Nginx 默认的proxy_read_timeout是 60 秒也就是说如果后端在 60 秒内没有响应Nginx 会主动断开连接。对于 Nacos 这种需要长时间保持连接的场景这个默认值明显不够用。我一般会调整这几个参数proxy_connect_timeout 60s; proxy_send_timeout 600s; proxy_read_timeout 600s;proxy_connect_timeout是建立和后端 TCP 连接的超时时间一般默认就行。proxy_send_timeout和proxy_read_timeout是两次写操作和读操作之间的间隔超时不是总超时。设置成 600 秒是为了确保客户端长时间没有消息发送时连接不会被 Nginx 提前掐断。另外如果你还在用 Nacos 1.x并且控制台在 Firefox 或者某些特定浏览器上出现实时日志和配置发布不正常的情况很可能就是 WebSocket 连接被 Nginx 断了。这时候还需要加上 WebSocket 升级相关的 Header 配置proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;Nacos 2.x 的控制台虽然已经改用 gRPC 和 HTTP 轮询了但加上这行配置没有任何副作用反而能兼容一些特殊情况。4. 多环境与集群场景的配置方案4.1 按环境拆分域名或路径实际生产里很少有人只部署一套 Nacos。开发环境、测试环境、预发布环境、生产环境至少得有个两三套。如果每套都用独立域名Nginx 配置就很清晰每套一个 server 块就行。但如果公司域名资源不够也可以在一个域名下用路径区分利用 Nginx 的 location 匹配。我这边是开发环境、测试环境、生产环境三套 Nacos域名分别对应nacos-dev.example.com、nacos-test.example.com、nacos.example.com。每个环境在 Nginx 里配置独立的 server 块参数基本一致只是 upstream 指向不同的 Nacos 节点。这样配置的优点是逻辑清晰互不干扰排查问题的时候直接找到对应 server 块就行。如果用同一个域名不同路径的方式比如/dev-nacos/、/test-nacos/、/prod-nacos/配置上要注意 Nacos 内部回调路径的问题。前面提到过Nacos 控制台登录后会有跳转如果它不知道自己是挂在子路径下的跳转会出现路径丢失。虽然可以通过设置 Nacos 的server.servlet.context-path来解决但跨环境切换时还是容易搞混。我建议除非是临时演示生产环境尽量用不同域名区分省心很多。4.2 Nacos 集群的负载均衡Nacos 集群部署时一般会有三个或更多节点组成集群。这种情况下Nginx 的作用就从单点代理变成了负载均衡入口。客户端只需要配置 Nginx 的地址不需要知道后面到底有几个 Nacos 节点。upstream nacos_cluster { ip_hash; server 192.168.1.11:8848 weight1; server 192.168.1.12:8848 weight1; server 192.168.1.13:8848 weight1; } server { listen 80; server_name nacos.example.com; location / { proxy_pass http://nacos_cluster; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }注意我在 upstream 里使用了ip_hash负载均衡算法。为什么要用 ip_hash 而不是默认的轮询因为 Nacos 客户端的 gRPC 长连接机制是有状态的。如果客户端每次请求都被 Nginx 分发到不同的 Nacos 节点客户端就需要反复重建 gRPC 连接造成不必要的性能开销甚至可能导致服务注册状态不一致。ip_hash能保证同一个客户端 IP 的请求始终落在同一个 Nacos 节点上gRPC 长连接就能保持稳定。但 ip_hash 也有一个副作用如果客户端 IP 是动态变化的比如移动网络环境下hash 结果会变依然可能导致节点切换。不过对于大部分微服务场景客户端都是固定内网 IP 的服务器ip_hash 完全够用。如果你用的是least_conn或者默认的轮询我建议在 gRPC 入口的 stream 代理层改为 hash 一致性算法避免长连接频繁切换。4.3 使用域名和 HTTPS配置 HTTPS 是现在的主流要求尤其当 Nacos 控制台需要从公网或者公司办公网访问时明文 HTTP 传输账号密码真的很不安全。Nacos 控制台的登录接口走的虽然是 POST但如果没有 TLS 加密密码在网络里就是裸奔的抓包工具一抓一个准。Nginx 配置 HTTPS 很简单核心是证书文件和私钥文件。server { listen 80; server_name nacos.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name nacos.example.com; ssl_certificate /etc/nginx/certs/nacos.example.com.pem; ssl_certificate_key /etc/nginx/certs/nacos.example.com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; location / { proxy_pass http://127.0.0.1:8848; 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; } } server { listen 9848 http2; server_name nacos.example.com; location / { grpc_pass grpc://127.0.0.1:9848; } }HTTP 自动跳转到 HTTPS 那个 return 301 是最简单的做法把 80 端口的请求全部导到 443。$host可以保留原始请求的域名$request_uri保留原始路径和参数这样跳转后的链接不会丢失信息。ssl_protocols设置成 TLSv1.2 和 TLSv1.3 是当前的主流选择TLSv1.0 和 TLSv1.1 已经太老了不建议继续支持。还有一个细节要注意当 Nacos 域名走 HTTPS 时Nacos 控制台内部生成的重定向 URL 默认会使用https吗不一定。Nginx 需要通过X-Forwarded-Proto $scheme把原始协议告诉后端Nacos 接收到https后才会在页面跳转、Locator 生成等场景使用 HTTPS 链接。这行配置很多人容易漏掉导致 HTTPS 部署完成后页面能打开但登录后跳转回 HTTP或者某些接口回调地址变成 HTTP。5. 常见问题与排查技巧5.1 控制台访问 401 / 403这是配置 Nginx 代理 Nacos 后最常见的报错之一。场景是直接访问 Nacos 的 IP:8848 一切正常但从 Nginx 代理访问时登录接口返回 401 或者 403。排查思路先确认 Nacos 开启了鉴权。Nacos 2.2.3 及之后的版本默认开启鉴权的话需要设置nacos.core.auth.plugin.nacos.token.secret.key这些参数。如果直接 IP 访问没问题代理访问有问题问题大概率出在 Nginx 转发时改变了请求的一些特征比如 Host 头、User-Agent 或者请求来源 IP。我曾经遇到过一种情况Nacos 控制台从 Nginx 代理访问时登录一直报 401但查 Nacos 服务端日志却发现登录接口已经正常登录成功了。后来发现是 Nginx 做了重试第一次请求成功但响应超时Nginx 自动重发了一次第二次请求在 Nacos 侧导致 token 冲突返回了 401。解决方法是检查 Nginx 的proxy_next_upstream配置默认情况下 Nginx 只会对连接失败、超时之类的错误做重试一般不会对 HTTP 401 做重试所以这种情况比较少见。更常见的原因还是 Header 配置不完整导致 Nacos 的登录校验逻辑拿不到预期的参数。建议你按这个顺序排查先看 Nginx 配置里有没有加proxy_set_header Host $host再看 Nacos 服务端日志确认请求确实到达了 Nacos最后用 curl 直接模拟 Nginx 转发的请求逐步比对和直接访问的差异。5.2 访问跳转到内网 IP / 端口现象通过 Nginx 代理访问 Nacos 控制台地址栏先是显示了正确的域名但登录完成后突然跳转到http://192.168.x.x:8848/nacos/然后页面就打不开了。这个问题的根源是 Nacos 生成的跳转 URL 是基于服务器本身感知到的 Host 和端口。当你直接用 IP:8848 访问时Nacos 认为自己就在192.168.x.x:8848所以所有跳转都指向这个地址。代理访问时你必须通过 Header 告诉 Nacos外部访问的地址是域名不是内网 IP。解决方案就是前面反复强调的那行核心配置proxy_set_header Host $host;确保$host是浏览器地址栏的域名。另外还有几个 Header 也很重要proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Port $server_port;X-Forwarded-Port用来告诉 Nacos 外部访问的端口。尤其是 HTTPS 非标准端口比如 8443时少了这个 HeaderNacos 生成的跳转链接端口就会变成 443 或者 80导致跳转失败。5.3 服务注册成功但一直不健康这个问题的排查过程往往很折磨人。服务能注册到 Nacos控制台也能看到服务实例但实例状态长期是不健康或者反复在健康与不健康之间横跳。首先你需要理解 Nacos 2.x 的健康检查机制。临时实例ephemeraltrue默认通过 gRPC 长连接维持心跳。客户端会定期通过 gRPC 连接向服务端发送心跳服务端如果在preserved.heart.beat.timeout时间内没有收到心跳就会把实例标记为不健康。所以不健康的根因绝大多数情况下是 gRPC 长连接没有建立或者不稳定。而 gRPC 长连接不稳定最常见的原因就是 Nginx 只代理了 8848 端口9848 端口的流量没有正确转发或者转发超时时间设置得太短。客户端注册和心跳走的 9848 端口连接一旦被 Nginx 断开Nacos 服务端在超时后就会把实例标记为不健康直到客户端重新建立连接。解决步骤第一在 Nacos 服务端执行ss -lntp | grep 9848确认 gRPC 端口确实在监听第二在客户端所在服务器上执行nslookup nacos.example.com确认域名解析到了正确地址第三在客户端服务器上用telnet nacos.example.com 9848测试 gRPC 端口的连通性第四确认 Nginx 对 9848 端口的转发配置没有语法错误并且确实生效了。还有一个容易被忽略的点如果你在 Nginx 的 HTTP 代理里配置了proxy_read_timeout 60s而 gRPC 的连接也是通过这个代理走的那么 60 秒没有数据传输后连接会被掐断。这种问题很隐蔽因为服务注册和心跳不一定是持续不断的偶尔有一段时间没有通信连接就被断了接着就是一场心跳重连的大戏。所以把proxy_read_timeout调大或者对 gRPC 使用独立的 stream 代理配置能有效避免这个问题。5.4 大配置发布的时候超时Nacos 配置中心发布的配置如果特别大比如几百 KB 甚至几 MB 的配置文件客户端拉取时可能触发 Nginx 的响应超时。尤其在公司网络带宽受限或者跨地域访问时这个概率更高。我在一次客户现场遇到过他们的配置中心里放了一个接近 1MB 的 JSON 文件客户端通过 Nginx 拉取时频繁超时但直接访问 Nacos 节点就没问题。后来定位到是 Nginx 的proxy_read_timeout太短加上后端 Nacos 在生成响应时有点慢导致 Nginx 判定超时并主动断开。我把代理的超时时间适当调大并且加大了proxy_buffer_size和proxy_buffers因为默认的 buffer 对于大响应体来说不够用Nginx 会反复向上游读取增加了延迟。proxy_buffer_size 16k; proxy_buffers 8 32k; proxy_busy_buffers_size 64k; proxy_read_timeout 600s;如果你遇到的是大配置发布或者大量配置拉取的场景这几个参数一定要检查。特别是那些用 Nacos 作为统一配置中心、配置项非常多的项目很容易踩到这个坑。5.5 常见问题速查表问题现象根因排查方向控制台登录后跳转内网地址缺少 Host 头转发检查proxy_set_header Host $host登录接口 401/403鉴权配置或 Header 不完整对比直接访问与代理访问的请求差异服务注册成功但不健康gRPC 端口未代理或连接被断开测试 9848 端口连通性、调大超时时间控制台页面打开但接口 404路径代理时前缀被移除检查proxy_pass路径写法大配置拉取超时响应体太大、buffer 不足调整proxy_buffers和相关超时参数客户端连接频繁断开长连接超时设置过短调大proxy_read_timeout和proxy_send_timeout这张表可以贴在你自己的运维笔记里下次遇到问题直接对照排查能省下不少时间。6. 关于 gRPC 端口偏移的一个难点6.1 偏移规则与 Nginx 端口依赖Nacos 2.x 的 gRPC 端口不是独立配置的而是在主端口基础上自动加 1000。主端口是 8848gRPC 就是 9848主端口如果是 8849gRPC 就是 9849。这些端口必须保持一致且不能被防火墙拦截。Nginx 做代理时如果你用了 HTTP 代理方式并开启 HTTP/2 来转发 gRPC那么 Nginx 对外暴露的 gRPC 监听端口和后端 Nacos 的 gRPC 端口可以不一致Nginx 只需要在grpc_pass里指定后端实际端口即可。但客户端的server-addr配置必须指向 Nginx 监听的 gRPC 端口。举个例子Nacos 的 gRPC 端口是 9848Nginx 监听的对外 gRPC 端口也是 9848客户端配置server-addrnacos.example.com:80时客户端会自动尝试连接nacos.example.com:9848来建立 gRPC 连接。也就是说即使你通过 Nginx 代理了 8848 的 HTTP 请求客户端还是会在 9848 端口上找 gRPC 服务。这就意味着如果你用了 Nginx 代理80 端口代理 8848那你必须同时让 9848 端口也能访问到后端的 9848 端口。所以配置 Nginx 时必须记得在防火墙和安全组里放行 9848 端口否则客户端虽然能通过 80 端口正常访问 Nacos 的 HTTP 接口但 gRPC 连接会被防火墙拦截服务注册不健康。6.2 非标准端口的注意事项如果你因为端口冲突把 Nacos 的主端口改成了 8849比如通过server.port8849指定那么 gRPC 端口会自动变成 9849。Nginx 配置时两处都要相应调整。我之前有一次为了在一台服务器上跑两套 Nacos一套 8848/9848另一套 8849/9849结果 Nginx 配置时只改了 HTTP 代理忘了改 gRPC 端口第二套环境的所有服务注册全部失败。后来在配置里补上了对应的 9849 监听才恢复正常。这种端口偏移机制的设计初衷是让运维少配置一个端口但对使用反向代理的场景来说反而容易多出一个遗漏点。建议你画一张表格把每套 Nacos 的 HTTP 端口、gRPC 端口、Nginx 监听端口、客户端配置地址都列出来配置的时候对照着来基本不会出错。
