常用命令与操作

本节介绍业务连续性（Halo Shield）集群日常运维中最常用的命令及其用法示例。各命令的完整参数、输出示例与交互流程详见附录G 集群管理命令参考。

查看集群状态

clumgrctl list — 查看集群成员状态

命令用途：查看所有集群成员的角色、状态、复制延迟等信息，是日常最常用的命令。

执行示例：

clumgrctl list

输出示例（一主两从集群，node1 为 Leader，node2、node3 为 Replica，复制延迟均为 0）：

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

注意事项：

Lag in MB 是主从延迟的关键指标，正常情况下应为 0。
若需要以树状结构查看从库挂载在哪个主库下，请使用 clumgrctl topology（详见附录G 集群管理命令参考）。

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

命令用途：查看当前生效的 DCS 动态配置。

执行示例：

clumgrctl show-config

输出示例（DCS 中的集群动态配置）：

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

注意事项：与本地 clustermgr_halo.yml 不完全相同，动态配置通过 edit-config 修改后会立即生效并持久化到 etcd。

clumgrctl history — 查看切换历史

命令用途：查看集群发生过的 failover/switchover 历史。

执行示例：

clumgrctl history

输出示例（TL 递增，每次主备切换生成一条记录，New Leader 列显示切换后的主库）：

+----+-----------+------------------------------+----------------------------------+------------+
| TL |       LSN | Reason                       | Timestamp                        | New Leader |
+----+-----------+------------------------------+----------------------------------+------------+
| 12 | 369098912 | no recovery target specified | 2026-08-13T14:28:21+08:00        | node1      |
| 13 | 385876128 | no recovery target specified | 2026-08-13T14:34:07+08:00        | node2      |
| 14 | 402653344 | no recovery target specified | 2026-08-13T14:35:15+08:00        | node1      |
+----+-----------+------------------------------+----------------------------------+------------+

注意事项：TL 递增表示发生过角色变更；可用于追溯故障切换时间点。

clumgrctl dsn — 生成连接串

命令用途：生成指定成员或当前 Leader 的数据库连接信息。

执行示例：

clumgrctl dsn -m node1 halo-cluster

注意事项：不写 -m 时默认返回 Leader 的连接信息，常用于应用配置或脚本探测。

clumgrctl topology — 查看集群拓扑

命令用途：以树状结构打印集群拓扑，显示各从库（Replica）挂载在哪个主库（Leader）下。

执行示例：

clumgrctl topology halo-cluster

输出示例（+ 表示从库，缩进挂载在其主库 node1 之下）：

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

注意事项：

成员名前的 + 表示该节点为从库，缩进挂载在其主库之下。
list 与 topology 的区别：list 为平铺列表，topology 以树状展示主从挂载关系。级联复制（从库再挂从库）场景下 topology 的层次结构更直观。

clumgrctl version — 查看版本

命令用途：查看 clumgrctl 命令自身的版本号。

执行示例：

clumgrctl version

输出示例：

clumgrctl version 4.0.6

手动主备切换

clumgrctl switchover — 计划内主备切换

命令用途：在集群健康时，手动将主库角色切换到指定从库。

执行示例：

clumgrctl switchover

输出示例（将主库从 node1 切换到 node2，命令为交互式，依次确认切换时间与操作）：

When should the switchover take place (e.g. 2026-08-13T15:33)  [now]:
Are you sure you want to switchover cluster halo-cluster, demoting current leader node1? [y/N]: y
2026-08-13 14:34:07 Successfully switched over to "node2"

切换完成后，原主 node1 自动降级为 Replica 并接入新主 node2：

| node1  | 192.168.10.146:1921 | Replica | streaming | 14 |         0 |
| node2  | 192.168.10.147:1921 | Leader  | running   | 14 |           |
| node3  | 192.168.10.148:1921 | Replica | streaming | 14 |         0 |

注意事项：

建议先 pause 再执行计划内切换，避免切换过程中又触发自动故障转移。
切换前确认目标从库延迟为 0。

clumgrctl failover — 故障转移

命令用途：当主库异常但仍能与 DCS（etcd）通信时，手动触发故障转移，将主库角色强制切换到指定从库。与 switchover 的区别在于：switchover 是集群健康时的计划内切换，failover 是主库出现异常时的强制切换。

执行示例：

clumgrctl failover

输出示例（需用 --candidate 指定目标从库，强制将主库切换到 node2）：

Are you sure you want to failover cluster halo-cluster, demoting current leader node1? [y/N]: y
2026-08-13 14:36:40 Successfully failed over to "node2"

注意事项：

failover 通常用于主库故障但 DCS 仍可访问、自动 failover 未触发或需指定目标节点的场景。
若主库已彻底失联且满足故障检测条件，clustermgr 会自动执行 failover，无需手动调用。
生产环境慎用，操作前确认目标从库数据完整、延迟可控。

暂停/恢复自动切换

clumgrctl pause / resume — 暂停/恢复自动故障转移

