附录G 集群管理命令参考

本附录列出业务连续性（Halo Shield）集群管理相关工具的全部命令与选项，包括 clumgrctl（Halo Shield 集群管理工具，基于 Patroni 封装）与 etcdctl（etcd 分布式协调服务管理工具）。

G.1 clumgrctl：业务连续性集群的成员管理、主备切换、配置维护等操作。
G.2 etcdctl：etcd 集群的成员、端点状态与健康检查。

本附录基于 Halo 1.0.16 所附带的 clumgrctl 4.0.6 与 etcd 3.5.10 版本编写。不同版本间命令行参数与输出格式可能略有差异，可用 clumgrctl version、etcdctl version 查看实际版本。

clumgrctl（业务连续性集群管理）

clumgrctl 是业务连续性集群的管理命令行工具，用于查看集群状态、执行主备切换、管理成员与配置等。使用格式：

clumgrctl [OPTIONS] COMMAND [ARGS]...

通用选项（所有子命令均可使用）：

选项	说明
`-c, --config-file TEXT`	指定配置文件
`-d, --dcs-url, --dcs TEXT`	DCS（分布式配置存储）连接地址
`-k, --insecure`	允许连接无证书的 SSL 站点
`--help`	显示帮助信息

命令总览

命令	说明
`list`	列出集群所有成员的角色、状态、复制延迟
`show-config`	查看集群当前生效的动态配置
`edit-config`	编辑集群动态配置
`reload`	重载成员配置
`switchover`	计划内主备切换
`failover`	故障转移
`reinit`	重新初始化集群成员
`restart`	重启集群成员
`pause`	暂停自动故障转移
`resume`	恢复自动故障转移
`history`	查看切换/故障转移历史
`topology`	以树状结构查看集群拓扑
`dsn`	生成成员或 Leader 的连接串
`version`	查看 clumgrctl 或运行中实例的版本
`flush`	丢弃已调度的 restart/switchover 事件
`query`	对集群数据库成员执行 SQL 查询
`remove`	从 DCS 移除集群（危险操作，下线集群时使用）

命令详解

list — 列出集群成员

列出指定集群的所有成员及其角色、状态、复制延迟等信息。

clumgrctl list [CLUSTER_NAMES]...

选项	说明
`--group INTEGER`	Citus group
`-e, --extended`	显示额外信息
`-t, --timestamp`	打印时间戳
`-f, --format [pretty\|tsv\|json\|yaml\|yml]`	输出格式
`-W`	每 2 秒自动刷新一次
`-w, --watch FLOAT`	每 X 秒自动刷新一次

执行示例：

clumgrctl list

输出示例：

+ Cluster: halo-cluster (7658605376259660485) -------+----+-----------+
| Member | Host                | Role    | State     | TL | Lag in MB |
+--------+---------------------+---------+-----------+----+-----------+
| node1  | 192.168.10.146:1921 | Leader  | running   |  9 |           |
| node2  | 192.168.10.147:1921 | Replica | streaming |  9 |         0 |
| node3  | 192.168.10.148:1921 | Replica | streaming |  9 |         0 |
+--------+---------------------+---------+-----------+----+-----------+

show-config — 查看集群动态配置

查看当前生效的 DCS 动态配置。

clumgrctl show-config [CLUSTER_NAME]

选项	说明
`--group INTEGER`	Citus group

执行示例：

clumgrctl show-config

输出示例：

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

edit-config — 编辑集群动态配置

编辑集群的动态配置。修改前建议先用 show-config 查看当前配置。

clumgrctl edit-config [CLUSTER_NAME]

选项	说明
`--group INTEGER`	Citus group
`-q, --quiet`	不显示变更内容
`-s, --set TEXT`	设置指定的配置值，可多次指定
`-p, --pg TEXT`	设置数据库参数值（`-s postgresql.parameters` 的简写），可多次指定
`--apply TEXT`	从文件应用配置（`-` 表示从标准输入）
`--replace TEXT`	从文件应用配置并替换现有配置（`-` 表示从标准输入）
`--force`	全程不询问确认

