ClickHouse 集群部署

本文说明如何使用 clickhouse_ansible 执行 ClickHouse 集群或单机模式部署。

文中命令默认基于绿色版 Ansible 已执行以下初始化：

cd /usr/local/dbbot/portable-ansible-v0.5.0-py3
bash setup_portable_ansible.sh
source ~/.bashrc

完成后可直接使用 ansible-playbook 和 ansible。

1. 适用范围

支持以下入口 Playbook：

  • playbooks/deploy_cluster.yml：集群部署。
  • playbooks/deploy_single.yml：单机或实验环境快速部署。

默认文档示例使用 3 分片 2 副本，但 inventory 设计支持扩展到其他 x 分片 y 副本拓扑。

2. 前置条件

部署前建议完成以下准备：

  1. 在控制节点安装 dbbot，并完成绿色版 Ansible 注册。
  2. 规划好 ClickHouse 节点与 ZooKeeper / Keeper 节点。
  3. 确认目标节点网络、时区、磁盘目录和操作系统基线符合要求。
  4. 确认控制节点能够免交互 SSH 到目标主机。
  5. 准备 ClickHouse 安装包，或确认控制节点可联网下载所需包。

3. 推荐的 inventory 分工

clickhouse_ansible 默认按场景拆分 inventory：

  • inventory/hosts.deploy.ini：部署专用。
  • inventory/hosts.dr_deploy.ini：容灾集群部署专用。
  • inventory/hosts.backup.ini：备份专用。
  • inventory/hosts.dr_backup.ini：容灾集群备份盘准备专用。
  • inventory/hosts.restore.ini：恢复专用。
  • inventory/hosts.nfs_server.ini：NFS 服务端专用。
  • inventory/hosts.single.ini：单机验证专用。

部署场景下，建议在 [all:vars] 中设置：

dbbot_inventory_purpose=deploy
ansible_python_interpreter=auto_silent
ansible_user=root
ansible_ssh_pass="'<your_ssh_password>'"

4. 部署 inventory 最小示例

[clickhouse_deploy]
ck-131-1 ansible_host=192.0.2.131 shard=1 replica=1 instance_id=1 replica_name=ck-s1-r1 system_hostname=ck-node1
ck-131-2 ansible_host=192.0.2.131 shard=3 replica=2 instance_id=2 replica_name=ck-s3-r2 system_hostname=ck-node1
ck-132-1 ansible_host=192.0.2.132 shard=1 replica=2 instance_id=1 replica_name=ck-s1-r2 system_hostname=ck-node2
ck-132-2 ansible_host=192.0.2.132 shard=2 replica=1 instance_id=2 replica_name=ck-s2-r1 system_hostname=ck-node2
ck-133-1 ansible_host=192.0.2.133 shard=2 replica=2 instance_id=1 replica_name=ck-s2-r2 system_hostname=ck-node3
ck-133-2 ansible_host=192.0.2.133 shard=3 replica=1 instance_id=2 replica_name=ck-s3-r1 system_hostname=ck-node3

[clickhouse_cluster:children]
clickhouse_deploy

[zookeeper_deploy]
ck-131-1 zk_id=1
ck-132-1 zk_id=2
ck-133-1 zk_id=3

[zookeeper_cluster:children]
zookeeper_deploy

[all:vars]
dbbot_inventory_purpose=deploy
ansible_python_interpreter=auto_silent
ansible_user=root
ansible_ssh_pass="'<your_ssh_password>'"

说明：

  • instance_id 建议显式填写，便于端口、目录和 service 名称推导。
  • 如果启用 fcs_set_hostname=true，可额外为主机行配置 system_hostname。
  • Keeper 模式下仍需确保协调节点定义完整。

5. 关键变量文件

部署前重点关注以下文件：

  • playbooks/vars/common_config.yml：版本、用户、目录、密码、Keeper 开关等通用参数。
  • playbooks/vars/cluster_config.yml：集群名称、端口基线和拓扑相关参数。
  • playbooks/vars/standalone_config.yml：单机模式行为。

常见需要确认的参数：

  • clickhouse_version
  • clickhouse_cluster_name
  • use_clickhouse_keeper
  • clickhouse_enable_ssl
  • clickhouse_install_debug_package
  • clickhouse_default_password
  • fcs_allow_dbbot_default_passwd
  • fcs_set_hostname
  • deploy_require_manual_confirm

