一、TongSearch中“配置”在系统里的真实形态

在 tongsearch 中，“配置”并不是一个统一的数据结构，而是在不同生命周期、不同作用域内被分散管理的多种配置形态。从实现上可以分为四类：

1. 启动期静态配置（Node Settings）

2. 运行期集群配置（Cluster Settings）

3. 索引级配置（Index Settings）

4. 请求级参数（Request-time Parameters）

它们的核心差异不在于“内容”，而在于：

• 由谁读取

• 什么时候读取

• 是否允许变更

• 通过什么机制传播

---

二、启动阶段：tongsearch.yml 是如何被读取的

1. 配置入口：Environment 与 Settings

TongSearch 启动的第一步是构建 Environment 对象，其职责是：

• 定位 config/ 目录

• 加载 tongsearch.yml

• 合并系统属性（-E）

• 合并 JVM 系统参数（-Dts.*）

tongsearch.yml 会被解析为一个不可变的 Settings 对象：

Settings settings = Settings.builder()
    .loadFromPath(configFile)
    .put(properties)
    .build();

这里有两个重要设计点：

• Settings 是不可变对象

• 所有配置在启动期一次性解析完成

这意味着：

tongsearch.yml 中的配置，从语义上就是“启动时常量”

---

2. 配置合并优先级

tongsearch 中配置来源的优先级（从低到高）：

1. tongsearch.yml

2. JVM system properties（-D）

3. 命令行参数（-E）

4. 内部硬编码默认值

最终合并成一个 Settings 实例，供所有模块共享。

---

三、配置注入：Settings 如何进入各个模块

1. 依赖注入模型（非 Spring）

tongsearch 使用的是自研的模块化注入机制（Guice 风格，但非 Spring）。

在这个阶段：

• Settings 被作为构造参数

• 注入到各个 Service / Module

• 模块自行解析关心的配置项

例如：

• TransportService 读取网络配置

• ClusterService 读取集群配置

• IndicesService 读取索引级默认配置

配置解析通常表现为：

public static final Setting<Integer> SOME_SETTING =
    Setting.intSetting("some.setting", 10, Setting.Property.NodeScope);

---

2. Setting：TS 配置系统的核心抽象

Setting<T> 是 tongsearch 中所有配置项的统一描述模型，其定义了：

• key 名称

• 默认值

• 校验规则

• 生效范围（Scope）

• 是否可动态更新

示例：

Setting<Boolean> ENABLED =
    Setting.boolSetting(
        "xpack.security.enabled",
        false,
        Setting.Property.NodeScope
    );

关键思想：

配置不是字符串，而是“有类型、有约束、有生命周期的对象”。

---

四、Cluster Settings：动态配置是如何生效的

1. Cluster Settings 的存储位置

通过 API 设置的配置：

PUT _cluster/settings

最终会被写入：

• Cluster State

• 由 Master 节点维护

• 持久化在 path.data/_state

Cluster State 中包含：

• metadata

• routing table

• cluster settings

---

2. 动态配置的传播机制

生效流程如下：

1. 请求发送至 Master

2. Master 更新 Cluster State

3. 通过 publish 机制广播

4. 各节点 ClusterApplierService 接收

5. 注册的 listener 被触发

代码逻辑核心在：

ClusterService
 └── ClusterSettings
     └── addSettingsUpdateConsumer()

例如：

clusterSettings.addSettingsUpdateConsumer(
    SOME_DYNAMIC_SETTING,
    this::applySetting
);

这使得配置更新成为事件驱动模型，而不是轮询或重载。

---

五、索引级配置：Index Settings 的双重来源

1. 索引配置的来源合并

Index Settings 的最终值来自三部分：

1. 创建索引时指定

2. 模板（Index Template）

3. 集群默认索引配置

合并发生在：

MetadataCreateIndexService

生成一个 IndexMetadata，并随 Cluster State 传播。

---

2. 为什么修改部分索引配置需要 close index

原因并非“实现偷懒”，而是Lucene 资源生命周期问题：

• Analyzer

• Similarity

• Codec

这些组件在 shard 初始化时绑定，一旦打开索引即不可变。

---

六、为什么有些配置必须重启

从实现角度看，必须重启的配置具备以下特征之一：

• 影响 JVM 初始化（如 heap）

• 影响线程模型

• 影响节点角色

• 影响底层 IO 结构

这些配置被标记为：

Setting.Property.NodeScope

并且没有注册 update consumer。

---

七、配置错误是如何被发现的

1. 启动期校验（Bootstrap Checks）

在 BootstrapChecks 中执行：

• 内存

• 文件描述符

• mmap

• 线程数

失败直接阻断启动。

---

2. 运行期校验

动态配置在更新时会：

• 类型校验

• 范围校验

• 语义校验（部分）

不通过直接拒绝写入 Cluster State。

---

八、总结：tongsearch 配置系统的设计哲学

tongsearch 的配置系统本质上是一个：

• 强类型

• 事件驱动

• 分布式一致

• 生命周期明确

的配置管理系统。

其核心思想不是“让你随便改参数”，而是：

用配置来约束系统状态变化的合法路径。

理解配置读取与生效机制，等价于理解 tongsearch 的启动模型、状态传播模型和模块边界设计。

---