执行示例：

clumgrctl edit-config

该命令会打开编辑器修改动态配置，保存后立即生效并持久化到 etcd。修改前建议先用 show-config 查看当前配置。

reload — 重载成员配置

重载指定成员的配置。

clumgrctl reload CLUSTER_NAME [MEMBER_NAMES]...

选项	说明
`--group INTEGER`	Citus group
`-r, --role [leader\|primary\|standby-leader\|replica\|standby\|any]`	仅重载具有该角色的成员
`--force`	全程不询问确认

执行示例：

clumgrctl reload halo-cluster node1

输出示例：

Success: reload on member node1

switchover — 计划内主备切换

将主库切换到指定的副本，适用于计划内维护。切换期间业务会有短暂中断。

clumgrctl switchover [CLUSTER_NAME]

选项	说明
`--group INTEGER`	Citus group
`--leader, --primary TEXT`	当前主库的名称
`--candidate TEXT`	候选主库的名称
`--scheduled TEXT`	调度切换的时间戳（明确的格式，如 ISO 8601）
`--force`	全程不询问确认

执行示例：

clumgrctl switchover

交互式输入：

Master [node1]:
Candidate ['node2', 'node3']: node2
When should the switchover take place (e.g. 2026-05-10T13:57) [now]:
Are you sure you want to switchover cluster halo-cluster, demoting current master node1? [y/N]: y

输出示例：

2026-05-10 12:57:57.44645 Successfully switched over to "node2"

failover — 故障转移

将主库角色转移到副本，通常在主库异常时使用。

clumgrctl failover [CLUSTER_NAME]

选项	说明
`--group INTEGER`	Citus group
`--candidate TEXT`	候选主库的名称
`--force`	全程不询问确认

执行示例：

clumgrctl failover

交互式输入：

Candidate ['node2', 'node3']: node2
Are you sure you want to failover cluster halo-cluster, demoting current master node1? [y/N]: y

reinit — 重新初始化成员

重新初始化指定的集群成员（基于主库重建副本数据）。

clumgrctl reinit CLUSTER_NAME [MEMBER_NAMES]...

选项	说明
`--group INTEGER`	Citus group
`--force`	全程不询问确认
`--wait`	等待重新初始化完成

执行示例：

clumgrctl reinit halo-cluster node3

输出示例：

Are you sure you want to reinitialize members node3? [y/N]: y
Success: reinitialize for member node3

restart — 重启成员

重启指定的集群成员。

clumgrctl restart CLUSTER_NAME [MEMBER_NAMES]...

选项	说明
`--group INTEGER`	Citus group
`-r, --role [leader\|primary\|standby-leader\|replica\|standby\|any]`	仅重启具有该角色的成员
`--any`	仅重启单个成员
`--scheduled TEXT`	调度重启的时间戳（明确的格式，如 ISO 8601）
`--db-version TEXT`	当数据库版本低于指定值时重启（如 `13.5`）
`--pending`	当处于 pending 状态时重启
`--timeout TEXT`	重启超过该时长则报错并在必要时切换
`--force`	全程不询问确认

执行示例：

clumgrctl restart halo-cluster node3

输出示例：

Are you sure you want to restart members node3? [y/N]: y
Restart if the Halo version is less than provided (e.g. 1.0.16) []:
Success: restart on member node3

pause — 暂停自动故障转移

暂停集群的自动故障转移（进入维护模式）。维护操作前常先 pause，避免误触发切换。

clumgrctl pause [CLUSTER_NAME]

选项	说明
`--group INTEGER`	Citus group
`--wait`	等待暂停在所有节点生效

执行示例：

clumgrctl pause

输出示例：

Success: cluster management is paused

再次执行 clumgrctl list 时会在表尾显示 Maintenance mode: on。

resume — 恢复自动故障转移

恢复集群的自动故障转移（退出维护模式）。

clumgrctl resume [CLUSTER_NAME]

