# Config-Center Technical Reference / 技术参考手册

> Last updated: 2026-04-17

## Architecture Overview / 架构概览

Config-center is a centralized configuration management service for TiDB Cloud clusters, replacing the legacy GitOps approach. It stores configuration files, templates, component images, versions, and cluster metadata.

Config-center 是 TiDB Cloud 集群的集中化配置管理服务，取代了旧的 GitOps 方式。它存储配置文件、模板、组件镜像、版本和集群元数据。

### Deployment Modes / 部署模式

| Mode | service_mode | Description |
|------|-------------|-------------|
| Global | `"global"` | Manages Dedicated clusters directly; proxies NG requests to regional services / 直接管理 Dedicated 集群，代理 NG 请求到 regional 服务 |
| Regional | `"regional"` | Serves a single NG region; shares RDS with cluster-service-ng / 服务单个 NG region，复用 cluster-service-ng 的 RDS |

Only `SHARED_POOL` and `LOGICAL_CLUSTER` use regional mode (see `ClusterType.UseRegionalMode()` in `proto/config_center/const.go`).

仅 `SHARED_POOL` 和 `LOGICAL_CLUSTER` 使用 regional 模式。

### Data Distribution / 数据分布

```
Global Config-Center (base EKS, Global DB)
├─ Dedicated cluster data: components, configs, texts    ← stored & served here
│  Dedicated 集群数据：组件、配置、文本                       ← 在此存储和服务
├─ Global data (shared across all regions):
│  全局数据（跨所有 region 共享）：
│  ├─ templates, template_values, default_templates
│  ├─ component_images, default_versions
│  ├─ param_dict
│  ├─ tenant_initial_custom_params
│  └─ region_routes
└─ NG cluster data: NOT stored here, proxied to regional
   NG 集群数据：不存储在此，代理到 regional

Regional Config-Center (per NG region, shares RDS with cluster-service-ng)
├─ NG cluster data: components, configs, texts           ← stored & served here
│  NG 集群数据：组件、配置、文本                              ← 在此存储和服务
└─ Global data (synced from global):
   全局数据（从 global 同步）：
   ├─ templates, template_values, default_templates
   ├─ component_images, default_versions
   └─ tenant_initial_custom_params
```

### Request Routing / 请求路由

```
Client → Global Config-Center
           ├─ ClusterType is DEDICATED_TIDB/TICDC/CHANGEFEED → process locally (Global DB)
           │                                                    本地处理（Global DB）
           └─ ClusterType is SHARED_POOL/LOGICAL_CLUSTER
              → lookup region_routes table (5s TTL cache)
              → proxy via HTTP to Regional Config-Center (Regional DB)
                通过 HTTP 代理到 Regional Config-Center（Regional DB）
```

### Global → Regional Sync / 全局→Regional 同步

Global data (templates, component_images, default_versions, tenant_initial_custom_params) is managed on global config-center first, then synced to each region. Key sync triggers:

全局数据（模板、组件镜像、默认版本、租户初始参数）先在 global config-center 管理，然后同步到每个 region。关键同步触发：

- `CreateConfigurationTemplate` → broadcast to all registered regions / 广播到所有已注册 region
- `UpdateComponentImage` → broadcast to all registered regions / 广播到所有已注册 region
- `SyncRegionalServer` → trigger a full sync for a specific region / 触发对指定 region 的全量同步

## Data Model / 数据模型

Full schema: `schema.sql` (auto-generated from `migration/*.up.sql`).

完整 schema 见 `schema.sql`（从 `migration/*.up.sql` 自动生成）。

### Tables / 表

