其他服务器设置 - ClickHouse Documentation

这些设置用于配置 ClickHouse 服务器，且由 ClickHouse 源代码自动生成。

abort_on_logical_error

发生 LOGICAL_ERROR 异常时使服务器崩溃。仅供专家使用。

allowed_disks_for_table_engines

允许用于 Iceberg 的磁盘列表

auth_use_forwarded_address

对于通过代理连接的客户端，使用源地址进行身份验证。

默认值： false

由于转发地址很容易被伪造，因此使用此设置时应格外谨慎——接受此类身份验证的服务器不应允许直接访问，而应仅通过受信任的代理访问。

bcrypt_workfactor

使用 Bcrypt 算法的 bcrypt_password 身份验证类型的工作因子。工作因子定义了计算哈希值并验证密码所需的计算量和时间。

默认值： 12

<bcrypt_workfactor>12</bcrypt_workfactor>

对于需要频繁进行身份验证的应用程序，鉴于 bcrypt 在较高 work factor 下会带来较大的计算开销，建议考虑使用其他身份验证方法。

blob_storage_log

blob_storage_log 系统表的相关设置。以下设置可通过子标签配置：

Setting	Description	Default	Note
`database`	数据库名称。
`table`	系统表名称。
`engine`	系统表的 MergeTree 引擎定义。		如果已定义 `partition_by` 或 `order_by`，则不能使用。如果未指定，默认使用 `MergeTree`
`partition_by`	系统表的自定义分区键。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `partition_by` 参数
`ttl`	指定表的生存时间 (TTL)。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `ttl` 参数
`order_by`	系统表的自定义排序键。如果定义了 `engine`，则不能使用。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `order_by` 参数
`storage_policy`	该表使用的存储策略名称 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `storage_policy` 参数
`settings`	控制 MergeTree 行为的附加参数 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `settings` 参数
`flush_interval_milliseconds`	将数据从内存缓冲区刷写到表的时间间隔。	`7500`
`max_size_rows`	日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。	`1048576`
`reserved_size_rows`	为日志预分配的内存行数。	`8192`
`buffer_size_rows_flush_threshold`	行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。	`max_size_rows / 2`
`flush_on_crash`	设置在发生崩溃时是否将日志转储到磁盘。	`false`

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

设置	描述	默认值
`skip_alias_columns`	为 `true` 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。	`false`

示例：

<blob_storage_log>
    <database>system</database>
    <table>blob_storage_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <ttl>event_date + INTERVAL 30 DAY</ttl>
</blob_storage_log>

builtin_dictionaries_reload_interval

重新加载内置字典之前的时间间隔 (以秒为单位) 。 ClickHouse 每隔 x 秒重新加载一次内置字典。因此，无需重启服务器即可“动态”编辑字典。示例

<builtin_dictionaries_reload_interval>3600</builtin_dictionaries_reload_interval>

cache_size_to_ram_max_ratio

设置缓存大小占 RAM 的最大比率。可在低内存系统上减小缓存大小。

cannot_allocate_thread_fault_injection_probability

仅用于测试。

cgroups_memory_usage_observer_wait_time

服务器根据 cgroups 中相应阈值调整其允许的最大内存消耗的时间间隔，单位为秒。要禁用 cgroup 观察器，请将该值设置为 0。

压缩

MergeTree 引擎表的数据压缩设置。

如果您刚开始使用 ClickHouse，建议不要修改此项。

配置模板：

<compression>
    <case>
      <min_part_size>...</min_part_size>
      <min_part_size_ratio>...</min_part_size_ratio>
      <method>...</method>
      <level>...</level>
    </case>
    ...
</compression>

<case> 字段：

min_part_size – 数据分区片段的最小大小。
min_part_size_ratio – 数据分区片段大小与表大小的比率。
method – 压缩方法。可选值：lz4、lz4hc、zstd、deflate_qpl。
level – 压缩级别。请参见编解码器。

你可以配置多个 <case> 部分。

满足条件时的操作：

如果某个数据分区片段匹配某组条件，ClickHouse 会使用指定的压缩方法。
如果某个数据分区片段匹配多组条件，ClickHouse 会使用最后一个匹配到的条件集 (<case> 部分会按顺序检查，每个匹配项都会覆盖之前的选择) 。

如果某个数据分区片段不满足任何条件，ClickHouse 会使用与大小相关的内置默认值：小于 100 MB 时使用 LZ4，等于或大于该值时使用 ZSTD(3)。与上述 min_part_size 条件一样，这里的大小是在选择编解码器时 (即数据写入之前) 已知的大小：刚插入的 part 为 0，merge 或 mutation 则为源 parts 的大小。因此，会使输入变小的重写操作 (例如 TTL DELETE 或 collapsing merge) 是按输入大小来归类的，可能产生一个低于阈值却仍使用 ZSTD(3) 的 part。

示例

<compression incl="clickhouse_compression">
    <case>
        <min_part_size>10000000000</min_part_size>
        <min_part_size_ratio>0.01</min_part_size_ratio>
        <method>zstd</method>
        <level>10</level>
    </case>
</compression>

配置文件

指定服务器配置文件。

config_reload_interval_ms

ClickHouse 重新加载配置并检查是否有新更改的频率

core_dump

配置 core dump 文件大小的软限制。

硬限制需通过系统工具配置。

示例

<core_dump>
     <size_limit>1073741824</size_limit>
</core_dump>

crash_log

crash_log 系统表操作的相关设置。以下设置可通过子标签进行配置：

Setting	Description	Default	Note
`buffer_size_rows_flush_threshold`	行数阈值。达到该阈值后，会在后台启动将日志刷新到磁盘的操作。	`max_size_rows / 2`
`database`	数据库名称。
`engine`	系统表的 MergeTree 引擎定义。		如果定义了 `partition_by` 或 `order_by`，则不能使用。如果未指定，默认选择 `MergeTree`
`flush_interval_milliseconds`	将数据从内存缓冲区刷新到表中的时间间隔。	`7500`
`flush_on_crash`	设置发生崩溃时是否应将日志转储到磁盘。	`false`
`max_size_rows`	日志的最大行数。当未刷新的日志数量达到 max_size 时，会将日志转储到磁盘。	`1024`
`order_by`	系统表的自定义排序键。如果定义了 `engine`，则不能使用。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 中指定 `order_by` 参数
`partition_by`	系统表的自定义分区键。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 中指定 `partition_by` 参数
`reserved_size_rows`	为日志预分配的内存行数。	`1024`
`settings`	用于控制 MergeTree 行为的附加参数 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 中指定 `settings` 参数
`storage_policy`	该表使用的存储策略名称 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 中指定 `storage_policy` 参数
`table`	系统表名称。
`ttl`	指定表的生存时间 (TTL)。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 中指定 `ttl` 参数

默认的服务器配置文件 config.xml 包含以下设置部分：

<crash_log>
    <database>system</database>
    <table>crash_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1024</max_size_rows>
    <reserved_size_rows>1024</reserved_size_rows>
    <buffer_size_rows_flush_threshold>512</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</crash_log>

create_union_system_log_tables

请求在系统日志表旁创建 all_... 表 (例如，system.query_log 对应 system.all_query_log，system.text_log 对应 system.all_text_log) 。这类表将相应的日志表、其轮转版本 (query_log_0、query_log_1、……) 和/或集群中所有副本上的同名表合并在一起，让您无需记住 clusterAllReplicas(default, merge(system, '^query_log')) 之类的写法即可一次查询所有这些表。此部分为可选项。如果配置了此部分，必须至少指定以下设置之一：

设置	描述
`merge_rotated_tables`	如果为 `true`，`all_...` 表会通过 `merge` 表函数查询日志表及其轮转版本。
`cluster`	如果指定，`all_...` 表会通过 `clusterAllReplicas` 表函数查询该集群中所有副本上的表 (使用 `SETTINGS skip_unavailable_shards = 1`，因此不可用副本不会导致查询失败) 。

如果同时指定这两个设置，该表会合并集群中所有副本上的轮转表。该选项适用于所有系统日志表，不能为不同的系统日志配置不同的设置。这些表会在每个日志首次刷写时创建在与系统日志表相同的数据库中，并会在日志表结构发生变化时 (即轮转时) 自动重新创建。它们不存储状态，因此可以随时安全地删除。只有 Atomic、Replicated 和 Shared 数据库引擎支持创建这些表。

使用 cluster 设置时，表定义会引用该集群，因此必须存在该集群才能加载此表。如果从配置中移除该集群，也应删除 all_... 表 (这些表会在下次刷写时根据新配置重新创建) 。

示例

<create_union_system_log_tables>
    <merge_rotated_tables>true</merge_rotated_tables>
    <cluster>default</cluster>
</create_union_system_log_tables>

database_atomic_delay_before_drop_table_sec

表被删除后，在这段延迟时间内可使用 UNDROP 语句将其恢复。如果执行 DROP TABLE 时使用了 SYNC 修饰符，则会忽略此设置。此设置的默认值为 480 (8 分钟) 。

dead_letter_queue

用于 ‘dead_letter_queue’ 系统表的设置。以下设置可通过子标签配置：

Setting	Description	Default	Note
`database`	数据库名称。
`table`	系统表名称。
`engine`	系统表的 MergeTree 引擎定义。		如果已定义 `partition_by` 或 `order_by`，则不能使用。如果未指定，默认使用 `MergeTree`
`partition_by`	系统表的自定义分区键。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `partition_by` 参数
`ttl`	指定表的生存时间 (TTL)。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `ttl` 参数
`order_by`	系统表的自定义排序键。如果定义了 `engine`，则不能使用。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `order_by` 参数
`storage_policy`	该表使用的存储策略名称 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `storage_policy` 参数
`settings`	控制 MergeTree 行为的附加参数 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `settings` 参数
`flush_interval_milliseconds`	将数据从内存缓冲区刷写到表的时间间隔。	`7500`
`max_size_rows`	日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。	`1048576`
`reserved_size_rows`	为日志预分配的内存行数。	`8192`
`buffer_size_rows_flush_threshold`	行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。	`max_size_rows / 2`
`flush_on_crash`	设置在发生崩溃时是否将日志转储到磁盘。	`false`

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

