vitepress-template

Appearance

System Configuration Management ​

**Referenced Files in This Document** - [[config.proto]](file/bi-sys/api/sys/v1/config.proto) - [[config.go]](file/bi-sys/internal/biz/config.go) - [[config.go]](file/bi-sys/internal/data/config.go) - [[config.go]](file/bi-sys/internal/service/config.go) - [[model.go]](file/bi-sys/internal/data/model/model.go) - [[main.go]](file/bi-sys/cmd/bi-sys/main.go) - [[nacos.go]](file/bi-sys/internal/server/nacos.go) - [[config.go]](file/bi-common/registry/nacos/config.go) - [[client.go]](file/bi-common/registry/nacos/client.go) - [[loader.go]](file/bi-common/registry/nacos/loader.go) - [[nacos-default.yaml]](file/bi-common/registry/nacos/nacos-default.yaml) - [[conf.proto]](file/bi-sys/internal/conf/conf.proto)

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 system configuration management service built on the bi-sys module. It covers configuration storage, retrieval, and update mechanisms, including environment-specific settings, configuration categories, validation rules, and default value management. It also documents the configuration data model, API endpoints, batch operations, auditing capabilities, caching strategies, change notifications, and integration with Nacos configuration management for environment-specific configuration loading.

Project Structure ​

The configuration management service spans three layers:

  • API layer: Protocol buffers define the gRPC/HTTP endpoints for configuration CRUD, listing, and cache refresh.
  • Service layer: Implements RPC handlers that translate requests into business use cases.
  • Business and Data layers: Encapsulate domain logic and persistence operations against the sys_config table.

Environment-specific configuration loading is integrated via Nacos, which supplies runtime configuration to the service bootstrap process.

Diagram sources

Section sources

Core Components ​

  • Configuration data model: Stores configuration entries in the sys_config table with fields for ID, name, key, value, type, remarks, and timestamps.
  • Business use case: Provides create, update, delete, batch delete, get by ID/key, and list operations with validation and uniqueness checks.
  • Data repository: Implements persistence operations using GORM, including existence checks and paginated queries.
  • Service layer: Exposes gRPC/HTTP endpoints for configuration management and cache refresh.
  • Nacos integration: Loads environment-specific configuration at startup and supports runtime change listening.

Section sources

Architecture Overview ​

The system integrates Nacos for environment-specific configuration loading during service bootstrap. The configuration management APIs operate independently of Nacos but can leverage Nacos for centralized runtime configuration.

Diagram sources

Detailed Component Analysis ​

Configuration Data Model ​

The SysConfig entity defines the persisted configuration record with:

  • Identity: config_id
  • Metadata: config_name, config_key, config_type (0=system builtin, 1=user-defined)
  • Value: config_value (string)
  • Audit: remark, created_by, updated_by, created_at, updated_at

Diagram sources

Section sources

Business Use Case: Validation and Uniqueness ​

  • Create validates uniqueness of config_key before insertion.
  • Update merges partial updates safely, preventing empty field overwrite and checking key uniqueness excluding the target record.
  • List applies pagination defaults and filters by name/key/type.

Diagram sources

Section sources

Data Repository: Persistence Operations ​

  • Create generates a new ID using a generator and inserts a new record.
  • Update uses selective field updates and sets updated_at.
  • GetByID/GetByKey fetch records by primary key or unique key.
  • List builds dynamic queries with LIKE filters and pagination.
  • ExistsByKey supports exclusion of a specific ID for update scenarios.

Diagram sources

Section sources

Service Layer: API Endpoints and Pagination ​

  • ListConfig: Supports pagination, filtering by name/key/type.
  • GetConfig/GetConfigByKey: Retrieve by ID or key.
  • CreateConfig/UpdateConfig/DeleteConfig/BatchDeleteConfig: Full CRUD plus batch deletion.
  • RefreshConfigCache: Placeholder for cache refresh logic.

Diagram sources

Section sources

