vitepress-template

Appearance

Configuration and Deployment ​

**Referenced Files in This Document** - [[main.go]](file/bi-basic/cmd/server/main.go) - [[wire.go]](file/bi-basic/cmd/server/wire.go) - [[application-dev.yaml]](file/bi-basic/configs/application-dev.yaml) - [[application-test.yaml]](file/bi-basic/configs/application-test.yaml) - [[application-prod.yaml]](file/bi-basic/configs/application-prod.yaml) - [[conf.proto]](file/bi-basic/app/service/internal/conf/conf.proto) - [[Dockerfile]](file/bi-basic/dockerfile) - [[deployment.yaml]](file/bi-basic/k8s/deployment.yaml) - [[service.yaml]](file/bi-basic/k8s/service.yaml) - [[client.go]](file/bi-common/registry/nacos/client.go) - [[discovery.go]](file/bi-common/registry/nacos/discovery.go) - [[config.go]](file/bi-common/registry/nacos/config.go) - [[logger.go]](file/bi-common/observability/logger/logger.go) - [[metrics.go]](file/bi-common/observability/metrics/metrics.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
  10. Appendices

Introduction ​

This document explains the configuration management and deployment patterns for bi-basic, focusing on environment-specific configuration files, Nacos integration, and the Kratos bootstrap process. It also covers service registration and discovery, health check considerations, containerization, Kubernetes deployment manifests, scaling, monitoring, logging, and operational procedures for the foundational data services layer.

Project Structure ​

The bi-basic module follows a layered structure aligned with Kratos conventions:

  • Entry point initializes configuration from Nacos, sets up logging, wires dependencies, and starts servers.
  • Configuration is defined via protobuf and environment-specific YAML files.
  • Containerization uses a two-stage Docker build and Kubernetes manifests define deployment and service exposure.

Diagram sources

Section sources

Core Components ​

  • Bootstrap configuration model: Defines Server, Data, Log, and Nacos fields for structured configuration loading.
  • Environment-specific application YAML files: Provide Nacos server/client/config settings per environment.
  • Kratos bootstrap: Loads configuration from Nacos, sets up logging, wires dependencies, and runs the application.
  • Nacos integration: Provides configuration center and service discovery capabilities.
  • Logging and metrics: Centralized logging setup and Prometheus metrics for observability.

Section sources

Architecture Overview ​

The system boots through Kratos, loads environment-specific configuration from Nacos, initializes logging, and wires the application components. Services are registered with Nacos for discovery and can expose health endpoints. Metrics are exported for monitoring.

Diagram sources

Detailed Component Analysis ​

Configuration Management ​

  • Environment selection: The entrypoint reads the -env flag to choose the appropriate application-<env>.yaml file.
  • Nacos configuration source: The selected YAML defines Nacos server address/port, namespace/group, and data IDs for configuration retrieval.
  • Bootstrap scanning: The loaded configuration is scanned into the Bootstrap struct, which includes Server, Data, Log, and reserved Nacos fields.

Diagram sources

Section sources

Kratos Bootstrap and Dependency Injection ​

  • Wire setup: The wireApp function composes providers for server, Kafka, data, business, and service layers, returning a configured Kratos app.
  • Application lifecycle: The app is created with ID, name, version, logger, servers, and registrar, then started.

Diagram sources

Section sources

Nacos Integration ​

  • Client creation: The Nacos client encapsulates configuration and naming clients, supports publishing/listening to configurations, and exposes convenience methods for service registration and discovery.
  • Discovery helpers: Methods support registering/deregistering instances, discovering healthy/all instances, selecting one healthy instance, subscribing/unsubscribing to service changes, and listing all services.

Diagram sources

Section sources

Service Registration and Discovery ​

  • Registration: The service registers itself with Nacos under a group and cluster, marking instances as ephemeral and healthy.
  • Discovery: Consumers can discover healthy instances, subscribe to changes, and select one instance for load-balanced routing.
  • Health checks: While explicit health endpoints are not present in the analyzed files, the Nacos client supports service liveness via heartbeat and ephemeral instances.

Diagram sources

Section sources

Logging Setup ​

  • Logger composition: Supports stdout, file, or combined output with JSON or text format.
  • File rotation: Uses lumberjack or daily rotation with configurable retention and compression.
  • Aliyun logging: Optional integration with Aliyun log service.

Diagram sources

Section sources

Monitoring and Metrics ​

  • Metrics: Exposes HTTP request counts/durations, DB query totals/errors/durations, cache hits/misses/latency, and business operation counters.
  • Export: Prometheus metrics are registered globally and can be scraped by a Prometheus server.

Diagram sources

Section sources

Containerization and Kubernetes Deployment ​

  • Docker build: Two-stage build with Go builder and minimal Alpine runtime; copies configs and binary; exposes port 10086; runs via CMD.
  • Kubernetes:
    • Deployment: Sets DEPLOY_ENV from a ConfigMap, injects Nacos credentials from a Secret, runs the server with -env $(DEPLOY_ENV), and exposes containerPort 10086.
    • Service: NodePort service exposing HTTP traffic on 10086 with a fixed nodePort for development/testing.

Diagram sources

Section sources

Dependency Analysis ​

  • Entry point depends on Nacos configuration source, Kratos config loader, Bootstrap proto, and logger setup.
  • Wire assembly composes server, Kafka, data, business, and service providers into a Kratos app.
  • Nacos client encapsulates configuration and naming clients, enabling centralized config and service discovery.

Diagram sources

Section sources

Performance Considerations ​

  • Connection pooling: Configure database pool sizes and timeouts in the Data section of the Bootstrap config to balance throughput and resource usage.
  • Kafka consumers: Tune worker counts and offsets per topic to align with event volume and processing capacity.
  • Resource requests/limits: Adjust CPU/memory requests/limits in the Kubernetes deployment to prevent throttling and improve stability.
  • Logging: Prefer JSON format for structured logs and enable file rotation to avoid disk pressure.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

  • Configuration loading failures: Verify the selected application-<env>.yaml exists and contains valid Nacos server/client/config sections.
  • Nacos connectivity: Confirm Nacos server address/port/group/namespace match the environment and credentials are set via Secrets.
  • Service registration: Ensure the service registers with the correct group and cluster; check ephemeral instance heartbeats.
  • Health checks: If health endpoints are not defined, rely on Nacos liveness via heartbeats and ephemeral instances.
  • Logs: Check both stdout and rotated files; confirm log level and format settings; verify Aliyun logging configuration if enabled.

Section sources

Conclusion ​

bi-basic leverages Kratos for a clean bootstrap and dependency injection model, integrates Nacos for centralized configuration and service discovery, and provides robust logging and metrics for observability. The containerization and Kubernetes manifests support straightforward deployment across environments, with clear separation of concerns for configuration, logging, and monitoring.

[No sources needed since this section summarizes without analyzing specific files]

Appendices ​