设置	描述	默认值
`skip_alias_columns`	为 `true` 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。	`false`

默认设置如下：

<dead_letter_queue>
    <database>system</database>
    <table>dead_letter</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
</dead_letter_queue>

dictionary_background_reconnect_interval

已启用 background_reconnect 的失败 MySQL 和 Postgres 字典进行重连尝试的时间间隔，单位为毫秒。

disk_transaction_wait_for_blob_removal

每个 disk 的 wait_for_blob_removal 设置的默认值。启用后，server 会在确认该操作前等待后台 blob 删除完成。

display_secrets_in_show_and_select

启用或禁用在针对表、数据库、表函数和字典的 SHOW 与 SELECT 查询中显示敏感信息。希望查看敏感信息的用户，还必须启用 format_display_secrets_in_show_and_select format 设置，并拥有 displaySecretsInShowAndSelect 权限。可能的值：

0 — 禁用。
1 — 启用。

dns_max_consecutive_failures

当连续失败达到此次数后，将停止继续尝试更新主机名的 DNS 缓存。相关信息仍会保留在 DNS 缓存中。0 表示不受限制。 另请参见

SYSTEM DROP DNS CACHE

dynamic_user_defined_executable_functions_path

用于存放由驱动动态创建的可执行 UDF 配置文件的目录 (参见 CREATE FUNCTION ... ENGINE = DriverName(...)) 。服务器重启时，会扫描该目录中的配置文件，并加载相应的 UDF，而无需再次调用驱动。示例

<dynamic_user_defined_executable_functions_path>/var/lib/clickhouse/dynamic_user_defined_executable_functions/</dynamic_user_defined_executable_functions_path>

加密

配置用于获取密钥的命令，供加密编解码器使用。密钥 (或多个密钥) 应写入环境变量，或在配置文件中设置。密钥可以是十六进制值，也可以是长度为 16 字节的字符串。示例从配置加载：

<encryption_codecs>
    <aes_128_gcm_siv>
        <key>1234567812345678</key>
    </aes_128_gcm_siv>
</encryption_codecs>

不建议将密钥存储在配置文件中，这样并不安全。你可以将密钥移到安全磁盘上的单独配置文件中，并在 config.d/ 目录下放置一个指向该配置文件的符号链接。

从配置中加载 (密钥为十六进制时) ：

<encryption_codecs>
    <aes_128_gcm_siv>
        <key_hex>00112233445566778899aabbccddeeff</key_hex>
    </aes_128_gcm_siv>
</encryption_codecs>

从环境变量中加载密钥：

<encryption_codecs>
    <aes_128_gcm_siv>
        <key_hex from_env="ENVVAR"></key_hex>
    </aes_128_gcm_siv>
</encryption_codecs>

这里，current_key_id 用于设置当前的加密密钥，所有指定的密钥都可用于解密。上述每种方法都可应用于多个密钥：

<encryption_codecs>
    <aes_128_gcm_siv>
        <key_hex id="0">00112233445566778899aabbccddeeff</key_hex>
        <key_hex id="1" from_env="ENVVAR"></key_hex>
        <current_key_id>1</current_key_id>
    </aes_128_gcm_siv>
</encryption_codecs>

这里的 current_key_id 表示当前用于加密的密钥。此外，用户还可以添加长度必须为 12 字节的 nonce (默认情况下，加密和解密过程使用的 nonce 由零字节组成) ：

<encryption_codecs>
    <aes_128_gcm_siv>
        <nonce>012345678910</nonce>
    </aes_128_gcm_siv>
</encryption_codecs>

或者也可以设置为十六进制：

<encryption_codecs>
    <aes_128_gcm_siv>
        <nonce_hex>abcdefabcdef</nonce_hex>
    </aes_128_gcm_siv>
</encryption_codecs>

上述所有内容都适用于 aes_256_gcm_siv (但密钥长度必须为 32 字节) 。

enforce_keeper_component_tracking

如果启用，则每个 ZooKeeper 请求都必须通过 Coordination::setCurrentComponent 设置组件名称。如果缺少该组件，则会抛出 LOGICAL_ERROR 异常。

error_log

默认情况下处于禁用状态。启用如需手动启用错误历史记录收集功能 system.error_log，请使用以下内容创建 /etc/clickhouse-server/config.d/error_log.xml：

<clickhouse>
    <error_log>
        <database>system</database>
        <table>error_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <collect_interval_milliseconds>1000</collect_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
    </error_log>
</clickhouse>

禁用要禁用 error_log 设置，请创建以下文件 /etc/clickhouse-server/config.d/disable_error_log.xml，其内容如下：

<clickhouse>
    <error_log remove="1" />
</clickhouse>

以下设置可通过子标签配置：

Setting	Description	Default	Note
`database`	数据库名称。
`table`	系统表名称。
`engine`	系统表的 MergeTree 引擎定义。		如果已定义 `partition_by` 或 `order_by`，则不能使用。如果未指定，默认使用 `MergeTree`
`partition_by`	系统表的自定义分区键。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `partition_by` 参数
`ttl`	指定表的生存时间 (TTL)。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `ttl` 参数
`order_by`	系统表的自定义排序键。如果定义了 `engine`，则不能使用。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `order_by` 参数
`storage_policy`	该表使用的存储策略名称 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `storage_policy` 参数
`settings`	控制 MergeTree 行为的附加参数 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `settings` 参数
`flush_interval_milliseconds`	将数据从内存缓冲区刷写到表的时间间隔。	`7500`
`max_size_rows`	日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。	`1048576`
`reserved_size_rows`	为日志预分配的内存行数。	`8192`
`buffer_size_rows_flush_threshold`	行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。	`max_size_rows / 2`
`flush_on_crash`	设置在发生崩溃时是否将日志转储到磁盘。	`false`

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

设置	描述	默认值
`skip_alias_columns`	为 `true` 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。	`false`

filesystem_caches_path

此设置指定缓存路径。示例

<filesystem_caches_path>/var/lib/clickhouse/filesystem_caches/</filesystem_caches_path>

google_protos_path

用于指定包含 Protobuf 类型 proto 文件的目录。示例

<google_protos_path>/usr/share/clickhouse/protos/</google_protos_path>

handshake_timeout_milliseconds

整个 TCP 握手阶段 (Hello + Addendum) 的挂钟时间超时时间，以毫秒为单位。限制未经身份验证的连接占用线程的最长时间。设为 0 可禁用。

hdfs.libhdfs3_conf

将 libhdfs3 指向其配置的正确位置。

hsts_max_age

HSTS 的过期时间，单位为秒。

值为 0 表示 ClickHouse 禁用 HSTS。如果设置为正数，则会启用 HSTS，且 max-age 为你设置的数值。

示例

<hsts_max_age>600000</hsts_max_age>

iceberg_background_schedule_pool_size

用于异步从远程 Iceberg catalog 拉取最新元数据的线程池大小；所有活跃表共享该线程池。

iceberg_manifest_decode_thread_pool_queue_size

可在用于解码 Iceberg 数据 manifest 文件的线程池上调度的最大作业数。

ignore_empty_sql_security_in_create_view_query

如果为 true，未指定 DEFINER 或 SQL SECURITY 的 CREATE VIEW 或 CREATE MATERIALIZED VIEW 查询将按原样存储，视图的 SQL security 类型为空。仅指定 DEFINER 视为指定 SQL SECURITY DEFINER，因此此类查询不受此设置影响。SQL security 类型为空的普通视图将以调用者的权限运行。对于显式指定目标表的 materialized view，将跳过对目标表的访问检查：向源表 insert 时无需拥有目标表的 INSERT privilege，从该视图读取时也无需拥有其 SELECT privilege。如果为 false，则在创建时会将 default_normal_view_sql_security、default_materialized_view_sql_security 和 default_view_definer 设置的默认值写入视图定义。使用这些设置的默认值时，未指定任何子句创建的 materialized view 会将创建该视图的用户记录为 definer，并以该用户的权限运行。可刷新materialized view 始终采用默认值，不受此设置影响。

更改此设置仅影响之后创建的视图；现有视图已存储的定义保持不变。

include_from

包含替换内容的文件路径。支持 XML 和 YAML 格式。有关详细信息，请参阅配置文件章节。默认为空，即不使用替换文件。在 26.8 版本之前，只要 /etc/metrika.xml 文件存在，系统就会隐式使用该文件；如果您依赖此文件，请显式指定其路径。请注意，独立于主服务器配置加载的配置文件——用户配置 (例如未包含在主文件中的 users.xml) 和 XML 字典配置——会从自身内容中读取 include_from 元素，而非从服务器配置中读取。每个依赖替换的此类文件都需要各自的 include_from 元素。示例

<include_from>/etc/clickhouse-server/substitutions.xml</include_from>

insert_deduplication_version

已弃用的迁移保护设置。ClickHouse 26.7 及更高版本仅支持统一的插入去重哈希 (new_unified_hash) ；如果存在此设置且值为任何其他值 (例如 old_separate_hashes 或 compatible_double_hashes) ，服务器将拒绝启动。升级前，请先在上一版本中运行 compatible_double_hashes 完成去重迁移 (该模式会同时写入旧版哈希和统一哈希) 。对于复制表，请至少运行 replicated_deduplication_window_seconds 对应的时长 (默认一小时) ；默认窗口会保留该窗口内所有 insert 的统一哈希，通常足以覆盖 insert 重试循环。对于 non_replicated_deduplication_window > 0 的非复制表，该窗口按计数而非按时间计算，因此升级前请至少运行 compatible_double_hashes 达到相同数量的 insert。

