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

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语法详解

相关推荐
TDengine (老段)8 小时前
TDengine 数学函数 DEGRESS 用户手册
大数据·数据库·sql·物联网·时序数据库·iot·tdengine
TDengine (老段)8 小时前
TDengine 数学函数 GREATEST 用户手册
大数据·数据库·物联网·时序数据库·iot·tdengine·涛思数据
字节数据平台9 小时前
火山引擎Data Agent再拓新场景,重磅推出用户研究Agent
大数据·人工智能·火山引擎
铭毅天下12 小时前
Elasticsearch 到 Easysearch 数据迁移 5 种方案选型实战总结
大数据·elasticsearch·搜索引擎·全文检索
跨境小新12 小时前
Facebook广告投放:地域定向流量不精准?x个优化指南
大数据·facebook
ZKNOW甄知科技13 小时前
客户案例 | 派克新材x甄知科技,构建全场景智能IT运维体系
大数据·运维·人工智能·科技·低代码·微服务·制造
币须赢14 小时前
688758赛分科技 阴上阴形态 洗盘上涨?
大数据
学掌门14 小时前
大数据知识合集之预处理方法
大数据
Elastic 中国社区官方博客15 小时前
Elasticsearch 推理 API 增加了开放的可定制服务
大数据·数据库·人工智能·elasticsearch·搜索引擎·ai·全文检索
蒙特卡洛的随机游走15 小时前
Spark核心数据(RDD、DataFrame 和 Dataset)
大数据·分布式·spark