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_default_user_allowed_networks`	`127.0.0.1`, `::1`	人工配置的 `default` 用户可信来源 IP/CIDR
`clickhouse_default_user_auto_include_cluster_nodes`	`true`	是否自动追加 inventory 中的 ClickHouse 节点精确 IP
`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 阶段拦截公开默认密码。
clickhouse_default_password 可以包含对 XML 或 shell 有特殊含义的字符；dbbot 会在生成文件时进行 XML 转义，也不会再把它放进受管 clickhouse-client 的进程参数。
每个实例将自动化凭据保存在 /etc/clickhouse-server[-N]/dbbot-client.xml，归属 root:root、权限为 0600。ClickHouse OS 账号使用的独立快速登录文件仍归属该账号并保持 0600。

`default` 用户可信来源

默认配置只手工声明本地回环地址，同时自动从部署 inventory 的 clickhouse_cluster 组提取并去重所有 ansible_host，最终写入 users.xml：

clickhouse_default_user_allowed_networks:
  - "127.0.0.1"
  - "::1"
clickhouse_default_user_auto_include_cluster_nodes: true

集群模式会追加所有 ClickHouse 节点的精确 IP，以保证 remote_servers 的节点间分布式查询能够继续使用 default 用户。单机模式只追加当前物理主机的 IP，不会自动信任同一 inventory 中的其他独立单机。

如果还需要信任 DBA 管理网段或堡垒机，可以直接扩展列表；自动发现的集群节点 IP 仍会追加：

clickhouse_default_user_allowed_networks:
  - "127.0.0.1"
  - "::1"
  - "10.20.30.0/24"
  - "10.40.50.60"
clickhouse_default_user_auto_include_cluster_nodes: true

如需完全手工控制，请关闭自动追加并写出全部可信来源：

clickhouse_default_user_allowed_networks:
  - "127.0.0.1"
  - "::1"
  - "10.10.10.11"
  - "10.10.10.12"
  - "10.10.10.13"
clickhouse_default_user_auto_include_cluster_nodes: false

如果确实需要恢复旧版“允许任意来源”的行为，可显式配置：

clickhouse_default_user_allowed_networks:
  - "::/0"
clickhouse_default_user_auto_include_cluster_nodes: false

::/0 会允许任意网络来源，不建议在可被非可信主机访问的环境中使用。列表项必须是 IP 地址或 CIDR；启用自动追加时，部署 inventory 的 ansible_host 也应填写 IP 地址。

2. 集群变量

文件：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`	多实例协议兼容端口步长

端口计算规则：

主端口按 instance_id 逐个加 1
MySQL / PostgreSQL 协议兼容端口按 instance_id 乘 clickhouse_aux_port_stride

3. 备份变量

文件：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` 只备份部分节点

生产建议：

生产环境优先使用固定 backup_batch_id
备份前先完成 setup_nfs_client_mount_rc_local.yml 和 prepare_backup_disk.yml

4. 恢复变量

文件：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_include_config_files`	`false`	是否回放配置快照；启用后解压前强制核对 SHA-256
`restore_mount_dir`	`/backup`	恢复目标侧挂载目录

恢复前务必先做两件事：

在恢复目标集群挂载 NFS
在恢复目标集群执行 prepare_backup_disk.yml

配置快照的 SHA-256 来自备份 manifest。校验值缺失或与 NFS 上实际压缩包不一致时，配置回放会失败，不会继续解压。

5. NFS 与清理变量

NFS server/client 的默认值写在 playbook 内。setup_nfs_server.yml 仅用于实验/测试，不是生产 NFS 交付入口。核心值如下：

变量	默认值	作用
`nfs_server_ip`	`198.51.100.162`	NFS 服务端 IP
`nfs_export_dir`	`/srv/nfs/clickhouse_backup`	服务端导出目录
`nfs_export_mode`	`0770`	实验 NFS 导出目录权限
`nfs_export_uid` / `nfs_export_gid`	`18123` / `18123`	实验导出目录的数值 UID/GID，与 ClickHouse 默认运行账号一致
`nfs_export_opts`	`rw,sync,no_subtree_check,no_root_squash`	仅实验兼容策略，不应用于生产 NFS
`nfs_mount_point`	`/backup`	客户端挂载目录
`dbbot_inventory_purpose`	`nfs_server` / `backup`	NFS server/client 守卫

清理变量位于：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 服务与目录

卸载删除前会强制确认 ClickHouse 和受管 ZooKeeper 已停止，并检查当前实例配置路径对应的进程；停服失败或进程残留会阻断删除。

6. 恢复校验变量

文件：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 条件，而不是直接比全表总数。