configuration-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuration Management

配置管理

Part of Agent Skills™ by googleadsagent.ai™

属于Agent Skills™，由googleadsagent.ai™提供

Description

概述

Configuration Management implements dynamic configuration with hot-reload capability, inspired by Nacos configuration management patterns. Applications fetch their configuration from a centralized store, subscribe to change notifications, and apply updates without restarting. This eliminates the traditional deploy-to-change-config cycle and enables runtime tuning of feature flags, rate limits, and behavior parameters.

Static configuration files (

.env

config.yaml

) force a deployment for every parameter change. In production systems handling real traffic, this creates unnecessary risk and delay. Dynamic configuration separates deployment (code changes) from tuning (parameter changes), allowing operators to adjust rate limits, enable feature flags, rotate credentials, and modify routing rules without touching the deployment pipeline.

This skill covers the full configuration lifecycle: schema definition with validation, centralized storage with versioning, push-based change notification, client-side caching with TTL, and rollback to any previous version. Configuration changes are treated as auditable events with the same rigor as code deployments.

配置管理模块实现了支持热重载的动态配置功能，灵感来源于Nacos配置管理模式。应用从中心化存储获取配置，订阅变更通知，无需重启即可应用更新。这消除了传统“变更配置需重新部署”的循环，支持在运行时调整功能标志、速率限制和行为参数。

静态配置文件（

.env

、

config.yaml

）要求每次参数变更都重新部署。在处理实时流量的生产系统中，这会带来不必要的风险和延迟。动态配置将部署（代码变更）与调优（参数变更）分离，允许运维人员调整速率限制、启用功能标志、轮换凭证和修改路由规则，而无需触及部署流水线。

该技能覆盖完整的配置生命周期：带校验的 Schema 定义、带版本控制的中心化存储、基于推送的变更通知、带TTL的客户端缓存，以及回滚至任意历史版本的能力。配置变更被视为可审计事件，其严谨性与代码部署一致。

Use When

适用场景

Managing feature flags across multiple environments
Tuning rate limits or throttling parameters without deploying
Implementing A/B testing configuration
Centralizing configuration for microservice architectures
Supporting configuration rollback for incident response
Building multi-tenant applications with per-tenant configuration

在多环境中管理功能标志
无需部署即可调整速率限制或限流参数
实现A/B测试配置
为微服务架构集中管理配置
支持事件响应中的配置回滚
构建支持租户专属配置的多租户应用

How It Works

工作原理

mermaid

sequenceDiagram
    participant App as Application
    participant Client as Config Client
    participant Store as Config Store (KV)
    participant Admin as Admin UI

    App->>Client: Initialize with schema
    Client->>Store: Fetch current config
    Store->>Client: Return config + version
    Client->>App: Apply config values
    Admin->>Store: Update config value
    Store->>Client: Push change notification
    Client->>Client: Validate against schema
    Client->>App: Hot-reload updated values
    Note over App: No restart required

The config client maintains a local cache synchronized with the centralized store. Changes are pushed via long-polling or WebSocket, validated against the schema, and applied to the running application without restart.

mermaid

sequenceDiagram
    participant App as Application
    participant Client as Config Client
    participant Store as Config Store (KV)
    participant Admin as Admin UI

    App->>Client: Initialize with schema
    Client->>Store: Fetch current config
    Store->>Client: Return config + version
    Client->>App: Apply config values
    Admin->>Store: Update config value
    Store->>Client: Push change notification
    Client->>Client: Validate against schema
    Client->>App: Hot-reload updated values
    Note over App: No restart required

配置客户端维护与中心化存储同步的本地缓存。变更通过长轮询或WebSocket推送，经过Schema校验后应用于运行中的应用，无需重启。

Implementation

实现示例

typescript

interface ConfigSchema {
  rateLimitPerMinute: { type: "number"; min: 1; max: 10000; default: 100 };
  featureFlags: {
    type: "object";
    properties: {
      newDashboard: { type: "boolean"; default: false };
      aiAssistant: { type: "boolean"; default: true };
    };
  };
  maintenanceMode: { type: "boolean"; default: false };
}

class ConfigClient<T extends Record<string, unknown>> {
  private cache: T;
  private version: number = 0;
  private listeners = new Map<keyof T, Set<(value: unknown) => void>>();

  constructor(
    private store: KVNamespace,
    private schema: ConfigSchema,
    private namespace: string
  ) {
    this.cache = this.buildDefaults(schema) as T;
  }

  async initialize(): Promise<void> {
    const raw = await this.store.get(`${this.namespace}:current`, "json");
    if (raw) {
      this.validate(raw as Partial<T>);
      this.cache = { ...this.cache, ...raw } as T;
    }
  }

  get<K extends keyof T>(key: K): T[K] {
    return this.cache[key];
  }

  async set<K extends keyof T>(key: K, value: T[K]): Promise<void> {
    this.validateField(key as string, value);
    const previous = { ...this.cache };
    this.cache[key] = value;
    this.version++;

    await Promise.all([
      this.store.put(`${this.namespace}:current`, JSON.stringify(this.cache)),
      this.store.put(
        `${this.namespace}:v${this.version}`,
        JSON.stringify({ from: previous, to: this.cache, timestamp: Date.now() })
      ),
    ]);

    this.notify(key, value);
  }

  onChange<K extends keyof T>(key: K, callback: (value: T[K]) => void): void {
    if (!this.listeners.has(key)) this.listeners.set(key, new Set());
    this.listeners.get(key)!.add(callback as (value: unknown) => void);
  }

  async rollback(targetVersion: number): Promise<void> {
    const snapshot = await this.store.get(
      `${this.namespace}:v${targetVersion}`, "json"
    ) as { from: T } | null;
    if (!snapshot) throw new Error(`Version ${targetVersion} not found`);
    this.cache = snapshot.from;
    await this.store.put(`${this.namespace}:current`, JSON.stringify(this.cache));
  }

  private notify<K extends keyof T>(key: K, value: T[K]): void {
    this.listeners.get(key)?.forEach(cb => cb(value));
  }

  private buildDefaults(schema: ConfigSchema): Record<string, unknown> {
    return Object.fromEntries(
      Object.entries(schema).map(([k, v]) => [k, (v as { default: unknown }).default])
    );
  }

  private validate(partial: Partial<T>): void { /* schema validation */ }
  private validateField(key: string, value: unknown): void { /* field validation */ }
}