Nacos源码与原理 01，Nacos 源码解析：服务注册的核心流程与核心数据结构

Nacos 作为主流的动态服务发现、配置管理和服务管理平台，是微服务架构中服务注册中心的核心组件。服务注册是 Nacos 最基础也最核心的能力，本文将从核心数据结构和完整注册流程两大维度，深入剖析 Nacos 服务注册的底层实现，结合核心源码还原其设计思路，帮助开发者理解 Nacos 服务注册的本质。

一、服务注册核心数据结构：服务模型的底层支撑

Nacos 服务注册的核心数据结构围绕服务 - 集群 - 实例的三层模型设计，所有注册信息的存储、交互、管理均基于这一模型展开，核心类集中在com.alibaba.nacos.api.naming.pojo包下，是理解服务注册的基础。

1.1 核心三层模型关系

Nacos 采用服务（Service）- 集群（Cluster）- 实例（Instance）三级分层结构，精准适配微服务架构中「一个服务多集群部署、一个集群多实例运行」的实际场景：

Instance（实例）：最小粒度，代表微服务的一个具体运行实例（如一台服务器上的user-service:8080），存储实例的网络信息、健康状态、元数据等；
Cluster（集群）：一组实例的集合，用于区分同一服务的不同部署集群（如杭州集群、上海集群），支持集群级别的配置（如健康检查、负载均衡策略）；
Service（服务）：微服务的抽象标识（如user-service、order-service），是集群的容器，一个服务可包含多个集群，是服务发现和注册的核心维度。

1.2 核心数据结构源码与核心属性解析

（1）Instance：服务实例核心载体

Instance是服务实例的直接映射，存储单个实例的所有关键信息，核心属性和作用如下（基于 Nacos 2.x 核心源码）：