io_thread_pool_queue_size

可在 IO Thread pool 中调度的作业最大数量。

值为 0 表示不受限制。

keep_alive_timeout

ClickHouse 在关闭连接前，针对 HTTP 协议等待传入请求的秒数。示例

<keep_alive_timeout>30</keep_alive_timeout>

ldap_servers

在此处列出 LDAP 服务器及其连接参数，以便：

将其用作专用本地用户的身份验证器，这些用户指定的是 ldap 身份验证机制而非 password
将其用作远程用户目录。

以下设置可通过子标签进行配置：

Setting	Description
`bind_dn`	用于构造要绑定的 DN 的模板。生成的 DN 会在每次身份验证尝试时，通过将模板中的所有 `\{user_name\}` 子串替换为实际用户名来构造。
`enable_tls`	用于控制是否与 LDAP 服务器建立安全连接的标志。对明文 (`ldap://`) 协议指定 `no` (不推荐) 。对基于 SSL/TLS 的 LDAP (`ldaps://`) 协议指定 `yes` (推荐，也是默认值) 。对旧版 StartTLS 协议指定 `starttls` (即明文 (`ldap://`) 协议升级为 TLS) 。
`host`	LDAP 服务器主机名或 IP，此参数为必填项且不能为空。
`port`	LDAP 服务器端口；如果 `enable_tls` 设置为 true，则默认值为 636，否则为 `389`。
`tls_ca_cert_dir`	包含 CA certificates 的目录路径。
`tls_ca_cert_file`	CA certificate 文件的路径。
`tls_cert_file`	certificate 文件的路径。
`tls_cipher_suite`	允许的密码套件 (采用 OpenSSL 表示法) 。
`tls_key_file`	certificate key 文件的路径。
`tls_minimum_protocol_version`	SSL/TLS 的最低协议版本。可接受的值为：`ssl2`、`ssl3`、`tls1.0`、`tls1.1`、`tls1.2` (默认值) 。
`tls_require_cert`	SSL/TLS 对端 certificate verification 的行为。可接受的值为：`never`、`allow`、`try`、`demand` (默认值) 。
`user_dn_detection`	包含 LDAP 搜索参数的部分，用于检测已绑定用户的实际 user DN。当 server 为 Active Directory 时，这主要用于后续 role mapping 中的搜索过滤器。生成的 user DN 会在允许使用 `\{user_dn\}` 子串的任何位置替换时使用。默认情况下，user DN 与 bind DN 相同，但执行搜索后，它会更新为实际检测到的 user DN 值。
`verification_cooldown`	成功执行绑定后的一段时间内 (以秒为单位) ，系统会假定该用户在所有后续 request 中都已成功通过身份验证，而无需联系 LDAP 服务器。指定 `0` (默认值) 可禁用缓存，并强制每次身份验证 request 都联系 LDAP 服务器。

设置 user_dn_detection 可通过子标签进行配置：

Setting	Description
`base_dn`	用于构造 LDAP 搜索 base DN 的模板。生成的 DN 会在 LDAP 搜索期间，通过将模板中的所有 `\{user_name\}` 和 ‘{bind_dn}’ 子串替换为实际用户名和 bind DN 来构造。
`scope`	LDAP 搜索的范围。可接受的值为：`base`、`one_level`、`children`、`subtree` (默认值) 。
`search_filter`	用于构造 LDAP 搜索 search filter 的模板。生成的过滤器会在 LDAP 搜索期间，通过将模板中的所有 `\{user_name\}`、`\{bind_dn\}` 和 `\{base_dn\}` 子串替换为实际用户名、bind DN 和 base DN 来构造。请注意，特殊字符必须在 XML 中正确转义。

示例：

<my_ldap_server>
    <host>localhost</host>
    <port>636</port>
    <bind_dn>uid={user_name},ou=users,dc=example,dc=com</bind_dn>
    <verification_cooldown>300</verification_cooldown>
    <enable_tls>yes</enable_tls>
    <tls_minimum_protocol_version>tls1.2</tls_minimum_protocol_version>
    <tls_require_cert>demand</tls_require_cert>
    <tls_cert_file>/path/to/tls_cert_file</tls_cert_file>
    <tls_key_file>/path/to/tls_key_file</tls_key_file>
    <tls_ca_cert_file>/path/to/tls_ca_cert_file</tls_ca_cert_file>
    <tls_ca_cert_dir>/path/to/tls_ca_cert_dir</tls_ca_cert_dir>
    <tls_cipher_suite>ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:AES256-GCM-SHA384</tls_cipher_suite>
</my_ldap_server>

示例 (典型的 Active Directory，已配置 user DN 检测，用于后续角色映射) ：

<my_ad_server>
    <host>localhost</host>
    <port>389</port>
    <bind_dn>EXAMPLE\{user_name}</bind_dn>
    <user_dn_detection>
        <base_dn>CN=Users,DC=example,DC=com</base_dn>
        <search_filter>(&amp;(objectClass=user)(sAMAccountName={user_name}))</search_filter>
    </user_dn_detection>
    <enable_tls>no</enable_tls>
</my_ad_server>

日志记录器

日志消息的位置和格式。键：

Key	Description
`async`	当为 `true` (默认) 时，日志将异步记录 (每个输出通道一个后台线程) 。否则，会在调用 LOG 的线程内记录日志
`async_queue_max_size`	使用异步日志时，队列中等待写出的消息最大保留数量。超出的消息将被丢弃
`console`	启用将日志输出到控制台。设置为 `1` 或 `true` 以启用。如果 ClickHouse 未以守护进程模式运行，默认值为 `1`；否则为 `0`。
`console_log_level`	控制台输出的日志级别。默认值为 `level`。
`console_shutdown_log_level`	Shutdown level 用于在服务器关闭时设置控制台日志级别。
`console_startup_log_level`	启动级别用于在服务器启动时设置控制台日志级别。启动完成后，日志级别会恢复为 `console_log_level` 设置
`count`	轮转策略：ClickHouse 最多保留多少个历史日志文件。
`errorlog`	错误日志文件的路径。
`formatting.type`	控制台输出的日志格式。目前仅支持 `json`
`level`	日志级别。可接受的值：`none` (关闭日志) 、`fatal`、`critical`、`error`、`warning`、`notice`、`information`、`debug`、`trace`、`test`
`log`	日志文件的路径。
`rotation`	轮转策略：控制何时轮转日志文件。轮转可以基于大小、时间，或两者结合。示例：100M、daily、100M,daily。一旦日志文件超过指定大小，或达到指定时间间隔，就会将其重命名并归档，然后创建新的日志文件。
`shutdown_level`	Shutdown level 用于在服务器关闭时设置根 logger 级别。
`size`	轮转策略：日志文件的最大大小 (以字节为单位) 。一旦日志文件大小超过此阈值，就会将其重命名并归档，然后创建新的日志文件。
`startup_level`	启动级别用于在服务器启动时设置根 logger 级别。启动完成后，日志级别会恢复为 `level` 设置
`stream_compress`	使用 LZ4 压缩日志消息。设置为 `1` 或 `true` 以启用。
`syslog_level`	输出到 syslog 的日志级别。
`use_syslog`	同时将日志输出转发到 syslog。

日志格式说明符 log 和 errorLog 路径中的文件名支持以下格式说明符，用于生成结果文件名 (目录部分不支持这些说明符) 。 “Example”列显示的是 2023-07-06 18:32:07 时的输出。

说明符	描述	示例
`%%`	字面 `%`	`%`
`%n`	换行符
`%t`	水平制表符
`%Y`	以十进制数表示的年份，例如 2017	`2023`
`%y`	以十进制数表示的年份后 2 位 (范围 [00,99])	`23`
`%C`	以十进制数表示的年份前 2 位 (范围 [00,99])	`20`
`%G`	四位数的 ISO 8601 基于周的年份，即包含指定周的年份。通常仅在与 `%V` 一起使用时有意义	`2023`
`%g`	ISO 8601 基于周的年份的后 2 位，即包含指定周的年份。	`23`
`%b`	月份名称缩写，例如 Oct (取决于区域设置)	`Jul`
`%h`	`%b` 的同义写法	`Jul`
`%B`	完整月份名称，例如 October (取决于区域设置)	`July`
`%m`	以十进制数表示的月份 (范围 [01,12])	`07`
`%U`	以十进制数表示的一年中的周数 (星期日为一周的第一天) (范围 [00,53])	`27`
`%W`	以十进制数表示的一年中的周数 (星期一为一周的第一天) (范围 [00,53])	`27`
`%V`	ISO 8601 周数 (范围 [01,53])	`27`
`%j`	以十进制数表示的一年中的第几天 (范围 [001,366])	`187`
`%d`	以零填充的十进制数表示的一月中的第几天 (范围 [01,31]) 。个位数前补零。	`06`
`%e`	以空格填充的十进制数表示的一月中的第几天 (范围 [1,31]) 。个位数前补空格。	`  6`
`%a`	星期名称缩写，例如 Fri (取决于区域设置)	`Thu`
`%A`	完整星期名称，例如 Friday (取决于区域设置)	`Thursday`
`%w`	以整数表示的星期几，其中星期日为 0 (范围 [0-6])	`4`
`%u`	以十进制数表示的星期几，其中星期一为 1 (ISO 8601 格式) (范围 [1-7])	`4`
`%H`	以十进制数表示的小时，24 小时制 (范围 [00-23])	`18`
`%I`	以十进制数表示的小时，12 小时制 (范围 [01,12])	`06`
`%M`	以十进制数表示的分钟 (范围 [00,59])	`32`
`%S`	以十进制数表示的秒 (范围 [00,60])	`07`
`%c`	标准日期时间字符串，例如 Sun Oct 17 04:41:13 2010 (取决于区域设置)	`Thu Jul 6 18:32:07 2023`
`%x`	本地化日期表示 (取决于区域设置)	`07/06/23`
`%X`	本地化时间表示，例如 18:40:20 或 6:40:20 PM (取决于区域设置)	`18:32:07`
`%D`	简短的 MM/DD/YY 日期格式，等同于 `%m/%d/%y`	`07/06/23`
`%F`	简短的 YYYY-MM-DD 日期，等同于 %Y-%m-%d	`2023-07-06`
`%r`	本地化的 12 小时制时间 (取决于区域设置)	`06:32:07 PM`
`%R`	等同于 “%H:%M”	`18:32`
`%T`	等同于 “%H:%M:%S” (ISO 8601 时间格式)	`18:32:07`
`%p`	本地化的上午/下午标识 (取决于区域设置)	`PM`
`%z`	ISO 8601 格式的 UTC 偏移量 (例如 -0430) ；如果时区信息不可用，则不显示任何字符	`+0800`
`%Z`	依赖区域设置的时区名称或缩写；如果时区信息不可用，则不显示任何字符	`Z AWST`