API Definitions and Validation Rules ​

  • Endpoints:
    • GET /api/v1/sys/configs (ListConfig)
    • GET /api/v1/sys/configs/{id} (GetConfig)
    • GET /api/v1/sys/configs/key/{config_key} (GetConfigByKey)
    • POST /api/v1/sys/configs (CreateConfig)
    • PUT /api/v1/sys/configs/{id} (UpdateConfig)
    • DELETE /api/v1/sys/configs/{id} (DeleteConfig)
    • POST /api/v1/sys/configs/batch-delete (BatchDeleteConfig)
    • POST /api/v1/sys/configs/refresh-cache (RefreshConfigCache)
  • Validation:
    • String length limits for name, key, value, remark.
    • Enum-like constraint for config_type (0 or 1).
    • Positive integer constraints for IDs and pagination.
    • Min/max item counts for batch delete.

Section sources

Environment-Specific Settings and Nacos Integration ​

  • Bootstrap loads environment-specific configuration file (application-{env}.yaml) and scans into the Bootstrap schema.
  • Nacos client supports single or multiple DataIDs, configurable server/client/auth/advanced settings, and validation.
  • Loader implements Kratos config.Source and Watcher interfaces to load and watch configuration changes.

Diagram sources

Section sources

Configuration Categories, Types, and Scope ​

  • Categories/types:
    • System builtin (config_type=0): Typically immutable or restricted entries managed by the platform.
    • User-defined (config_type=1): Entries created/managed by administrators.
  • Scope:
    • System-wide: Stored in sys_config; retrieved by key/value for global consumption.
    • Tenant-specific overrides: Not implemented in the referenced code; would require extension to support tenant-scoped keys or separate tables.

Section sources

Default Value Management ​

  • Nacos default configuration embedded in YAML provides sensible defaults for server address/port, client settings, and advanced flags.
  • The DefaultConfig function loads embedded defaults and ensures a default DataId if none provided.

Section sources

Batch Operations and Auditing ​

  • BatchDeleteConfig accepts a list of IDs with min/max constraints.
  • Auditing fields (created_by, updated_by, created_at, updated_at) are maintained by the repository and returned in API responses.

Section sources

Dynamic Configuration Updates and Change Notifications ​

  • Nacos client supports ListenConfig to register callbacks for content changes.
  • Loader wraps ListenConfig into a Watcher that emits KeyValue changes per DataId.

Section sources

Configuration Caching Strategies ​

  • RefreshConfigCache endpoint is defined but currently unimplemented in the service layer.
  • Nacos client exposes advanced flags such as not_load_cache_at_start, update_cache_when_empty, and update_thread_num to tune cache behavior.

Section sources

Rollback Mechanisms ​

  • No explicit rollback mechanism is present in the referenced code for configuration updates.
  • Consider adding versioning or audit logs to enable future rollback capabilities.

Section sources

Dependency Analysis ​

The configuration management service depends on:

  • Protocol buffers for API contracts.
  • GORM for data persistence.
  • Nacos SDK for configuration sourcing and watching.
  • Kratos config for unified configuration loading.

Diagram sources

Section sources

Performance Considerations ​

  • Prefer paginated queries for large datasets.
  • Use selective field updates to minimize write overhead.
  • Tune Nacos advanced flags (e.g., update_thread_num) for high-frequency change scenarios.
  • Avoid excessive polling; rely on Nacos ListenConfig for real-time updates.

Troubleshooting Guide ​

  • Duplicate key errors occur when attempting to create or update a configuration with an existing key.
  • Not found errors are returned when querying non-existent IDs or keys.
  • Validation errors arise from violating string length or numeric constraints in API requests.
  • Nacos connectivity issues: verify server address/port, group, and DataId configuration; ensure environment-specific application-{env}.yaml is present.

Section sources

Conclusion ​

The system configuration management service provides a robust foundation for storing, retrieving, and updating configuration entries with strong validation and environment-specific loading via Nacos. While system-wide settings are supported, tenant-specific overrides and a fully implemented cache refresh mechanism are areas for future enhancement. The modular design enables straightforward extension for advanced features such as auditing, rollback, and tenant-scoped configuration resolution.