TDengine 技术参数配置大全

1. 背景

TDengine 的 taos.cfg 中配置项及使用 SQL 命令 alter 修改的系统变量之间的关系如何，哪些是持久存储项，哪些设置是临时项，这章将详细说明。

本文是技术参考资料，请收藏。

2.定义

1. 全局配置参数

• 全局配置参数：作用于集群内所有 dnode 且在集群内必须保持一致的变量，也称为全局变量、系统变量 或全局参数。例如:

timezone/charset/countAlwaysReturnValue

  以上配置必须保持一致，不一致则程序返回结果可能会有问题。

2.局部配置参数

• 局部配置参数：作用于集群内某个 dnode 或客户端(taosc，视为集群的一个节点) 但不要求集群内必须保持一致的变量，也称为局部参数 或 局部变量；根据作用范围，可分为服务端(dnode)局部变量、客户端(taosc)局部变量，示例如下：

1) 只适用于 dnode 的局部配置参数：

例如：dDebugFlag/vDebugFlag/numOfMnodeReadThreads/numOfVnodeReadThreads 2) 只适用于客户端 taosc 的局部配置参数：

例如，cDebugFlag/minSlidingTime 3) 既适用于 dnode 也适用于 taosc 的局部配置参数： 例如，debugFlag/firstEp/numOfLogLines/logDir/tempDir

• 客户端局部配置参数通过 clientHb 进行同步，默认与服务端保持一致；需要与服务端不一致的配置参数，可手动在客户端所使用的配置文件中配置。

    注：在本文中，”变量“ 和 ”配置参数“ 具有相同含义，视为等价。

3.行为说明

• 系统变量

• 查看系统变量

show variables/show cluster variables; 
// 查看系统变量， 二者等价 
select * from information_schema.ins_configs; 
// 查看系统变量，相比较 show variables 缺少 scope 列

目前，show variables 与 select * from ins_configs 输出内容基本一致，但是用了两种完全不同的实现方式。实际上，二者统一使用 ins_configs 的机制即可。

• 增加 category 以区分变量类别，global 表示系统变量，local 表示局部变量。示例如下，因为 show variables 的作用就是展示系统变量，所以以下输出中的 category 字段的值均为 global。

taos> show variables; name | value | scope| category| ============================================================================================= statusInterval | 1 | statics | global| timezone | Asia/Shanghai (CST, +0800) | sysconf | global| locale | en_US.UTF-8 | sysconf | global| charset | UTF-8 | sysconf | global| monitor | 1 | monitor | global| monitorInterval | 30 | monitor | global| slowLogThreshold | 10 | slowlog | global| slowLogMaxLen | 4096 | slowlog | global| slowLogScope | QUERY | slowlog | global| ...

Query OK, 9 row(s) in set (0.002328s)

1. 系统变量列表

• 以下变量在 3.3.4.0 版本开始被归类为系统变量:

• 修改系统变量

通过任意客户端修改系统变量，该系统变量的修改会被自动传递到集群中的所有 dnode 并被持久化，在集群重启后仍然有效。修改系统变量使用如下命令。

alter all dnodes '${systemVariableName}' '${value}';

1. 校验新的系统变量取值是否在取值范围内，如果不在取值范围内则报错，并提示用户正确的取值范围。

2. 使用 alter dnode dnode_id 会提示参数不合法。

• dnode 局部变量

• 查看 dnode 变量

• 增加了类别 catetory 列，以区分不同类型的变量。

• 目前，show dnode {dnodeId} variables 会显示适用于 dnode 的所有变量，包含局部变量和系统变量。

dnode_id | name | value | scope| category| =========================================================================================== 1 | firstEp | u3-31:6030 | cluster | local | 1 | secondEp | u3-31:6030 | cluster | local | 1 | fqdn | u3-31 | cluster | local | 1 | serverPort | 6030 | cluster | local | 1 | tempDir | /tmp/ | conf | local | 1 | minimalTmpDirGB | 1.000000 | query | local | 1 | shellActivityTimer | 3 | transport | local | 1 | compressMsgSize | -1 | compress | local | ... Query OK, 194 row(s) in set (0.010489s)

• dnode 局部变量列表

该列表包含在 dnode 生效的配置参数（不包含全局配置参数）。