public class Instance implements Serializable { // 实例唯一标识（可选，默认由ip+port生成） private String instanceId; // 实例IP地址（核心，服务发现的基础） private String ip; // 实例端口（核心） private int port; // 实例状态：UP(上线)/DOWN(下线)/STARTING(启动中)/OUT_OF_SERVICE(非服务状态) private InstanceStatus status = InstanceStatus.UP; // 实例权重（用于负载均衡，默认1.0，0表示不参与负载） private double weight = 1.0D; // 是否开启健康检查（默认true，由Nacos服务端检测实例健康状态） private boolean healthy = true; // 实例所属集群名称（默认DEFAULT_CLUSTER_NAME） private String clusterName = Constants.DEFAULT_CLUSTER_NAME; // 实例所属服务名称（全局唯一，关联至上层Service） private String serviceName; // 实例元数据（扩展属性，如版本号、环境、机房等，k-v结构） private Map<String, String> metadata = new HashMap<>(); // 网络协议（如http/grpc，默认http） private String protocol = Constants.DEFAULT_PROTOCOL; // 实例是否临时节点（核心：决定数据存储方式和过期策略，下文重点讲解） private boolean ephemeral = true; // 省略getter/setter/构造方法 }

核心关键点：ephemeral（临时节点）属性是 Nacos 服务注册的核心设计，直接决定实例的存储逻辑和生命周期管理。

（2）Cluster：集群配置与实例集合

Cluster封装了集群的配置信息和所属实例列表，核心属性聚焦集群级别的个性化配置，适配多集群部署需求：

public class Cluster implements Serializable { // 集群名称（如HZ/Shanghai，唯一标识服务下的集群） private String name; // 集群所属服务名称 private String serviceName; // 集群下的所有实例列表 private List<Instance> instances = new ArrayList<>(); // 健康检查配置（核心：支持TCP/HTTP/MySQL健康检查，自定义检查规则） private AbstractHealthChecker healthChecker; // 健康检查参数（如超时时间、检查间隔、失败阈值） private HealthCheckConfig healthCheckConfig = new HealthCheckConfig(); // 集群元数据（扩展配置） private Map<String, String> metadata = new HashMap<>(); // 负载均衡策略（如随机、轮询、权重，默认权重） private String loadBalancer = Constants.DEFAULT_LOAD_BALANCER; // 省略配置类和方法 }

（3）Service：服务核心抽象与集群容器

Service是 Nacos 服务注册的顶层抽象，管理一个服务下的所有集群，同时存储服务级别的全局配置，核心属性：

public class Service implements Serializable { // 服务名称（全局唯一，如group@@user-service，包含分组信息） private String name; // 服务分组（默认DEFAULT_GROUP，用于服务按业务隔离） private String group = Constants.DEFAULT_GROUP; // 服务下的所有集群列表 private Map<String, Cluster> clusters = new ConcurrentHashMap<>(); // 服务所属命名空间（用于多租户/多环境隔离，默认public） private String namespaceId = Constants.DEFAULT_NAMESPACE_ID; // 服务是否持久化（与实例ephemeral对应，决定服务级别的存储策略） private boolean persistent; // 服务元数据 private Map<String, String> metadata = new HashMap<>(); // 服务保护阈值（核心：防止实例全部下线导致服务不可用，默认0.0） private float protectThreshold = 0.0F; // 服务更新时间戳（用于一致性同步） private long lastModifiedTime; // 省略服务管理方法（如添加集群、获取实例） }

1.3 核心设计：ephemeral（临时节点）的关键作用

Instance中的ephemeral属性是 Nacos 服务注册的核心设计亮点，默认值为true，其核心作用是决定服务实例的存储方式和生命周期管理策略，直接影响 Nacos 服务端的底层实现：

存储方式差异：
- ephemeral=true（临时实例）：实例信息存储在Nacos 服务端的内存中，同时通过Raft 协议同步到集群其他节点，保证内存数据的集群一致性；
- ephemeral=false（持久化实例）：实例信息持久化到嵌入式数据库 Derby（默认）或外部数据库（如 MySQL），通过数据库保证数据持久化，即使 Nacos 集群重启，实例信息也不会丢失。
生命周期管理差异：
- 临时实例：依赖客户端心跳机制保活，客户端会定期（默认 5 秒）向 Nacos 服务端发送心跳，若服务端超过指定时间（默认 15 秒）未收到心跳，会将实例标记为不健康；超过 30 秒未收到心跳，直接删除实例信息；
- 持久化实例：无需客户端心跳，由 Nacos 服务端通过主动健康检查管理实例状态，实例信息不会因心跳中断被删除，仅会标记为不健康。
适用场景：
- 临时实例：适用于无状态微服务实例（如 Spring Cloud/Dubbo 服务），实例可以动态上下线，支持快速扩缩容；
- 持久化实例：适用于有状态服务（如数据库、消息队列），实例信息需要持久化，防止 Nacos 重启导致服务发现失败。

二、服务注册完整核心流程（客户端 → 服务端）

Nacos 服务注册采用客户端主动发起注册请求 + 服务端分层处理 + 数据持久化 / 内存存储 + 集群一致性同步的设计，核心流程分为客户端侧和服务端侧两大部分，覆盖从请求发起、参数校验到数据存储、集群同步的全链路，以下基于 Nacos 2.x 核心源码（OpenAPI + 核心业务层）展开解析。

2.1 整体流程概览

Nacos 服务注册的核心链路可概括为：客户端构造实例信息→ 调用 Nacos OpenAPI 发起注册请求 → 服务端 OpenAPI 层接收请求并参数校验 → 服务端核心业务层处理（创建 / 获取 Service/Cluster） → 实例信息存储（内存 / Raft / 数据库） → 集群一致性同步 → 返回注册成功响应 → 客户端开启心跳保活（临时实例）。

2.2 客户端侧：实例信息构造与注册请求发起

客户端侧核心依赖 Nacos 提供的NamingService接口，主流微服务框架（Spring Cloud Alibaba/Dubbo）均基于此接口封装服务注册逻辑，核心步骤 2 步：

步骤 1：构造 Instance 实例，设置核心属性

客户端首先根据自身运行信息（IP、端口、服务名）构造Instance对象，指定集群、元数据、是否为临时节点等核心属性，示例伪代码：

// 1. 获取Nacos命名服务实例 NamingService namingService = NacosFactory.createNamingService("nacos-server:8848"); // 2. 构造服务实例 Instance instance = new Instance(); instance.setIp(InetAddress.getLocalHost().getHostAddress()); // 本机IP instance.setPort(8080); // 服务端口 instance.setServiceName("user-service"); // 服务名 instance.setClusterName("HZ"); // 所属集群 instance.setEphemeral(true); // 临时实例（默认） instance.setMetadata(Collections.singletonMap("version", "v1")); // 元数据 instance.setWeight(1.0D); // 权重

步骤 2：调用 registerInstance 方法发起注册请求

通过NamingService.registerInstance()方法将实例注册到 Nacos 服务端，该方法最终通过HTTP POST 请求调用 Nacos 服务端的 OpenAPI/nacos/v1/ns/instance，核心伪代码：

// 3. 发起服务注册 namingService.registerInstance(instance.getServiceName(), instance); // 底层调用OpenAPI：POST http://nacos-server:8848/nacos/v1/ns/instance // 请求参数包含：serviceName、ip、port、clusterName、ephemeral、metadata等

核心细节：客户端注册成功后，若为临时实例（ephemeral=true），会立即开启心跳定时任务（默认 5 秒一次），向服务端/nacos/v1/ns/instance/beat接口发送心跳，保活实例状态。

2.3 服务端侧：OpenAPI 层 - 请求接收与参数校验

Nacos 服务端通过RESTful OpenAPI接收客户端注册请求，核心入口为InstanceController类的register方法，属于服务端的接入层，核心职责是请求接收、参数解析和基础校验，不处理核心业务逻辑，保证接入层的轻量性。

核心源码（InstanceController.register）

@RestController @RequestMapping("/nacos/v1/ns/instance") public class InstanceController { @Autowired private InstanceService instanceService; @PostMapping public String register(HttpServletRequest request) { try { // 1. 解析请求参数（从Request中提取ip、port、serviceName、ephemeral等） String serviceName = WebUtils.required(request, "serviceName"); String ip = WebUtils.required(request, "ip"); int port = Integer.parseInt(WebUtils.required(request, "port")); String clusterName = WebUtils.optional(request, "clusterName", Constants.DEFAULT_CLUSTER_NAME); boolean ephemeral = Boolean.parseBoolean(WebUtils.optional(request, "ephemeral", "true")); // 解析元数据、权重等其他参数... // 2. 基础参数校验（IP格式、端口范围、服务名非空等） checkParam(ip, port, serviceName); // 3. 调用核心业务层处理注册逻辑 instanceService.registerInstance(serviceName, clusterName, new Instance(ip, port, ephemeral, ...)); // 4. 返回注册成功响应（JSON格式：{"code":200,"message":"success","data":null}） return WebUtils.success(); } catch (Exception e) { log.error("Instance register failed", e); return WebUtils.failure(e.getMessage()); } } }

核心职责：OpenAPI 层仅做「参数解析 + 基础校验 + 请求转发」，将业务逻辑解耦到核心业务层InstanceService，符合「单一职责」设计原则，便于后续扩展和维护。

2.4 服务端侧：核心业务层 - Service/Cluster 的创建与获取

核心业务层由InstanceService接口及其实现类InstanceServiceImpl提供，这一层是服务注册的核心处理层，核心职责是基于服务名、集群名，完成 Service 和 Cluster 的懒加载创建（不存在则创建，存在则直接获取），保证「服务 - 集群 - 实例」三层模型的完整性，为后续实例存储做准备。

核心处理逻辑（InstanceServiceImpl.registerInstance）

@Service public class InstanceServiceImpl implements InstanceService { @Autowired private ServiceManager serviceManager; @Override public void registerInstance(String serviceName, String clusterName, Instance instance) { // 1. 处理服务名（拼接分组，生成全局唯一服务名：group@@serviceName） serviceName = NamingUtils.getGroupedName(serviceName, Constants.DEFAULT_GROUP); // 2. 懒加载创建/获取Service对象（核心：服务不存在则初始化创建） Service service = serviceManager.getOrCreateService(Constants.DEFAULT_NAMESPACE_ID, serviceName); // 3. 懒加载创建/获取Cluster对象（核心：集群不存在则初始化创建） Cluster cluster = service.getOrCreateCluster(clusterName); // 4. 将实例添加到集群的实例列表中 cluster.addInstance(instance); // 5. 调用存储层，完成实例信息的持久化/内存存储 persistService(service, instance); } }

核心细节：

懒加载创建：Nacos 不会提前创建 Service 和 Cluster，而是在第一个实例注册时才初始化创建，避免空服务占用资源，适配微服务动态注册的特点；
全局唯一标识：Service 的全局唯一标识由「命名空间 ID + 分组名 + 服务名」组成，保证多租户、多分组下的服务隔离；
线程安全：ServiceManager中通过ConcurrentHashMap管理所有 Service，getOrCreateService方法通过加锁保证多线程下的创建安全性。

2.5 服务端侧：存储层 - 基于 ephemeral 的差异化存储

存储层是服务注册的数据落地层，核心逻辑是根据实例的 ephemeral 属性（是否临时节点），执行差异化的存储策略，这一层直接承接核心业务层的处理结果，将实例信息落地到内存、Raft 集群或数据库，是 Nacos 服务注册的底层实现核心。

核心存储逻辑（伪代码简化版）

private void persistService(Service service, Instance instance) { boolean ephemeral = instance.isEphemeral(); if (ephemeral) { // 临时实例：内存存储 + Raft集群同步 // 1. 将实例信息写入Nacos服务端内存（ConcurrentHashMap） inMemoryStorage.put(instance.getServiceName(), instance); // 2. 通过Raft协议将实例信息同步到Nacos集群其他节点，保证集群一致性 raftProtocol.syncInstance(instance); } else { // 持久化实例：数据库存储（Derby/MySQL） // 1. 将Service/Cluster/Instance信息持久化到数据库表（nacos_service/nacos_cluster/nacos_instance） dbStorage.insertOrUpdateInstance(instance); // 2. 数据库操作完成后，更新内存缓存，保证服务发现的性能 inMemoryStorage.refreshCache(instance.getServiceName()); } }

存储层核心设计：

临时实例：采用「内存为主 + Raft 同步」的策略，兼顾性能和集群一致性，内存操作保证服务发现的低延迟，Raft 协议保证 Nacos 集群节点间的数据一致；
持久化实例：采用「数据库持久化 + 内存缓存」的策略，兼顾数据可靠性和查询性能，数据库保证数据不丢失，内存缓存避免频繁查询数据库。

2.6 服务端侧：集群一致性同步与响应返回

集群一致性同步：完成实例存储后，Nacos 会根据存储策略执行集群同步：临时实例通过 Raft 协议将实例信息同步到集群所有节点；持久化实例通过数据库的事务特性保证集群节点查询到一致的数据（Nacos 集群节点共享同一数据库）；
返回注册成功响应：所有处理完成后，服务端通过 OpenAPI 层向客户端返回200 成功响应，包含统一的 JSON 格式结果；
客户端后续操作：客户端收到成功响应后，若为临时实例，立即启动心跳定时任务，持续向服务端发送心跳保活；若为持久化实例，无需心跳，由服务端主动执行健康检查。

三、核心流程总结

Nacos 服务注册的核心流程围绕「三层模型」和「差异化存储」两大核心设计展开，从客户端到服务端的全链路可总结为 5 个核心阶段：

客户端构造：构造 Instance 实例，设置 IP、端口、服务名、ephemeral 等核心属性，发起 HTTP 注册请求；
接入层处理：服务端 OpenAPI 层（InstanceController）接收请求，解析并校验参数，转发至核心业务层；
业务层处理：核心业务层（InstanceService）懒加载创建 / 获取 Service 和 Cluster，构建完整的「服务 - 集群 - 实例」三层模型；
存储层落地：根据 ephemeral 属性执行差异化存储，临时实例存内存 + Raft 同步，持久化实例存数据库 + 更新缓存；
后续保活：客户端注册成功后，临时实例开启心跳保活，持久化实例由服务端主动健康检查，服务端完成集群一致性同步。

四、设计亮点与核心价值

三层模型设计：服务 - 集群 - 实例的分层结构，精准适配微服务多集群、多实例的部署场景，支持集群级、服务级的精细化配置；
ephemeral 差异化存储：通过临时 / 持久化实例的区分，兼顾了无状态服务的动态性和有状态服务的可靠性，适配不同业务场景；
懒加载创建：Service/Cluster 在首个实例注册时才创建，避免空资源占用，提升 Nacos 服务端的资源利用率；
分层架构设计：OpenAPI 层、业务层、存储层解耦，各层职责单一，便于扩展和维护（如新增存储方式、扩展健康检查规则）；
性能与一致性兼顾：临时实例的内存 + Raft 设计，既保证了服务发现的低延迟，又保证了集群数据的一致性；持久化实例的数据库 + 缓存设计，兼顾了数据可靠性和查询性能。