配置详解

执行环境说明：本章配置文件与命令中的 IP 地址、用户名与密码均为演示环境取值，部署时请替换为实际环境的真实信息，并使用强密码。

本章为各配置项的参考说明。etcd_config.sh 与 clustermgr_config.sh 的执行步骤，见部署 etcd 与 Clustermgr。

etcd.conf 说明

执行 etcd_config.sh 后，会在每个节点生成 /u01/app/halo/product/shield/etcd/v3.5.10/conf/etcd.conf。以 node1（IP 为 192.168.10.146）为例，生成的配置文件内容如下：

ETCD_DATA_DIR="/u01/app/halo/product/shield/etcd/v3.5.10/data/etcd_node1.etcd"
ETCD_LISTEN_PEER_URLS="http://192.168.10.146:2380"
ETCD_LISTEN_CLIENT_URLS="http://192.168.10.146:2379,http://127.0.0.1:2379"
ETCD_NAME="etcd_node1"
ETCD_INITIAL_ADVERTISE_PEER_URLS="http://192.168.10.146:2380"
ETCD_ADVERTISE_CLIENT_URLS="http://192.168.10.146:2379"
ETCD_INITIAL_CLUSTER="etcd_node1=http://192.168.10.146:2380,etcd_node2=http://192.168.10.147:2380,etcd_node3=http://192.168.10.148:2380"
ETCD_INITIAL_CLUSTER_TOKEN="halo-etcd-cluster"
ETCD_INITIAL_CLUSTER_STATE="new"
# ETCD_ENABLE_V2="true"
ETCD_LOG_OUTPUTS="/u01/app/halo/product/shield/etcd/v3.5.10/logs/etcd.log"
ETCD_LOG_LEVEL="warn"
ETCD_ENABLE_LOG_ROTATION="true"
ETCD_LOG_ROTATION_CONFIG_JSON='{"maxsize": 50, "maxage": 10, "maxbackups": 0, "localtime": false, "compress": true}'

主要配置项说明：

配置项	说明
ETCD_DATA_DIR	etcd 数据存储目录
ETCD_LISTEN_PEER_URLS	etcd 集群内部通信监听地址（端口 2380）
ETCD_LISTEN_CLIENT_URLS	etcd 客户端监听地址（端口 2379），包含本机回环地址
ETCD_NAME	etcd 节点名称，需唯一
ETCD_INITIAL_ADVERTISE_PEER_URLS	向集群其他节点通告的 peer 地址
ETCD_ADVERTISE_CLIENT_URLS	向客户端通告的地址
ETCD_INITIAL_CLUSTER	初始集群成员列表
ETCD_INITIAL_CLUSTER_TOKEN	集群 token，同一集群所有节点需一致
ETCD_INITIAL_CLUSTER_STATE	初始集群状态，首次部署为 new，后续加入为 existing
ETCD_ENABLE_V2	是否启用 etcd v2 API（默认注释关闭，clustermgr 使用 v3 API）
ETCD_LOG_OUTPUTS	日志输出路径
ETCD_LOG_LEVEL	日志级别，生产环境建议 warn
ETCD_ENABLE_LOG_ROTATION	是否启用日志轮转
ETCD_LOG_ROTATION_CONFIG_JSON	日志轮转参数（单文件大小 MB、保留份数、是否压缩等）

clustermgr_halo.yml 详解

clustermgr_halo.yml 是 clustermgr 的核心配置文件，位于 /u01/app/halo/product/shield/clustermgr/conf/clustermgr_halo.yml。以下是一个 node1 的完整示例：

scope: halo-cluster
name: node1

log:
  level: INFO
  traceback_level: ERROR
  dir: /u01/app/halo/product/shield/clustermgr/logs
  file_num: 10

restapi:
  listen: 0.0.0.0:8008
  connect_address: 192.168.10.146:8008

etcd3:
  hosts: 192.168.10.146:2379,192.168.10.147:2379,192.168.10.148:2379

bootstrap:
  dcs:
    ttl: 30
    loop_wait: 10
    retry_timeout: 10
    maximum_lag_on_failover: 1048576
    master_start_timeout: 300
    synchronous_mode: false
    postgresql:
      use_pg_rewind: true
      use_slots: true
      parameters:
        wal_level: replica
        hot_standby: "on"
        max_wal_senders: 10
        max_replication_slots: 10
        wal_log_hints: "on"

postgresql:
  listen: "*:1921"
  connect_address: 192.168.10.146:1921
  database: halo0root
  data_dir: /data/halo
  bin_dir: /u01/app/halo/product/dbms/16/bin
  pgpass: /u01/app/halo/product/shield/clustermgr/.pgpass
  callbacks:
    on_start: /u01/app/halo/product/shield/clustermgr/scripts/clustermgr_callback.sh
    on_stop: /u01/app/halo/product/shield/clustermgr/scripts/clustermgr_callback.sh
    on_role_change: /u01/app/halo/product/shield/clustermgr/scripts/clustermgr_callback.sh
  authentication:
    replication:
      username: replica
      password: "123456"
    superuser:
      username: clustermgr
      password: clustermgr
    rewind:
      username: clustermgr
      password: clustermgr

