ClickHouse 目录结构与配置

本文用于说明 clickhouse_ansible 的目录布局、配置入口和推荐维护方式。

1. 顶层目录

典型路径：

/usr/local/dbbot/clickhouse_ansible

关键目录：

  • downloads/：ClickHouse 和 ZooKeeper 安装包。
  • inventory/：部署、备份、恢复、NFS 服务端等场景的主机清单。
  • playbooks/：入口 Playbook、预任务和变量文件。
  • roles/：系统初始化、协调组件部署、ClickHouse 部署等角色。
  • artifacts/manifests/：备份与恢复运行产物。

2. 目录结构示例

clickhouse_ansible/
├── artifacts/
│   └── manifests/
├── downloads/
├── inventory/
│   ├── hosts.deploy.ini
│   ├── hosts.dr_deploy.ini
│   ├── hosts.backup.ini
│   ├── hosts.dr_backup.ini
│   ├── hosts.restore.ini
│   ├── hosts.nfs_server.ini
│   └── hosts.single.ini
├── playbooks/
│   ├── deploy_cluster.yml
│   ├── deploy_single.yml
│   ├── setup_nfs_server.yml
│   ├── setup_nfs_client_mount_rc_local.yml
│   ├── prepare_backup_disk.yml
│   ├── backup_cluster.yml
│   ├── restore_cluster.yml
│   ├── uninstall_cluster.yml
│   ├── pre_tasks/
│   ├── tasks/
│   └── vars/
└── roles/
    ├── init_system/
    ├── deploy_zookeeper/
    └── deploy_clickhouse/

3. inventory 文件职责

  • hosts.deploy.ini：部署专用，要求 dbbot_inventory_purpose=deploy。
  • hosts.dr_deploy.ini：容灾集群部署专用，要求 dbbot_inventory_purpose=deploy。
  • hosts.backup.ini：备份专用，要求 dbbot_inventory_purpose=backup。
  • hosts.dr_backup.ini：容灾目标的 NFS 挂载与备份盘准备专用，要求 dbbot_inventory_purpose=backup。
  • hosts.restore.ini：恢复专用，要求 dbbot_inventory_purpose=restore。
  • hosts.nfs_server.ini：NFS 服务端专用，要求 dbbot_inventory_purpose=nfs_server。
  • hosts.single.ini：单机验证专用。

这种拆分的目的是降低误操作概率，避免把备份或恢复命令误打到部署 inventory。

4. 变量文件职责

4.1 playbooks/vars/common_config.yml

用于维护通用参数，例如：

  • clickhouse_version
  • clickhouse_user / clickhouse_group
  • clickhouse_uid / clickhouse_gid
  • clickhouse_data_dir_base
  • clickhouse_default_password
  • fcs_allow_dbbot_default_passwd
  • clickhouse_enable_ssl
  • use_clickhouse_keeper
  • clickhouse_install_debug_package

说明：

  • clickhouse_default_password 的开源默认值是 Dbbot_default@8888。
  • 默认 fcs_allow_dbbot_default_passwd: false，因此如果仍使用这个公开默认密码，相关 Playbook 会在 pre_tasks 阶段直接失败。

4.2 playbooks/vars/cluster_config.yml

用于维护集群层级参数，例如：

  • clickhouse_cluster_name
  • clickhouse_tcp_port_base
  • clickhouse_http_port_base
  • clickhouse_interserver_http_port_base

4.3 playbooks/vars/backup_config.yml

用于备份策略和 manifest 输出，例如：

  • backup_mode
  • backup_storage_disk
  • backup_mount_dir
  • backup_checkpoint_mode
  • backup_require_replicated_tables

4.4 playbooks/vars/restore_config.yml

用于恢复行为控制，例如：

  • restore_batch_id
  • restore_to_all_replicas
  • restore_allow_non_empty_tables
  • restore_enable_two_phase_mv_compat

4.5 playbooks/vars/standalone_config.yml

用于单机验证模式，例如：

  • clickhouse_topology_mode
  • clickhouse_single_host_required

4.6 playbooks/vars/uninstall_config.yml

用于控制卸载行为，例如：

  • uninstall_purge_clickhouse_config
  • uninstall_purge_clickhouse_data
  • uninstall_remove_backup_mount
  • uninstall_purge_zookeeper

5. 执行逻辑概览

入口 Playbook 一般遵循以下顺序：

  1. pre_tasks：参数校验、拓扑解析、环境检查、公开默认密码拦截。
  2. roles：执行系统初始化、协调组件部署、ClickHouse 部署或备份恢复逻辑。
  3. artifacts/manifests：对备份和恢复流程输出运行元数据。

6. 实践建议

  • 为部署、备份、恢复分别维护 inventory。
  • 为 NFS 服务端单独维护 hosts.nfs_server.ini。
  • 在多环境中统一 clickhouse_uid / clickhouse_gid，减少跨集群恢复权限问题。
  • 对生产环境优先使用固定版本号与固定批次号，方便审计和回滚。
  • 默认不安装调试包；只有明确需要故障分析时再启用 clickhouse_install_debug_package=true。