选项	说明
`--group INTEGER`	Citus group
`--wait`	等待暂停在所有节点清除

history — 查看切换历史

查看集群的故障转移/主备切换历史。

clumgrctl history [CLUSTER_NAME]

选项	说明
`--group INTEGER`	Citus group
`-f, --format [pretty\|tsv\|json\|yaml\|yml]`	输出格式

执行示例：

clumgrctl history

输出示例：

+----+-----------+------------------------------+----------------------------------+------------+
| TL |       LSN | Reason                       | Timestamp                        | New Leader |
+----+-----------+------------------------------+----------------------------------+------------+
|  1 | 167772320 | no recovery target specified | 2026-07-08T11:35:15.555857+08:00 | node1      |
|  2 | 184549536 | no recovery target specified | 2026-07-10T08:38:09.891873+08:00 | node1      |
|  3 | 201326752 | no recovery target specified | 2026-07-15T11:56:27.136833+08:00 | node1      |
+----+-----------+------------------------------+----------------------------------+------------+

topology — 查看集群拓扑

以树状结构（ASCII）显示集群拓扑，可直观看出副本挂在哪个主库下。

clumgrctl topology [CLUSTER_NAMES]...

选项	说明
`--group INTEGER`	Citus group
`-W`	每 2 秒自动刷新一次
`-w, --watch FLOAT`	每 X 秒自动刷新一次

执行示例：

clumgrctl topology halo-cluster

输出示例：

+ Cluster: halo-cluster (7658605376259660485) --------+----+-----------+
| Member  | Host                | Role    | State     | TL | Lag in MB |
+---------+---------------------+---------+-----------+----+-----------+
| node1   | 192.168.10.146:1921 | Leader  | running   |  9 |           |
| + node2 | 192.168.10.147:1921 | Replica | streaming |  9 |         0 |
| + node3 | 192.168.10.148:1921 | Replica | streaming |  9 |         0 |
+---------+---------------------+---------+-----------+----+-----------+

成员名前的 + 表示该节点为从库，缩进挂载在其主库之下。

dsn — 生成连接串

生成指定成员或当前 Leader 的数据库连接信息。不指定 -m 时默认返回 Leader 的连接串。

clumgrctl dsn [CLUSTER_NAME]

选项	说明
`-r, --role [leader\|primary\|standby-leader\|replica\|standby\|any]`	返回具有该角色的任意成员的连接串
`-m, --member TEXT`	生成该成员的连接串
`--group INTEGER`	Citus group

执行示例：

clumgrctl dsn -m node1 halo-cluster

输出示例：

host=192.168.10.146 port=1921

不指定 -m 时默认返回 Leader 的连接串。

version — 查看版本

查看 clumgrctl 命令自身的版本，或运行中的 Clustermgr 实例的版本。

clumgrctl version [CLUSTER_NAME] [MEMBER_NAMES]...

选项	说明
`--group INTEGER`	Citus group

执行示例：

clumgrctl version

输出示例：

clumgrctl version 4.0.6

flush — 丢弃已调度的事件

丢弃已调度的 restart 或 switchover 事件（例如此前通过 --scheduled 排程但尚未执行的切换/重启）。

clumgrctl flush CLUSTER_NAME [MEMBER_NAMES]... {restart|switchover}

选项	说明
`--group INTEGER`	Citus group
`-r, --role [leader\|primary\|standby-leader\|replica\|standby\|any]`	仅丢弃具有该角色成员的事件
`--force`	全程不询问确认

query — 查询集群数据库成员

对集群中的数据库成员执行 SQL 查询。

说明：执行 query 前需确保 clustermgr 配置文件中 postgresql.pgpass 指定的 .pgpass 文件已正确创建（权限 600），或已通过其他方式配置免密连接，否则会因无法提供密码而连接失败。

clumgrctl query [CLUSTER_NAME]

