【大数据技术】ClickHouse配置详细解读

ClickHouse 配置信息详细解读

ClickHouse 的配置系统非常灵活，支持多层次配置管理。下面我将从配置文件结构、核心配置项、高级配置到最佳实践进行全面解读。

一、配置文件结构

1.1 配置文件目录结构

/etc/clickhouse-server/
├── config.xml                    # 主配置文件
├── users.xml                     # 用户和权限配置
├── config.d/                     # 配置片段目录
│   ├── macros.xml               # 集群宏定义
│   ├── listen.xml               # 网络监听配置
│   ├── storage.xml             # 存储配置
│   └── zookeeper.xml           # ZooKeeper配置
├── users.d/                     # 用户配置片段
│   ├── default.xml             # 默认用户配置
│   └── readonly.xml            # 只读用户配置
└── conf.d/                      # 其他配置片段（可选）

1.2 配置加载顺序

1. 加载主配置文件 config.xml
2. 按字母顺序加载 config.d/*.xml
3. 按字母顺序加载 conf.d/*.xml（如果存在）
4. 后加载的配置会覆盖前面的同名配置项

二、主配置文件 (config.xml) 详细解读

2.1 基础配置部分

<!-- /etc/clickhouse-server/config.xml -->
<yandex><!-- 日志配置 --><logger><!-- 日志级别: trace, debug, information, warning, error --><level>information</level><!-- 日志文件路径 --><log>/var/log/clickhouse-server/clickhouse-server.log</log><errorlog>/var/log/clickhouse-server/clickhouse-server.err.log</errorlog><!-- 日志文件大小和数量限制 --><size>1000M</size><count>10</count><!-- 控制台输出 --><console>false</console></logger><!-- HTTP 和 TCP 接口配置 --><http_port>8123</http_port><tcp_port>9000</tcp_port><!-- MySQL 协议兼容端口 --><mysql_port>9004</mysql_port><!-- PostgreSQL 协议兼容端口（实验性） --><postgresql_port>9005</postgresql_port><!-- 集群内部通信端口 --><interserver_http_port>9009</interserver_http_port><!-- 监听地址配置 --><!-- 监听所有 IPv4 地址 --><listen_host>0.0.0.0</listen_host><!-- 监听所有 IPv6 地址 --><listen_host>::</listen_host><!-- 如果绑定失败是否继续启动 --><listen_try>1</listen_try><!-- 最大连接数限制 --><max_connections>4096</max_connections><keep_alive_timeout>3</keep_alive_timeout><!-- 最大并发查询数 --><max_concurrent_queries>100</max_concurrent_queries><!-- 数据存储路径 --><path>/var/lib/clickhouse/</path><tmp_path>/var/lib/clickhouse/tmp/</tmp_path><user_files_path>/var/lib/clickhouse/user_files/</user_files_path><format_schema_path>/var/lib/clickhouse/format_schemas/</format_schema_path><!-- 默认配置文件和数据库 --><default_profile>default</default_profile><default_database>default</default_database><!-- 服务器时区 --><timezone>Asia/Shanghai</timezone><!-- 默认字符集 --><default_codec>compression</default_codec>
</yandex>

2.2 查询和资源限制配置

<yandex><!-- 查询限制配置 --><max_query_size>262144</max_query_size><max_ast_elements>50000</max_ast_elements><max_expanded_ast_elements>500000</max_expanded_ast_elements><!-- 内存限制 --><max_memory_usage>10000000000</max_memory_usage><max_memory_usage_for_user>0</max_memory_usage_for_user><max_memory_usage_for_all_queries>0</max_memory_usage_for_all_queries><!-- 执行时间限制 --><max_execution_time>300</max_execution_time><max_execution_time_for_user>0</max_execution_time_for_user><!-- 读取限制 --><max_rows_to_read>0</max_rows_to_read><max_bytes_to_read>0</max_bytes_to_read><max_rows_to_read_for_user>0</max_rows_to_read_for_user><max_bytes_to_read_for_user>0</max_bytes_to_read_for_user><!-- 网络传输限制 --><max_bytes_before_external_group_by>0</max_bytes_before_external_group_by><max_bytes_before_external_sort>0</max_bytes_before_external_sort>
</yandex>

2.3 存储引擎配置

<yandex><!-- MergeTree 引擎配置 --><merge_tree><!-- 最大可疑损坏分区数 --><max_suspicious_broken_parts>5</max_suspicious_broken_parts><!-- 部分加载线程数 --><max_part_loading_threads>auto</max_part_loading_threads><!-- 变异操作并发控制 --><number_of_free_entries_in_pool_to_execute_mutation>10</number_of_free_entries_in_pool_to_execute_mutation><!-- 后台合并线程数 --><background_pool_size>16</background_pool_size><background_schedule_pool_size>16</background_schedule_pool_size><background_move_pool_size>8</background_move_pool_size><background_fetches_pool_size>8</background_fetches_pool_size><background_common_pool_size>8</background_common_pool_size><background_merges_mutations_concurrency_ratio>2</background_merges_mutations_concurrency_ratio></merge_tree><!-- 分布式引擎配置 --><distributed_ddl><!-- 分布式 DDL 执行超时 --><task_max_timeout>180</task_max_timeout><!-- 任务检查间隔 --><task_check_time>10</task_check_time></distributed_ddl>
</yandex>

三、用户和权限配置 (users.xml)

3.1 用户配置详解

<!-- /etc/clickhouse-server/users.xml -->
<yandex><!-- 用户列表 --><users><!-- 默认用户 --><default><!-- 密码配置 --><password></password>  <!-- 空密码 --><!-- 或使用 SHA256 哈希 --><password_sha256_hex>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</password_sha256_hex><!-- 或使用双 SHA1 哈希（兼容 MySQL） --><password_double_sha1_hex>da39a3ee5e6b4b0d3255bfef95601890afd80709</password_double_sha1_hex><!-- 网络访问控制 --><networks><ip>::/0</ip>      <!-- IPv6 所有地址 --><ip>127.0.0.1</ip> <!-- 本地回环 --><ip>192.168.0.0/16</ip> <!-- 内网网段 --></networks><!-- 用户配置集 --><profile>default</profile><!-- 配额配置 --><quota>default</quota><!-- 允许访问的数据库 --><allow_databases><database>default</database><database>test</database></allow_databases><!-- 允许 DDL 操作 --><allow_ddl>true</allow_ddl></default><!-- 只读用户示例 --><readonly_user><password>readonly_password</password><profile>readonly</profile><quota>default</quota><networks><ip>192.168.1.0/24</ip></networks></readonly_user></users>
</yandex>

3.2 配置集 (Profiles) 详解

<yandex><profiles><!-- 默认配置集 --><default><!-- 内存使用限制 --><max_memory_usage>10000000000</max_memory_usage><max_memory_usage_for_user>0</max_memory_usage_for_user><!-- 执行时间限制 --><max_execution_time>300</max_execution_time><timeout_before_checking_execution_speed>15</timeout_before_checking_execution_speed><!-- 读取限制 --><max_rows_to_read>0</max_rows_to_read><max_bytes_to_read>0</max_bytes_to_read><read_overflow_mode>throw</read_overflow_mode><!-- 结果限制 --><max_result_rows>0</max_result_rows><max_result_bytes>0</max_result_bytes><result_overflow_mode>throw</result_overflow_mode><!-- 权限控制 --><readonly>0</readonly>  <!-- 0-无限制, 1-只读, 2-仅DDL --><allow_ddl>true</allow_ddl><!-- 负载均衡策略 --><load_balancing>random</load_balancing><!-- 分布式查询设置 --><distributed_product_mode>deny</distributed_product_mode><skip_unavailable_shards>false</skip_unavailable_shards><!-- 其他优化设置 --><max_threads>auto</max_threads><max_block_size>65536</max_block_size><preferred_block_size_bytes>1000000</preferred_block_size_bytes></default><!-- 只读配置集 --><readonly><readonly>1</readonly><allow_ddl>false</allow_ddl><max_memory_usage>5000000000</max_memory_usage></readonly><!-- Web 界面配置集 --><web><max_memory_usage>1000000000</max_memory_usage><max_execution_time>30</max_execution_time><max_rows_to_read>1000000</max_rows_to_read><max_result_rows>1000</max_result_rows><max_result_bytes>1000000</max_result_bytes></web></profiles>
</yandex>

3.3 配额 (Quotas) 配置详解

<yandex><quotas><!-- 默认配额 --><default><!-- 时间间隔配置 --><interval><!-- 间隔时长（秒） --><duration>3600</duration><!-- 查询次数限制 --><queries>0</queries><!-- 错误查询次数 --><errors>0</errors><!-- 结果行数限制 --><result_rows>0</result_rows><!-- 读取行数限制 --><read_rows>0</read_rows><!-- 执行时间限制（秒） --><execution_time>0</execution_time></interval><!-- 多个间隔示例 --><interval><duration>60</duration><queries>100</queries>  <!-- 每分钟最多100次查询 --></interval><interval><duration>3600</duration><queries>1000</queries> <!-- 每小时最多1000次查询 --></interval></default><!-- 严格配额示例 --><strict><interval><duration>3600</duration><queries>100</queries><errors>10</errors><result_rows>1000000</result_rows><read_rows>10000000</read_rows><execution_time>600</execution_time></interval></strict></quotas>
</yandex>

四、分布式集群配置

4.1 集群配置 (remote_servers)

<!-- config.d/clusters.xml -->
<yandex><remote_servers><!-- 简单集群配置 --><my_cluster><!-- 分片1（包含2个副本） --><shard><weight>1</weight><internal_replication>true</internal_replication><replica><host>node1</host><port>9000</port><!-- 可选：用户和密码 --><user>default</user><password></password><!-- 可选：安全连接 --><secure>0</secure></replica><replica><host>node2</host><port>9000</port></replica></shard><!-- 分片2（单副本） --><shard><weight>1</weight><internal_replication>true</internal_replication><replica><host>node3</host><port>9000</port></replica></shard></my_cluster><!-- 分片权重配置示例 --><weighted_cluster><shard><weight>2</weight>  <!-- 双倍权重 --><replica><host>node1</host><port>9000</port></replica></shard><shard><weight>1</weight>  <!-- 正常权重 --><replica><host>node2</host><port>9000</port></replica></shard></weighted_cluster></remote_servers>
</yandex>

4.2 ZooKeeper 配置

<!-- config.d/zookeeper.xml -->
<yandex><zookeeper><!-- ZooKeeper 集群节点 --><node index="1"><host>zk1.example.com</host><port>2181</port></node><node index="2"><host>zk2.example.com</host><port>2181</port></node><node index="3"><host>zk3.example.com</host><port>2181</port></node><!-- 会话和操作超时 --><session_timeout_ms>30000</session_timeout_ms><operation_timeout_ms>10000</operation_timeout_ms><!-- 连接重试 --><root>/clickhouse</root><identity>user:password</identity></zookeeper>
</yandex>

4.3 宏配置 (Macros)

<!-- config.d/macros.xml -->
<yandex><macros><!-- 每个节点需要不同的宏配置 --><shard>01</shard><replica>node01</replica><layer>01</layer><cluster>my_cluster</cluster></macros>
</yandex>

五、存储配置详解

5.1 多磁盘存储配置

<!-- config.d/storage.xml -->
<yandex><storage_configuration><disks><!-- 默认磁盘 --><default><path>/var/lib/clickhouse/</path><!-- 保留空间检查 --><keep_free_space_bytes>10485760</keep_free_space_bytes></default><!-- SSD 磁盘 --><ssd><path>/ssd/clickhouse/</path><keep_free_space_bytes>1073741824</keep_free_space_bytes></ssd><!-- HDD 磁盘 --><hdd><path>/hdd/clickhouse/</path></hdd><!-- 对象存储（S3） --><s3><type>s3</type><endpoint>https://s3.amazonaws.com/</endpoint><access_key_id>your_access_key</access_key_id><secret_access_key>your_secret_key</secret_access_key><region>us-east-1</region><use_environment_credentials>false</use_environment_credentials></s3></disks><policies><!-- 默认策略 --><default><volumes><main><disk>default</disk><disk>ssd</disk></main></volumes></default><!-- 热冷数据策略 --><hot_cold><volumes><hot><disk>ssd</disk><max_data_part_size_bytes>1073741824</max_data_part_size_bytes></hot><cold><disk>hdd</disk></cold></volumes><!-- 移动策略 --><move_factor>0.1</move_factor></hot_cold><!-- JBOD 策略（Just a Bunch Of Disks） --><jbod><volumes><jbod_volume><disk>default</disk><disk>ssd</disk><disk>hdd</disk><max_data_part_size_bytes>5368709120</max_data_part_size_bytes></jbod_volume></volumes></jbod></policies></storage_configuration>
</yandex>

六、高级配置选项

6.1 压缩配置

<yandex><compression><!-- 案例1：小分区使用高压缩率 --><case><min_part_size>1000000</min_part_size><min_part_size_ratio>0.01</min_part_size_ratio><method>zstd</method><level>5</level></case><!-- 案例2：中等分区使用平衡压缩 --><case><min_part_size>100000000</min_part_size><min_part_size_ratio>0.1</min_part_size_ratio><method>lz4</method></case><!-- 案例3：大分区使用快速压缩 --><case><min_part_size>1000000000</min_part_size><min_part_size_ratio>0.5</min_part_size_ratio><method>lz4</method></case></compression>
</yandex>

6.2 日志和监控配置

<yandex><!-- 查询日志 --><query_log><database>system</database><table>query_log</table><partition_by>toYYYYMM(event_date)</partition_by><flush_interval_milliseconds>7500</flush_interval_milliseconds></query_log><!-- 追踪日志 --><trace_log><database>system</database><table>trace_log</table><partition_by>toYYYYMM(event_date)</partition_by><flush_interval_milliseconds>7500</flush_interval_milliseconds></trace_log><!-- 性能指标配置 --><asynchronous_metrics_log><database>system</database><table>asynchronous_metrics_log</table></asynchronous_metrics_log><!-- 部分日志 --><part_log><database>system</database><table>part_log</table></part_log>
</yandex>

6.3 安全配置

<yandex><!-- SSL/TLS 配置 --><openSSL><server><certificateFile>/path/to/server.crt</certificateFile><privateKeyFile>/path/to/server.key</privateKeyFile><dhParamsFile>/path/to/dhparams.pem</dhParamsFile><verificationMode>none</verificationMode><loadDefaultCAFile>true</loadDefaultCAFile><cacheSessions>true</cacheSessions><preferServerCiphers>true</preferServerCiphers></server></openSSL><!-- HTTPS 端口 --><https_port>8443</https_port><tcp_port_secure>9440</tcp_port_secure>
</yandex>

七、最佳实践配置示例

7.1 生产环境配置示例

<!-- config.d/production.xml -->
<yandex><!-- 生产环境优化配置 --><max_table_size_to_drop>0</max_table_size_to_drop><max_partition_size_to_drop>0</max_partition_size_to_drop><!-- 禁用危险操作 --><allow_drop_table>0</allow_drop_table><allow_suspicious_low_cardinality_types>0</allow_suspicious_low_cardinality_types><!-- 内存优化 --><max_memory_usage>20000000000</max_memory_usage><max_bytes_before_external_group_by>10000000000</max_bytes_before_external_group_by><max_bytes_before_external_sort>1000000000</max_bytes_before_external_sort><!-- 合并优化 --><merge_tree><max_bytes_to_merge_at_min_space_in_pool>107374182400</max_bytes_to_merge_at_min_space_in_pool><merge_with_ttl_timeout>14400</merge_with_ttl_timeout></merge_tree>
</yandex>

7.2 监控和告警配置

<!-- config.d/monitoring.xml -->
<yandex><!-- 内置监控配置 --><metric_log><database>system</database><table>metric_log</table><flush_interval_milliseconds>5000</flush_interval_milliseconds></metric_log><!-- 文本日志级别 --><logger><level>information</level><console>false</console></logger><!-- 性能计数器 --><performance_schema>true</performance_schema>
</yandex>

八、配置验证和重载

8.1 配置验证命令

# 检查配置文件语法
clickhouse check-config# 查看当前生效的配置
clickhouse-client --query="SELECT * FROM system.settings WHERE name LIKE '%memory%'"# 查看服务器配置
clickhouse-client --query="SELECT * FROM system.server_settings"

8.2 动态配置重载

-- 重载配置（无需重启）
SYSTEM RELOAD CONFIG;
SYSTEM RELOAD USERS;
SYSTEM RELOAD DICTIONARIES;-- 查看配置重载状态
SELECT * FROM system.events WHERE event LIKE '%ConfigReload%';

九、重要配置项总结

配置类别	关键配置项	推荐值	说明
内存	max_memory_usage	服务器内存的50-80%	单查询最大内存
连接	max_connections	根据业务调整	最大并发连接数
存储	storage_policy	根据磁盘配置	数据存储策略
合并	background_pool_size	CPU核心数×2	后台合并线程数
网络	keep_alive_timeout	3-10秒	连接保持时间
安全	readonly	1（生产环境）	只读模式控制

通过合理配置这些参数，可以显著提升 ClickHouse 的性能和稳定性。建议根据实际业务需求和硬件资源进行调优。

相关文献

【大数据知识】ClickHouse入门
【大数据知识】今天聊聊Clickhouse部署方案
【大数据相关】ClickHouse命令行与SQL语法详解