watchdog:
  mode: automatic
  device: /dev/watchdog
  safety_margin: 5

tags:
  nofailover: false
  noloadbalance: false
  clonefrom: false
  nosync: false
  nostream: false

说明：postgresql.authentication 下需同时配置 username 与 password，密码必须与数据库中创建该用户时（CREATE USER ... PASSWORD ...）设置的密码一致。clustermgr 凭此连接 Halo 执行状态管理、切换与 pg_rewind 等操作。

callback 脚本与 VIP 配置

callback 脚本负责在主库切换时漂移 VIP，默认路径为 /u01/app/halo/product/shield/clustermgr/scripts/clustermgr_callback.sh。脚本主要内容如下：

#!/bin/bash

###
# Change the variables below
###
vip_ip="192.168.10.110"
vip_netmask="255.255.255.0"
broadcast_ip="192.168.10.255"
vip_interface="ens160"
###

readonly cb_name=$1
readonly role=$2
readonly scope=$3

function usage() {
    echo "Usage: $0 <on_start|on_stop|on_role_change> <role> <scope>";
    exit 1;
}

echo "this is clustermgr callback $cb_name $role $scope"

case $cb_name in
    on_stop)
        /usr/bin/sudo /usr/sbin/ip addr del ${vip_ip}/${vip_netmask} dev ${vip_interface} label ${vip_interface}:1
        /usr/bin/sudo /usr/sbin/iptables -F
        ;;
    on_start)
        if [[ $role == 'master' ]]||[[ $role == 'promoted' ]]||[[ $role == 'primary' ]]; then
            /usr/bin/sudo /usr/sbin/ip addr add ${vip_ip}/${vip_netmask} brd ${broadcast_ip} dev ${vip_interface} label ${vip_interface}:1
            /usr/bin/sudo /usr/sbin/arping -q -A -c 1 -I ${vip_interface} ${vip_ip}
            /usr/bin/sudo /usr/sbin/iptables -F
        elif [[ $role == 'slave' ]]||[[ $role == 'replica' ]]||[[ $role == 'logical' ]]; then
            /usr/bin/sudo /usr/sbin/ip addr del ${vip_ip}/${vip_netmask} dev ${vip_interface} label ${vip_interface}:1
            /usr/bin/sudo /usr/sbin/iptables -F
        fi
        ;;
    on_role_change)
        if [[ $role == 'master' ]]||[[ $role == 'promoted' ]]||[[ $role == 'primary' ]]; then
            /usr/bin/sudo /usr/sbin/ip addr add ${vip_ip}/${vip_netmask} brd ${broadcast_ip} dev ${vip_interface} label ${vip_interface}:1
            /usr/bin/sudo /usr/sbin/arping -q -A -c 1 -I ${vip_interface} ${vip_ip}
            /usr/bin/sudo /usr/sbin/iptables -F
        elif [[ $role == 'slave' ]]||[[ $role == 'replica' ]]||[[ $role == 'logical' ]]; then
            /usr/bin/sudo /usr/sbin/ip addr del ${vip_ip}/${vip_netmask} dev ${vip_interface} label ${vip_interface}:1
            /usr/bin/sudo /usr/sbin/iptables -F
        fi
        ;;
    *)
        usage
        ;;
esac

说明：

• vip_ip、vip_netmask、broadcast_ip、vip_interface 需根据实际环境修改。
• on_start 和 on_role_change 在节点成为主库时绑定 VIP，在成为从库时解绑。
• on_stop 在实例停止时解绑 VIP。
• 需要 sudoers 配置：halo ALL=(ALL) NOPASSWD: /usr/sbin/ip, /usr/sbin/arping, /usr/sbin/iptables

watchdog 配置（可选）

watchdog（看门狗）是一种超时保护机制。clustermgr 在正常工作时，会定期"喂狗"；如果由于进程卡死、系统假死或其他异常导致 clustermgr 无法继续喂狗，watchdog 会在超过 safety_margin 秒后触发系统重启，从而避免集群长时间处于无管理状态或潜在脑裂风险。

• 软件看门狗：通过 Linux softdog 模块模拟，无需专用硬件，适合大多数环境。
• 硬件看门狗：部分服务器或云平台提供硬件 watchdog 设备，可靠性更高。

watchdog.mode 可取以下值：

取值	说明
off	不启用 watchdog
automatic	优先尝试启用 watchdog；若系统未提供可用设备（如 /dev/watchdog 不存在、softdog 模块未加载），clustermgr 将跳过 watchdog 降级运行，不影响集群正常工作
required	强制要求 watchdog；若设备不可用，clustermgr 将拒绝启动

说明：在 automatic 模式下，若节点上不存在可用的 watchdog 设备（/dev/watchdog 缺失或 softdog 模块未加载），clustermgr 会记录告警并跳过 watchdog 功能继续运行——集群仍可正常提供高可用，只是失去硬件级的最后一道脑裂防线。生产环境若需启用，应先加载 softdog 模块（modprobe softdog）或确认存在硬件 watchdog 设备。