# Core Microservices in the laokou-cloud Module of KCloud-Platform-IoT

> Discover the core microservices within KCloud-Platform-IoT's laokou-cloud module. Learn about laokou-gateway, laokou-monitor, and laokou-nacos powering the IoT platform.

- Repository: [laokou/kcloud-platform-iot](https://github.com/koushenhai/kcloud-platform-iot)
- Tags: architecture
- Published: 2026-03-05

---

**The laokou-cloud module aggregates three essential Spring Boot microservices—laokou-gateway (API gateway), laokou-monitor (observability), and laokou-nacos (configuration/registry)—that form the backbone of the KCloud-Platform-IoT infrastructure.**

The `laokou-cloud` module within the [koushenhai/kcloud-platform-iot](https://github.com/koushenhai/kcloud-platform-iot) repository serves as the central infrastructure layer for the entire IoT platform. This Maven aggregator module houses the core microservices responsible for traffic management, system monitoring, and service coordination. Understanding these components is critical for deploying, scaling, and customizing the KCloud-Platform-IoT architecture.

## Overview of the laokou-cloud Architecture

The `laokou-cloud` module is defined as a Maven parent project with `pom` packaging, grouping three sub-modules that handle cross-cutting concerns. According to the [[`laokou-cloud/pom.xml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-cloud/pom.xml)](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-cloud/pom.xml), the module structure is:

```xml
<modules>
    <module>laokou-gateway</module>
    <module>laokou-monitor</module>
    <module>laokou-nacos</module>
</modules>

```

Each microservice operates as an independent Spring Boot application with distinct responsibilities, yet they share common infrastructure patterns such as reactive programming models and integration with the platform's shared libraries (e.g., `laokou-common`).

## Deep Dive into Each Microservice

### laokou-gateway: API Gateway and Traffic Management

The **laokou-gateway** microservice acts as the single entry point for all client requests, implemented using **Spring Cloud Gateway** on a reactive stack. Located in `laokou-cloud/laokou-gateway/`, this service handles routing, security enforcement, and cross-cutting concerns before forwarding requests to downstream business services.

Key architectural components include:

- **Global Filters**: The [[`AuthFilter.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/AuthFilter.java)](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-cloud/laokou-gateway/src/main/java/org/laokou/gateway/filter/AuthFilter.java) enforces authentication policies across all routes, while `CorsConfig` manages cross-origin resource sharing.
- **Dynamic Routing**: Routes are loaded from [`router.json`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/router.json) and can be refreshed dynamically via integration with the Nacos configuration center (`NacosRouteDefinitionRepository`).
- **Multi-tenant Support**: The gateway utilizes `ReactiveI18nUtils` for internationalization and tenant-aware request processing.

The entry point for this service is [[`GatewayApp.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/GatewayApp.java)](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-cloud/laokou-gateway/src/main/java/org/laokou/gateway/GatewayApp.java), which bootstraps the reactive Spring context and loads the gateway-specific auto-configurations.

### laokou-monitor: Observability and Health Management

The **laokou-monitor** microservice provides comprehensive monitoring capabilities for the entire platform ecosystem. Built on **Spring WebFlux** and **Spring Boot Actuator**, this service aggregates health metrics, exposes management endpoints, and triggers alerts when service status changes.

Core features include:

- **Actuator Endpoints**: Exposes standard Spring Boot Actuator paths such as `/actuator/health` for liveness/readiness checks and `/actuator/metrics` for runtime telemetry.
- **Custom Notifications**: The `StatusChangeNotifier` class handles service status transition events, enabling proactive alerting when microservices go offline.
- **Security Configuration**: [[`ReactiveSecurityConfig.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/ReactiveSecurityConfig.java)](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-cloud/laokou-monitor/src/main/java/org/laokou/monitor/config/ReactiveSecurityConfig.java) secures sensitive actuator endpoints using reactive Spring Security.

The service boots via [[`MonitorApp.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/MonitorApp.java)](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-cloud/laokou-monitor/src/main/java/org/laokou/monitor/MonitorApp.java), which initializes the monitoring context and registers platform-specific health indicators.

### laokou-nacos: Configuration Center and Service Registry

The **laokou-nacos** microservice embeds **Alibaba Nacos** to provide centralized configuration management, service discovery, and naming services for all platform components. Unlike standalone Nacos deployments, this module runs Nacos as a Spring Boot application within the platform's ecosystem.

Architectural highlights:

- **Embedded Server Components**: [[`NacosApp.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/NacosApp.java)](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-cloud/laokou-nacos/src/main/java/org/laokou/nacos/NacosApp.java) uses `SpringApplicationBuilder` to start multiple Nacos sub-components including the core naming server, web console, and MCP (Model Context Protocol) registry.
- **PostgreSQL Persistence**: The service includes custom MyBatis mappers such as `TenantInfoMapperByPostgresql` for persisting configuration and tenant data in PostgreSQL databases.
- **Environment-specific Configurations**: Properties files like `application-prod.properties` configure database connections, cluster modes, and server ports for different deployment environments.

This microservice enables dynamic configuration updates without redeployment and provides the service registry that allows `laokou-gateway` to discover downstream services using logical service names (e.g., `lb://device-service`).

## Practical Implementation Examples

### Building and Launching the Microservices

To compile and start the core microservices from the repository root:

```bash

# Build the laokou-cloud module and its dependencies

mvn clean package -pl laokou-cloud -am -DskipTests

# Launch each service (paths assume target directory contains the packaged JARs)

java -jar laokou-cloud/laokou-gateway/target/laokou-gateway.jar --spring.profiles.active=dev
java -jar laokou-cloud/laokou-monitor/target/laokou-monitor.jar --spring.profiles.active=dev
java -jar laokou-cloud/laokou-nacos/target/laokou-nacos.jar --spring.profiles.active=prod

```

### Configuring Dynamic Routes in Nacos

The gateway loads route definitions from Nacos configuration. A typical route configuration stored in Nacos (dataId: `gateway-routes`, group: `DEFAULT_GROUP`) appears as:

```yaml
spring:
  cloud:
    gateway:
      routes:
        - id: device-service-route
          uri: lb://device-service
          predicates:
            - Path=/api/devices/**
          filters:
            - StripPrefix=1
            - name: Retry
              args:
                retries: 3
                statuses: BAD_GATEWAY

```

The gateway's `NacosRouteDefinitionRepository` polls this configuration and updates routes without requiring a service restart.

### Consuming Configuration with Refresh Scope

Services can consume centralized configuration from Nacos using Spring Cloud's `@RefreshScope`:

```java
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.stereotype.Component;

@RefreshScope
@Component
public class IoTDeviceProperties {

    @Value("${iot.device.timeout:5000}")
    private long deviceTimeout;

    @Value("${iot.device.retry-count:3}")
    private int retryCount;

    // Business logic accessing configuration...
    public long getTimeout() {
        return deviceTimeout;
    }
}

```

When administrators update `iot.device.timeout` in the Nacos console, the value refreshes automatically in all consuming services within seconds.

## Key Source Files and Entry Points

Understanding the codebase structure requires familiarity with these critical files:

| Microservice | Key File | Purpose |
|--------------|----------|---------|
| **Gateway** | [[`GatewayApp.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/GatewayApp.java)](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-cloud/laokou-gateway/src/main/java/org/laokou/gateway/GatewayApp.java) | Spring Boot entry point initializing the reactive gateway context |
| | [[`AuthFilter.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/AuthFilter.java)](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-cloud/laokou-gateway/src/main/java/org/laokou/gateway/filter/AuthFilter.java) | Global filter implementing JWT/OAuth2 authentication logic |
| | [`router.json`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/router.json) | Default static route definitions loaded at startup |
| **Monitor** | [[`MonitorApp.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/MonitorApp.java)](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-cloud/laokou-monitor/src/main/java/org/laokou/monitor/MonitorApp.java) | Application bootstrap for the monitoring dashboard |
| | [`StatusChangeNotifier.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/StatusChangeNotifier.java) | Event listener for service health state transitions |
| **Nacos** | [[`NacosApp.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/NacosApp.java)](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-cloud/laokou-nacos/src/main/java/org/laokou/nacos/NacosApp.java) | Multi-context bootstrap for embedded Nacos server components |
| | [`TenantInfoMapperByPostgresql.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/TenantInfoMapperByPostgresql.java) | MyBatis mapper for tenant metadata persistence |
| | `application-prod.properties` | Production configuration for Nacos persistence and clustering |

## Summary

- The **laokou-cloud** module is a Maven aggregator containing three infrastructure microservices: **laokou-gateway**, **laokou-monitor**, and **laokou-nacos**.
- **laokou-gateway** provides reactive API routing, authentication via `AuthFilter`, and dynamic route loading from Nacos.
- **laokou-monitor** delivers observability through Spring Boot Actuator, exposing health endpoints and status change notifications.
- **laokou-nacos** embeds the Alibaba Nacos server for configuration management and service discovery, utilizing PostgreSQL mappers for persistence.
- All services are Spring Boot applications with entry points (`GatewayApp`, `MonitorApp`, `NacosApp`) that support externalized configuration and independent deployment.

## Frequently Asked Questions

### What is the primary role of the laokou-gateway microservice?

The **laokou-gateway** serves as the platform's API gateway, handling all inbound traffic routing, cross-origin configuration, and global security enforcement. It uses Spring Cloud Gateway to provide reactive, non-blocking request processing and dynamically loads routing rules from the Nacos configuration center, enabling zero-downtime route updates.

### How does laokou-nacos differ from a standalone Nacos installation?

Unlike standalone Nacos servers, **laokou-nacos** runs as an embedded Spring Boot application within the KCloud-Platform-IoT ecosystem. It integrates with the platform's PostgreSQL database through custom MyBatis mappers (e.g., `TenantInfoMapperByPostgresql`) and shares common infrastructure libraries. The [[`NacosApp.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/NacosApp.java)](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-cloud/laokou-nacos/src/main/java/org/laokou/nacos/NacosApp.java) bootstrap class programmatically starts multiple Nacos components using `SpringApplicationBuilder`, allowing tight integration with the platform's security and monitoring frameworks.

### Can the laokou-monitor service track custom business metrics?

Yes, while **laokou-monitor** primarily exposes standard Spring Boot Actuator endpoints (`/actuator/health`, `/actuator/metrics`), it can be extended to publish custom business metrics. The service includes a `StatusChangeNotifier` that reacts to service status changes, and developers can add custom `HealthIndicator` beans or Micrometer metrics that automatically appear in the monitoring dashboard and Prometheus scrapes.

### What configuration is required to enable dynamic route updates in the gateway?

To enable dynamic routing, ensure the `laokou-gateway` service has Nacos discovery enabled and points to the correct configuration dataId (typically `gateway-routes`) in its [`application.yml`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/application.yml). The gateway's `NacosRouteDefinitionRepository` polls Nacos for changes; when administrators update route definitions in the Nacos console, the gateway refreshes its route cache without requiring a restart, achieving hot-updating of API paths.