Logo

菜单

易君召
发布于 2026-09-07 / 作者：易君召 / 3 阅读
0

Nacos 常见问题分析与排查

Nacos 核心能力：服务注册发现 + 配置中心，问题主要分为：服务注册异常、配置读取异常、集群问题、存储、网络、权限、版本兼容、性能问题。下面整理生产高频故障、根因、排查思路、解决方案。

一、服务注册 & 发现问题（微服务最常见）

1. 服务实例注册不上 Nacos

现象：应用启动日志无报错，但 Nacos 控制台看不到服务；或者控制台实例列表为空。 常见根因

  1. 配置错误：spring.cloud.nacos.discovery.server‑addr 地址写错，端口错误（Nacos 默认 8848，注意 2.x 不写 http://；集群逗号分隔，不要加空格）

# 错误
server-addr: http://127.0.0.1:8848
# 正确
server-addr: 127.0.0.1:8848,127.0.0.2:8848

  1. 网络不通：应用服务器无法访问 Nacos 8848；防火墙、安全组拦截；Docker 容器内网地址无法对外暴露。

  2. 命名空间不匹配：代码指定 namespace，控制台看的是 public；namespace ID 不是名字，要用 ID。

  3. 分组 Group 不一致：服务注册指定 Group，控制台筛选没选对应 Group。

  4. SpringBoot / SpringCloud Alibaba 版本不兼容（大坑）版本错会直接注册失效。

  5. 应用没有引入 spring‑cloud‑starter‑alibaba‑nacos‑discovery 依赖。

  6. 应用启动太快，Nacos 客户端初始化还没完成就退出；短生命周期程序。

排查步骤

  1. 看应用启动日志，搜索 nacos，是否输出 register service success

  2. 应用机器执行 telnet nc -zv nacos-ip 8848 验证连通性

  3. 核对 namespaceId、group；不要用 namespace 名称，使用 ID

  4. 核对 SpringCloud Alibaba 版本矩阵

2. 实例显示不健康 / 下线，频繁上下线（抖动）

现象：实例一会在线，一会消失；控制台健康状态 false。 根因：

  1. 客户端心跳超时：客户端默认 5 秒心跳；服务端 15 秒没收到心跳标记不健康，30 秒剔除实例。

  • 客户端机器 CPU 高、GC 卡顿，心跳线程阻塞。

  1. 网络抖动：防火墙、负载均衡会话超时，心跳包丢包。

  2. 客户端与服务端时钟时间差过大。

  3. Docker 容器注册内网 IP，外部服务无法访问；ip‑type: external 配置对外注册公网 IP。

spring.cloud.nacos.discovery.ip-type: EXTERNAL

  1. Nacos 服务端压力大，处理心跳队列积压。

调优参数

spring.cloud.nacos.discovery.heart-beat-interval: 5000
spring.cloud.nacos.discovery.heart-beat-timeout: 15000
spring.cloud.nacos.discovery.ip-delete-timeout: 30000

3. 消费者拿不到服务实例列表

现象：服务已经注册成功，调用报找不到服务实例。

  1. 消费者的 namespace、group 和提供者不一致。

  2. 消费者没有开启发现：@EnableDiscoveryClient

  3. 消费者本地缓存还没刷新；Nacos 客户端订阅推送延迟。

  4. 服务全部不健康，过滤之后实例列表为空。

二、Nacos 配置中心常见问题

1. 项目读取不到 Nacos 配置

现象：Nacos 控制台配置存在，应用读不到配置值。

  1. 优先级问题：bootstrap.yml/bootstrap.yaml SpringCloud 必须使用 bootstrap，application.yml 加载晚，拿不到 nacos 配置。

SpringBoot 2.4+ 默认不加载 bootstrap，需要引入依赖：

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>

  1. dataId 拼接规则没搞懂 dataId = ${spring.application.name}-${spring.profiles.active}.${file‑extension}

  2. group 不匹配；namespaceId 不一致。

  3. file‑extension 文件后缀写错，支持 yaml/properties，yml 不识别，要用 yaml。

  4. 配置没有发布，仅保存。

  5. 配置加密错误，密钥不对。

2. @RefreshScope 动态刷新不生效

  1. 类没有加 @RefreshScope；静态变量无法自动刷新。

  2. 修改的配置项没有触发 Nacos 配置变更推送。

  3. 版本 bug：部分 Spring‑Cloud‑Alibaba 版本存在刷新 bug。

  4. 本地缓存问题，客户端没有收到变更事件。

注意：@Value 配合 @RefreshScope 才支持刷新；@ConfigurationProperties 默认支持刷新，不需要加注解。

3. 配置变更频繁推送，客户端大量日志

  • 同一个 dataId 重复发布；或者集群同步抖动。