选项	说明
`--group INTEGER`	Citus group
`--format TEXT`	输出格式（pretty / tsv / json / yaml）
`-f, --file FILENAME`	从该文件执行 SQL 命令
`--password`	强制提示输入口令
`-U, --username TEXT`	数据库用户名
`-W`	每 2 秒自动刷新一次
`-w, --watch FLOAT`	每 X 秒自动刷新一次
`-r, --role [leader\|primary\|standby-leader\|replica\|standby\|any]`	查询具有该角色的成员
`-m, --member TEXT`	查询指定成员
`--delimiter TEXT`	列分隔符
`-c, --command TEXT`	要执行的 SQL 命令
`-d, --dbname TEXT`	要连接的数据库名

remove — 从 DCS 移除集群

将集群从 DCS（分布式配置存储）中移除。此操作危险，会清空集群的协调信息，仅在彻底下线集群时使用。

clumgrctl remove CLUSTER_NAME

选项	说明
`--group INTEGER`	Citus group
`-f, --format [pretty\|tsv\|json\|yaml\|yml]`	输出格式

etcdctl（etcd 集群管理）

etcdctl 是 etcd 分布式协调服务的命令行管理工具。业务连续性方案使用 etcd 作为 DCS，常用操作为查看端点状态、成员列表与健康检查。使用格式：

etcdctl [OPTIONS] COMMAND [ARGS]...

说明：本节仅列出业务连续性运维中常用的几条 etcdctl 命令。etcdctl 完整命令集请参考 etcd 官方文档或 etcdctl --help。

endpoint status — 查看 etcd 集群状态

查看各 etcd 节点的版本、DB 大小、是否 Leader、Raft 索引等信息。

etcdctl endpoint status --cluster=true -w table

输出示例：

+----------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
|          ENDPOINT          |        ID        | VERSION | DB SIZE | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS |
+----------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+
| http://192.168.10.147:2379 | 1caa36c5119bc134 |  3.5.10 |   49 kB |      true |      false |         6 |        144 |                144 |        |
| http://192.168.10.148:2379 | 865099e2e3dbfe8e |  3.5.10 |   49 kB |     false |      false |         6 |        144 |                144 |        |
| http://192.168.10.146:2379 | f5e1b2ef0f9c8a0b |  3.5.10 |   49 kB |     false |      false |         6 |        144 |                144 |        |
+----------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+

member list — 查看 etcd 成员

列出 etcd 集群所有成员及其 peer/client 地址。

etcdctl member list -w table

输出示例：

+------------------+---------+------------+----------------------------+----------------------------+------------+
|        ID        | STATUS  |    NAME    |         PEER ADDRS         |        CLIENT ADDRS        | IS LEARNER |
+------------------+---------+------------+----------------------------+----------------------------+------------+
| 1caa36c5119bc134 | started | etcd_node2 | http://192.168.10.147:2380 | http://192.168.10.147:2379 |      false |
| 865099e2e3dbfe8e | started | etcd_node3 | http://192.168.10.148:2380 | http://192.168.10.148:2379 |      false |
| f5e1b2ef0f9c8a0b | started | etcd_node1 | http://192.168.10.146:2380 | http://192.168.10.146:2379 |      false |
+------------------+---------+------------+----------------------------+----------------------------+------------+

endpoint health — 检查 etcd 健康

检查所有 etcd 端点是否可正常提交提案。

etcdctl endpoint health --cluster=true

输出示例：

http://192.168.10.146:2379 is healthy: successfully committed proposal: took = 12.339568ms
http://192.168.10.147:2379 is healthy: successfully committed proposal: took = 12.354846ms
http://192.168.10.148:2379 is healthy: successfully committed proposal: took = 12.788127ms

clumgrctl（业务连续性集群管理）​

命令总览​

命令详解​

etcdctl（etcd 集群管理）​

endpoint status — 查看 etcd 集群状态​

member list — 查看 etcd 成员​

endpoint health — 检查 etcd 健康​

clumgrctl（业务连续性集群管理）

命令总览

命令详解

etcdctl（etcd 集群管理）

endpoint status — 查看 etcd 集群状态

member list — 查看 etcd 成员

endpoint health — 检查 etcd 健康