• 查看 dnode 只读局部变量

使用以下命令查看 readonly 变量。（readonly 变量大多为系统信息，仅做展示但不可修改）

show dnode {dnodeId} variables readonly

• dnode 只读局部变量列表

• 修改 dnode 局部变量

dnode 的局部变量被修改后只对当前 dnode 生效，并被自动持久化，在 dnode 重启后仍然有效。

alter dnode ${dnodeId} '${dnodeVariableName} ${value}' alter all dnodes '${dnodeVariableName} ${value}'

1. 检查局部变量是否支持动态修改，如果不支持则报错，提示用户当前局部变量不支持修改。

2. 检查新的局部变量取值是否在取值范围内，如果不在取值范围内则报错，并提示用户当前局部变量的取值范围。

• 客户端（taosc）局部变量

• 查看客户端变量

• 增加了类别 catetory 列，以区分不同类型的变量。

• show local variables 显示应用于当前客户端 (taosc实例）的变量

taos> show local variables; name | value | scope| category| ==================================================================================== firstEp | u3-31:6030 | cluster | local| secondEp | u3-31:6030 | cluster | local| fqdn | u3-31 | cluster | local| serverPort | 6030 | cluster | local| tempDir | /tmp/ | conf | local| minimalTmpDirGB | 1.000000 | query | local| shellActivityTimer | 3 | transport | local| compressMsgSize | -1 | compress | local| queryPolicy | 1 | query | local| enableQueryHb | 1 | query | local| enableScience | 0 | query | local| querySmaOptimize | 0 | query | local| queryPlannerTrace | 0 | query | local| queryNodeChunkSize | 32768 | query | local| ... Query OK, 80 row(s) in set (0.001913s)

• 客户端（taosc）局部变量列表

该列表包含在 taosc 生效的配置参数（不包含全局配置参数）。

• 查看客户端 (taosc) 只读局部变量

使用以下命令查看 readonly 变量。（readonly 变量大多为系统信息，仅做展示但不可修改）

show local variables readonly

• 客户端 (taosc) 只读局部变量列表

• 修改客户端局部变量

通过 taos shell 或 API 修改客户端局部变量后，在该 taos shell 实例或客户端程序的运行期间有效，退出重启后失效，需要重新设置。

alter local '${localVariableName} {value}';

1. 检查局部变量是否支持动态修改，如果不支持则报错，提示用户当前局部变量不支持修改。

2. 检查新的局部变量取值是否在取值范围内，如果不在取值范围内则报错，并提示用户当前局部变量的取值范围。

• taosd 行为

• 启动时配置文件中 forceReadConfig 为 1

taosd 成功启动后会自动将所有生效的系统变量和局部变量（无论它们的来源是配置文件还是默认值）自动持久化到内部存储中，该内部存储对用户不可见不可修改。人工修改内部存储的变量会导致不可预测的产品行为，涛思数据不对此行为负责。

集群中每个节点的首次启动无论 forceReadConfig 是否打开均需要读取指定配置文件或者使用默认配置文件。

• 启动时配置文件中 forceReadConfig 为 0

如果启动时关闭 forceReadConfig ，则 taosd 仅会读取 dataDir 参数，然后自动使用系统上次运行时持久化的系统变量和局部变量。如果本次启动为该集群中本节点 taosd 的首次启动，或者集群中不存在内部持久化的系统变量和局部变量，则 taosd 会自动使用默认配置文件启动。如果默认配置文件不存在或存储配置错误，则启动失败。

• 修改系统变量或 dnode 局部变量

在集群首次启动以后，所有的配置参数修改都推荐使用 SQL 命令进行，否则极易造成配置参数的错误、不一致以及过往配置的丢失。

部分参数需要重启后生效，则不改动当前内存中的值，仅做持久化，避免前后参数不一致带来的问题。

• 细分场景

1. 集群首次启动：

   1. 集群中的第一个节点，必须指定配置文件或者使用默认配置文件

   2. 集群中的第二到第N个节点，同上，如果配置文件中存在系统变量不一致的情况，报错退出

2. 集群中的某个节点重启（在集群中其它节点仍然存活的情况下）：

   1. (推荐)指定配置文件并且forceReadConfig配置为0，需保证配置文件中包含 dataDir ,则使用持久化的局部变量;同时校验参数版本号是否落后于集群版本，如果落后于集群，则从集群中重新拉取系统变量，否则使用本地存储的系统变量。

   2. （不推荐）指定配置文件并且forceReadConfig配置为1，则全部使用配置文件（配置文件中没有的使用默认值）启动，如果存在与集群中系统变量不一致的情况则报错退出。重启成功后会自动覆盖持久化的局部变量。

3. 集群停止后，重新启动集群中的第一个节点

   1. （推荐）指定配置文件并且forceReadConfig配置为0，需保证配置文件中包含 dataDir ,则使用持久化的系统变量和局部变量。

   2. （不推荐）指定配置文件并且forceReadConfig配置为1，则全部使用配置文件（配置文件中没有的使用默认值）启动，重启成功后会自动覆盖持久化的系统变量和局部变量。

• taos shell 行为

• 启动 taos shell

taos shell 启动时如果指定配置文件则使用该配置文件，如果不指定配置文件则使用默认配置文件。如果指定的配置文件或默认配置文件中有配置错误则启动失败。

• 修改 taos shell 所在客户端配置

如果希望对 taos shell 所使用的客户端配置参数进行修改，最佳实践是修改配置文件（以达到持久化目的）并重启 taos shell。如果使用 SQL 命令动态修改，也建议同步修改配置文件，否则下次重启后要重复进行同样的动态修改。

• 如何新增参数 (供研发参考)

如何增加配置参数

• 增加磁盘 disk id 检测功能

背景：

用户在停机后，重启数据库服务前，可能会忘记进行磁盘挂载，在一个空目录下重启数据库服务，并且用户不清楚数据已经丢失，可能运行一段时间才会发现。这样无疑给用户造成了损失，并且增加了运维成本。

功能概述：

基于配置参数的持久化功能，taosd 会在首次启动时，持久化各个数据目录对应的 disk id ，在 taosd 重启时，会校验当前各个数据目录所对应的 disk id 和之前记录的 disk id 是否一致，如果不一致则退出数据库服务，并提示用户检查是否磁盘忘记挂载。如果用户主动切换磁盘，可以通过设置参数diskIDCheckEnabled 跳过检查。

• taosd 行为

• forceReadConfig 行为

如果您不想使用配置参数的持久化功能，可以使用 forceReadConfig ，强制从配置文件读取配置参数覆盖本地持久化的配置参数，但需要注意 forceReadConfig 仅对局部配置参数生效，全局配置参数仍然以集群持久化的值为准。

4. 兼容性

1. 新建集群，无兼容性问题

2. 旧集群升级

   1. 首次启动使用指定或默认的配置文件启动，无兼容性问题

   2. 首次启动后不建议再通过修改配置文件的方式修改配置，如果通过修改配置文件的方式则重启时要指定配置文件

   3. 首次启动后推荐只使用动态修改系统变量或局部变量的方式，再次启动时不应指定配置文件，则再次启动时会自动使用内部持久化存储的系统变量和局部变量，无兼容性问题

3. 降级

   1. 仅可降级到 做完 sdb 处理逻辑之后的版本，具体版本会在发版后补充到这里。

   2. 如果降级到不支持本特性的版本，则降级后要指定配置文件启动或使用默认配置文件启动，曾经做过的配置修改均会丢失，但无兼容性问题。

5. 运维

1. 本特性的主要价值在于对运维的帮助：修改系统变量或局部变量立即生效无需重启，并在下次重启后依然有效。

2. 最佳实践：集群首次启动成功后不再使用配置文件，通过 SQL 命令修改系统变量或局部变量，重新启动 taosd 时不指定配置文件

3. Linux/Windows 平台的 systemd 脚本有可能需要进行修改，service restart 所对应的命令行参数不能指定配置文件

6. 使用场景

动态修改系统变量或局部变量立即生效无需重启，并在下次重启后依然有效。

7. 约束和限制

1. 全局配置参数在出现网络分区之后恢复时，可能会出现各个 dnode 不一致情况。

2. 全局配置参数在变更时，可能会存在短时间的不一致。

3. 全局配置参数存放在 sdb 中，mnode 重启回放日志时，可能会出现配置参数修改内容丢失，等待 mnode 彻底恢复后，恢复正常。