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

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 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/master/laokou-cloud/pom.xml), the module structure is:

<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/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 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/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/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/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/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:

# 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:

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:

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/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/master/laokou-cloud/laokou-gateway/src/main/java/org/laokou/gateway/filter/AuthFilter.java)	Global filter implementing JWT/OAuth2 authentication logic
	router.json	Default static route definitions loaded at startup
Monitor	[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	Event listener for service health state transitions
Nacos	[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	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/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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}