ClickHouse 造数与演练工具

本文说明 /usr/local/dbbot/clickhouse_ansible/examples 下两类辅助工具的用途和基本用法。它们不是部署入口，而是用来补齐“部署 -> 造数 -> 备份 -> 恢复 -> 数据对比”这条演练链路。

1. 工具位置

典型路径：

/usr/local/dbbot/clickhouse_ansible/examples

当前主要包含两类工具：

路径作用适用场景
examples/business_demo/generate_ck_business_demo.sh一次性生成业务风格模拟数据部署后验收、查询演示、备份前准备基础数据
examples/hot_backup_lab/init_lab.sh初始化热备演练库与基础表备份/恢复演练前准备实验环境
examples/hot_backup_lab/writer_ctl.sh启动、停止、观察持续写入器验证备份窗口期间持续写入和恢复后数据口径
examples/hot_backup_lab/query_examples.sql提供一组演练验收 SQL备份前记录基线、恢复后快速核对

说明：

  • examples/README.md 对这两个子目录有简要说明。
  • examples/*/run/、日志、PID 文件都属于运行时产物，不应提交。
  • 示例中的 IP、密码和集群名均为占位值，使用前请替换成你的实际环境。

2. 推荐演练链路

如果你要完整演练 ClickHouse 交付闭环，建议按这个顺序：

  1. 先完成 ClickHouse 集群部署
  2. 用本页介绍的工具生成静态数据或持续写入数据
  3. 在备份前执行基线 SQL，保留验收结果
  4. 执行 ClickHouse 备份
  5. 执行 ClickHouse 恢复
  6. 用 ClickHouse 数据对比与恢复校验 或基线 SQL 对比恢复结果

3. business_demo：一次性业务造数

generate_ck_business_demo.sh 适合在部署完成后快速造出一批“像业务库”的数据，用于：

  • 验证分布式表、复制表和物化汇总表是否正常
  • 演示订单、行为、库存、慢日志等常见分析场景
  • 给后续备份与恢复准备一套稳定的基线数据

默认目标库是 lab_ck_biz，会创建并灌入以下几类表：

  • 维表：dim_shop、dim_category、dim_sku
  • 事实表：fact_order_item、fact_user_action、fact_inventory_snapshot
  • 慢日志表：mysql_slowlog_raw
  • 汇总表：dws_sku_day

最小示例：

cd /usr/local/dbbot/clickhouse_ansible
bash examples/business_demo/generate_ck_business_demo.sh \
  --host 192.0.2.11 \
  --port 9000 \
  --user default \
  --password '<clickhouse_password>' \
  --cluster 'example_3shards_2replicas' \
  --db lab_ck_biz \
  --reset

常用参数：

  • --reset：先 DROP DATABASE 再重建，适合重复演练。
  • --orders：控制订单明细行数，默认 3000000。
  • --actions：控制行为日志行数，默认 9000000。
  • --slowlogs：控制慢日志行数，默认 3000000。
  • --days：控制时间跨度，默认 60 天。

如果只想做小规模验证，可以收小参数：

cd /usr/local/dbbot/clickhouse_ansible
bash examples/business_demo/generate_ck_business_demo.sh \
  --host 192.0.2.11 \
  --password '<clickhouse_password>' \
  --orders 500000 \
  --actions 1500000 \
  --slowlogs 500000

4. hot_backup_lab：持续写入演练

hot_backup_lab 更适合“备份窗口还在写入”的演练场景。它由三部分组成：

  1. init_lab.sh：初始化实验库、建表、灌入基础数据
  2. writer_ctl.sh：后台持续写入 fact_order_item、fact_user_action、mysql_slowlog_raw
  3. query_examples.sql：提供实时写入、排行、漏斗、慢 SQL 和基线统计 SQL

4.1 初始化实验库

cd /usr/local/dbbot/clickhouse_ansible
bash examples/hot_backup_lab/init_lab.sh \
  --host 192.0.2.11 \
  --port 9000 \
  --user default \
  --password '<clickhouse_password>' \
  --cluster 'example_3shards_2replicas' \
  --db lab_hot_backup \
  --reset

如果想一次准备多个演练库，可改用 --dbs：

cd /usr/local/dbbot/clickhouse_ansible
bash examples/hot_backup_lab/init_lab.sh \
  --host 192.0.2.11 \
  --port 9000 \
  --user default \
  --password '<clickhouse_password>' \
  --cluster 'example_3shards_2replicas' \
  --dbs lab_hot_backup,lab_hot_backup_ext,lab_hot_backup_analytics \
  --reset

4.2 启动持续写入

cd /usr/local/dbbot/clickhouse_ansible
bash examples/hot_backup_lab/writer_ctl.sh start \
  --host 192.0.2.11 \
  --port 9000 \
  --user default \
  --password '<clickhouse_password>' \
  --db lab_hot_backup \
  --order-batch 3000 \
  --action-batch 9000 \
  --slow-batch 1500 \
  --interval 2

常用动作：

  • start：后台启动写入器
  • run：前台运行，适合现场观察
  • status：查看进程状态与最近一分钟写入量
  • stop：停止后台写入器

查看状态：

cd /usr/local/dbbot/clickhouse_ansible
bash examples/hot_backup_lab/writer_ctl.sh status \
  --host 192.0.2.11 \
  --port 9000 \
  --user default \
  --password '<clickhouse_password>' \
  --db lab_hot_backup

停止写入：

cd /usr/local/dbbot/clickhouse_ansible
bash examples/hot_backup_lab/writer_ctl.sh stop

运行文件默认在：

  • examples/hot_backup_lab/run/writer.pid
  • examples/hot_backup_lab/run/writer.log

5. 数据对比怎么做

5.1 快速基线对比

如果只是想做一次简单演练，最直接的方式是在备份前后分别执行：

cd /usr/local/dbbot/clickhouse_ansible
clickhouse-client \
  --host 192.0.2.11 \
  --port 9000 \
  --user default \
  --password '<clickhouse_password>' \
  --multiquery < examples/hot_backup_lab/query_examples.sql

其中最后一组 SQL 会输出 fact_order_item、fact_user_action、mysql_slowlog_raw 的总量，可作为备份前后的基线结果。

5.2 跨集群数据对比

如果要对“源集群”和“恢复目标集群”做正式验收，推荐使用独立 Playbook：

cd /usr/local/dbbot/clickhouse_ansible/playbooks
ansible-playbook \
  -i ../inventory/hosts.backup.ini \
  -i ../inventory/hosts.restore.ini \
  validate_restore_consistency.yml

它的详细说明见：ClickHouse 数据对比与恢复校验。

一个最小校验项示例：

validate_checks:
  - name: "order_items_full_count"
    database: "lab_hot_backup"
    local_table: "fact_order_item_local"

  - name: "slowlog_recent_window"
    database: "lab_hot_backup"
    local_table: "mysql_slowlog_raw_local"
    where: "log_time >= toDateTime('2026-03-01 00:00:00')"

说明：

  • 非 TTL 表适合做全表 count() 对比。
  • 带 TTL ... DELETE 的表更适合做固定时间窗口对比。
  • validate_checks 放在 playbooks/vars/validate_restore_config.yml 中维护。

6. 注意事项

  1. business_demo 更适合准备一套稳定样本数据，hot_backup_lab 更适合持续写入演练。
  2. mysql_slowlog_raw_local 这类 TTL 表，不建议直接拿源/目标全表总数做唯一验收标准。
  3. 如果演练期间源集群还在持续写入，跨集群强一致对比只适合固定窗口或停写后的静态验收。
  4. 大量造数前先评估磁盘空间、后台 Merge 压力和备份盘容量。

7. 相关文档

  1. ClickHouse 集群部署
  2. ClickHouse 备份
  3. ClickHouse 恢复
  4. ClickHouse 数据对比与恢复校验