跳到主要内容
跳到主要内容
编辑此页

配置文件

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 属性的默认值​

可以设置默认值，并且仅当使用 replace="1" 设置环境变量或 ZooKeeper 节点时才替换它（必须在 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" 属性（例如，macros 的设置）。

  • 如果要用替换来替换整个元素，请使用 include 作为元素名称。也可以从 ZooKeeper 执行替换，方法是指定属性 from_zk = "/path/to/node"。在这种情况下，元素值将替换为 /path/to/node 处的 ZooKeeper 节点的内容。如果您将整个 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。

YAML 和 XML 格式在 ClickHouse 配置方面存在一些差异。以下是一些以 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 节点，并动态重新加载用户和集群的设置。这意味着您可以修改集群、用户及其设置，而无需重启服务器。