ClickHouse 变量与参数说明

本文汇总 clickhouse_ansible 公开能力中最常改、最容易影响结果的变量，帮助你在部署、备份、恢复前快速定位配置入口。

1. 通用变量

文件：playbooks/vars/common_config.yml

变量	默认值	作用
`clickhouse_version`	`23.6.1`	ClickHouse 版本，支持三段或四段写法
`clickhouse_install_debug_package`	`false`	是否额外准备并安装 `clickhouse-common-static-dbg`
`clickhouse_default_password`	`Dbbot_default@8888`	`default` 用户密码
`clickhouse_uid` / `clickhouse_gid`	`18123` / `18123`	ClickHouse 用户和组的固定 UID/GID
`fcs_auto_download_packages`	`true`	控制节点是否自动下载 ClickHouse 安装包
`fcs_set_hostname`	`true`	是否修改目标主机 hostname
`fcs_allow_dbbot_default_passwd`	`false`	是否允许使用公开默认密码继续执行
`use_clickhouse_keeper`	`false`	`false` 使用独立 ZooKeeper，`true` 使用 ClickHouse Keeper
`clickhouse_enable_ssl`	`false`	是否启用 SSL
`deploy_require_manual_confirm`	`true`	部署前是否要求控制台确认

说明：

clickhouse_install_debug_package=false 是当前建议默认值，能显著减少下载和分发时间。
源集群与容灾集群建议统一 clickhouse_uid / clickhouse_gid，避免 NFS 恢复时权限错位。
clickhouse_default_password 的公开默认值是 Dbbot_default@8888。
默认 fcs_allow_dbbot_default_passwd: false，因此部署、备份、恢复相关 Playbook 会在 pre_tasks 阶段拦截公开默认密码。

文件：playbooks/vars/cluster_config.yml

变量	默认值	作用
`clickhouse_cluster_name`	`example_3shards_2replicas`	集群名
`clickhouse_tcp_port_base`	`9000`	ClickHouse TCP 端口基线
`clickhouse_http_port_base`	`8123`	ClickHouse HTTP 端口基线
`clickhouse_interserver_http_port_base`	`9009`	副本间 HTTP 端口基线
`clickhouse_mysql_port_base`	`9004`	MySQL 协议兼容端口基线
`clickhouse_postgresql_port_base`	`9005`	PostgreSQL 协议兼容端口基线
`clickhouse_aux_port_stride`	`10`	多实例协议兼容端口步长

端口计算规则：

文件：playbooks/vars/backup_config.yml

变量	默认值	作用
`backup_databases` / `backup_tables`	`[]`	备份对象，至少设置一项
`backup_mode`	`full`	备份模式，支持 `full` / `incremental`
`backup_base_batch_id`	`""`	增量备份基线批次号
`backup_storage_disk`	`backup_nfs`	ClickHouse 侧备份磁盘名
`backup_mount_dir`	`/backup`	NFS 挂载目录
`backup_checkpoint_mode`	`file`	`safe_ts` 记录方式
`backup_require_replicated_tables`	`true`	是否阻断非复制本地表备份
`backup_allow_partial_cluster`	`false`	是否允许 `--limit` 只备份部分节点

生产建议：

文件：playbooks/vars/restore_config.yml

变量	默认值	作用
`restore_batch_id`	`""`	目标恢复批次号，必填
`restore_manifest_file`	`""`	manifest 路径，默认自动定位
`restore_to_all_replicas`	`true`	是否所有副本都参与恢复
`restore_allow_non_empty_tables`	`false`	是否允许恢复到非空表
`restore_enable_two_phase_mv_compat`	`true`	是否启用 MV 两阶段兼容恢复
`restore_allow_partial_cluster`	`false`	是否允许 `--limit` 只恢复部分节点
`restore_require_manual_confirm`	`true`	恢复前是否要求控制台确认
`restore_mount_dir`	`/backup`	恢复目标侧挂载目录

恢复前务必先做两件事：

NFS server/client 的默认值写在 playbook 内，核心值如下：

清理变量位于：playbooks/vars/uninstall_config.yml

变量	默认值	作用
`uninstall_require_manual_confirm`	`true`	卸载前是否要求确认
`uninstall_purge_clickhouse_config`	`true`	是否删除 ClickHouse 配置
`uninstall_purge_clickhouse_data`	`true`	是否删除 ClickHouse 数据目录
`uninstall_purge_clickhouse_logs`	`true`	是否删除 ClickHouse 日志目录
`uninstall_remove_backup_mount`	`false`	是否顺带卸载 `/backup` 并移除 rc.local 挂载脚本
`uninstall_purge_zookeeper`	`true`	是否删除独立 ZooKeeper 服务与目录

文件：playbooks/vars/validate_restore_config.yml

变量	默认值	作用
`validate_source_group`	`clickhouse_backup`	源集群分组
`validate_target_group`	`clickhouse_restore`	目标集群分组
`validate_source_query_host`	`127.0.0.1`	源端查询地址
`validate_target_query_host`	`127.0.0.1`	目标端查询地址
`validate_fail_on_missing_pairs`	`true`	源/目标缺少对应分片副本时是否失败
`validate_checks`	`[]`	校验项列表

使用这个 playbook 时，需要同时传入两套 inventory，例如：

ansible-playbook \
  -i ../inventory/hosts.backup.ini \
  -i ../inventory/hosts.restore.ini \
  validate_restore_consistency.yml

对 TTL 表，建议在 validate_checks 中写固定时间窗口的 where 条件，而不是直接比全表总数。