【大信息技术】ClickHouse配置详细解读
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 配置加载顺序
- 加载主配置文件
config.xml - 按字母顺序加载
config.d/*.xml - 按字母顺序加载
conf.d/*.xml（如果存在） - 后加载的配置会覆盖前面的同名配置项
二、主配置文件 (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语法详解
浙公网安备 33010602011771号