| Table | Purpose / 用途 | Key Columns |
|-------|---------------|-------------|
| `templates` | Immutable config templates / 不可变配置模板 | id, cluster_type, config_type, template_name, tags(JSON) |
| `template_values` | Template K-V pairs / 模板键值对 | template_id, key, value(TOML-encoded) |
| `default_templates` | (version, cloud, instance) → template_id mapping / 默认模板映射 | cluster_type, config_type, version, cloud_provider, instance, region, tenant_id |
| `cluster_config_info` | Per-cluster config file metadata / 集群配置文件元数据 | cluster_type, cluster_id, filename, template_id, config_type, belong_to |
| `cluster_config_params` | Per-cluster custom params / 集群自定义参数 | cluster_type, cluster_id, filename, key, value |
| `cluster_config_texts` | Cached serialized config output / 缓存的序列化配置输出 | cluster_type, cluster_id, filename, data(TEXT) |
| `cluster_components` | Component version & image per cluster / 集群组件版本和镜像 | cluster_type, cluster_id, component_name, version, overwrite_image_tag, base_image, image_tag, instance |
| `component_images` | Global (component, version) → image mapping / 全局组件→镜像映射 | cluster_type, component_name, version, tenant_id, base_image, tag, GA |
| `default_versions` | Default version rules (hierarchical) / 默认版本规则（层级化） | cluster_type, component_name, cloud_provider, region, tenant_id, version, cluster_version |
| `param_dict` | Available parameter dictionary / 可用参数字典 | cluster_type, config_type, version, param_key, type(enum), hot_reloadable, risk_level, validation(JSON) |
| `tenant_initial_custom_params` | Tenant-level initial params / 租户级别初始参数 | cluster_type, tenant_id, config_type, key, value |
| `region_routes` | Regional endpoint registry / Regional 端点注册表 | cluster_type, logical_region, endpoint |
| `audit_logs` | Request/response audit trail / 请求/响应审计日志 | api_name, cluster_type, cluster_id, request, response |

### Soft Delete / 软删除

Tables with `delete_time` column: `templates`, `cluster_config_info`, `cluster_components`, `param_dict`. Queries filter by `WHERE delete_time IS NULL`.

含 `delete_time` 列的表使用软删除，查询时过滤 `WHERE delete_time IS NULL`。

## Core Concepts / 核心概念

### ConfigurationFile = Template + Custom Params

```
                 ┌─────────────────┐
                 │  System Template │  ← immutable, shared across clusters
                 │  (template_id)   │     不可变，跨集群共享
                 └────────┬────────┘
                          │ merge 合并
                 ┌────────▼────────┐
                 │  Custom Params   │  ← per-cluster overrides (TSE/user set)
                 │  (custom_params) │     集群级别覆盖（TSE/用户设置）
                 └────────┬────────┘
                          │ serialize 序列化
                 ┌────────▼────────┐
                 │  text (cached)   │  ← final TOML/JSON/YAML/LINES output
                 │                  │     最终配置文件输出（缓存保证多次 get 逐字节一致）
                 └─────────────────┘
```

### Template Deduplication / 模板去重

Templates are deduplicated by SHA256(data). When creating a template with identical content + name + tags within the same cluster_type + config_type, the existing template_id is reused.

模板通过 SHA256(data) 去重。同 cluster_type + config_type 下，内容 + name + tags 相同则复用已有 template_id。

### Default Template Selection Hierarchy / 默认模板选择层级

See `searchDefaultConfigurationTemplateIdDirectly()` in `internal/service/config_template.go`.

详见 `internal/service/config_template.go` 中的 `searchDefaultConfigurationTemplateIdDirectly()`。

```
(version, cloud_provider, node_instance, region, tenant_id)   ← most specific / 最具体
(version, cloud_provider, node_instance, region, "")
(version, "",             "",            region, "")           ← any cloud & SKU / 任意云和机型
("",      "",             "",            region, "")           ← any version / 任意版本
```

**Dedicated vs NG template binding:**
- **Dedicated**: Default templates are bound per (version, cloud_provider, node_instance) — different SKUs have different default configs / 默认模板按 (version, cloud_provider, node_instance) 绑定，不同机型有不同默认配置
- **NextGen**: Default templates are **node_instance-independent** — all specs share the same default config per version, the kernel handles hardware differences internally / 默认模板**与机型无关**，同版本所有规格共享相同默认配置，硬件差异由内核内部处理

