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

问道飞鱼2025-09-28 23:19

ClickHouse 配置信息详细解读

  • [ClickHouse 配置信息详细解读](#ClickHouse 配置信息详细解读)
    • 一、配置文件结构
      • [1.1 配置文件目录结构](#1.1 配置文件目录结构)
      • [1.2 配置加载顺序](#1.2 配置加载顺序)
    • [二、主配置文件 (config.xml) 详细解读](#二、主配置文件 (config.xml) 详细解读)
      • [2.1 基础配置部分](#2.1 基础配置部分)
      • [2.2 查询和资源限制配置](#2.2 查询和资源限制配置)
      • [2.3 存储引擎配置](#2.3 存储引擎配置)
    • 三、用户和权限配置 (users.xml)
      • [3.1 用户配置详解](#3.1 用户配置详解)
      • [3.2 配置集 (Profiles) 详解](#3.2 配置集 (Profiles) 详解)
      • [3.3 配额 (Quotas) 配置详解](#3.3 配额 (Quotas) 配置详解)
    • 四、分布式集群配置
      • [4.1 集群配置 (remote_servers)](#4.1 集群配置 (remote_servers))
      • [4.2 ZooKeeper 配置](#4.2 ZooKeeper 配置)
      • [4.3 宏配置 (Macros)](#4.3 宏配置 (Macros))
    • 五、存储配置详解
      • [5.1 多磁盘存储配置](#5.1 多磁盘存储配置)
    • 六、高级配置选项
      • [6.1 压缩配置](#6.1 压缩配置)
      • [6.2 日志和监控配置](#6.2 日志和监控配置)
      • [6.3 安全配置](#6.3 安全配置)
    • 七、最佳实践配置示例
      • [7.1 生产环境配置示例](#7.1 生产环境配置示例)
      • [7.2 监控和告警配置](#7.2 监控和告警配置)
    • 八、配置验证和重载
      • [8.1 配置验证命令](#8.1 配置验证命令)
      • [8.2 动态配置重载](#8.2 动态配置重载)
    • 九、重要配置项总结
    • 相关文献

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 基础配置部分

xml 复制代码 
<!-- /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 查询和资源限制配置

xml 复制代码 
<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 存储引擎配置

xml 复制代码 
<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 用户配置详解

xml 复制代码 
<!-- /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) 详解

xml 复制代码 
<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) 配置详解

xml 复制代码 
<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)

xml 复制代码 
<!-- 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 配置

xml 复制代码 
<!-- 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)

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

五、存储配置详解

5.1 多磁盘存储配置

xml 复制代码 
<!-- 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 压缩配置

xml 复制代码 
<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 日志和监控配置

xml 复制代码 
<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 安全配置

xml 复制代码 
<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 生产环境配置示例

xml 复制代码 
<!-- 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 监控和告警配置

xml 复制代码 
<!-- 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 配置验证命令

bash 复制代码 
# 检查配置文件语法
clickhouse check-config

# 查看当前生效的配置
clickhouse-client --query="SELECT * FROM system.settings WHERE name LIKE '%memory%'"

# 查看服务器配置
clickhouse-client --query="SELECT * FROM system.server_settings"

8.2 动态配置重载

sql 复制代码 
-- 重载配置（无需重启）
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语法详解

相关推荐
ModelWhale4 小时前
喜报！和鲸科技获张江国家自主创新示范区专项发展资金支持
大数据·人工智能·科研
RoboWizard4 小时前
移动固态硬盘无法被电脑识别怎么办？
大数据·人工智能·缓存·电脑·金士顿
阿里云大数据AI技术5 小时前
云栖2025 | 阿里云自研大数据平台 ODPS 重磅升级：全面支持AI计算和服务
大数据·阿里云·odps·云栖大会
伊织code5 小时前
Elasticsearch - 分布式搜索与分析引擎
大数据·分布式·elasticsearch
董可伦6 小时前
Hadoop HA 集群安装配置
大数据·hadoop·分布式
学习中的阿陈6 小时前
Hadoop完全分布式配置
大数据·hadoop·分布式
EasyGBS7 小时前
EasyGBS如何构建全域覆盖的应急管理与安全生产解决方案？
大数据
黄焖鸡能干四碗7 小时前
企业信息化建设总体规划设计方案
大数据·运维·数据库·人工智能·web安全
Daitu_Adam7 小时前
R语言——离群点检测应用
大数据·数据分析·r语言·数据可视化
热门推荐
01GitHub 镜像站点02UV 工具安装与国内镜像源配置指南03UV安装并设置国内源04阿里最新开源Wan2.2-Animate-14B 本地部署教程：统一双模态框架，MoE架构赋能电影级角色动画与替换05Spec-Kit 使用指南06KGG转MP3工具|非KGM文件|解密音频0746个Nano-banana 精选提示词，持续更新中08Multisim使用教程详尽版--(2025最新版)09Linux下V2Ray安装配置指南10Burp与其他安全工具联动及代理设置教程