命令用途：进入/退出维护模式；维护期间 clustermgr 不会自动执行 failover。

执行示例：

clumgrctl pause

输出示例：

Success: cluster management is paused

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

| node1  | 192.168.10.146:1921 | Leader  | running   | 17 |           |
| node2  | 192.168.10.147:1921 | Replica | streaming | 17 |         0 |
| node3  | 192.168.10.148:1921 | Replica | streaming | 17 |         0 |
+--------+---------------------+---------+-----------+----+-----------+
 Maintenance mode: on

退出维护模式使用 clumgrctl resume，返回 Success: cluster management is resumed。

注意事项：

执行计划内维护（如重启数据库、调整参数）前建议先 pause。
维护完成后务必 resume，否则集群失去自动高可用保护。

重新初始化副本与重启

clumgrctl reinit — 重新初始化副本

命令用途：当某个从库数据损坏、延迟过大或配置不一致时，从主库重新拉取全量数据。

执行示例：

clumgrctl reinit halo-cluster node3

输出示例：

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

reinit 在后台异步执行（删除该节点 $PGDATA 并从主库重新拉取全量数据），完成后 node3 自动恢复为 Replica 并重新进入 streaming 状态。

注意事项：

会删除该节点现有 $PGDATA，请谨慎操作。
执行前建议先确认主库可正常访问，且网络带宽足够。

clumgrctl restart — 重启指定成员

命令用途：重新启动某个节点的 Halo 实例（由 clustermgr 管理）。

执行示例：

clumgrctl restart halo-cluster node3

输出示例（交互式，依次确认重启时间、操作确认、版本条件）：

When should the restart take place (e.g. 2026-08-13T15:37)  [now]:
Are you sure you want to restart members node3? [y/N]: y
Restart if the database version is less than provided (e.g. 13.5)  []:
Success: restart on member node3

注意事项：

重启 Leader 会触发短暂切换，建议在业务低峰期执行。
可配合 pause 与 switchover 实现滚动重启。

clumgrctl reload — 重载配置

命令用途：让指定节点重新读取本地 clustermgr_halo.yml 配置并生效，无需重启 clustermgr 进程。

执行示例：

clumgrctl reload halo-cluster node1

注意事项：

reload 适用于修改本地配置文件（clustermgr_halo.yml）后使其生效；若要修改集群动态配置（DCS 中），应使用 edit-config。
修改 PostgreSQL 参数等需要重启实例才能生效的配置，reload 不够，需配合 restart。

修改动态配置

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

命令用途：修改当前生效的 DCS 动态配置，修改后会立即生效并持久化到 etcd。

执行示例：

clumgrctl edit-config

注意事项：

修改前建议先用 clumgrctl show-config 查看当前配置。
对关键参数（如 ttl、loop_wait、synchronous_mode）的修改会影响故障检测与复制行为，请在维护窗口内谨慎操作。
建议在执行 edit-config 前 pause 集群，避免配置变更期间触发自动切换。

etcd 常用操作

etcdctl endpoint status — 查看 etcd 集群状态

命令用途：查看各 etcd 节点的版本、DB 大小、是否 Leader、Raft 索引等。

执行示例：

etcdctl endpoint status --cluster=true -w table

输出示例（IS LEADER 为 true 的节点是 etcd leader）：

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

注意事项：

IS LEADER 为 true 的节点是 etcd leader。
若任一节点显示 unhealthy，需优先排查 etcd 网络与磁盘。

etcdctl member list — 查看 etcd 成员

命令用途：列出 etcd 集群所有成员及其 peer/client 地址。

执行示例：

etcdctl member list -w table

输出示例：

+------------------+---------+------------+----------------------------+----------------------------+------------+
|        ID        | STATUS  |    NAME    |         PEER ADDRS         |        CLIENT ADDRS        | IS LEARNER |
+------------------+---------+------------+----------------------------+----------------------------+------------+
| f5e1b2ef0f9c8a0b | started | etcd_node1 | http://192.168.10.146:2380 | http://192.168.10.146:2379 |      false |
| 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 |
+------------------+---------+------------+----------------------------+----------------------------+------------+

注意事项：扩容/缩容 etcd 前，先用此命令确认成员状态。

etcdctl endpoint health — 检查 etcd 健康

命令用途：检查所有 etcd 端点是否可正常提交提案。

执行示例：

etcdctl endpoint health --cluster=true

输出示例：

http://192.168.10.146:2379 is healthy: successfully committed proposal: took = 4.643495ms
http://192.168.10.147:2379 is healthy: successfully committed proposal: took = 8.968014ms
http://192.168.10.148:2379 is healthy: successfully committed proposal: took = 8.894606ms

注意事项：任一节点显示 unhealthy 时，需优先排查 etcd 网络与磁盘。

查看集群状态​

手动主备切换​

暂停/恢复自动切换​

重新初始化副本与重启​

修改动态配置​

etcd 常用操作​

查看集群状态

手动主备切换

暂停/恢复自动切换

重新初始化副本与重启

修改动态配置

etcd 常用操作