Note: In `SearchDefaultConfigurationTemplateIdInTx()`, for NG clusters, the region is auto-set from `ServerRegion`. For BYOC INIT_SQL, a region-specific search is tried first, then falls back to region="".

注意：在 `SearchDefaultConfigurationTemplateIdInTx()` 中，NG 集群的 region 由 `ServerRegion` 自动设置。BYOC INIT_SQL 会先尝试带 region 搜索，然后回退到 region=""。

### Image Resolution / 镜像解析

```
ClusterComponent.version + component_name
  → component_images table lookup (with tenant_id fallback to 0)
  → base_image + tag
  → if overwrite_image_tag is set, effective_tag = overwrite_image_tag
     otherwise effective_tag = tag from component_images
```

### Default Version Hierarchy / 默认版本层级

See `GetDefaultVersion()` in `internal/service/global_data.go`. Rules are tried in order; the first match wins (matched fields shown, others queried as ""/0):

详见 `internal/service/global_data.go` 中的 `GetDefaultVersion()`。按顺序匹配，命中即返回（仅列出参与匹配的字段，其余按 ""/0 查询）：

```
"tenant":         (component, tenant_id)                               ← highest priority / 最高优先级
"cluster_version":(component, cluster_version)
"region":         (component, cluster_version, cloud_provider, region)
"cloud_provider": (component, cluster_version, cloud_provider)
"global":         (component)                                          ← global default / 全局默认
```

Note: the `tenant` rule ignores `cluster_version`; the `region`/`cloud_provider` rules include `cluster_version`. The `region`/`cloud_provider` rules are only attempted when the request sets `region`/`cloud_provider` respectively.

注意：`tenant` 规则忽略 `cluster_version`；`region`/`cloud_provider` 规则包含 `cluster_version`。仅当请求分别设置了 `region`/`cloud_provider` 时才会尝试对应规则。

### MetaProfile (formerly ClusterProfile) / 元配置

MetaProfile bundles component image tags + custom config template IDs into a single entity, stored internally as config_type `"CC_META_PROFILE"`. Used during `InitClusterMeta` to apply a predefined set of images and configs.

MetaProfile 将组件镜像标签和自定义配置模板 ID 打包为一个实体，内部存储为 config_type `"CC_META_PROFILE"`。在 `InitClusterMeta` 时用于应用预定义的镜像和配置组合。

```go
// proto/config_center/const.go
type MetaProfileConfig struct {
    ComponentTags         map[string]string  // component → image_tag
    ConfigCustomTemplates map[string]int64   // config_type → child_template_id
}
```

### Format Rules / 格式规则

See `ClusterType.GetConfigTypeFormat()` in `const.go`. Summary:

| Format | Used by / 用于 |
|--------|---------------|
| TOML | tidb, tikv, pd, tiflash, tiflash_learner, ticdc, tiproxy, tidb-lightning, and most NG configs |
| JSON | backup, restore, changefeed-*, tidb_sem |
| LINES | INIT_SQL (one SQL statement per line) |

## API Surface / API 接口

Full proto definition: `proto/config_center/config_center.proto`

完整 proto 定义见 `proto/config_center/config_center.proto`

### RPC Groups / RPC 分组