示例

<logger>
    <level>trace</level>
    <log>/var/log/clickhouse-server/clickhouse-server-%F-%T.log</log>
    <errorlog>/var/log/clickhouse-server/clickhouse-server-%F-%T.err.log</errorlog>
    <size>1000M</size>
    <count>10</count>
    <stream_compress>true</stream_compress>
</logger>

若仅将日志消息打印到控制台：

<logger>
    <level>information</level>
    <console>true</console>
</logger>

按级别覆盖 可以覆盖各个日志名称的日志级别。例如，要将日志记录器 “Backup” 和 “RBAC” 的所有消息静默。

<logger>
    <levels>
        <logger>
            <name>Backup</name>
            <level>none</level>
        </logger>
        <logger>
            <name>RBAC</name>
            <level>none</level>
        </logger>
    </levels>
</logger>

syslog 如需额外将日志消息写入 syslog：

<logger>
    <use_syslog>1</use_syslog>
    <syslog>
        <address>syslog.remote:10514</address>
        <hostname>myhost.local</hostname>
        <facility>LOG_LOCAL6</facility>
        <format>syslog</format>
    </syslog>
</logger>

<syslog> 的键：

Key	Description
`address`	syslog 地址，格式为 `host\[:port\]`。如果省略，则使用本地守护进程。
`hostname`	发送日志的主机名 (可选) 。
`facility`	syslog 的 facility 关键字。必须使用带有 “LOG_” 前缀的大写形式指定，例如 `LOG_USER`、`LOG_DAEMON`、`LOG_LOCAL3` 等。默认值：如果指定了 `address`，则为 `LOG_USER`；否则为 `LOG_DAEMON`。
`format`	日志消息格式。可选值：`bsd` 和 `syslog.`

日志格式 你可以指定输出到控制台日志中的日志格式。目前仅支持 JSON。示例下面是一个输出 JSON 日志的示例：

{
  "date_time_utc": "2024-11-06T09:06:09Z",
  "date_time": "1650918987.180175",
  "thread_name": "#1",
  "thread_id": "254545",
  "level": "Trace",
  "query_id": "",
  "logger_name": "BaseDaemon",
  "message": "Received signal 2",
  "source_file": "../base/daemon/BaseDaemon.cpp; virtual void SignalListener::run()",
  "source_line": "192"
}

要启用 JSON 日志支持，可使用以下代码片段：

<logger>
    <formatting>
        <type>json</type>
        <!-- Can be configured on a per-channel basis (log, errorlog, console, syslog), or globally for all channels (then just omit it). -->
        <!-- <channel></channel> -->
        <names>
            <date_time>date_time</date_time>
            <thread_name>thread_name</thread_name>
            <thread_id>thread_id</thread_id>
            <level>level</level>
            <query_id>query_id</query_id>
            <logger_name>logger_name</logger_name>
            <message>message</message>
            <source_file>source_file</source_file>
            <source_line>source_line</source_line>
        </names>
    </formatting>
</logger>

重命名 JSON 日志中的键 可以通过修改 <names> 标签内各项标签的值来更改键名。例如，要将 DATE_TIME 改为 MY_DATE_TIME，可以使用 <date_time>MY_DATE_TIME</date_time>。 省略 JSON 日志中的键 可以通过将相应属性注释掉来省略日志属性。例如，如果你不希望日志输出 query_id，可以将 <query_id> 标签注释掉。

logger.count

轮转策略：最多保留多少个 ClickHouse 历史日志文件。

logger.errorlog

错误日志文件的路径。

logger.formatting.type

控制台输出的日志格式。目前仅支持 <json>。

logger.level

日志级别。可接受的值：<none> (关闭日志) 、<fatal>、<critical>、<error>、<warning>、<notice>、<information>、<debug>、<trace>、<test>。

logger.log

日志文件路径。

logger.rotation

轮转策略：用于控制日志文件何时进行轮转。轮转可基于大小、时间，或两者结合。示例：100M、daily、100M,daily。日志文件一旦超过指定大小，或达到指定时间间隔时，就会被重命名并归档，同时创建新的日志文件。

logger.shutdown_level

Shutdown level 用于在服务器关闭时设置根日志记录器的级别。

logger.size

轮转策略：日志文件的最大大小 (单位为字节) 。一旦日志文件大小超过此阈值，该文件会被重命名并归档，同时创建一个新的日志文件。

logger.startup_level

启动级别用于在服务器启动时设置根日志记录器的级别。启动完成后，日志级别会恢复为 <level> 设置。

logger.stream_compress

使用 LZ4 压缩日志消息。将其设置为 <1> 或 <true> 以启用。

logger.syslog_level

写入 syslog 的日志级别。

logger.use_syslog

同时将日志输出转发到 syslog。

macros

用于复制表的参数替换。如果不使用复制表，则可省略。更多信息，请参阅创建复制表一节。示例

<macros incl="macros" optional="true" />

message_queue_disable_insertion

禁用消息队列引擎 (Kafka、RabbitMQ、NATS) 向已附加的 materialized view 进行插入

metric_log

默认情况下，它是禁用的。启用如需手动启用指标历史记录收集 system.metric_log，请创建 /etc/clickhouse-server/config.d/metric_log.xml，内容如下：

<clickhouse>
    <metric_log>
        <database>system</database>
        <table>metric_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <collect_interval_milliseconds>1000</collect_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
    </metric_log>
</clickhouse>

禁用要禁用 metric_log 设置，请创建以下文件 /etc/clickhouse-server/config.d/disable_metric_log.xml，内容如下：

<clickhouse>
    <metric_log remove="1" />
</clickhouse>

以下设置可通过子标签配置：

Setting	Description	Default	Note
`database`	数据库名称。
`table`	系统表名称。
`engine`	系统表的 MergeTree 引擎定义。		如果已定义 `partition_by` 或 `order_by`，则不能使用。如果未指定，默认使用 `MergeTree`
`partition_by`	系统表的自定义分区键。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `partition_by` 参数
`ttl`	指定表的生存时间 (TTL)。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `ttl` 参数
`order_by`	系统表的自定义排序键。如果定义了 `engine`，则不能使用。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `order_by` 参数
`storage_policy`	该表使用的存储策略名称 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `storage_policy` 参数
`settings`	控制 MergeTree 行为的附加参数 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `settings` 参数
`flush_interval_milliseconds`	将数据从内存缓冲区刷写到表的时间间隔。	`7500`
`max_size_rows`	日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。	`1048576`
`reserved_size_rows`	为日志预分配的内存行数。	`8192`
`buffer_size_rows_flush_threshold`	行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。	`max_size_rows / 2`
`flush_on_crash`	设置在发生崩溃时是否将日志转储到磁盘。	`false`

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

设置	描述	默认值
`skip_alias_columns`	为 `true` 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。	`false`

mmap_cache_size

此设置可避免频繁调用 open/close (由于随之产生的缺页异常，这类调用开销很高) ，并让多个线程和查询复用映射。该设置值表示映射区域的数量 (通常等于映射文件的数量) 。可以在以下系统表中通过下列指标监控映射文件中的数据量：

system.metrics、system.metric_log 中的 MMappedFiles/MMappedFileBytes/MMapCacheCells
system.events、system.processes、system.query_log、system.query_thread_log、system.query_views_log 中的 CreatedReadBufferMMap/CreatedReadBufferMMapFailed/MMappedFileCacheHits/MMappedFileCacheMisses

映射文件中的数据量不会直接占用内存，也不会计入查询或服务器的内存使用量，因为这部分内存可以像操作系统页缓存一样被丢弃。该缓存在 MergeTree 家族表中的旧 parts 被移除时会自动丢弃 (文件会被关闭) ，也可以通过 SYSTEM DROP MMAP CACHE 查询手动丢弃。此设置可在运行时修改，并会立即生效。

mutation_workload

用于调节变更与其他工作负载之间资源的使用和共享方式。指定的值将作为所有后台变更的 workload 设置值。该值可被 MergeTree 设置覆盖。 另请参见

Workload Scheduling

named_collections_storage.type

named collections 的存储类型。可选值为 local、local_encrypted、keeper、 keeper_encrypted、zookeeper 和 zookeeper_encrypted。配置为 named_collections_storage.type (在 XML 中为 <named_collections_storage><type>) 。

oom_score

在 Linux 系统中，此设置可控制 OOM killer 的行为。

openSSL

SSL 客户端/服务器配置。 libpoco 库提供了对 SSL 的支持。可用的配置选项说明见 SSLManager.h。默认值可在 SSLManager.cpp 中找到。 certificateFile、privateKeyFile 和 caConfig 所引用的文件在发生变更时或执行 SYSTEM RELOAD CONFIG 时会被重新加载，无需重启。新建立的连接使用重新加载后的证书，已建立的连接不受影响。服务器/客户端设置项：

