vitepress-template

Appearance

Management Services ​

**Referenced Files in This Document** - [[bi-sys/cmd/bi-sys/main.go]](file/bi-sys/cmd/bi-sys/main.go) - [[bi-sys/internal/server/server.go]](file/bi-sys/internal/server/server.go) - [[bi-sys/configs/application-dev.yaml]](file/bi-sys/configs/application-dev.yaml) - [[bi-tenant/cmd/bi-tenant/main.go]](file/bi-tenant/cmd/bi-tenant/main.go) - [[bi-tenant/internal/server/server.go]](file/bi-tenant/internal/server/server.go) - [[bi-tenant/configs/application-dev.yaml]](file/bi-tenant/configs/application-dev.yaml) - [[bi-cron/main.go]](file/bi-cron/main.go) - [[bi-cron/cmd/root.go]](file/bi-cron/cmd/root.go) - [[bi-cron/internal/config/config.go]](file/bi-cron/internal/config/config.go) - [[bi-cron/README.md]](file/bi-cron/readme.md) - [[bi-common/registry/nacos/client.go]](file/bi-common/registry/nacos/client.go) - [[bi-common/observability/logger/logger.go]](file/bi-common/observability/logger/logger.go) - [[bi-common/utils/snowflake/snowflake.go]](file/bi-common/utils/snowflake/snowflake.go)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction ​

This document describes the management and administrative backend services that collectively support system administration, tenant isolation, and automated operations across the platform. It covers:

  • bi-sys: system management service for user administration and configuration
  • bi-tenant: multi-tenant management service for tenant isolation and RBAC
  • bi-cron: distributed task scheduling service for automated data synchronization

Each service is designed to integrate with shared infrastructure components such as Nacos for configuration and service discovery, Kratos for microservice frameworks, and unified logging/tracing for observability.

Project Structure ​

The three services share a consistent structure:

  • Command entry points under cmd/<service>/main.go
  • Configuration via Nacos with environment-specific application-<env>.yaml files
  • Internal wiring via Google Wire provider sets for server creation
  • Shared libraries for Nacos registry, logging, and ID generation

Diagram sources

Section sources

Core Components ​

  • bi-sys system management service

    • Initializes Kratos application with HTTP and gRPC servers
    • Loads environment-specific Nacos configuration and bootstraps logging and ID generation
    • Wires services via Google Wire and registers with Nacos when applicable

  • bi-tenant multi-tenant management service

    • Similar bootstrap pattern to bi-sys but uses Nacos registry for service registration
    • Supports tenant isolation and RBAC through shared auth and RBAC utilities

  • bi-cron distributed task scheduler

    • Lightweight CLI built with Cobra for Kubernetes CronJob integration
    • Loads Nacos configuration, discovers target services, and executes gRPC tasks
    • Provides modular extension points for new services and tasks

Key shared infrastructure:

  • Nacos client initialization and configuration loading
  • Unified logging/tracing setup
  • Snowflake ID generator initialization

Section sources

Architecture Overview ​

The services follow a layered architecture:

  • Entry points initialize configuration, logging, and infrastructure
  • Server wiring creates HTTP/gRPC endpoints
  • Nacos handles configuration and service discovery
  • Shared libraries provide auth, RBAC, logging, and ID generation

Diagram sources

Detailed Component Analysis ​

bi-sys System Management Service ​

Role:

  • Centralized system administration and configuration management
  • Provides HTTP/gRPC endpoints for administrative operations
  • Integrates with Nacos for dynamic configuration and service discovery
  • Uses unified logging and ID generation for observability and uniqueness

Configuration management:

  • Environment-specific configuration loaded from application-<env>.yaml
  • Bootstraps logging and initializes Snowflake ID generator with Nacos-aware settings

Operational flow:

  • Parse environment flag
  • Build Kratos app with HTTP/gRPC servers
  • Initialize logger and ID generator
  • Wire application components and register with Nacos

Diagram sources

Section sources

bi-tenant Multi-Tenant Management Service ​

Role:

  • Tenant isolation and RBAC enforcement
  • Manages tenant-scoped resources and policies
  • Integrates with Nacos for configuration and service registration

Configuration management:

  • Environment-specific configuration loaded from application-<env>.yaml
  • Uses Nacos registry for service registration and discovery

Operational flow:

  • Parse environment flag
  • Load Nacos configuration and create Kratos app
  • Initialize logger and Snowflake ID generator
  • Wire application and register with Nacos registry

Diagram sources

Section sources

bi-cron Distributed Task Scheduling Service ​

Role:

  • Executes scheduled data synchronization tasks via gRPC
  • Designed for Kubernetes CronJob integration
  • Supports modular expansion for new services and tasks

Configuration management:

  • Nacos connection configured via nacos-<env>.yaml
  • Application-specific gRPC service configurations loaded from Nacos data IDs

Execution flow:

  • Load Nacos configuration
  • Discover target service address via Nacos service discovery
  • Establish gRPC connection and execute task method
  • Close connection and exit

Diagram sources

Section sources

Dependency Analysis ​

Shared dependencies and integration points:

  • Nacos client for configuration and service discovery
  • Kratos framework for HTTP/gRPC servers
  • Unified logging/tracing and Snowflake ID generator
  • Wire for dependency injection

Diagram sources

Section sources

Performance Considerations ​

  • Use environment-specific configuration files to tune timeouts and resource limits per deployment stage
  • Ensure Nacos client configuration aligns with cluster capacity and network latency
  • Configure Snowflake ID generator appropriately for throughput needs
  • Monitor gRPC client connection reuse and keep-alive settings for bi-cron tasks
  • Apply circuit breaker and retry strategies at the gRPC client level where appropriate

Troubleshooting Guide ​

Common issues and resolutions:

  • Nacos connectivity failures
    • Verify server address, port, and credentials in environment-specific YAML files
    • Confirm namespace ID and group match service registrations
  • Configuration loading errors
    • Check data IDs existence and content validity in Nacos
    • Merge precedence: later data IDs override earlier ones
  • Service discovery failures
    • Ensure target services are registered with correct service name and group
    • Validate health checks and endpoint availability
  • Logging and tracing initialization
    • Confirm logger setup parameters and environment variable propagation
  • ID generation issues
    • Validate Snowflake configuration and uniqueness constraints across instances

Section sources

Conclusion ​

The management services provide a cohesive foundation for system administration, tenant isolation, and automated operations:

  • bi-sys centralizes configuration and admin operations
  • bi-tenant enforces tenant isolation and RBAC with robust service registration
  • bi-cron enables reliable, scalable task execution integrated with Kubernetes

By leveraging shared infrastructure components and consistent configuration patterns, these services support maintainability, observability, and extensibility across environments.