配置文件
ClickHouse 服务器可以使用 XML 或 YAML 语法中的配置文件进行配置。在大多数安装类型中,ClickHouse 服务器使用 /etc/clickhouse-server/config.xml
作为默认配置文件运行,但也可以在服务器启动时使用命令行选项 --config-file=
或 -C
手动指定配置文件的位置。其他配置文件可以放置在相对于主配置文件的 config.d/
目录中,例如 /etc/clickhouse-server/config.d/
目录中。此目录中的文件和主配置在将配置应用于 ClickHouse 服务器之前在预处理步骤中合并。配置文件按字母顺序合并。为了简化更新并改进模块化,最佳实践是不修改默认的 config.xml
文件,并将其他自定义项放置在 config.d/
中。(ClickHouse Keeper 配置位于 /etc/clickhouse-keeper/keeper_config.xml
中,因此其他文件需要放在 /etc/clickhouse-keeper/keeper_config.d/
中。)
可以混合使用 XML 和 YAML 配置文件,例如,可以有一个主配置文件 config.xml
和其他配置文件 config.d/network.xml
、config.d/timezone.yaml
和 config.d/keeper.yaml
。不支持在单个配置文件中混合使用 XML 和 YAML。XML 配置文件应使用 <clickhouse>...</clickhouse>
作为顶级标签。在 YAML 配置文件中,clickhouse:
是可选的,解析器会在不存在时隐式插入它。
合并配置
两个配置文件(通常为主配置文件和 config.d/
中的另一个配置文件)按如下方式合并
- 如果一个节点(即通向元素的路径)出现在两个文件中,并且没有属性
replace
或remove
,则它将包含在合并的配置文件中,并且来自两个节点的子节点将包含在内并递归地合并。 - 如果两个节点之一包含属性
replace
,则它将包含在合并的配置文件中,但仅包含来自具有属性replace
的节点的子节点。 - 如果两个节点之一包含属性
remove
,则该节点不会包含在合并的配置文件中(如果它已经存在,则会删除它)。
示例
<!-- config.xml -->
<clickhouse>
<config_a>
<setting_1>1</setting_1>
</config_a>
<config_b>
<setting_2>2</setting_2>
</config_b>
<config_c>
<setting_3>3</setting_3>
</config_c>
</clickhouse>
和
<!-- config.d/other_config.xml -->
<clickhouse>
<config_a>
<setting_4>4</setting_4>
</config_a>
<config_b replace="replace">
<setting_5>5</setting_5>
</config_b>
<config_c remove="remove">
<setting_6>6</setting_6>
</config_c>
</clickhouse>
生成合并的配置文件
<clickhouse>
<config_a>
<setting_1>1</setting_1>
<setting_4>4</setting_4>
</config_a>
<config_b>
<setting_5>5</setting_5>
</config_b>
</clickhouse>
使用 from_env 和 from_zk
要指定元素的值应替换为环境变量的值,可以使用属性 from_env
。
带有 $MAX_QUERY_SIZE = 150000
的示例
<clickhouse>
<profiles>
<default>
<max_query_size from_env="MAX_QUERY_SIZE"/>
</default>
</profiles>
</clickhouse>
等于
<clickhouse>
<profiles>
<default>
<max_query_size>150000</max_query_size>
</default>
</profiles>
</clickhouse>
使用 from_zk
也可实现相同的效果
<clickhouse>
<postgresql_port from_zk="/zk_configs/postgresql_port"/>
</clickhouse>
# clickhouse-keeper-client
/ :) touch /zk_configs
/ :) create /zk_configs/postgresql_port "9005"
/ :) get /zk_configs/postgresql_port
9005
等于
<clickhouse>
<postgresql_port>9005</postgresql_port>
</clickhouse>
from_env 和 from_zk 属性的默认值
可以设置默认值,并且仅在环境变量或 Zookeeper 节点设置时替换它,使用 replace="1"
(必须在 from_env 之前声明)。
使用之前的示例,但 MAX_QUERY_SIZE
未设置
<clickhouse>
<profiles>
<default>
<max_query_size replace="1" from_env="MAX_QUERY_SIZE">150000</max_query_size>
</default>
</profiles>
</clickhouse>
将采用默认值
<clickhouse>
<profiles>
<default>
<max_query_size>150000</max_query_size>
</default>
</profiles>
</clickhouse>
替换配置
配置可以定义替换。有两种类型的替换
如果元素具有
incl
属性,则将使用来自文件的相应替换作为值。默认情况下,替换文件路径为/etc/metrika.xml
。这可以在服务器配置中的 include_from 元素中更改。替换值在该文件中的/clickhouse/substitution_name
元素中指定。如果在incl
中指定的替换不存在,则会将其记录在日志中。要防止 ClickHouse 记录丢失的替换,请指定optional="true"
属性(例如,宏 的设置)。如果要使用替换替换整个元素,请使用
include
作为元素名称。也可以通过指定属性from_zk = "/path/to/node"
从 ZooKeeper 执行替换。在这种情况下,元素值将替换为 Zookeeper 节点/path/to/node
中的内容。这也适用于将整个 XML 子树存储为 Zookeeper 节点,它将完全插入到源元素中。
XML 替换示例
<clickhouse>
<!-- Appends XML subtree found at `/profiles-in-zookeeper` ZK path to `<profiles>` element. -->
<profiles from_zk="/profiles-in-zookeeper" />
<users>
<!-- Replaces `include` element with the subtree found at `/users-in-zookeeper` ZK path. -->
<include from_zk="/users-in-zookeeper" />
<include from_zk="/other-users-in-zookeeper" />
</users>
</clickhouse>
如果要将替换内容与现有配置合并,而不是追加,可以使用属性 merge="true"
,例如:<include from_zk="/some_path" merge="true">
。在这种情况下,现有配置将与替换中的内容合并,并且现有配置设置将被替换为替换中的值。
加密和隐藏配置
可以使用对称加密来加密配置元素,例如,明文密码或私钥。为此,首先配置 加密编解码器,然后将属性 encrypted_by
添加到要加密的元素中,并将加密编解码器的名称作为值。
与属性 from_zk
、from_env
和 incl
(或元素 include
)不同,在预处理文件中不会执行任何替换,即加密值的解密。解密仅在服务器进程运行时发生。
示例
<clickhouse>
<encryption_codecs>
<aes_128_gcm_siv>
<key_hex>00112233445566778899aabbccddeeff</key_hex>
</aes_128_gcm_siv>
</encryption_codecs>
<interserver_http_credentials>
<user>admin</user>
<password encrypted_by="AES_128_GCM_SIV">961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85</password>
</interserver_http_credentials>
</clickhouse>
要加密值,可以使用(示例)程序 encrypt_decrypt
示例
./encrypt_decrypt /etc/clickhouse-server/config.xml -e AES_128_GCM_SIV abcd
961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85
即使使用加密的配置元素,加密的元素仍会出现在预处理的配置文件中。如果这对您的 ClickHouse 部署来说是个问题,我们建议两种替代方法:将预处理文件的权限设置为 600,或者使用 hide_in_preprocessed
属性。
示例
<clickhouse>
<interserver_http_credentials hide_in_preprocessed="true">
<user>admin</user>
<password>secret</password>
</interserver_http_credentials>
</clickhouse>
用户设置
config.xml
文件可以指定一个包含用户设置、配置文件和配额的单独配置。此配置的相对路径在 users_config
元素中设置。默认情况下,它是 users.xml
。如果省略 users_config
,则用户设置、配置文件和配额直接在 config.xml
中指定。
用户配置可以类似于 config.xml
和 config.d/
那样分成单独的文件。目录名称定义为 users_config
设置,不带 .xml
后缀,并连接 .d
。目录 users.d
默认使用,因为 users_config
默认设置为 users.xml
。
请注意,配置文件首先会 合并,同时考虑设置,然后处理包含项。
XML 示例
例如,可以为每个用户创建单独的配置文件,如下所示
$ cat /etc/clickhouse-server/users.d/alice.xml
<clickhouse>
<users>
<alice>
<profile>analytics</profile>
<networks>
<ip>::/0</ip>
</networks>
<password_sha256_hex>...</password_sha256_hex>
<quota>analytics</quota>
</alice>
</users>
</clickhouse>
YAML 示例
这里您可以看到使用 YAML 编写的默认配置:config.yaml.example.
在 ClickHouse 配置方面,YAML 和 XML 格式之间存在一些差异。以下是一些使用 YAML 格式编写配置的技巧。
带有文本值的 XML 标签由 YAML 键值对表示
key: value
相应的 XML
<key>value</key>
嵌套的 XML 节点由 YAML 映射表示
map_key:
key1: val1
key2: val2
key3: val3
相应的 XML
<map_key>
<key1>val1</key1>
<key2>val2</key2>
<key3>val3</key3>
</map_key>
要创建多个相同的 XML 标签,请使用 YAML 序列
seq_key:
- val1
- val2
- key1: val3
- map:
key2: val4
key3: val5
相应的 XML
<seq_key>val1</seq_key>
<seq_key>val2</seq_key>
<seq_key>
<key1>val3</key1>
</seq_key>
<seq_key>
<map>
<key2>val4</key2>
<key3>val5</key3>
</map>
</seq_key>
要提供 XML 属性,可以使用带有 @
前缀的属性键。请注意,@
是 YAML 标准保留的,因此必须用双引号括起来
map:
"@attr1": value1
"@attr2": value2
key: 123
相应的 XML
<map attr1="value1" attr2="value2">
<key>123</key>
</map>
也可以在 YAML 序列中使用属性
seq:
- "@attr1": value1
- "@attr2": value2
- 123
- abc
相应的 XML
<seq attr1="value1" attr2="value2">123</seq>
<seq attr1="value1" attr2="value2">abc</seq>
上述语法不允许将带有 XML 属性的 XML 文本节点表达为 YAML。可以使用 `#text` 属性键来实现这种特殊情况。
map_key:
"@attr1": value1
"#text": value2
相应的 XML
<map_key attr1="value1">value2</map>
实现细节
对于每个配置文件,服务器在启动时也会生成 `file-preprocessed.xml` 文件。这些文件包含所有已完成的替换和覆盖,仅供参考使用。如果配置文件中使用了 ZooKeeper 替换,但 ZooKeeper 在服务器启动时不可用,则服务器会从预处理文件中加载配置。
服务器会跟踪配置文件的变化,以及执行替换和覆盖时使用的文件和 ZooKeeper 节点,并动态地为用户和集群重新加载设置。这意味着您无需重启服务器即可修改集群、用户及其设置。