选项	说明	默认值
`cacheSessions`	启用或禁用会话缓存。必须与 `sessionIdContext` 搭配使用。可选值：`true`、`false`。	`false`
`caConfig`	包含受信任 CA 证书的文件或目录路径。如果指向的是文件，则该文件必须为 PEM 格式，并且可以包含多个 CA 证书。如果指向的是目录，则其中每个 CA 证书都必须对应一个 .pem 文件。文件名会根据 CA subject name 哈希值进行查找。详情请参阅 SSL_CTX_load_verify_locations 的 man page。与 `certificateFile` 和 `privateKeyFile` 一样，当文件发生变化或执行 `SYSTEM RELOAD CONFIG` 时，CA 证书会在无需重启的情况下重新加载。
`certificateFile`	PEM 格式的客户端/服务器证书文件路径。如果 `privateKeyFile` 中包含该证书，则可省略。
`cipherList`	支持的 OpenSSL 加密套件。	`ALL:!ADH:!LOW:!EXP:!MD5:!3DES:@STRENGTH`
`disableProtocols`	禁止使用的协议。
`extendedVerification`	如果启用，则验证证书的 CN 或 SAN 是否与对端主机名匹配。	`openSSL.client` 为 `true`，`openSSL.server` 为 `false`
`fips`	启用 OpenSSL FIPS 模式。如果该库使用的 OpenSSL 版本支持 FIPS，则此功能受支持。	`false`
`invalidCertificateHandler`	用于验证无效证书的处理程序类 (CertificateHandler 的子类) 。例如：`<invalidCertificateHandler> <name>RejectCertificateHandler</name> </invalidCertificateHandler>`。	`RejectCertificateHandler`
`loadDefaultCAFile`	是否使用 OpenSSL 的内置 CA 证书。ClickHouse 认为，内置 CA 证书位于文件 `/etc/ssl/cert.pem` (或目录 `/etc/ssl/certs`) 中，或者位于环境变量 `SSL_CERT_FILE` (或 `SSL_CERT_DIR`) 指定的文件 (或目录) 中。	`true`
`preferServerCiphers`	优先使用客户端选择的服务器密码套件。	`false`
`privateKeyFile`	包含 PEM 证书私钥的文件路径。该文件也可以同时包含私钥和证书。
`privateKeyPassphraseHandler`	用于获取访问私钥所需口令的类 (PrivateKeyPassphraseHandler 的子类) 。例如：`<privateKeyPassphraseHandler>`、`<name>KeyFileHandler</name>`、`<options><password>test</password></options>`、`</privateKeyPassphraseHandler>`。	`KeyConsoleHandler`
`requireTLSv1`	要求使用 TLSv1 连接。可选值：`true`、`false`。	`false`
`requireTLSv1_1`	要求使用 TLSv1.1 连接。可选值：`true`、`false`。	`false`
`requireTLSv1_2`	要求使用 TLSv1.2 连接。可接受的值：`true`、`false`。	`false`
`sessionCacheSize`	服务器可缓存的最大会话数。值为 `0` 表示会话数不受限制。	1024*20
`sessionIdContext`	一组唯一的随机字符，服务器会将其附加到每个生成的标识符上。该字符串的长度不得超过 `SSL_MAX_SSL_SESSION_ID_LENGTH`。始终建议设置此参数，因为无论是服务器缓存了会话，还是客户端请求了缓存，它都有助于避免出现问题。	`$\{application.name\}`
`sessionTimeout`	服务器缓存会话的时长 (单位：小时) 。	`2`
`verificationDepth`	验证链的最大长度。如果证书链长度超过设定值，验证会失败。	`9`
`verificationMode`	用于验证节点证书的方法。详见 Context 类的说明。可能的值：`none`、`relaxed`、`strict`、`once`。	`relaxed`

设置示例：

<openSSL>
    <server>
        <!-- openssl req -subj "/CN=localhost" -new -newkey rsa:2048 -days 365 -nodes -x509 -keyout /etc/clickhouse-server/server.key -out /etc/clickhouse-server/server.crt -->
        <certificateFile>/etc/clickhouse-server/server.crt</certificateFile>
        <privateKeyFile>/etc/clickhouse-server/server.key</privateKeyFile>
        <!-- openssl dhparam -out /etc/clickhouse-server/dhparam.pem 4096 -->
        <dhParamsFile>/etc/clickhouse-server/dhparam.pem</dhParamsFile>
        <verificationMode>none</verificationMode>
        <loadDefaultCAFile>true</loadDefaultCAFile>
        <cacheSessions>true</cacheSessions>
        <disableProtocols>sslv2,sslv3</disableProtocols>
        <preferServerCiphers>true</preferServerCiphers>
    </server>
    <client>
        <loadDefaultCAFile>true</loadDefaultCAFile>
        <cacheSessions>true</cacheSessions>
        <disableProtocols>sslv2,sslv3</disableProtocols>
        <preferServerCiphers>true</preferServerCiphers>
        <!-- Use for self-signed: <verificationMode>none</verificationMode> -->
        <invalidCertificateHandler>
            <!-- Use for self-signed: <name>AcceptCertificateHandler</name> -->
            <name>RejectCertificateHandler</name>
        </invalidCertificateHandler>
    </client>
</openSSL>

openSSL.client.caConfig

指向包含受信任 CA 证书的文件或目录的 path。如果指向文件，则该文件必须为 PEM 格式，并且可以包含多个 CA 证书。如果指向目录，则目录中必须为每个 CA 证书提供一个 .pem 文件。文件名会根据 CA subject name 的哈希值进行查找。详见 SSL_CTX_load_verify_locations 的 man page。当文件发生变化或执行 SYSTEM RELOAD CONFIG 时，CA 证书会在无需重启的情况下重新加载；新建立的连接将使用重新加载后的证书进行验证。

openSSL.client.cacheSessions

启用或禁用会话缓存。必须与 <sessionIdContext> 配合使用。可选值：<true>、<false>。

openSSL.client.certificateFile

PEM 格式的客户端/服务器证书文件的路径。如果 <privateKeyFile> 中已包含该证书，则可省略此项。

openSSL.client.cipherList

支持的 OpenSSL 加密套件列表。

openSSL.client.disableProtocols

禁止使用的协议。

openSSL.client.extendedVerification

启用后，会验证证书的 CN 或 SAN 是否与对端主机名一致。

openSSL.client.fips

启用 OpenSSL FIPS 模式。仅当该库使用的 OpenSSL 版本支持 FIPS 时，此设置才受支持。

openSSL.client.invalidCertificateHandler.name

用于校验无效证书的类 (CertificateHandler 的子类) 。例如：<<invalidCertificateHandler> <name>RejectCertificateHandler</name> </invalidCertificateHandler>>。

openSSL.client.loadDefaultCAFile

确定是否使用默认 CA 证书。ClickHouse 会在文件 </etc/ssl/cert.pem> (或目录 </etc/ssl/certs>) 、环境变量 <SSL_CERT_FILE> (或 <SSL_CERT_DIR>) 指定的文件 (或目录) ，以及各发行版的其他常见位置中查找这些证书。如果文件系统中未找到 CA 证书、未显式配置 caConfig，且二进制文件构建时嵌入了 CA 证书 (默认如此，由 ENABLE_EMBEDDED_CA_CERTIFICATES 构建选项控制) ，则会改用嵌入式证书。因此，即使在没有任何文件的最小化环境中 (例如“从零开始”构建的容器) ，TLS 也能正常工作。如果构建中未嵌入 CA 证书，则在这种情况下会引发错误。

openSSL.client.preferServerCiphers

优先使用服务器端的密码套件。

openSSL.client.privateKeyFile

包含 PEM 证书私钥的文件的路径。该文件也可以同时包含私钥和证书。

openSSL.client.privateKeyPassphraseHandler.name

用于请求访问私钥所需口令短语的类 (PrivateKeyPassphraseHandler 的子类) 。例如：<<privateKeyPassphraseHandler>>, <<name>KeyFileHandler</name>>, <<options><password>test</password></options>>, <</privateKeyPassphraseHandler>>

openSSL.client.verificationDepth

证书验证链的最大长度。若证书链长度超过设定值，验证将失败。

openSSL.client.verificationMode

用于验证节点证书的方式。详见 Context 类的说明。可能的值：<none>、<relaxed>、<strict>、<once>。

openSSL.server.caConfig

指向包含受信任 CA 证书的文件或目录的路径。如果这里指向一个文件，则该文件必须采用 PEM 格式，并且可以包含多个 CA 证书。如果这里指向一个目录，则该目录中必须为每个 CA 证书提供一个 .pem 文件。文件名通过 CA subject name 的哈希值查找。详细信息请参见 SSL_CTX_load_verify_locations 的 man page。当文件发生变化或执行 SYSTEM RELOAD CONFIG 时，CA 证书会在不重启的情况下重新加载；新的连接将使用重新加载后的证书进行验证。

openSSL.server.cacheSessions

启用或禁用会话缓存。必须与 <sessionIdContext> 配合使用。可接受值：<true>、<false>。

openSSL.server.certificateFile

PEM 格式的客户端/服务器证书文件的路径。如果 <privateKeyFile> 中包含该证书，则可省略此项。

openSSL.server.cipherList

支持的 OpenSSL 加密套件。

openSSL.server.disableProtocols

禁止使用的协议。

openSSL.server.extendedVerification

如果启用，将验证证书的 CN 或 SAN 是否与对端主机名匹配。

openSSL.server.fips

启用 OpenSSL FIPS 模式。仅当该库使用的 OpenSSL 版本支持 FIPS 时，此功能才受支持。

openSSL.server.invalidCertificateHandler.name

用于校验无效证书的类 (CertificateHandler 的子类) 。例如：<<invalidCertificateHandler> <name>RejectCertificateHandler</name> </invalidCertificateHandler>>。

openSSL.server.loadDefaultCAFile

