从容器启动到注册成功,Nacos 客户端到底发了什么
"服务注册"这件事,用起来只有一行配置:
spring:
cloud:
nacos:
discovery:
server-addr: 127.0.0.1:8848
但这一行配好之后,从 Spring 容器启动完成到 Nacos 控制台看到一个实例,中间经过了五层调用。
面试问"Nacos 注册原理",答"客户端把 ip 和端口发给服务端"只能算及格。真正能加分的是说清谁触发的、发了什么、服务端怎么存的、为什么临时实例不用主动注销。
这篇按调用链走一遍。

一、先把 Nacos 跑起来
单机模式启动
# 解压后
cd nacos/bin
sh startup.sh -m standalone # Linux / Mac
startup.cmd -m standalone # Windows
-m standalone 是关键。不加这个参数,Nacos 会以集群模式启动,然后因为找不到 cluster.conf 而启动失败。
三个端口,别只记住 8848
| 端口 | 协议 | 用途 |
|---|---|---|
| 8848 | HTTP | 控制台、OpenAPI、1.x 的注册接口 |
| 9848 | gRPC | 2.x 客户端与服务端通信(= 8848 + 1000) |
| 9849 | gRPC | 2.x 服务端之间的数据同步(= 8848 + 1001) |
只有 8848 通、9848 不通,是最常见的部署事故。
现象是:控制台能打开,客户端也显示"注册成功",但服务列表是空的。原因就是 gRPC 端口没放通。
防火墙、K8s Service、云厂商安全组,三处都要检查。
2.x 为什么改用 gRPC
1.x 的模式是:客户端短轮询(每 5 秒问一次"我的服务列表变了吗")+ 服务端 UDP 推送。
问题:
- 轮询有延迟(最长 5 秒才知道有变化)
- UDP 推送不可靠,容易丢
- 连接数随实例数线性增长
2.x 改成 gRPC 长连接 + 服务端主动推送:
- 一个客户端一条连接,复用
- 变化实时推送
- 连接本身就能当心跳用(连接断了就认为是下线)
这就是 2.x 里"心跳"变简单了的原因。

