Deep Dive into Nacos Service Registry: Architecture, Implementation, and Service Registration/Discovery Mechanisms

Today we share an in‑depth look at the underlying principles of the Nacos registration center, from service registration to service discovery, with detailed explanations and code examples.

1. Nacos Introduction

Before discussing Nacos, we briefly review service registration and discovery in micro‑service architectures. Service consumers need to maintain the addresses of provider nodes and remove failed nodes from configuration, which motivates the introduction of a service registry.

Service address management

Service registration

Dynamic service awareness

Nacos aims to solve unified configuration, service registration, and discovery for micro‑services, integrating both a registration center and a configuration center.

Nacos supports DNS‑based and RPC‑based service discovery, health checks via Ping/TCP and HTTP/Mysql, dynamic configuration, weighted DNS routing, and metadata management.

2. Nacos Registration Center Implementation Principles

2.1 Nacos Architecture Diagram

The architecture consists of the following modules:

Provider APP : service provider.

Consumer APP : service consumer.

Name Server : implements high‑availability routing via Virtual IP or DNS.

Nacos Server : the core server offering OpenAPI, Config Service, Naming Service, and a Raft‑based consistency protocol.

Additional components include the Nacos Console for management.

2.2 Registration Center Principles

Service registration involves three steps: registering the instance, performing health checks, and finally invoking the OpenAPI to persist the instance.

When a service instance starts, it registers itself; when it stops, it deregisters.

Consumers query the registry to discover healthy instances.

The registry periodically performs health‑check calls to ensure instance availability.

3. Nacos Source Code Analysis

3.1 Nacos Service Registration

The key Spring Cloud interface is ServiceRegistry :

public interface ServiceRegistry
{
void register(R registration);
void deregister(R registration);
void close();
void setStatus(R registration, String status);
T getStatus(R registration);
}

Nacos implements this interface with NacosServiceRegistry . The registration flow ultimately calls the Nacos client SDK’s NamingService.registerInstance() method.

public void register(Registration registration) {
if (StringUtils.isEmpty(registration.getServiceId())) {
log.warn("No service to register for nacos client...");
} else {
String serviceId = registration.getServiceId();
String group = this.nacosDiscoveryProperties.getGroup();
Instance instance = this.getNacosInstanceFromRegistration(registration);
try {
this.namingService.registerInstance(serviceId, group, instance);
log.info("nacos registry, {} {} {}:{} register finished", group, serviceId, instance.getIp(), instance.getPort());
} catch (Exception e) {
log.error("nacos registry, {} register failed...", serviceId, e);
ReflectionUtils.rethrowRuntimeException(e);
}
}
}

The registerInstance() method adds a heartbeat ( BeatInfo ) for health monitoring and then calls serverProxy.registerService() to persist the instance via OpenAPI.

public void registerInstance(String serviceName, String groupName, Instance instance) throws NacosException {
if (instance.isEphemeral()) {
BeatInfo beatInfo = new BeatInfo();
beatInfo.setServiceName(NamingUtils.getGroupedName(serviceName, groupName));
beatInfo.setIp(instance.getIp());
beatInfo.setPort(instance.getPort());
beatInfo.setCluster(instance.getClusterName());
beatInfo.setWeight(instance.getWeight());
beatInfo.setMetadata(instance.getMetadata());
beatInfo.setPeriod(instance.getInstanceHeartBeatInterval() == 0L ? DEFAULT_HEART_BEAT_INTERVAL : instance.getInstanceHeartBeatInterval());
this.beatReactor.addBeatInfo(NamingUtils.getGroupedName(serviceName, groupName), beatInfo);
}
this.serverProxy.registerService(NamingUtils.getGroupedName(serviceName, groupName), groupName, instance);
}

3.2 Nacos Service Discovery

Service discovery is triggered when a remote call (e.g., via OpenFeign) needs to locate a provider. The NacosServerList.getServers() method obtains instances through NacosNamingService.selectInstances() .

public List
selectInstances(String serviceName, String groupName, boolean healthy) throws NacosException {
return this.selectInstances(serviceName, groupName, healthy, true);
}

The underlying HostReactor maintains three maps ( serviceInfoMap , updatingMap , futureMap ) to cache service metadata and schedule periodic updates.

private Map
serviceInfoMap;
private Map
updatingMap;
private Map
> futureMap;

When a service is first requested, getServiceInfo() creates a ServiceInfo object if absent, triggers an immediate update via updateServiceNow() , and schedules regular updates with scheduleUpdateIfAbsent() .

public ServiceInfo getServiceInfo(String serviceName, String clusters) {
ServiceInfo serviceObj = this.getServiceInfo0(serviceName, clusters);
if (serviceObj == null) {
serviceObj = new ServiceInfo(serviceName, clusters);
this.serviceInfoMap.put(serviceObj.getKey(), serviceObj);
this.updatingMap.put(serviceName, new Object());
this.updateServiceNow(serviceName, clusters);
this.updatingMap.remove(serviceName);
}
this.scheduleUpdateIfAbsent(serviceName, clusters);
return this.serviceInfoMap.get(serviceObj.getKey());
}

Periodic updates are performed by a scheduled task that fetches the latest instance list from the Nacos server and refreshes the local cache.

public void scheduleUpdateIfAbsent(String serviceName, String clusters) {
if (this.futureMap.get(ServiceInfo.getKey(serviceName, clusters)) == null) {
synchronized (this.futureMap) {
if (this.futureMap.get(ServiceInfo.getKey(serviceName, clusters)) == null) {
ScheduledFuture
future = this.addTask(new HostReactor.UpdateTask(serviceName, clusters));
this.futureMap.put(ServiceInfo.getKey(serviceName, clusters), future);
}
}
}
}

In summary, Nacos registers services through Spring Cloud’s auto‑configuration, performs health‑check heartbeats, and caches service metadata locally to provide fast, resilient discovery.

Service Registration Summary

Provider registers via VIP to a high‑availability Nacos cluster using OpenAPI.

Nacos Server synchronizes data across nodes using Raft.

Service Discovery Summary

Discovery can be subscription‑based (local cache) or direct (server query).

HostReactor’s maps ( serviceInfoMap , updatingMap , futureMap ) maintain instance data and schedule updates.

For further reading, see the related articles listed at the end of the original post.