ClickHouse 配置文件使用说明

本文主要介绍 ClickHouse 的配置文件。在 ClickHouse 中配置主要分为两类，一类是负责 server 端配置的，另一类是负责用户端配置的。负责 server 端配置的一般会放在 config.xml 文件中，负责用户端配置的一般会放在 users.xml 文件中。当然如果都放在 config.xml 文件中也是可以的，但按照习惯还是会将二者分为两个文件进行配置。所后续不在将 config.xml 和 users.xml 分开来介绍下面的功能，都是可以通用的。

多配置文件功能

ClickHouse 为了配置文件具有更大的灵活性，还支持了多配置文件功能，就是可以将负责不同功能的配置分为多个配置文件，ClickHouse 在启动时会去读区所有文件，并将所有配置文件内容进行合并来作为最终的配置。这样的好处是可以对配置进行分类管理。比如 ClickHouse 集群拓扑结构相关的配置就可以独立为一个配置文件（通常可以命名为 clusters.xml），宏相关的配置也可以独立为一个配置文件（通常可以命名为 macros.xml）。

想使用多配置文件功能就需要了解下 ClickHouse 是如何加载配置文件的。ClickHouse 默认的主配置的路径为 /etc/clickhouse-server/config.xml（当然也可以在 ClickHouse Server 启动时用 --config-file=/etc/config/config.xml 指定配置文件的路径），如果在 config.xml 所在的文件夹内存在 config.d 目录，ClickHouse 就会遍历这个目录里的所有文件，并将内容进行合并，生成最终的配置内容。每次重启 ClickHouse 都会执行上述步骤。

如果将相同配置设置了不同值，ClickHouse 是怎么处理的呢？下面以 macro 为例看 ClickHouse 是怎么处理的。实验分为两种情况，一种是在 config.xml 重复配置 marco，另一种是使用不同的配置文件重复配置 marco。

单文件重复配置

我们在 config.xml 增加如下配置，然后启动 ClickHouse Server ，查看 a 的值。

<clickhouse>......<macros><a>1</a></macros><macros><a>2</a></macros>
</clickhouse>

通过下面语句查询 a 的值为1。

SELECT * FROM system.macros┌─macro─┬─substitution─┐
│ a     │ 1            │
└───────┴──────────────┘

这说明在同一个配置文件中，如果相同配置参数配置不同值，那 ClickHouse 会使用先出现的值。

多文件重复配置

分别在 config.d 目录中配置两个文件 a.xml 和 b.xml，同样都配置 macro。

a.xml:
<clickhouse><macros><a>1</a></macros>
</clickhouse>b.xml:
<clickhouse><macros><a>2</a></macros>
</clickhouse>

同样通过上述语句查询 a 的值为2。

SELECT * FROM system.macros┌─macro─┬─substitution─┐
│ a     │ 2            │
└───────┴──────────────┘

为什么这次会取值为2而不是1呢？我们可以观察到 ClickHouse Server 的日志：

2023.01.07 11:26:51.092322 [ 25669095 ] {} <Debug> ConfigReloader: Loading config 'config.xml'
Processing configuration file 'config.xml'.
Merging configuration file 'config.d/a.xml'.
Merging configuration file 'config.d/b.xml'.

ClickHouse 首先会加载 config.xml，然后遍历 config.d 目录来加载所有配置文件，顺序是文件名的字母序，如果不同文件包含同样的配置参数时，后加载的会覆盖之前的参数值。如果把 a.xml 改为 c.xml，那最终执行 SELECT * FROM system.macros 的结果就会为1，可以自行尝试一下。

小结

虽然我们了解了 ClickHouse 加载配置文件的行为，但是还是尽可能不要出现重复配置的问题。

配置替换功能

ClickHouse 支持使用环境变量、 xml 节及 zookeeper 节点值替换配置值。

使用环境变量替换

ClickHouse 支持在 xml 节中使用 from_env="xxx" 的方式来使用环境变量替换当前配置值。用法如下：

<clickhouse><macros><replica from_env="REPLICA" /></macros>
</clickhouse>

可以通过 export REPLICA=0 来指定环境变量，再通过 SELECT * FROM system.macros WHERE macro = 'replica' 查询结果为0。等价于配置 <replica>0</replica>。

使用 xml 节替换

ClickHouse 支持在 xml 节中使用 incl="xxx" 的方式来指定某个 xml 节来替换当前 xml 节。用法如下：

<clickhouse><zookeeper incl="zookeeper-servers" optional="true"><node><host>host1</host><port>2181</port></node></zookeeper>  
</clickhouse><clickhouse><zookeeper-servers><node><host>host2</host><port>2182</port></node></zookeeper-servers>
</clickhouse>

这样 <zookeeper> 就会被 <zookeeper-servers> 所包含的内容替换。等价于如下配置方式：

<clickhouse><zookeeper><node><host>host2</host><port>2182</port></node></zookeeper>
</clickhouse>

optional="true" 这个属性是为了避免指定的 xml 节不存在会报错的问题。如果为 true，且 <zookeeper-servers> 不存在，则 <zookeeper> 会使用 host 为 host1 和 port 为 2181 的配置。一般情况不建议配置 optional="true"，涉及到关键配置信息，有错误要提前报错发现，避免使用错误的配置。

使用 zookeeper 节点值替换

ClickHouse 支持在 xml 节中使用 from_zk="xxx" 的方式来指定某个 zookeeper 的节点值（需要 xml 节形式）来替换当前 xml 节。用法如下：

<clickhouse><remote_servers from_zk="/clickhouse/remote_servers"><default><shard><internal_replication>true</internal_replication><replica><host>host1</host><port>9000</port></replica><replica><host>host2</host><port>9000</port></replica></shard></default></remote_servers>
</clickhouse><!-- zookeeper 节点/clickhouse/remote_servers内容如下 --><default><shard><internal_replication>true</internal_replication><replica><host>host3</host><port>9000</port></replica><replica><host>host4</host><port>9000</port></replica></shard></default>

这样名为 default 的 cluster 配置就会被 zookeeper 上 /clickhouse/remote_servers 节点的值替换，请注意 zookeeper 节点中的缩紧，这会被带入配置中，如果为了对其考虑，在 zookeeper 节点中可以保留缩紧。

配置支持 yaml 格式

ClickHouse 也支持 yaml 的格式的配置文件。具体例子可以参考 config.yaml.example。而且 ClickHouse 还支持 yaml 和 xml 混合使用，但是不能在一个文件中同时使用 yaml 和 xml。本节不过多介绍这部分内容。因为 yaml 在表达 xml 节的属性（如 from_env="xxx"）时的写法不是很直观易懂，并且一般生产环境中还是默认使用 xml 格式来做配置文件，所以这部了解即可，不推荐使用。

---

欢迎添加微信：xiedeyantu，讨论技术问题。