二、注册是被谁触发的
不是 main 方法,也不是 @EnableDiscoveryClient,而是一个事件。
触发链条
Spring Boot 启动
→ 内嵌 WebServer 启动完成
→ 发布 WebServerInitializedEvent
→ AbstractAutoServiceRegistration 监听(实现 ApplicationListener)
→ bind(event) → start()
→ NacosServiceRegistry.register(registration)
核心代码在 AbstractAutoServiceRegistration:
public void onApplicationEvent(WebServerInitializedEvent event) {
bind(event); // 拿到端口
}
public void bind(WebServerInitializedEvent event) {
ApplicationContext context = event.getApplicationContext();
if (context instanceof ConfigurableWebServerApplicationContext cwsac
&& "management".equals(cwsac.getServerNamespace())) {
return; // 管理端口不注册
}
this.port.compareAndSet(0, event.getWebServer().getPort());
this.start(); // 触发注册
}
为什么要等这个事件?
因为在 WebServer 启动之前,你不知道真实端口。配了 server.port=0(随机端口)时尤其如此。
register 方法
NacosServiceRegistry 实现了 Spring Cloud 的 ServiceRegistry 接口:
public void register(Registration registration) {
// 1. 没配服务名就直接返回
if (StringUtils.isEmpty(registration.getServiceId())) {
return;
}
// 2. 组装 Instance
NamingService namingService = namingService();
String serviceId = registration.getServiceId();
String group = nacosDiscoveryProperties.getGroup();
Instance instance = getNacosInstanceFromRegistration(registration);
// 3. 调注册
namingService.registerInstance(serviceId, group, instance);
}
Instance 里有这些字段:
instance.setIp(registration.getHost());
instance.setPort(registration.getPort());
instance.setWeight(nacosDiscoveryProperties.getWeight());
instance.setClusterName(nacosDiscoveryProperties.getClusterName());
instance.setMetadata(registration.getMetadata());
instance.setEphemeral(nacosDiscoveryProperties.isEphemeral()); // 默认 true
注意 ephemeral 默认是 true,也就是临时实例。这是后面所有"心跳""自动剔除"行为的前提。
三、客户端在校验什么
注册之前有一轮校验,代码在 NacosNamingService#registerInstance。
校验项
private void checkInstanceIsLegal(Instance instance) throws NacosException {
// 1. 实例不能为 null
if (instance == null) {
throw new NacosException(NacosException.INVALID_PARAM, "Instance can't be null");
}
// 2. weight 必须 >= 0
if (instance.getWeight() < 0) {
throw new NacosException(NacosException.INVALID_PARAM, "Instance weight can't be negative");
}
// 3. 必须指定 ip(或者让服务端自动获取)
if (instance.getIp() == null && !instance.isEphemeral()) {
// 持久实例必须显式指定
}
}
再加上服务名合法性校验:
ParamUtils.checkParam(serviceName, groupName); // 不能为空、不能含非法字符
一个容易忽略的点:服务名不能带下划线以外的特殊字符
Nacos 2.x 对 serviceName 和 group 的字符集有限制。用 @FeignClient("user_service") 这种带下划线的名字没问题,但如果用了 user-service/v1 这种带斜杠的,会直接报参数错误。
注册前的另一件事:拿到本机 IP
这一步比想象中麻烦。InetUtils 会遍历网卡,选一个"合适的 IP"。
在多网卡机器(Docker、虚拟机、双网卡服务器)上,经常选错——注册上去的是 172.17.0.1(docker0 网桥),别的机器根本连不上。
解决办法:显式指定。
spring:
cloud:
nacos:
discovery:
ip: 192.168.1.100
或者在启动参数里加 -Dspring.cloud.nacos.discovery.ip=...。
四、服务端怎么处理
请求到了服务端,走的是 InstanceRequestHandler。
处理链路
InstanceRequestHandler.handle()
→ registerInstance(request)
→ ClientOperationService(根据 ephemeral 选实现)
├─ EphemeralClientOperationService → 临时实例
└─ PersistentClientOperationService → 持久实例
→ ServiceManager.registerInstance()
→ Service.putInstance()
→ 发布 InstanceChangeEvent
→ 推送订阅者
临时实例和持久实例,存在哪
| 临时(ephemeral) | 持久(persistent) | |
|---|---|---|
| 存储位置 | 内存(Service 的 ConcurrentHashMap) | 内存 + 磁盘(Distro 协议 / 数据库) |
| 保活方式 | 客户端连接 + 心跳 | 服务端主动健康检查 |
| 断开后 | 立即被剔除 | 保留,只是标记不健康 |
| 典型场景 | Spring Cloud | DNS 场景、固定后端 |
Spring Cloud 默认用临时实例,因为微服务实例本来就该是"活着就注册、挂了就消失"。
变更推送
Service.putInstance 之后会发布 InstanceChangeEvent,订阅了这个服务的客户端会收到推送。
2.x 的推送走的是 gRPC 的 PushRequest,比 1.x 的 UDP 可靠得多。
五、心跳:2.x 之后不用自己发了
这是 2.x 和 1.x 最大的行为差异。
1.x:客户端定时发心跳
// 每 5 秒发一次 PUT /nacos/v1/ns/instance/beat
服务端 15 秒没收到,标记不健康;30 秒没收到,剔除。
2.x:连接就是心跳
客户端和服务端建立 gRPC 长连接,连接还活着就说明实例活着。
- 连接断开 → 服务端立刻感知 → 剔除实例
- 不需要额外的
beat请求
所以 2.x 下服务下线几乎是实时的(秒级),而 1.x 要等 15~30 秒。
但这也带来一个新问题:网络抖动会导致实例被误剔除。如果你们的网络不稳定,会出现服务频繁上下线,可以在客户端配置重连参数。
六、四个常见问题,按现象排查
1. 注册上了,但服务列表是空的
先查 namespace 和 group。
客户端配了 namespace: dev,控制台看的是 public,两边对不上,永远是空的。
spring:
cloud:
nacos:
discovery:
namespace: dev # 这里填的是 namespace 的 ID,不是名字
group: DEFAULT_GROUP
namespace 要填 ID,不是名称。 这个是新手第一坑。
2. 能注册,但调用方连不上
查注册上去的 IP。
# 在客户端机器上执行
hostname -I
ifconfig
如果注册的是 172.17.x.x 或者 127.0.0.1,就是 InetUtils 选错网卡了,显式指定 spring.cloud.nacos.discovery.ip。
3. 控制台能开,注册报错
查 9848 端口。
2.x 客户端必须能访问 9848(gRPC)。只开 8848 会导致注册超时。
4. 实例频繁上下线
看心跳超时和网络。
- 2.x 下检查 gRPC 连接是否稳定
- 检查是否有 GC 停顿超过心跳间隔(长时间 Full GC 会导致连接被判死)
七、把这条链压缩成五句话
- 注册不是
main里调的,是WebServerInitializedEvent触发的——因为要等真实端口 NacosServiceRegistry.register组装Instance,ephemeral默认 true- 注册前会校验服务名、权重、IP,服务名有字符集限制
- 服务端按
ephemeral分流到内存或持久存储,变更通过事件推送给订阅者 - 2.x 用 gRPC 长连接代替心跳,下线更快,但也更容易被网络抖动误判
如果面试只给你一分钟,就说这五句。比背"客户端发送 ip 和端口"强得多。
这一节对应课程 3-1 到 3-5:Nacos 源码安装启动、Spring Boot 触发注册、客户端发起注册、注册前校验。五节连起来正好是完整的一条注册链路,视频里对着源码一行行走过。

想要这套笔记 + 源码调试记录的,扫码加我,备注「Java」👇

不用转发、不用关注,加上直接发你。
2600



被折叠的 条评论
为什么被折叠?