三、Nacos 集群问题

1. 集群节点状态异常，部分节点无法加入集群

  1. cluster.conf 配置所有节点 IP:8848，不要写 127.0.0.1；所有节点配置完全一样。

  2. 节点之间网络互通，端口 7848 集群通信端口必须开放！集群间 Raft 通信端口 7848，很多人只开 8848，集群直接异常。

  3. 时间同步，所有服务器时间必须一致。

  4. 数据库必须统一，所有集群节点指向同一个 MySQL 库。

  5. Nacos2.x gRPC 端口 9848/9849 也要开放，客户端 2.x 使用 gRPC 通信。

Nacos2.x 端口清单

  • 8848：http 端口

  • 9848：gRPC 客户端端口

  • 9849：gRPC 内部端口

  • 7848：Raft 集群通信端口

2. 集群选主异常，leader 频繁切换

根因：

  1. 节点网络延迟高，Raft 心跳超时。

  2. 节点数少于 3 个，集群高可用要求至少 3 节点。

  3. 磁盘 IO 性能差，写快照慢，leader 超时。

  4. jvm 内存不足，GC 停顿。

3. 读写分离，访问不同节点看到的数据不一致

Raft 协议，写请求必须落到 leader；follower 同步延迟。

  • 客户端配置多个 server‑addr，会随机访问节点；如果访问 follower，短暂数据延迟。

  • 不要把 Nacos 集群前面套普通负载均衡做统一入口，容易出现各种诡异问题。

四、存储相关问题

1. 内置 Derby 数据库（单机模式）

  • 单机默认 Derby，重启数据丢失；生产必须切换 MySQL。

  • 切换数据库：修改 conf/application.properties，开启 mysql 配置，执行 mysql 初始化脚本 nacos‑mysql.sql。

2. MySQL 使用踩坑

  1. MySQL 版本：Nacos2.x 推荐 MySQL8；MySQL5.7 也支持。

  2. 数据库时区必须正确；

  3. 数据库连接池过小，集群节点多导致连接耗尽。

db.pool.config.maximum-pool-size=20

  1. 数据库宕机，Nacos 服务依然可以读缓存，但无法写入注册和配置。

五、权限认证问题 Nacos-Auth

  1. 登录 403 无权限，nacos.core.auth.enabled=true 开启鉴权后，默认密钥要修改。

nacos.core.auth.server.identity.key=nacos
nacos.core.auth.server.identity.secret=xxx自定义

  1. 客户端需要配置 access‑key /secret‑key，否则注册、读取配置报 403。

spring.cloud.nacos.discovery.access-key: xxx
spring.cloud.nacos.discovery.secret-key: xxx

  1. 旧版本升级开启鉴权后老客户端不兼容。

六、性能与生产常见坑

  1. Nacos 服务端 GC 频繁，CPU 高

  • JVM 堆内存配置，单机建议 2‑4G；集群节点根据实例数量调大。

  • 大量服务实例（几千以上）需要调优参数。

  1. 客户端大量打印 too many subscribed 过多订阅 dataId，内存上涨。

  2. Nacos 2.x gRPC 连接泄漏 低版本 bug，建议升级稳定版本：2.3.2 / 2.4.x。

  3. Docker 部署 Nacos 坑

  • 容器内部 hostname 解析问题；cluster.conf 写宿主机 IP 不要写容器名。

  • 持久化挂载目录缺失，重启丢数据。

七、快速排查排障流程（故障排查模板）

  1. 区分是配置中心问题还是服务注册发现问题

  2. 看应用客户端日志，搜索 nacos 关键字，看报错：连接异常、鉴权 403、注册失败、订阅失败。

  3. 网络检查：8848、9848、7848 端口连通性。

  4. 核对四件套：server‑addr、namespaceId、group、版本兼容。

  5. Nacos 服务端日志目录：nacos/logs/

    • nacos.log：主日志

    • raft‑meta.log：集群 raft 选主日志

    • config.log：配置中心日志

    • naming.log：服务注册发现日志

  6. 集群看 leader 节点：控制台集群管理查看节点角色。

八、版本避坑总结

  • 不建议：2.2.0、2.2.1 存在不少 gRPC、内存泄漏 bug

  • 稳定版本：2.3.2（生产使用最多）；新版本 2.4.3

  • Spring Cloud Alibaba 版本一定要和 Nacos 客户端版本对齐。

本文原创作者：易君召，详见：https://www.yijunzhao.cn/authors/yijunzhao，转载请注明出处。

原文链接 https://www.yijunzhao.cn/archives/nacos-common-problems-troubleshooting-guide

欢迎访问 小易撩挨踢

https://www.yijunzhao.cn/

AI 应用开发常用框架
常见配置文件格式对比与特点