决定是否使用默认 CA 证书。ClickHouse 会在文件 </etc/ssl/cert.pem> (或目录 </etc/ssl/certs>) 中、环境变量 <SSL_CERT_FILE> (或 <SSL_CERT_DIR>) 所指定的文件 (或目录) 中，以及各发行版的其他常见位置中查找这些证书。如果在文件系统上未找到 CA 证书，也未显式配置 caConfig，且二进制文件构建时启用了嵌入式 CA 证书 (默认行为，由 ENABLE_EMBEDDED_CA_CERTIFICATES 构建选项控制) ，则会改用嵌入式证书，因此即使在没有任何文件的极简环境中 (例如以 “从零开始” 构建的容器中) ，TLS 仍可正常工作。而在未嵌入式 CA 证书的构建中，这种情况下会抛出错误。

openSSL.server.preferServerCiphers

优先使用服务器端密码套件，而非客户端偏好的密码套件。

openSSL.server.privateKeyFile

包含 PEM 证书私钥的文件的路径。该文件也可以同时包含私钥和证书。

openSSL.server.privateKeyPassphraseHandler.name

openSSL.server.sessionCacheSize

服务器可缓存的最大会话数。值为 0 表示会话数不受限制。

openSSL.server.sessionIdContext

一串唯一的随机字符，服务器会将其附加到每个生成的标识符中。该字符串的长度不得超过 <SSL_MAX_SSL_SESSION_ID_LENGTH>。始终建议设置此参数，因为无论是服务器缓存了会话，还是客户端请求了缓存，它都有助于避免出现问题。

openSSL.server.sessionTimeout

在服务器上缓存会话的时长 (以小时为单位) 。

openSSL.server.verificationDepth

证书验证链的最大长度。若证书链长度超过该设置值，验证将失败。

openSSL.server.verificationMode

检查节点证书的方式。详见 Context 类的说明。可能的值：<none>、<relaxed>、<strict>、<once>。

opentelemetry_span_log

opentelemetry_span_log 系统表的设置。以下设置可通过子标签配置：

Setting	Description	Default	Note
`database`	数据库名称。
`table`	系统表名称。
`engine`	系统表的 MergeTree 引擎定义。		如果已定义 `partition_by` 或 `order_by`，则不能使用。如果未指定，默认使用 `MergeTree`
`partition_by`	系统表的自定义分区键。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `partition_by` 参数
`ttl`	指定表的生存时间 (TTL)。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `ttl` 参数
`order_by`	系统表的自定义排序键。如果定义了 `engine`，则不能使用。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `order_by` 参数
`storage_policy`	该表使用的存储策略名称 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `storage_policy` 参数
`settings`	控制 MergeTree 行为的附加参数 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `settings` 参数
`flush_interval_milliseconds`	将数据从内存缓冲区刷写到表的时间间隔。	`7500`
`max_size_rows`	日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。	`1048576`
`reserved_size_rows`	为日志预分配的内存行数。	`8192`
`buffer_size_rows_flush_threshold`	行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。	`max_size_rows / 2`
`flush_on_crash`	设置在发生崩溃时是否将日志转储到磁盘。	`false`

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

设置	描述	默认值
`skip_alias_columns`	为 `true` 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。	`false`

示例：

<opentelemetry_span_log>
    <engine>
        engine MergeTree
        partition by toYYYYMM(finish_date)
        order by (finish_date, finish_time_us, trace_id)
    </engine>
    <database>system</database>
    <table>opentelemetry_span_log</table>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</opentelemetry_span_log>

part_log

记录与 MergeTree 相关的日志事件，例如添加或合并数据。你可以使用这些日志来模拟合并算法并比较其特性，也可以将合并过程可视化。查询会记录到 system.part_log 表中，而不是单独的文件中。你可以通过 table 参数配置该表的名称 (见下文) 。以下设置可通过子标签配置：

Setting	Description	Default	Note
`database`	数据库名称。
`table`	系统表名称。
`engine`	系统表的 MergeTree 引擎定义。		如果已定义 `partition_by` 或 `order_by`，则不能使用。如果未指定，默认使用 `MergeTree`
`partition_by`	系统表的自定义分区键。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `partition_by` 参数
`ttl`	指定表的生存时间 (TTL)。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `ttl` 参数
`order_by`	系统表的自定义排序键。如果定义了 `engine`，则不能使用。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `order_by` 参数
`storage_policy`	该表使用的存储策略名称 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `storage_policy` 参数
`settings`	控制 MergeTree 行为的附加参数 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `settings` 参数
`flush_interval_milliseconds`	将数据从内存缓冲区刷写到表的时间间隔。	`7500`
`max_size_rows`	日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。	`1048576`
`reserved_size_rows`	为日志预分配的内存行数。	`8192`
`buffer_size_rows_flush_threshold`	行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。	`max_size_rows / 2`
`flush_on_crash`	设置在发生崩溃时是否将日志转储到磁盘。	`false`

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

设置	描述	默认值
`skip_alias_columns`	为 `true` 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。	`false`

示例