| Group / 分组 | RPCs | Description / 描述 |
|-------------|------|-------------------|
| ConfigurationFile | Create, BatchCreate, Get, List, Update, BatchUpdate, AutoUpdate, BatchAutoUpdate, Upsert, BatchUpsert, Delete, BatchDelete | Cluster-level config CRUD / 集群级配置文件 CRUD |
| Template | Create, BatchCreate, Get, List, Delete, SearchDefault, BatchSearchDefault, UpdateDefault, DeleteDefault, BatchUpdateDefault, ListBindings, GetUsage | Template management / 模板管理 |
| ClusterComponent | Get, List, Search, Update, BatchUpdate | Component version & image management / 组件版本和镜像管理 |
| ClusterMeta | Init, Get, Update, AutoUpdate | Atomic cluster operations (components + configs) / 原子集群操作 |
| MetaProfile | Create, Get, List, Delete | Bundled config+image profiles / 打包的配置+镜像组合 |
| DefaultVersion | Get, Update, Delete, ListRules | Default version management / 默认版本管理 |
| ComponentImage | Get, Update, List | Global image registry / 全局镜像注册 |
| TenantParams | Get, List, Update, BatchUpdate | Tenant initial config / 租户初始配置 |
| Dict | BatchCreate, Get, List, ListVersions, Update, Purge, CopyFromOldVersion | Parameter dictionary / 参数字典 |
| Instance | ListAvailableVersions, ListAvailableInstances | Version & instance discovery / 版本和机型查询 |
| Regional | Register, List, Get, Offline, Sync | Regional endpoint management / Regional 端点管理 |

### Key API Patterns / 关键 API 模式

**Update vs AutoUpdate:**
- `UpdateClusterConfigurationFile`: Caller specifies template_id and/or custom_params explicitly / 调用方显式指定 template_id 和/或 custom_params
- `AutoUpdateClusterConfigurationFile`: Config-center selects template from (version, cloud_provider, node_instance); auto-fills tenant init params for new files / Config-center 根据版本/机型自动选择模板，新文件自动填充租户初始参数

**`CreateClusterConfigFileRequest` has two oneofs** (used in Create / `InitClusterMeta`):

`system_template_source` — which template to bind:
- `from_sku` (`FromSKU{version, cloud_provider, node_instance, tenant_id}`): auto-select default template by SKU / 按 SKU 自动选默认模板
- `from_template` (`FromTemplate{template_id}`): bind an explicit template / 绑定指定模板

`custom_params_source` — initial custom params (may be empty inside `InitClusterMeta`):
- `from_input_values` (`FromInputValues{custom_params}`): use custom_params from request / 使用请求中的 custom_params
- `from_tenant` (`FromTenant{tenant_id}`): copy from tenant initial params / 从租户初始参数复制
- `from_custom_template` (`FromTemplate{template_id}`): copy from another template / 从另一个模板复制

**allow_missing**: When true, `UpdateClusterComponent`/`UpdateClusterConfigurationFile` creates the resource if not found / 为 true 时，不存在则创建

**update_related_configuration_files**: In `UpdateClusterComponent`, auto-updates all config files belonging to this component / 在更新组件时自动更新关联的配置文件

**validate_only**: Dry-run mode, returns computed result without persisting / 干运行模式，返回计算结果但不持久化

**previous_text**: Optimistic concurrency control — fails if current text doesn't match / 乐观并发控制，当前 text 不匹配则失败

## ClusterType & Component Mappings / 集群类型和组件映射

See `const.go` for full definitions. Key functions:

详见 `const.go`。关键函数：

- `AvailableComponents()` — components per cluster type / 每种集群类型的组件列表
- `AvailableConfigTypes()` — config types per cluster type / 每种集群类型的配置类型列表
- `ConfigType2Component()` — config type → component mapping / 配置类型→组件映射
- `Component2ConfigTypes()` — component → config types mapping / 组件→配置类型映射
- `GetConfigTypeFormat()` — config type → serialization format / 配置类型→序列化格式
- `DictSource()` — dict sharing (e.g., TICDC_NG shares dict with TICDC) / 字典共享

## Configuration / 服务配置

```toml
service_mode = "global"  # or "regional"

[server]
grpc_port = 8080
http_port = 8081

[regional]
cloud_provider = "aws"
logical_region = "us-west-2"  # only for regional mode

[log]
level = "info"

[database]
host = "localhost"
port = 3306
database = "config_center"
user = "root"
password = ""  # override via DB_PASSWORD env var
```