更完整的参数说明见：ClickHouse 变量与参数说明

密码守卫说明：

  • clickhouse_default_password 的开源默认值是 Dbbot_default@8888。
  • 默认 fcs_allow_dbbot_default_passwd: false，因此部署、备份、恢复相关 Playbook 会在 pre_tasks 阶段拦截这个公开默认密码。
  • 实验环境如果想快速验证，可以显式设置 fcs_allow_dbbot_default_passwd: true；生产环境不建议这样做。

6. 准备安装包

如果关闭自动下载，需提前把安装包放入 downloads/：

cd /usr/local/dbbot/clickhouse_ansible/downloads
wget "https://packages.clickhouse.com/tgz/stable/clickhouse-common-static-23.6.1.1524-amd64.tgz"
wget "https://packages.clickhouse.com/tgz/stable/clickhouse-server-23.6.1.1524-amd64.tgz"
wget "https://packages.clickhouse.com/tgz/stable/clickhouse-client-23.6.1.1524-amd64.tgz"
wget "https://archive.apache.org/dist/zookeeper/zookeeper-3.8.4/apache-zookeeper-3.8.4-bin.tar.gz"

说明：

  • clickhouse-common-static-dbg 已改成可选项，只有在 clickhouse_install_debug_package=true 时才需要准备和安装。
  • 正式发版默认建议保持 clickhouse_install_debug_package=false，减少包体积和分发时间。

7. 执行部署

7.1 语法检查

cd /usr/local/dbbot/clickhouse_ansible/playbooks
ansible-playbook \
  -i ../inventory/hosts.deploy.ini \
  deploy_cluster.yml --syntax-check

7.2 集群部署

cd /usr/local/dbbot/clickhouse_ansible/playbooks
ansible-playbook \
  -i ../inventory/hosts.deploy.ini \
  deploy_cluster.yml

7.3 Keeper 模式部署

cd /usr/local/dbbot/clickhouse_ansible/playbooks
ansible-playbook \
  -i ../inventory/hosts.deploy.ini \
  deploy_cluster.yml \
  -e "use_clickhouse_keeper=true"

7.4 单机模式部署

cd /usr/local/dbbot/clickhouse_ansible/playbooks
ansible-playbook \
  -i ../inventory/hosts.single.ini \
  deploy_single.yml

8. 系统变更项

部署 playbook 不只是安装 ClickHouse，还会对目标主机做系统侧初始化。默认可能涉及：

  1. 设置时区为 Asia/Shanghai
  2. 修改 hostname 与 /etc/hosts 映射
  3. 禁用 swap，并注释 /etc/fstab 中的 swap 条目
  4. 调整 limits.conf / limits.d
  5. 调整 sysctl.d 下的 ClickHouse 专用参数
  6. 调整 THP、SELinux 和防火墙

如果你不希望某些行为生效，至少应提前评估：

  • fcs_set_hostname
  • clickhouse_uid / clickhouse_gid
  • fcs_auto_download_packages
  • clickhouse_install_debug_package

9. 部署后验证

8.1 端口监听

ansible \
  all -i ../inventory/hosts.deploy.ini -m shell \
  -a "ss -lntp | egrep ':8123 |:8124 |:8443 |:8444 |:9000 |:9001 |:9440 |:9441 '"

8.2 集群拓扑

SELECT cluster, shard_num, replica_num, host_name, port
FROM system.clusters
WHERE cluster = 'example_3shards_2replicas'
ORDER BY shard_num, replica_num;

8.3 副本状态

SELECT table, is_readonly, queue_size, absolute_delay
FROM system.replicas
ORDER BY table;

10. 常见注意事项

  1. 部署默认要求 dbbot_inventory_purpose=deploy，避免误用备份或恢复 inventory。
  2. ansible_ssh_pass 建议保持 "'密码'" 这种写法，避免 Ansible inventory 解析异常。
  3. 默认启用手工确认门禁，不建议在生产长期关闭。
  4. 若不希望修改系统 hostname，可将 fcs_set_hostname 设为 false。
  5. 若目标机已有同 UID/GID 账号，需要先调整 clickhouse_uid / clickhouse_gid。
  6. 如果后续要做备份或恢复，请继续阅读 ClickHouse 备份 和 ClickHouse 恢复，先完成 NFS 和备份盘准备。