<part_log>
    <database>system</database>
    <table>part_log</table>
    <partition_by>toMonday(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</part_log>

path

数据所在目录的路径。

末尾的斜杠必不可少。

示例

<path>/var/lib/clickhouse/</path>

per_cpu_untracked_memory_thread_buffer

每个线程在不占用每 CPU 共享预算的情况下，可保留的未跟踪内存量，单位为字节。它通过在小额内存分配时分摊每 CPU 记账开销来降低成本；在最坏情况下，还会作为额外余量叠加到 max_per_cpu_untracked_memory * number_of_cpus 之上。值为 0 时会移除这部分余量：每次 allocation 都会更新共享的每 CPU 计数器 (精度最高，但 contention 也更高) 。仅限 Linux。

point_in_polygon_cache_size

函数 pointInPolygon 在使用常量 Polygon 参数时，其预处理多边形缓存的最大大小 (以字节为单位) 。超过此限制的条目会按照最近最少使用顺序被逐出。将其设置为 0 会禁用缓存：所有已缓存的多边形都会被逐出，之后的每个查询都会重新预处理其常量多边形。也可以在不更改此限制的情况下，使用 SYSTEM DROP POINT IN POLYGON CACHE 查询手动清除此缓存。

此设置可在运行时修改，并会立即生效。

prefixes_deserialization_thread_pool_thread_pool_queue_size

可在 prefixes 反序列化线程池上调度的最大作业数。

值为 0 表示无限制。

prepare_system_log_tables_on_startup

如果为 true，ClickHouse 会在启动前创建所有已配置的 system.*_log 表。如果某些启动脚本依赖这些表，此设置会很有帮助。

process_query_plan_packet

此设置允许读取 QueryPlan 数据包。启用 serialize_query_plan 时，会为分布式查询发送此数据包。默认处于禁用状态，以避免查询计划二进制反序列化中的缺陷可能引发的安全问题。示例

<process_query_plan_packet>true</process_query_plan_packet>

processors_profile_log

processors_profile_log 系统表的相关设置。以下设置可通过子标签配置：

Setting	Description	Default	Note
`database`	数据库名称。
`table`	系统表名称。
`engine`	系统表的 MergeTree 引擎定义。		如果已定义 `partition_by` 或 `order_by`，则不能使用。如果未指定，默认使用 `MergeTree`
`partition_by`	系统表的自定义分区键。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `partition_by` 参数
`ttl`	指定表的生存时间 (TTL)。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `ttl` 参数
`order_by`	系统表的自定义排序键。如果定义了 `engine`，则不能使用。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `order_by` 参数
`storage_policy`	该表使用的存储策略名称 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `storage_policy` 参数
`settings`	控制 MergeTree 行为的附加参数 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `settings` 参数
`flush_interval_milliseconds`	将数据从内存缓冲区刷写到表的时间间隔。	`7500`
`max_size_rows`	日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。	`1048576`
`reserved_size_rows`	为日志预分配的内存行数。	`8192`
`buffer_size_rows_flush_threshold`	行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。	`max_size_rows / 2`
`flush_on_crash`	设置在发生崩溃时是否将日志转储到磁盘。	`false`

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

设置	描述	默认值
`skip_alias_columns`	为 `true` 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。	`false`

默认设置如下：

<processors_profile_log>
    <database>system</database>
    <table>processors_profile_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</processors_profile_log>

prometheus

暴露供 Prometheus 抓取的指标数据。设置：

endpoint – prometheus server 用于抓取指标的 HTTP 端点。以 ’/’ 开头。
port – endpoint 的端口。
metrics – 暴露来自 system.metrics 表的指标。
events – 暴露来自 system.events 表的指标。
asynchronous_metrics – 暴露来自 system.asynchronous_metrics 表的当前指标值。键值指标 (即按 CPU 核心、块设备、网络接口或磁盘细分的指标) 会为每个键暴露一个样本，并将键作为标记携带：ClickHouseAsyncMetrics_BlockReadBytes{device="sda"}。asynchronous_metrics_key_values_mode 服务器设置可改为以 26.8 之前的拼接名称暴露它们 (ClickHouseAsyncMetrics_BlockReadBytes_sda) ，或同时以两种方式暴露。
errors - 暴露自上次服务器重启以来按错误代码统计的错误数量。此信息也可从 system.errors 获取。
labels – 添加到每个暴露指标的固定标记。每个子元素定义一个标记：元素名称为标记名称 (必须匹配 [a-zA-Z_][a-zA-Z0-9_]*) ，元素值为标记值。标记值支持标准配置替换，例如 from_env 属性。如果标记名称以 __ 开头 (Prometheus 保留) ，或与此端点在某个已启用部分中写入的标记冲突，则会被拒绝——否则同一样本会携带两个同名标记。因此，保留标记集取决于端点当前启用的导出内容：启用 histograms 时为 le；启用 info 时为 ClickHouse_Info 标记 (name、version、version_describe、version_major、version_minor、version_patch) ；启用 asynchronous_metrics 且键值异步指标以键值形式发布时 (这由 asynchronous_metrics_key_values_mode 服务器设置决定) ，为这些指标的键标记 (channel、cpu、device、disk、interface、mc、sensor) ；启用 histograms/dimensional_metrics 时，则包括由暴露的直方图或维度指标族使用的所有标记 (例如 group、direction 或 operation_type) 。由于这取决于端点实际暴露的内容，某个名称在一个端点上可能有效，但在另一个端点上会被拒绝——例如，Keeper keeper_metrics_only 端点仅暴露 keeper_* 指标族，因此仅由服务器指标族使用的标记可在该端点上使用。加载配置时 (包括执行 SYSTEM RELOAD CONFIG 时) 会按同一规则校验这些固定标记：如果某次重新加载会导致固定标记冲突 (无论是新增了此类标记，还是修改了 asynchronous_metrics_key_values_mode 使得键标记开始被写入) ，该次重新加载会在生效前被整体拒绝，而不会导致同一标记被暴露两次。若该模式的修改被接受，则会重新创建暴露这些指标的端点，从而使同一配置的新形式与标记一并发布。

示例

<clickhouse>
    <listen_host>0.0.0.0</listen_host>
    <http_port>8123</http_port>
    <tcp_port>9000</tcp_port>
    <prometheus>
        <endpoint>/metrics</endpoint>
        <port>9363</port>
        <metrics>true</metrics>
        <events>true</events>
        <asynchronous_metrics>true</asynchronous_metrics>
        <errors>true</errors>
        <labels>
            <environment>production</environment>
            <shard from_env="SHARD_NAME"></shard>
        </labels>
    </prometheus>
</clickhouse>

检查 (将 127.0.0.1 替换为 ClickHouse 服务器的 IP 地址或主机名) ：

curl 127.0.0.1:9363/metrics

prometheus.keeper_metrics_only

暴露与 Keeper 相关的指标

代理

为 HTTP 和 HTTPS 请求定义代理服务器。目前 S3 存储、S3 表函数和 URL 函数支持此功能。定义代理服务器有三种方式：

环境变量
代理列表
远程代理解析器。

还支持使用 no_proxy 让特定 host 绕过代理服务器。 环境变量 http_proxy 和 https_proxy 环境变量允许你为指定协议设置代理服务器。如果你已在系统中设置了它们，通常即可直接生效。如果某种协议只有一个代理服务器，并且该代理服务器不会变化，这是最简单的方法。 代理列表 这种方法允许你为某种协议指定一个或多个代理服务器。如果定义了多个代理服务器， ClickHouse 会以轮询方式使用不同的代理，将负载分散到各个服务器上。如果某种协议有多个代理服务器，并且代理服务器列表不会变化，这是最简单的方法。 配置模板

<proxy>
    <http>
        <uri>http://proxy1</uri>
        <uri>http://proxy2:3128</uri>
    </http>
    <https>
        <uri>http://proxy1:3128</uri>
    </https>
</proxy>

在下方选项卡中选择一个父字段以查看其子字段：

<proxy>
<http> 和 <https>

Field	Description
`<http>`	一个或多个 HTTP 代理的列表
`<https>`	一个或多个 HTTPS 代理的列表

Field	Description
`<uri>`	代理的 URI

远程代理解析器 代理服务器可能会动态变化。在这种情况下，你可以定义一个解析器的端点。ClickHouse 会向该端点发送一个空的 GET 请求，远程解析器应返回代理主机。ClickHouse 将使用它按以下模板构造代理 URI：\{proxy_scheme\}://\{proxy_host\}:{proxy_port} 配置模板

<proxy>
    <http>
        <resolver>
            <endpoint>http://resolver:8080/hostname</endpoint>
            <proxy_scheme>http</proxy_scheme>
            <proxy_port>80</proxy_port>
            <proxy_cache_time>10</proxy_cache_time>
        </resolver>
    </http>

    <https>
        <resolver>
            <endpoint>http://resolver:8080/hostname</endpoint>
            <proxy_scheme>http</proxy_scheme>
            <proxy_port>3128</proxy_port>
            <proxy_cache_time>10</proxy_cache_time>
        </resolver>
    </https>

</proxy>

在下方选项卡中选择一个父字段，以查看其子字段：

<proxy>
<http> 和 <https>
<resolver>

字段	描述
`<http>`	一个或多个解析器*的列表
`<https>`	一个或多个解析器*的列表

字段	描述
`<resolver>`	解析器的端点及其他详细信息

你可以包含多个 <resolver> 元素，但对于给定协议，只会使用第一个 <resolver>。该协议的其他 <resolver> 元素都会被忽略。这意味着负载均衡 (如果需要) 应由远程解析器来实现。

字段	描述
`<endpoint>`	代理解析器的 URI
`<proxy_scheme>`	最终代理 URI 的协议。可以是 `http` 或 `https`。
`<proxy_port>`	代理解析器的端口号
`<proxy_cache_time>`	来自解析器的值应由 ClickHouse 缓存的时长 (以秒为单位) 。将此值设为 `0` 会使 ClickHouse 在每次 HTTP 或 HTTPS 请求时都联系解析器。

优先次序 代理设置按以下顺序确定：

顺序	设置
1.	远程代理解析器
2.	代理列表
3.	环境变量

ClickHouse 会检查与请求协议对应的最高优先级解析器类型。如果未定义，则会继续检查优先级次高的解析器类型，直到环境解析器为止。这也意味着可以混合使用多种解析器类型。

remap_executable

用于使用大页重新分配机器代码 (“text”) 内存的设置。

此功能仍处于高度 Experimental 状态。

示例

<remap_executable>false</remap_executable>

replica_group_name

Replicated 数据库的副本组名称。由 Replicated 数据库创建的集群将由同一组中的副本组成。 DDL 查询只会等待同一组中的副本。

默认值： ""

示例

<replica_group_name>backups</replica_group_name>

replicated_merge_tree

用于 ReplicatedMergeTree 表的细化调整。此设置的优先级更高。更多信息，请参阅 MergeTreeSettings.h 头文件。示例

<replicated_merge_tree>
    <max_suspicious_broken_parts>5</max_suspicious_broken_parts>
</replicated_merge_tree>

restore_threads

用于执行 RESTORE 请求的最大线程数。

send_crash_reports

用于向 ClickHouse 核心开发团队发送崩溃报告的设置。如果启用此功能，尤其是在预生产环境中，我们将非常感谢。键：

Key	Description
`enabled`	用于启用此功能的布尔标志，默认值为 `true`。将其设置为 `false` 可避免发送崩溃报告。
`endpoint`	你可以覆盖用于发送崩溃报告的端点 URL。
`send_logical_errors`	`LOGICAL_ERROR` 类似于 `assert`，表示 ClickHouse 中存在一个 bug。此布尔标志用于启用发送这类异常 (默认值：`true`) 。

推荐用法

<send_crash_reports>
    <enabled>true</enabled>
</send_crash_reports>

series_keeper_path

Keeper 中的路径，用于存放由 generateSerialID 函数生成的自增编号。每个序列都会成为该路径下的一个节点。

ssh_server

首次连接时，主机密钥的公钥部分会写入 SSH 客户端上的 known_hosts 文件。 Host Key Configurations 默认未启用。取消注释主机密钥配置，并提供相应 SSH key 的路径以启用这些配置：示例：

<ssh_server>
    <host_rsa_key>path_to_the_ssh_key</host_rsa_key>
    <host_ecdsa_key>path_to_the_ssh_key</host_ecdsa_key>
    <host_ed25519_key>path_to_the_ssh_key</host_ed25519_key>
</ssh_server>

table_engines_require_grant

如果设置为 true，用户必须先获得相应权限，才能使用特定引擎创建表，例如 GRANT TABLE ENGINE ON TinyLog to user。

默认值： false

默认情况下，出于向后兼容考虑，使用特定表引擎创建表时会忽略该权限；不过，你可以将此项设置为 true 来更改这一行为。

tcp_ssh_port

SSH 服务器使用的端口，允许用户通过 PTY 使用嵌入式客户端以交互方式连接并执行查询。示例：

<tcp_ssh_port>9022</tcp_ssh_port>

text_log

用于记录文本消息的系统表 text_log 的设置。以下设置可通过子标签配置：

Setting	Description	Default	Note
`database`	数据库名称。
`table`	系统表名称。
`engine`	系统表的 MergeTree 引擎定义。		如果已定义 `partition_by` 或 `order_by`，则不能使用。如果未指定，默认使用 `MergeTree`
`partition_by`	系统表的自定义分区键。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `partition_by` 参数
`ttl`	指定表的生存时间 (TTL)。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `ttl` 参数
`order_by`	系统表的自定义排序键。如果定义了 `engine`，则不能使用。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `order_by` 参数
`storage_policy`	该表使用的存储策略名称 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `storage_policy` 参数
`settings`	控制 MergeTree 行为的附加参数 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `settings` 参数
`flush_interval_milliseconds`	将数据从内存缓冲区刷写到表的时间间隔。	`7500`
`max_size_rows`	日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。	`1048576`
`reserved_size_rows`	为日志预分配的内存行数。	`8192`
`buffer_size_rows_flush_threshold`	行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。	`max_size_rows / 2`
`flush_on_crash`	设置在发生崩溃时是否将日志转储到磁盘。	`false`

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

设置	描述	默认值
`skip_alias_columns`	为 `true` 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。	`false`

此外：

设置	描述	默认值
`level`	将存储到表中的最高消息级别 (默认为 `Trace`) 。	`Trace`

示例

<clickhouse>
    <text_log>
        <level>notice</level>
        <database>system</database>
        <table>text_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
        <!-- <partition_by>event_date</partition_by> -->
        <engine>Engine = MergeTree PARTITION BY event_date ORDER BY event_time TTL event_date + INTERVAL 30 day</engine>
    </text_log>
</clickhouse>

thread_pool_queue_size

可调度到全局线程池中的最大作业数。增大队列大小会增加内存占用。建议将此值保持为与 max_thread_pool_size 相同。

值为 0 表示不受限制。

示例

<thread_pool_queue_size>12000</thread_pool_queue_size>

throw_on_unknown_workload

定义当查询设置 ‘workload’ 访问未知 WORKLOAD 时的行为。

如果为 true，尝试访问未知 workload 的查询会抛出 RESOURCE_ACCESS_DENIED 异常。这在 WORKLOAD 层级结构建立完成且包含 WORKLOAD default 后，可用于对所有查询强制实施资源调度。
如果为 false (默认值) ，对于 ‘workload’ 设置指向未知 WORKLOAD 的查询，将提供不受限制且不进行资源调度的访问。这在 WORKLOAD default 添加之前、配置 WORKLOAD 层级结构期间非常重要。

示例

<throw_on_unknown_workload>true</throw_on_unknown_workload>

另请参阅

工作负载调度

时区

服务器的时区。以 UTC 时区或地理位置的 IANA 标识符指定 (例如 Africa/Abidjan) 。当日期时间字段以文本格式输出 (打印到屏幕上或写入文件中) 时，以及从字符串获取日期时间时，时区是 String 和日期时间格式之间转换所必需的。此外，如果处理日期和时间的函数未在输入参数中接收到时区，也会使用该时区。示例

<timezone>Asia/Istanbul</timezone>

另请参阅

session_timezone

trace_log

trace_log 系统表的运行设置。以下设置可通过子标签配置：

Setting	Description	Default	Note
`database`	数据库名称。
`table`	系统表名称。
`engine`	系统表的 MergeTree 引擎定义。		如果已定义 `partition_by` 或 `order_by`，则不能使用。如果未指定，默认使用 `MergeTree`
`partition_by`	系统表的自定义分区键。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `partition_by` 参数
`ttl`	指定表的生存时间 (TTL)。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `ttl` 参数
`order_by`	系统表的自定义排序键。如果定义了 `engine`，则不能使用。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `order_by` 参数
`storage_policy`	该表使用的存储策略名称 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `storage_policy` 参数
`settings`	控制 MergeTree 行为的附加参数 (可选) 。		如果为系统表指定了 `engine`，则应直接在 ‘engine’ 内指定 `settings` 参数
`flush_interval_milliseconds`	将数据从内存缓冲区刷写到表的时间间隔。	`7500`
`max_size_rows`	日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。	`1048576`
`reserved_size_rows`	为日志预分配的内存行数。	`8192`
`buffer_size_rows_flush_threshold`	行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。	`max_size_rows / 2`
`flush_on_crash`	设置在发生崩溃时是否将日志转储到磁盘。	`false`

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

设置	描述	默认值
`skip_alias_columns`	为 `true` 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。	`false`

默认服务器配置文件 config.xml 包含以下设置部分：

<trace_log>
    <database>system</database>
    <table>trace_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
    <symbolize>true</symbolize>
</trace_log>

url_scheme_mappers

用于将缩写或符号形式的 URL 前缀转换为完整 URL 的配置。示例：

<url_scheme_mappers>
    <s3>
        <to>https://{bucket}.s3.amazonaws.com</to>
    </s3>
    <gs>
        <to>https://storage.googleapis.com/{bucket}</to>
    </gs>
    <oss>
        <to>https://{bucket}.oss.aliyuncs.com</to>
    </oss>
</url_scheme_mappers>

validate_tcp_client_information

确定在接收到 Query 数据包时，是否启用对客户端信息的验证。默认情况下，该设置为 false：

<validate_tcp_client_information>false</validate_tcp_client_information>

wait_dictionaries_load_at_startup

此设置用于指定当 dictionaries_lazy_load 为 false 时的行为。 (如果 dictionaries_lazy_load 为 true，则此设置不起任何作用。) 如果 wait_dictionaries_load_at_startup 为 false，则 server 会在启动时开始加载所有字典，并在加载过程中并行接收 connections。当某个字典首次在查询中使用时，如果该字典尚未加载完成，则该查询会一直等待，直到字典加载完成。将 wait_dictionaries_load_at_startup 设置为 false 可以让 ClickHouse 启动得更快，但某些查询的执行速度可能会变慢 (因为它们需要等待某些字典加载完成) 。如果 wait_dictionaries_load_at_startup 为 true，则 server 会在启动时等待，直到所有字典都完成加载 (无论成功与否) 后，才接收任何 connections。示例

<wait_dictionaries_load_at_startup>true</wait_dictionaries_load_at_startup>

webassembly_udf_engine

用于执行 WebAssembly UDF 的引擎。唯一支持的取值为 ‘wasmtime’。

webterminal_allowed_origins

允许打开 /webterminal WebSocket 会话的完整来源 (scheme + host + 可选 port) 列表，多个值以逗号分隔。为空时，将严格执行同源策略 (Origin 必须与请求的 scheme、host 和 port 匹配) 。如果部署位于执行 TLS 终止的反向代理之后，且浏览器使用的是 https，但 request.isSecure() 为 false，请设置此项。示例：https://example.com,https://app.example.com:8443。

最后修改于 2026年9月28日

​abort_on_logical_error

​allowed_disks_for_table_engines

​auth_use_forwarded_address

​bcrypt_workfactor

​blob_storage_log

​builtin_dictionaries_reload_interval

​cache_size_to_ram_max_ratio

​cannot_allocate_thread_fault_injection_probability

​cgroups_memory_usage_observer_wait_time

​压缩

​配置文件

​config_reload_interval_ms

​core_dump

​crash_log

​create_union_system_log_tables

​database_atomic_delay_before_drop_table_sec

​dead_letter_queue

​dictionary_background_reconnect_interval

​disk_transaction_wait_for_blob_removal

​display_secrets_in_show_and_select

​dns_max_consecutive_failures

​dynamic_user_defined_executable_functions_path

​加密

​enforce_keeper_component_tracking

​error_log

​filesystem_caches_path

​google_protos_path

​handshake_timeout_milliseconds

​hdfs.libhdfs3_conf

​hsts_max_age

​iceberg_background_schedule_pool_size

​iceberg_manifest_decode_thread_pool_queue_size

​ignore_empty_sql_security_in_create_view_query

​include_from

​insert_deduplication_version

​io_thread_pool_queue_size

​keep_alive_timeout

​ldap_servers

​日志记录器

​logger.count

​logger.errorlog

​logger.formatting.type

​logger.level

​logger.log

​logger.rotation

​logger.shutdown_level

​logger.size

​logger.startup_level

​logger.stream_compress

​logger.syslog_level

​logger.use_syslog

​macros

​message_queue_disable_insertion

​metric_log

​mmap_cache_size

​mutation_workload

​named_collections_storage.type

​oom_score

​openSSL

​openSSL.client.caConfig

​openSSL.client.cacheSessions

​openSSL.client.certificateFile

​openSSL.client.cipherList

​openSSL.client.disableProtocols

​openSSL.client.extendedVerification

​openSSL.client.fips

​openSSL.client.invalidCertificateHandler.name

​openSSL.client.loadDefaultCAFile

​openSSL.client.preferServerCiphers

​openSSL.client.privateKeyFile

​openSSL.client.privateKeyPassphraseHandler.name

​openSSL.client.verificationDepth

​openSSL.client.verificationMode

​openSSL.server.caConfig

​openSSL.server.cacheSessions

​openSSL.server.certificateFile

​openSSL.server.cipherList

​openSSL.server.disableProtocols

​openSSL.server.extendedVerification

​openSSL.server.fips

abort_on_logical_error

allowed_disks_for_table_engines

auth_use_forwarded_address

bcrypt_workfactor

blob_storage_log

builtin_dictionaries_reload_interval

cache_size_to_ram_max_ratio

cannot_allocate_thread_fault_injection_probability

cgroups_memory_usage_observer_wait_time

压缩

配置文件

config_reload_interval_ms

core_dump

crash_log

create_union_system_log_tables

database_atomic_delay_before_drop_table_sec

dead_letter_queue

dictionary_background_reconnect_interval

disk_transaction_wait_for_blob_removal

display_secrets_in_show_and_select

dns_max_consecutive_failures

dynamic_user_defined_executable_functions_path

加密

enforce_keeper_component_tracking

error_log

filesystem_caches_path

google_protos_path

handshake_timeout_milliseconds

hdfs.libhdfs3_conf

hsts_max_age

iceberg_background_schedule_pool_size

iceberg_manifest_decode_thread_pool_queue_size

ignore_empty_sql_security_in_create_view_query

include_from

insert_deduplication_version

io_thread_pool_queue_size

keep_alive_timeout

ldap_servers

日志记录器

logger.count

logger.errorlog

logger.formatting.type

logger.level

logger.log

logger.rotation

logger.shutdown_level

logger.size

logger.startup_level

logger.stream_compress

logger.syslog_level

logger.use_syslog

macros

message_queue_disable_insertion

metric_log

mmap_cache_size

mutation_workload

named_collections_storage.type

oom_score

openSSL

openSSL.client.caConfig

openSSL.client.cacheSessions

openSSL.client.certificateFile

openSSL.client.cipherList

openSSL.client.disableProtocols

openSSL.client.extendedVerification

openSSL.client.fips

openSSL.client.invalidCertificateHandler.name

openSSL.client.loadDefaultCAFile

openSSL.client.preferServerCiphers

openSSL.client.privateKeyFile

openSSL.client.privateKeyPassphraseHandler.name

openSSL.client.verificationDepth

openSSL.client.verificationMode

openSSL.server.caConfig

openSSL.server.cacheSessions

openSSL.server.certificateFile

openSSL.server.cipherList

openSSL.server.disableProtocols

openSSL.server.extendedVerification

openSSL.server.fips