Appearance
Nacos 排错
Nacos 排错要先把现象切开。"Nacos 出问题了"其实可能落到控制台打不开、节点不入集群、配置读不到、配置发布失败、服务实例掉线、客户端鉴权失败——六类问题的排查路径完全不同。
可以按"控制面"和"业务面"两个清单划分：控制面看控制台能不能登录、集群节点是不是 UP、数据库有没有写进配置；业务面看客户端能不能注册、能不能读到配置、能不能发现实例。
一、控制台打不开
Nacos 3.x 控制台地址是 http://192.168.10.11:8080/next/，先确认访问的不是 8848。
bash
systemctl status nacos --no-pager
ss -lntp | egrep ':(8080|8848)\b'
journalctl -u nacos -n 100 --no-pager| 现象 | 方向 |
|---|---|
8080 根本不监听 | Nacos 没启动成功，或启动中途退出——看日志 |
8848 能通但提示去 8080 | 访问了 API 端口，不是控制台 |
| 登录后空白 | 前端资源加载失败、浏览器缓存、服务端响应异常 |
| 初始化密码页反复出现 | 数据库没存上用户信息，MySQL 连接异常 |
二、启动失败
两个日志源都要看：Nacos 自己的 start.out / nacos.log，和 systemd 的 journalctl：
bash
tail -n 200 /opt/nacos/logs/start.out
tail -n 200 /opt/nacos/logs/nacos.log
journalctl -u nacos -n 200 --no-pager| 报错方向 | 处理 |
|---|---|
| Java 版本不符合 | 安装 Java 17+，JAVA_HOME 在 systemd unit 里显式指定 |
| MySQL 连接失败 | 检查 db.url.0 的地址、端口、账号密码、3306 可达性 |
| 表不存在 | 没有导入 Nacos 对应版本的 MySQL schema 脚本 |
| 鉴权配置缺失 | 补齐 identity.key/value 和 token.secret.key |
| 内存不足 | 调低 CUSTOM_NACOS_MEMORY，确认机器剩余内存 |
Nacos 3.x 对鉴权配置的检查比旧版严格。只在文件末尾追加同名配置可能绕不过启动脚本的检查——脚本读到原始的默认空值直接报错。在原配置项位置填入有效值更可靠。
三、节点不入集群
集群管理页面只有本机节点时，三台机器的 cluster.conf 和通信端口要放在一起对比：
bash
# 每台都要确认
cat /opt/nacos/conf/cluster.conf
# 从一台测试到其他节点的端口连通性
nc -vz 192.168.10.12 8848
nc -vz 192.168.10.12 9848
nc -vz 192.168.10.12 9849
nc -vz 192.168.10.12 7848常见原因：
| 现象 | 方向 |
|---|---|
| 只看到本机 | cluster.conf 不一致或节点间端口不通 |
| 某台反复重启 | JVM 参数、MySQL 连接、配置解析错误 |
| 版本不一致 | 软链接指向不同版本目录 |
| 节点 IP 显示异常 | 多网卡环境下识别了错误的网卡地址 |
四、配置发布失败
发布失败时看控制台提示、Nacos 日志和 MySQL 三方面：
bash
# 先确认鉴权接口可用
curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/auth/user/login' \
-d 'username=nacos&password=nacos'
# 确认 MySQL 配置表能读写
mysql -unacos -pNacos@123456 -h192.168.10.11 nacos_config \
-e "select data_id, group_id, tenant_id from config_info limit 5;"| 现象 | 方向 |
|---|---|
| 403 / 鉴权失败 | Token 过期、账号密码错、鉴权参数三节点不一致 |
| 发布后列表没有 | namespace/group/dataId 三段的某一环和查询条件对不上 |
| MySQL 报错 | schema 版本和 Nacos 版本不匹配、账号权限不足 |
| 内容保存成功但应用解析失败 | 配置格式本身有问题（YAML 缩进、特殊字符） |
配置发布后如果接口异常，历史版本能快速对比修改前后差异。
五、配置不生效——三步定位
先用 API 直接读配置，排除"Nacos 里就没有"的可能：
bash
curl -sS \
'http://192.168.10.11:8848/nacos/v3/client/cs/config?dataId=ops-demo.yaml&groupName=DEFAULT_GROUP&namespaceId=&username=nacos&password=nacos'然后从应用所在机器用同样的命令测。应用机器能不能访问 Nacos 比在 Nacos 本机测试更关键。
| 现象 | 方向 |
|---|---|
| API 读不到 | 配置没发布，或 namespace/group/dataId 不一致 |
| API 能读到，应用读不到 | 应用连错了 Nacos 地址、namespace 配置不对、账号密码错 |
| 启动时能读到，运行中不变 | 应用没开动态刷新或业务代码没监听配置变更 |
| 部分实例变了 | 不同实例的启动参数或 Nacos 客户端配置不一致 |
六、服务注册不上
服务端用 API 快速验证注册能力是否正常：
bash
curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/client/ns/instance' \
-d 'serviceName=ops-demo-service' \
-d 'groupName=DEFAULT_GROUP' \
-d 'ip=192.168.10.13' \
-d 'port=18080' \
-d 'username=nacos' \
-d 'password=nacos'手工注册正常而业务应用注册不上，说明问题在应用侧。
| 现象 | 方向 |
|---|---|
| 服务名为空 | 应用配置里没写服务名 |
| 注册到错误 namespace | 环境配置不一致 |
| 连接超时 | 应用到 Nacos 的 8848/9848 不通 |
| 403 | 账号密码错、Token 过期、权限不够 |
| 注册后马上消失 | 临时实例心跳维持不了——网络、gRPC 连接、应用进程状态 |
七、实例掉线或不健康
临时实例掉线直接和心跳关联。可能原因：应用进程停了、JVM GC 长暂停导致心跳没发出去、网络抖动、Nacos gRPC 连接中断。
检查层次：
| 层 | 看什么 |
|---|---|
| 应用进程 | 进程在不在、端口在不在监听 |
| 应用日志 | Nacos 心跳日志、重连日志、鉴权错误 |
| 网络 | 应用到 Nacos 的 8848/9848 是否持续可达 |
| 控制台 | 实例的健康状态、IP、端口、分组 |
| Nacos 日志 | naming、remote、auth 相关模块的异常 |
如果只是某一批实例同时掉线，优先看它们是否在同一台宿主机、同一个网段、同一批发布版本。全部实例同时异常再考虑 Nacos 集群、数据库或入口负载均衡的问题。
八、鉴权异常
鉴权异常常见于升级、重启或改配置后。三节点的鉴权参数必须完全一致——identity.key、identity.value、token.secret.key 任何一项不同，A 节点签发的 Token 到 B 节点可能校验失败。
验证登录链路：
bash
curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/auth/user/login' \
-d 'username=nacos&password=nacos'能返回 accessToken 说明登录链路通了。后续 API 仍然 403 时，确认请求是否带了 Token 以及接口路径是否为当前版本支持的路径（Nacos 3.x 的新 /v3 接口和旧 /v1 接口返回可能不一样）。
九、复盘记录
故障复盘保留：
| 信息 | 说明 |
|---|---|
| 影响范围 | 控制台不可用 / 配置发布失败 / 服务发现异常——各自影响范围不同 |
| 时间线 | 开始时间、发现时间、恢复时间 |
| 版本和节点 | Nacos 版本、异常节点 IP、单节点还是全集群 |
| 配置变更 | 最近改过的 application.properties、配置项、权限变更 |
| 现场证据 | 控制台截图、日志片段、API 返回、端口检查结果 |
| 恢复动作 | 回滚什么配置、重启哪些节点、修了哪个数据库连接、切了哪条网络规则 |