hruljov/clickhouse-bulk

hruljov/clickhouse-bulk 镜像说明

镜像概述

这是clickhouse-bulk工具的官方Docker镜像，clickhouse-bulk是一款用于优化ClickHouse数据插入的批量处理工具，可将多个插入请求合并后发送到ClickHouse服务器，有效提升写入性能并减少服务器请求压力。

核心功能

• 对多个请求进行分组，发送到任意ClickHouse服务器
• 按时间间隔发送收集到的数据
• 支持VALUES、TabSeparated等数据格式
• 支持多服务器负载均衡发送
• 支持在查询参数或请求体中传递查询语句
• 支持用户名、密码、数据库等查询参数
• 支持基本认证机制

使用场景

• 高并发数据写入场景，需批量处理以减少ClickHouse服务器请求次数
• 需要按固定时间间隔批量提交数据的场景
• 多ClickHouse服务器集群环境下的负载均衡写入需求

配置说明

命令选项

• -config：指定配置文件路径（JSON格式），默认值为_config.json

配置文件示例

javascript
{
  "listen": ":8124", // 监听端口
  "flush_count": 10000, // 按换行符统计的插入行数阈值
  "flush_interval": 1000, // 插入时间间隔（毫秒）
  "dump_check_interval": 300, // 重新发送dump文件的间隔（秒，-1表示禁用）
  "debug": false, // 是否记录传入请求
  "dump_dir": "dumps", // 存储未发送数据的目录（当ClickHouse出错时）
  "clickhouse": {
    "down_timeout": 60, // 服务器宕机时的等待时间（秒）
    "connect_timeout": 10, // 连接服务器的超时时间（秒）
    "servers": [
      "http://127.0.0.1:8123" // ClickHouse服务器列表
    ]
  }
}

环境变量（Docker镜像专用）

• CLICKHOUSE_SERVERS：逗号分隔的ClickHouse服务器列表
• CLICKHOUSE_FLUSH_COUNT：触发插入的行数阈值
• CLICKHOUSE_FLUSH_INTERVAL：插入时间间隔（毫秒）
• DUMP_CHECK_INTERVAL：重新发送dump文件的间隔（秒）
• CLICKHOUSE_DOWN_TIMEOUT：服务器宕机时的等待时间（秒）
• CLICKHOUSE_CONNECT_TIMEOUT：连接服务器的超时时间（秒）

Docker部署示例

单容器运行

bash
docker run -d -p 8124:8124 \
  -e CLICKHOUSE_SERVERS=http://your-clickhouse-server:8123 \
  -e CLICKHOUSE_FLUSH_COUNT=10000 \
  -e CLICKHOUSE_FLUSH_INTERVAL=1000 \
  docker.xuanyuan.run/hruljov/clickhouse-bulk

指标查看

手动检查主要运行指标：

bash
curl -s http://127.0.0.1:8124/metrics | grep "^ch_"

• ch_bad_servers：当前不可用的服务器数量
• ch_dump_count：启动以来保存的dump文件数量
• ch_queued_dumps：当前目录中的dump文件数量
• ch_good_servers：当前可用的服务器数量
• ch_received_count：启动以来接收的请求数量
• ch_sent_count：启动以来发送的请求数量

优化建议

为获得更好的性能，SQL语句中的FORMAT和VALUES关键字必须大写。 ===FULL_DESC===