KingbaseES V8R3 读写分离集群运维与故障处理手册

king_harry2026-06-30 14:56

目录

  • [第一章 集群架构概述](#第一章 集群架构概述)

  • [第二章 系统环境与配置要求](#第二章 系统环境与配置要求)

  • [第三章 核心配置文件详解](#第三章 核心配置文件详解)

  • [第四章 日常巡检标准](#第四章 日常巡检标准)

  • [第五章 集群启停管理](#第五章 集群启停管理)

  • [第六章 主备切换操作](#第六章 主备切换操作)

  • [第七章 故障自动恢复机制](#第七章 故障自动恢复机制)

  • [第八章 手动故障恢复操作](#第八章 手动故障恢复操作)

  • [第九章 故障场景与处理方案](#第九章 故障场景与处理方案)

  • [第十章 VIP管理](#第十章 VIP管理)

  • [第十一章 在线扩缩容](#第十一章 在线扩缩容)

  • [第十二章 参数调整与配置变更](#第十二章 参数调整与配置变更)

  • [第十三章 常见故障FAQ](#第十三章 常见故障FAQ)

  • [第十四章 运维禁令与注意事项](#第十四章 运维禁令与注意事项)

  • [第十五章 运维工具箱](#第十五章 运维工具箱)

  • [附录A V8R3与V8R6+架构差异对照](#附录A V8R3与V8R6+架构差异对照)

  • [附录B 故障判断与恢复命令速查表](#附录B 故障判断与恢复命令速查表)

  • [附录C 参数配置速查表](#附录C 参数配置速查表)

第一章 集群架构概述

1.1 核心架构组件

KingbaseES V8R3 读写分离集群采用基于 Pgpool-II（kingbasecluster） 的技术架构，与 V8R6+ 使用 repmgrd/kbha 的架构有本质区别。

组件 功能说明 监听端口
kingbasecluster（基于 Pgpool-II） 中间件层，负责读写请求分发、连接池、负载均衡、健康检测 9999
watchdog Pgpool 子进程，负责高可用监控、节点间 heartbeat 通讯、VIP 管理、主备选举投票 9000（heartbeat）
es_ha_model / HAmodule.conf 集群 HA 自动化脚本和配置，控制 failover 切换和 auto-recovery 行为 -
kingbaseES 数据库服务 主库提供读写服务，备库提供只读服务，通过流复制（Streaming Replication）同步数据 54321
pcp 命令集 Pgpool 集群管理命令，用于节点注册/脱离/切换等操作 9898（pcp 端口）

1.2 集群端口通讯

端口 服务 说明
9999 kingbasecluster 应用连接中间件端口，读写请求入口
9898 pcp 集群管理命令端口（pcp_attach_node 等）
9000 watchdog heartbeat watchdog 进程间互监控通讯端口
54321 kingbaseES 数据库 数据库物理端口，流复制端口

1.3 集群典型拓扑

复制代码 
                    ┌─────────────┐
                    │  应用客户端   │
                    └──────┬──────┘
                           │ 连接 Cluster VIP:192.192.103.185:9999
                    ┌──────┴──────┐
                    │ kingbasecluster │  ← 读写请求分发 + 连接池
                    │   (Pgpool-II)   │
                    └──────┬──────┘
                           │ 读写分离路由
              ┌────────────┼────────────┐
              │                         │
     ┌────────┴────────┐        ┌───────┴───────┐
     │  主库 primary    │        │  备库 standby   │
     │  54321端口       │  WAL   │  54321端口      │
     │  DB VIP所在节点   │ 流复制 │  只读服务        │
     │  192.192.103.183 │←──────│               │
     └─────────────────┘        └───────────────┘
              │                         │
              └── watchdog heartbeat ───┘
                   (9000端口互监控)

1.4 读写分离实现原理

V8R3 的读写分离由 kingbasecluster 中间件自动实现：

  • SELECT 等只读请求：按负载均衡权重分发到备库（lb_weight 配置）

  • INSERT/UPDATE/DELETE 等写请求：自动路由到主库

  • 读写混合事务：第一个写操作之前的读操作按读事务处理，遇到写操作后所有请求路由到主库

应用只需连接 kingbasecluster 的 9999 端口（或 Cluster VIP），无需自行判断读写路由。

1.5 同步模式

模式 说明 性能与数据安全
sync（同步） 主库事务需等待备库 WAL 落盘确认才返回 数据不丢，但影响性能
async（异步） 主库不等待备库确认，性能最高 可能丢数据
半同步 介于同步和异步之间，WAL 落盘即返回 推荐一般生产环境

生产环境推荐同步模式确保数据不丢；高并发场景酌情选用半同步或异步。

1.6 核心概念

概念 说明
primary（主库） 提供读写服务，生成 WAL 日志
standby（备库） 提供只读服务，接收重放 WAL 日志
recovery.conf V8R3 备库标识和恢复配置文件（V8R6+改用 standby.signal）
recovery.done 主库标识文件（备库升主后 recovery.conf 改名生成）
watchdog MASTER 当前活跃的 kingbasecluster 节点，持有 Cluster VIP
watchdog STANDBY 备用的 kingbasecluster 节点
DB VIP 数据库服务 VIP，始终跟随主库漂移
Cluster VIP 集群管理 VIP（delegate_IP），始终跟随 watchdog MASTER 漂移
pcp Pgpool Cluster Protocol，集群管理命令接口
脑裂 集群同时出现多个 primary 节点，导致数据分歧

第二章 系统环境与配置要求

2.1 硬件要求

  • 2路网络区分内外网，本地服务器置于同一千兆交换机

  • 外挂磁盘阵列与各主机置于同网段

2.2 操作系统强制性配置

资源限制（/etc/security/limits.conf）
复制代码 
* soft nofile 655360
* hard nofile 655360
* soft nproc 655360
* hard nproc 655360
* soft core unlimited
* hard core unlimited

⚠️ nofile 的 hard limit 不能超过 /proc/sys/fs/nr_open

内核参数（/etc/sysctl.conf）
复制代码 
kernel.sem= 5010 641280 5010 256
fs.file-max=7672460
fs.aio-max-nr=1048576
net.core.rmem_default=262144
net.core.rmem_max=4194304
net.core.wmem_default=262144
net.core.wmem_max=4194304
net.ipv4.ip_local_port_range=9000 65500
net.ipv4.tcp_wmem=8192 65536 16777216
net.ipv4.tcp_rmem=8192 87380 16777216
vm.min_free_kbytes=512000
vm.vfs_cache_pressure=200
vm.swappiness=20
net.ipv4.tcp_max_syn_backlog=4096
net.core.somaxconn=4096
Remove IPC 配置
复制代码 
# /etc/systemd/logind.conf
RemoveIPC=no    # 必须设为 no，否则共享内存可能被回收
时钟同步
  • 集群所有节点必须做时钟同步 ，系统时间误差需在 2秒以内
防火墙配置

建议关闭防火墙，若无法关闭需开放：

端口 用途
54321 数据库端口
9999 kingbasecluster 中间件端口
9898 pcp 管理端口
9000 watchdog heartbeat 端口
8890 sys_securecmdd 端口（如使用）
关闭数据库自动启动服务
复制代码 
systemctl stop kingbased
systemctl disable kingbased

2.3 VIP 相关前置配置

复制代码 
# ip 命令需赋予普通用户 setuid 权限
chown root.root /sbin/ip
chmod 4755 /sbin/ip
​
# arping 命令同理
chown root.root ${cluster_path}/kingbasecluster/bin/arping
chmod 4755 ${cluster_path}/kingbasecluster/bin/arping

⚠️ watchdog 启动需 root 权限，因为它需要控制 VIP 接口。kingbasecluster 启动时需以管理员权限运行。

2.4 libnsl 适配（银河麒麟V10等新系统）

复制代码 
find /usr/lib64 /usr/lib -name "libnsl.so*"
ln -s /usr/lib64/libnsl.so.2 /usr/lib64/libnsl.so.1

第三章 核心配置文件详解

3.1 kingbasecluster.conf（中间件核心配置）

kingbasecluster.conf 是基于 Pgpool-II 的配置文件，位于 ${cluster_path}/kingbasecluster/etc/ 目录。

Backend（后端数据库节点）配置
复制代码 
# 从0开始编号
backend_hostname0 = '192.192.103.181'     # 主库IP
backend_port0 = 54321                      # 数据库端口
backend_weight0 = 1                        # 负载均衡权重
backend_data_directory0 = '/home/kingbase/cluster/ks_cluster/db/data'
backend_flag0 = 'DISALLOW_TO_FAILOVER'     # 主库禁止自动failover
​
backend_hostname1 = '192.192.103.182'     # 备库IP
backend_port1 = 54321
backend_weight1 = 1
backend_data_directory1 = '/home/kingbase/cluster/ks_cluster/db/data'
backend_flag1 = 'ALLOW_TO_FAILOVER'       # 备库允许自动failover

backend_flag 详解：

Flag 说明
ALLOW_TO_FAILOVER 允许 failover 或 detach，默认值
DISALLOW_TO_FAILOVER 禁止 failover，用于被 HA 保护的节点
ALWAYS_PRIMARY 始终视为 primary
Health Check（健康检查）配置
复制代码 
health_check_period = 10               # 健康检查间隔（秒），0=禁用
health_check_timeout = 20              # 健康检查超时（秒）
health_check_user = 'SYSTEM'           # 健康检查用户
health_check_password = ''             # 健康检查密码
health_check_database = 'TEST'         # 健康检查数据库
health_check_max_retries = 10          # 最大重试次数
health_check_retry_delay = 20          # 重试间隔（秒）

⚠️ health_check 需要每个后端额外 1 个连接，需相应调整 max_connections

Failover（故障切换）配置
复制代码 
failover_mode = 'automatic'            # 故障切换模式
failover_command = ''                   # 切换时执行的命令
recovery_1st_stage_command = ''         # 恢复第一阶段命令
recovery_2nd_stage_command = ''         # 恢复第二阶段命令
连接池和负载均衡配置
复制代码 
listen_addresses = '*'                  # 监听地址
port = 9999                             # 中间件服务端口
num_init_children = 16                  # 连接池进程数
max_pool = 4                            # 每进程最大连接池数
child_life_time = 300                   # 子进程生存时间（秒）
connection_life_time = 0                # 连接生存时间
child_max_connections = 0               # 子进程最大连接数
Watchdog（看门狗）配置
复制代码 
# ---- WATCHDOG ----
use_watchdog = on                       # 激活看门狗（必须on）
trusted_servers = '192.192.103.128'     # 信任网关列表，逗号分隔
ping_path = '/bin'                      # ping命令路径
​
wd_interval = 10                        # pgpool生命检查间隔（秒）
wd_life_point = 3                       # 生命检测失败重试次数
wd_lifecheck_method = 'heartbeat'       # 生命检测方式
​
# Cluster VIP 配置
delegate_IP = '192.192.103.185'          # 集群VIP地址
ifconfig_path = '/sbin'                  # ifconfig命令路径
if_up_cmd = 'ifconfig eth0:0 inet $IP$ netmask 255.255.255.0'
if_down_cmd = 'ifconfig eth0:0 down'
arping_path = '/usr/sbin'               # arping命令路径
arping_cmd = 'arping -U $IP$ -w 1'      # ARP请求命令
​
# Watchdog 互监控配置
wd_hostname = '192.192.103.181'          # 本节点IP
wd_port = 9000                          # watchdog通讯端口
​
# 其他节点 watchdog 配置
other_pgpool_hostname0 = '192.192.103.182'
other_pgpool_port0 = 9999
other_wd_port0 = 9000

watchdog 关键功能：

  1. pgpool 服务的生命检测 --- 通过发送查询到 kingbaseES 检查响应

  2. watchdog 进程相互监控 --- 通过 heartbeat（9000端口）交换状态信息

  3. 自动 VIP 地址分配 --- 主备切换时自动迁移 Cluster VIP

  4. 恢复时自动注册备用服务器

3.2 HAmodule.conf（集群HA配置）

HAmodule.conf 是 V8R3 特有的 HA 配置文件（不同于 V8R6+ 的 repmgr.conf），位于 ${cluster_path}/db/etc/ 和 ${cluster_path}/kingbasecluster/etc/ 目录下（两处都需要配置且保持一致）。

复制代码 
# ---- AUTO PRIMARY RECOVERY ----
# failover切换后原主库是否自动恢复为备库
# 0=关闭（默认），1=开启
AUTO_PRIMARY_RECOVERY=0
​
# ---- DB VIP ----
# 数据库VIP地址，用于数据库服务连接，跟随主库漂移
db_vip="192.192.103.183"
​
# ---- Cluster VIP ----
# 集群VIP地址，对应kingbasecluster.conf中的delegate_IP
cluster_vip="192.192.103.185"
​
# ---- 信任网关 ----
# 用于检测网络连通性，防止脑裂（建议配置网关IP，不要配置节点IP或127.0.0.1）
trust_ip="192.192.103.128"
​
# ---- 网卡设备 ----
# VIP绑定的网卡名称
DEV="eth0"
​
# ---- 数据库端口 ----
db_port="54321"
​
# ---- 网络配置路径 ----
ifconfig_path="/sbin"
arping_path="/usr/sbin"
ping_path="/bin"

AUTO_PRIMARY_RECOVERY 详解：

值 说明 推荐场景
0 failover 后原主库不自动恢复，需人工介入 默认值，安全优先
1 failover 后原主库自动被 recovery 为备库加入集群 无人值守生产环境

3.3 信任网关防脑裂原理

场景 主库行为 备库行为
主库网络故障 发现同步中断 + ping 网关失败 → 关闭主库 发现同步中断 + ping 网关正常 → 执行 failover 升主
备库网络故障 发现同步中断 + ping 网关正常 → 踢出备库 发现同步中断 + ping 网关失败 → 降级，不执行 failover

⚠️ trusted_servers 不建议配置为数据库节点 IP 或 127.0.0.1

3.4 数据库配置文件

V8R3 集群数据库的配置文件为 kingbase.conf（与单机相同），关键参数参考 附录C。

3.5 pcp.conf（PCP认证配置）

pcp.conf 位于 ${cluster_path}/kingbasecluster/etc/，存储 pcp 命令的用户名和 MD5 密码：

复制代码 
kingbase:$md5hash

3.6 recovery.conf（备库恢复配置）

V8R3 特有的备库标识文件（V8R6+ 改用 standby.signal + kingbase.auto.conf）：

复制代码 
standby_mode='on'
primary_conninfo='port=54321 host=主库IP user=SYSTEM password=12345678ab application_name=node1'
recovery_target_timeline='latest'
primary_slot_name='slot_node1'

第四章 日常巡检标准

4.1 逻辑状态检查（核心）

通过 kingbasecluster 中间件端口查看节点状态：

复制代码 
/home/kingbase/cluster/ks_cluster/db/bin/ksql \
  -USYSTEM -dTEST -W12345678ab -p9999 \
  -c "show pool_nodes"

正常标准：

  • ✅ 所有节点 status 必须为 up

  • ✅ 必须有且仅有 一个 primary

  • ✅ replication_delay 长期维持在 0

4.2 物理进程检查

复制代码 
# kingbasecluster 及 watchdog 进程
ps -ef | grep kingbasecluster
# 正常：包含 kingbasecluster: watchdog, kingbasecluster: heartbeat等子进程
​
# 数据库进程
ps -ef | grep kingbase
# 正常：包含 logger, checkpointer, writer, wal writer, walsender/walreceiver 等
​
# crond 定时任务
cat /etc/cron.d/KINGBASECRON
# 正常：包含 network_rewind.sh 和 restartcluster.sh 定时任务

4.3 watchdog 状态检查

复制代码 
/home/kingbase/cluster/ks_cluster/kingbasecluster/bin/pcp_watchdog_info \
  -h 127.0.0.1 -p 9898 -U kingbase

正常标准：

  • ✅ Quorum state = QUORUM EXIST

  • ✅ Master Node 指向当前主节点

  • ✅ 所有节点 Status 正常（MASTER=4, STANDBY=7）

4.4 VIP 检查

复制代码 
ip a

正常标准：

  • ✅ DB VIP 应在当前 primary 节点上

  • ✅ Cluster VIP 应在 watchdog MASTER 节点上

4.5 流复制状态检查

复制代码 
SELECT usename, application_name, client_addr, sync_state, state
FROM sys_stat_replication;

正常标准：

  • ✅ state 为 streaming

  • ✅ sync_state 与配置的同步模式一致

4.6 复制延迟检查

在备库执行：

复制代码 
SELECT CASE 
  WHEN sys_last_wal_receive_lsn() = sys_last_wal_replay_lsn() THEN 0 
  ELSE EXTRACT(EPOCH FROM now() - sys_last_xact_replay_timestamp()) 
END AS replication_lag;

正常标准：延迟值 0 或 < 10

4.7 磁盘空间检查

复制代码 
df -h

预警标准 ：/home/kingbase/ 使用率 < 80%

4.8 归档日志检查

复制代码 
# 检查 sys_xlog/sys_wal 是否堆积
ls -la $data_path/sys_wal/ | wc -l

⚠️ 归档目录写满会导致主库停止服务

4.9 recovery.conf 检查（V8R3特有）

复制代码 
# 备库 data 目录应存在 recovery.conf
ls $data_path/recovery.conf
​
# 主库 data 目录应存在 recovery.done（而非 recovery.conf）
ls $data_path/recovery.done

4.10 License 检查

复制代码 
SELECT get_license_validdays() AS valid_days;

预警标准：valid_days < 7 需更换

第五章 集群启停管理

5.1 一键启停

复制代码 
cd /home/kingbase/cluster/ks_cluster/bin
​
# 启动集群
sh kingbase_monitor.sh start
​
# 停止集群
sh kingbase_monitor.sh stop
​
# 重启集群
sh kingbase_monitor.sh restart

5.2 启动流程详解

kingbase_monitor.sh start 执行顺序：

  1. 检查关闭状态：检查各节点 data 目录是否存在 recovery.conf/recovery.done，判断主备角色，避免双主

  2. 启动数据库服务：依次启动所有节点的数据库（sys_ctl start）

  3. 启动 kingbasecluster：需要 root 权限（watchdog 需控制 VIP）

  4. watchdog 自动选举：

    • 状态演变：DEAD → LOADING → JOINING → INITIALIZING → MASTER/STANDBY

    • 首先被 active 的节点选举为 MASTER 角色

    • 其他节点收到 heartbeat 后加入 cluster，配置为 STANDBY

  5. 加载 VIP：DB VIP 加载到 primary 节点，Cluster VIP 加载到 watchdog MASTER 节点

5.3 停止流程详解

kingbase_monitor.sh stop 执行顺序：

  1. 停止 kingbasecluster 中间件服务

  2. 删除 Cluster VIP

  3. 停止 crond 定时任务（KINGBASECRON）

  4. 停止所有节点数据库服务（sys_ctl stop）

  5. 删除 DB VIP

5.4 验证启动成功

复制代码 
/home/kingbase/cluster/ks_cluster/db/bin/all_monitor.sh

确认所有组件状态为 active。

第六章 主备切换操作

6.1 手动 Switchover（计划内切换）

适用场景：计划内维护、补丁升级等

操作步骤：

  1. 确认集群状态正常（show pool_nodes 所有节点 up）

  2. 在当前主库停止数据库服务：

复制代码 
sys_ctl stop -D /home/kingbase/cluster/ks_cluster/db/data

  1. 等待 watchdog 检测到主库故障，自动执行 failover（约1-2分钟）

  2. 原主库恢复为备库：

    • 若 AUTO_PRIMARY_RECOVERY=1：自动恢复（crond 定时任务 network_rewind.sh 自动执行）

    • 若 AUTO_PRIMARY_RECOVERY=0：需手动配置 recovery.conf 并启动备库

  3. 验证切换结果：show pool_nodes 确认新主备状态

6.2 自动 Failover（故障自动切换）

由 watchdog 自动触发：

  1. 检测阶段 ：kingbasecluster 的 health_check 检测到主库不可用，重试 health_check_max_retries 次

  2. 确认阶段：watchdog 通过 heartbeat 通讯确认其他节点状态，投票确认 failover

  3. 执行阶段：

    • 停止原主库的数据库服务（尝试通过 es_ha_model 脚本远程关闭）

    • 备库执行 sys_ctl promote 升为主库

    • DB VIP 漂移到新主库节点

    • Cluster VIP 漂移到新 watchdog MASTER

  4. 恢复阶段：原主库根据 AUTO_PRIMARY_RECOVERY 配置自动或手动恢复为备库

6.3 sys_ctl promote 手工切换备库为主库

当自动 failover 失败时，可手动操作：

复制代码 
# 在备库执行
sys_ctl promote -D /home/kingbase/cluster/ks_cluster/db/data

升主后需更新 kingbasecluster 的节点角色：

复制代码 
/home/kingbase/cluster/ks_cluster/kingbasecluster/bin/pcp_promote_node \
  -U kingbase -h 127.0.0.1 -p 9898 -n [备库节点ID]

第七章 故障自动恢复机制

7.1 AUTO_PRIMARY_RECOVERY 配置

值 说明 行为
0（默认） 不自动恢复原主库 failover 后原主库需人工介入恢复为备库
1 自动恢复原主库 failover 后 crond 定时任务自动执行 network_rewind.sh 将原主库恢复为备库

7.2 自动恢复流程（AUTO_PRIMARY_RECOVERY=1）

  1. failover 切换完成，备库升为新主库

  2. 原主库的 crond 定时任务检测到本节点数据库已停止且无 recovery.conf

  3. 执行 network_rewind.sh：

    • 检查本节点 data 目录状态

    • 使用 sys_rewind 同步数据与新主库一致

    • 配置 recovery.conf（指向新主库）

    • 删除 recovery.done（如存在）

    • 启动数据库为备库

    • 通过 pcp_attach_node 在 kingbasecluster 中注册节点

7.3 crond 定时任务

V8R3 集群通过 crond 定时任务实现自动守护：

复制代码 
cat /etc/cron.d/KINGBASECRON
# 内容示例：
*/1 * * * * kingbase /home/kingbase/cluster/ks_cluster/db/bin/network_rewind.sh
*/1 * * * * kingbase /home/kingbase/cluster/ks_cluster/db/bin/restartcluster.sh
定时任务 功能
network_rewind.sh 检测故障节点并自动恢复（sys_rewind + recovery.conf + pcp_attach_node）
restartcluster.sh 检测 kingbasecluster 服务状态并自动重启

7.4 watchdog 守护机制

功能 实现方式
pgpool 生命检测 发送查询到 kingbaseES 检查响应
watchdog 互监控 heartbeat（9000端口）交换状态信息
VIP 自动管理 watchdog MASTER 持有 Cluster VIP，切换时自动漂移
备用服务器自动注册 恢复的节点自动注册为 STANDBY

第八章 手动故障恢复操作

8.1 故障节点重新加入集群（pcp_attach_node）

当节点流复制正常但 show pool_nodes 显示 status 为 down 时：

复制代码 
/home/kingbase/cluster/ks_cluster/kingbasecluster/bin/pcp_attach_node \
  -U kingbase -h 127.0.0.1 -p 9898 -n [节点ID]

前置条件：

  • 该节点数据库服务正常在线（sys_ctl status -D $data_path 返回 running）

  • 流复制连接正常

操作步骤：

  1. 确认节点数据库在线：sys_ctl status -D $data_path

  2. 执行 pcp_attach_node 重新注册节点

  3. 验证：show pool_nodes 确认 status 变为 up

8.2 原主库手动恢复为备库

当 AUTO_PRIMARY_RECOVERY=0 或自动恢复失败时：

步骤 1：停止原主库数据库

复制代码 
sys_ctl stop -D $data_path

步骤 2：配置 recovery.conf（在 data 目录下创建）

复制代码 
standby_mode='on'
primary_conninfo='port=54321 host=新主库IP user=SYSTEM password=12345678ab application_name=node1'
recovery_target_timeline='latest'
primary_slot_name='slot_node1'   # 填写新主库上未使用的复制槽名称

步骤 3：删除 recovery.done（如存在）

复制代码 
rm -f $data_path/recovery.done

步骤 4：使用 sys_rewind 同步数据（如原主库曾启动过且与新主库数据分歧）

复制代码 
sys_rewind -D $data_path \
  --source-server="host=新主库IP port=54321 user=SYSTEM dbname=TEST"

步骤 5：启动备库

复制代码 
sys_ctl start -D $data_path

步骤 6：注册到 kingbasecluster

复制代码 
pcp_attach_node -U kingbase -h 127.0.0.1 -p 9898 -n [原主库节点ID]

步骤 7：验证

复制代码 
# 查看集群状态
ksql -USYSTEM -dTEST -p9999 -c "show pool_nodes"
​
# 查看流复制
ksql -USYSTEM -dTEST -p54321 -c "select * from sys_stat_replication;"

8.3 备库完全重建（rejoin/rewind 失败时）

如果 sys_rewind 无法完成同步，需从主库重新克隆备库：

复制代码 
# 停止备库
sys_ctl stop -D $data_path
​
# 清理备库 data 目录（先备份！）
cp -r $data_path $data_path_bak
rm -rf $data_path/*
​
# 从主库克隆数据（使用 sys_basebackup 或 pg_basebackup）
sys_basebackup -h 新主库IP -U SYSTEM -D $data_path -X stream -P -R
​
# 或使用 recovery.conf 手动配置后启动

8.4 脑裂处理

识别 ：show pool_nodes 出现两个或多个 primary 节点

处理步骤：

  1. 判断哪个节点数据最新：

    • 运行中查 LSN：select sys_current_wal_lsn();

    • 运行中查时间线：select timeline_id from sys_control_checkpoint();

    • 停机状态：sys_controldata -D $data_path 查看 Latest checkpoint's TimeLineID

  2. 以数据最新节点为真正主库

  3. 停止其他"假主库"：

复制代码 
sys_ctl stop -D $data_path

  1. 将"假主库"恢复为备库（参照 [8.2 原主库手动恢复](#8.2 原主库手动恢复)）

  2. 通过 pcp_attach_node 重新注册

  3. 验证集群仅有一个 primary

8.5 全节点故障恢复

复制代码 
# 一键启动集群
sh kingbase_monitor.sh start

验证：

复制代码 
ksql -USYSTEM -dTEST -p9999 -c "show pool_nodes"

若出现双主：参照脑裂处理流程。

第九章 故障场景与处理方案

9.1 主库故障

故障类型 集群应对行为 业务影响 恢复方案
主库停库 health_check 检测主库不可用，watchdog 触发 failover，备库升主，VIP 漂移 切换期间业务中断 AUTO_PRIMARY_RECOVERY=1：自动恢复；=0：手动参照 8.2
主库掉电/系统崩溃 同主库停库 同主库停库 服务器恢复后启动集群
主库进程被杀 kingbasecluster health_check 检测到不可用，触发 failover 切换期间业务中断 crond 定时任务自动拉起或手动恢复
主库 hang 住 所有进程 hang：health_check 超时后触发 failover；仅主进程 hang：新建连接异常 新建连接异常或业务中断 重启主库或执行 switchover

9.2 备库故障

故障类型 集群应对行为 业务影响 恢复方案
备库停库/掉电 kingbasecluster 将备库从 pool 中 detach，读请求路由到主库 读性能下降 备库恢复后 pcp_attach_node 注册
备库网络中断 同备库停库 读性能下降 网络恢复后自动或手动恢复
同步备库故障 主库同步转异步继续运行 数据同步延迟 备库恢复后流复制自动重建

9.3 网络类故障

故障类型 集群应对行为 业务影响
主节点网络中断 ping 信任网关失败→关闭主库；备库 ping 网关正常→failover 升主 切换期间中断
网络丢包 10% 基本无影响 无
网络丢包 30% 可能触发 failover 集群可能无法服务
网络分区 可能出现脑裂 多主
网关失联 所有节点 ping 网关失败→watchdog 不执行 failover 集群失去自动切换能力

9.4 资源耗尽类故障

故障类型 集群应对行为 业务影响
数据盘满 内核可能 core，需人工介入 可能无法恢复
连接满 kingbasecluster 新连接失败 新建连接报错
磁盘 IO 高 响应低 响应低
CPU/内存高 响应低 响应低

第十章 VIP管理

10.1 双 VIP 机制

V8R3 集群管理两种 VIP：

VIP 类型 说明 跟随对象 配置位置
DB VIP 数据库服务 VIP，应用连接数据库使用 跟随 primary 节点漂移 HAmodule.conf db_vip
Cluster VIP 集群管理 VIP，应用连接中间件使用 跟随 watchdog MASTER 漂移 HAmodule.conf cluster_vip / kingbasecluster.conf delegate_IP

10.2 VIP 自动管理

  • DB VIP：由 es_ha_model 脚本管理，failover 时自动从原主卸载并加载到新主

  • Cluster VIP：由 watchdog 管理，watchdog MASTER 持有，切换时自动漂移

10.3 VIP 手动管理

复制代码 
# 加载 VIP
ip addr add ${VIP}/${MASK} dev ${DEV} label ${DEV}:3
​
# 卸载 VIP
ip addr del ${VIP}/${MASK} dev ${DEV}
​
# 发送 arping 通知
arping -U ${VIP} -w 2 -c 2 -i ${DEV}

10.4 VIP 加载故障排查

原因 1：ip/arping 权限不足

复制代码 
# 解决方案
chown root.root /sbin/ip && chmod 4755 /sbin/ip
chown root.root ${cluster_path}/kingbasecluster/bin/arping && chmod 4755 ${cluster_path}/kingbasecluster/bin/arping

原因 2：arping_path 配置错误

复制代码 
# 错误：参数名应为 arping_path 而非 arping
# kingbasecluster.conf 或 HAmodule.conf 中
arping='/home/kingbase/.../bin'        # ❌ 错误
arping_path='/home/kingbase/.../bin'   # ✅ 正确

原因 3：HAmodule.conf 中 DEV 变量为空

复制代码 
# 检查并修改 HAmodule.conf
DEV="eth0"    # 必须指定网卡名称

原因 4：中文 locale 问题（OpenEuler/kylin）

复制代码 
# ping 返回中文"已接收"而非"received"，脚本 grep 英文关键词匹配失败
# 解决方案：在脚本开头添加
export LANG=C

第十一章 在线扩缩容

11.1 添加备库节点

操作步骤：

  1. 修改 kingbasecluster.conf：添加新的 backend 配置段（如 backend_hostname2 等）

  2. 修改 HAmodule.conf（db/etc/ 和 kingbasecluster/etc/ 两处）：

    • 更新节点数量配置

    • 添加新节点信息

  3. 备库配置 crond 定时任务：

复制代码 
# /etc/cron.d/KINGBASECRON
*/1 * * * * kingbase /home/kingbase/cluster/ks_cluster/db/bin/network_rewind.sh
*/1 * * * * kingbase /home/kingbase/cluster/ks_cluster/db/bin/restartcluster.sh

  1. 重启 kingbasecluster 服务使配置生效

  2. 验证 ：show pool_nodes 确认新节点已加入

11.2 删除备库节点

  1. 修改 kingbasecluster.conf 移除对应 backend 配置段

  2. 修改 HAmodule.conf 移除对应节点信息

  3. 重启 kingbasecluster 服务

  4. 主库清理残留复制槽：

复制代码 
SELECT sys_drop_replication_slot('slot_name');

⚠️ 不能直接删除主库节点，需先 switchover 切换为主备后再删除

第十二章 参数调整与配置变更

12.1 kingbasecluster.conf 修改

修改后需重启 kingbasecluster 服务：

复制代码 
# 停止
/home/kingbase/cluster/ks_cluster/kingbasecluster/bin/kingbasecluster stop
​
# 启动（需 root 权限）
/home/kingbase/cluster/ks_cluster/kingbasecluster/bin/kingbasecluster start

12.2 HAmodule.conf 修改

修改后需同步修改 db/etc/HAmodule.conf 和 kingbasecluster/etc/HAmodule.conf 两处，保持一致。

12.3 数据库配置修改

  • 需重启生效的参数：修改 kingbase.conf 后重启数据库或集群

  • 不需要重启的参数 ：sys_ctl -D $data_path reload

12.4 同步模式调整

修改 kingbase.conf 中的 synchronous_standby_names 参数：

复制代码 
# 同步模式
synchronous_standby_names = '1 (node2)'
​
# 优选同步模式（推荐）
synchronous_standby_names = 'ANY 1(node2,node3)'
​
# 异步模式
synchronous_standby_names = ''

修改后需 reload 或重启数据库。

第十三章 常见故障FAQ

13.1 kingbase_monitor.sh 启动失败 --- pam_nologin 错误

现象 ：启动集群时提示 pam_nologin(8) 错误

原因：/etc/nologin 文件存在，PAM 模块阻止非 root 用户登录

解决：

复制代码 
rm /etc/nologin

13.2 OpenEuler/kylin 系统 kingbasecluster 无法启动

现象：kingbasecluster 启动失败，日志显示 ping 网关失败，但手工 ping 正常

原因：系统返回中文提示"已接收"而非"received"，脚本 grep 英文关键词匹配失败

解决 ：在脚本开头添加 export LANG=C

13.3 VIP 加载失败 --- ip/arping 权限不足

现象 ：[ERROR] No execute permission for "/usr/sbin/ip" 或 arping

解决：

复制代码 
chown root.root /sbin/ip && chmod 4755 /sbin/ip
chown root.root ${cluster_path}/kingbasecluster/bin/arping && chmod 4755 ${cluster_path}/kingbasecluster/bin/arping

13.4 VIP 加载失败 --- arping_path 配置错误

现象 ：failover 切换 VIP 加载超时，日志提示 arping unknown paramName

原因 ：kingbasecluster.conf 或 HAmodule.conf 中参数名写为 arping 而非 arping_path

解决 ：修正为 arping_path

13.5 VIP 加载失败 --- DEV 变量为空

现象 ：手工执行 sh -x change_vip.sh 发现 DEV 变量为空

原因：HAmodule.conf 中 DEV 未赋值

解决 ：在所有 HAmodule.conf 文件中给 DEV 指定网卡名称：DEV="eth0"

13.6 failover 切换后节点均处于 standby

现象：show pool_nodes 显示两个节点均为 standby，无流复制

处理：

  1. 先解决流复制：配置 recovery.conf → 启动原主库为备库 → 确认流复制正常

  2. 更新集群状态：在主备节点分别执行 pcp_attach_node

  3. 验证 show pool_nodes

13.7 esHAmodel.sh 脚本错误

现象：V8R3 集群启动 esHAmodel.sh 失败

排查：检查脚本执行权限、环境变量、路径配置、LANG 设置

13.8 集群名称不能使用 "cluster"

现象：部署时集群名称设为 "cluster" 导致异常

解决：使用其他名称如 ks_cluster

13.9 防火墙导致 show pool_nodes 信息错误

解决：关闭防火墙或开放所有集群相关端口（54321/9999/9898/9000）

13.10 pcp_node_refresh 误触发 failover

⚠️ pcp_node_refresh 会将指定节点踢出并重新加入集群。对主库执行此命令会导致主备切换！

13.11 DATA_SIZE_DIFF 告警

现象：集群启动时报 DATA_SIZE_DIFF 超过阈值

排查：检查 sys_stat_replication 中的 lsn_lag，确认主备数据差异

13.12 libssl 问题

现象：kingbasecluster 启动报 libssl 相关错误

排查：检查 OpenSSL 库版本兼容性

13.13 crond 定时任务 PID 文件问题

现象：restartcluster.sh 无法正常启动 kingbasecluster

原因：某次启动异常创建了有问题的 pid 文件，后续定时任务读取 pid 文件时出错

解决：清理残留 pid 文件后重新启动

13.14 旧主库未自动拉起（V8R3特有）

现象：failover 后旧主库未自动加入集群

解决：

  1. 在旧主库 data 目录创建 recovery.conf（参考 8.2节）

  2. 删除 recovery.done（如存在）

  3. 等待约1分钟，旧主库自动拉起为备库

第十四章 运维禁令与注意事项

🚫 禁令一：禁止直接在备库写数据

必须通过 9999 端口（kingbasecluster 中间件）或连接主库 54321 端口写入。备库为只读，直接写会导致数据不一致。

🚫 禁令二：禁止单节点修改配置

修改 kingbasecluster.conf 或 HAmodule.conf 后，必须在所有节点同步修改，避免角色切换后配置不一致。

⚠️ HAmodule.conf 需同步修改 db/etc/ 和 kingbasecluster/etc/ 两处

🚫 禁令三：禁止心跳网络不稳定

确保节点间 heartbeat 网络（9000端口）稳定，否则会引发脑裂导致 VIP 冲突。

🚫 禁令四：禁止对主库执行 pcp_node_refresh

对主库执行 pcp_node_refresh 会导致 failover 切换！

🚫 禁令五：禁止集群中缩小 max_connections

集群中 max_connections 只能调大不能调小。

⚠️ 注意一：归档目录不能写满

归档目录写满会导致主库停止服务。

⚠️ 注意二：kingbasecluster 启动需 root 权限

watchdog 进程需要控制 VIP 接口，kingbasecluster 启动必须拥有管理员权限。

⚠️ 注意三：trusted_servers 不要配置节点 IP

信任网关应配置网关 IP（如交换机 IP），不要配置数据库节点 IP 或 127.0.0.1。

⚠️ 注意四：recovery.conf 是 V8R3 备库标识

V8R3 使用 recovery.conf（而非 standby.signal）标识备库。备库 data 目录必须存在此文件，主库 data 目录应有 recovery.done。

第十五章 运维工具箱

任务 常用工具/命令
查看集群节点状态 ksql -USYSTEM -dTEST -p9999 -c "show pool_nodes"
查看 watchdog 状态 pcp_watchdog_info -h 127.0.0.1 -p 9898 -U kingbase
查看节点详细信息 pcp_node_info -h 127.0.0.1 -p 9898 -U kingbase -n [节点ID]
挂载被隔离节点 pcp_attach_node -U kingbase -h 127.0.0.1 -p 9898 -n [节点ID]
脱离节点 pcp_detach_node -U kingbase -h 127.0.0.1 -p 9898 -n [节点ID]
强制升主节点 pcp_promote_node -U kingbase -h 127.0.0.1 -p 9898 -n [节点ID]
手工升主备库 sys_ctl promote -D $data_path
查看当前连接数 select count(*) from sys_stat_activity;
查看长事务 select pid, state, query_start from sys_stat_activity where state<>'idle';
查看流复制状态 select * from sys_stat_replication;
查看复制槽 select * from sys_replication_slots;
查看复制延迟 select case when sys_last_wal_receive_lsn()=sys_last_wal_replay_lsn() then 0 else EXTRACT(EPOCH FROM now()-sys_last_xact_replay_timestamp()) end;
杀长事务 select sys_terminate_backend(pid);
查看数据库进程 `ps -ef
查看 kingbasecluster 进程 `ps -ef
查看 watchdog 进程 `ps -ef
一键启停集群 kingbase_monitor.sh start / stop / restart
手工启停中间件 kingbasecluster start / stop
全节点状态检查 all_monitor.sh
sys_rewind 同步 sys_rewind -D $data_path --source-server="host=新主IP port=54321 user=SYSTEM dbname=TEST"
检查 crond 定时任务 cat /etc/cron.d/KINGBASECRON

附录A V8R3与V8R6+架构差异对照

项目 V8R3 V8R6+
中间件 kingbasecluster（Pgpool-II） 无中间件（直连数据库）
HA组件 watchdog + es_ha_model/HAmodule.conf repmgrd + kbha
核心配置文件 kingbasecluster.conf + HAmodule.conf repmgr.conf
备库标识文件 recovery.conf standby.signal
服务端口 9999（中间件）+ 54321（DB） 54321（DB直连）
节点管理命令 pcp 命令集 + show pool_nodes repmgr 命令集
自动恢复配置 AUTO_PRIMARY_RECOVERY（HAmodule.conf） recovery 参数（repmgr.conf）
备库恢复方式 crond 定时任务 + network_rewind.sh repmgrd 进程监控 + kbha 进程
集群启停脚本 kingbase_monitor.sh sys_monitor.sh
VIP管理 watchdog（if_up_cmd/if_down_cmd）+ es_ha_model kbha 进程
读写分发方式 kingbasecluster 中间件自动路由 JDBC 驱动级路由
双VIP机制 DB VIP + Cluster VIP 单 VIP
watchdog选举 heartbeat 通讯 + MASTER/STANDBY repmgrd 竞选

附录B 故障判断与恢复命令速查表

故障判断命令

编号 命令 用途
FC-1 ksql -USYSTEM -dTEST -p9999 -c "show pool_nodes" 看集群节点状态
FC-2 pcp_watchdog_info -h 127.0.0.1 -p 9898 -U kingbase 看 watchdog 状态
FC-3 `ps -ef grep kingbasecluster`
FC-4 `ps -ef grep kingbase`
FC-5 `ps -ef grep watchdog`
FC-6 ls $data_path/recovery.conf / ls $data_path/recovery.done 判断主备角色
FC-7 ksql -h 主库IP -U SYSTEM -d TEST -c "select * from sys_stat_replication;" 看流复制状态
FC-8 sys_ctl status -D $data_path 看数据库运行状态

故障恢复命令

编号 命令 用途
FR-1 select sys_current_wal_lsn(); / select timeline_id from sys_control_checkpoint(); 多主判断真正主库
FR-2 kingbase_monitor.sh start 全节点故障一键启动
FR-3 pcp_attach_node -U kingbase -h 127.0.0.1 -p 9898 -n [ID] 被隔离节点重新注册
FR-4 配置 recovery.conf + sys_rewind + sys_ctl start + pcp_attach_node 原主库手动恢复为备库
FR-5 show pool_nodes + sys_stat_replication 恢复后验证

附录C 参数配置速查表

kingbasecluster.conf 关键参数

类别 参数 建议值 说明
Backend backend_hostname0/1 主/备库IP 后端节点IP
Backend backend_port0/1 54321 数据库端口
Backend backend_weight0/1 1 负载均衡权重
Backend backend_flag0 DISALLOW_TO_FAILOVER 主库禁止自动failover
Backend backend_flag1 ALLOW_TO_FAILOVER 备库允许failover
Health health_check_period 10 健康检查间隔（秒）
Health health_check_timeout 20 健康检查超时（秒）
Health health_check_max_retries 10 最大重试次数
Health health_check_retry_delay 20 重试间隔（秒）
Health health_check_user SYSTEM 健康检查用户
Watchdog use_watchdog on 激活看门狗
Watchdog trusted_servers 网关IP 信任网关列表
Watchdog wd_interval 10 生命检查间隔
Watchdog wd_life_point 3 失败重试次数
Watchdog delegate_IP Cluster VIP 集群VIP
Watchdog wd_port 9000 heartbeat端口
Failover failover_mode automatic 自动故障切换
连接池 num_init_children 16 连接池进程数
连接池 max_pool 4 每进程最大连接池

HAmodule.conf 关键参数

参数 建议值 说明
AUTO_PRIMARY_RECOVERY 1（生产推荐） failover后自动恢复原主库
db_vip 如 192.192.103.183 数据库VIP
cluster_vip 如 192.192.103.185 集群VIP（=delegate_IP）
trust_ip 网关IP 信任网关
DEV eth0 VIP绑定网卡
db_port 54321 数据库端口
ifconfig_path /sbin ifconfig路径
arping_path /usr/sbin 或集群bin arping路径
ping_path /bin ping路径

数据库 kingbase.conf 关键参数

参数 建议值 说明
wal_level replica 主备最低要求
full_page_writes on 防坏块
wal_log_hints on sys_rewind前提
hot_standby on 备库可读
synchronous_commit remote_apply 数据强一致
max_wal_senders 32 WAL发送进程数
wal_keep_segments 512 WAL保留数
max_connections 使用数×120% 只能调大不能调小
archive_mode on 开启归档
shared_buffers 内存1/3 共享缓冲
tcp_keepalives_idle 2 TCP心跳间隔
wal_sender_timeout 30000 主库检测超时(ms)
wal_receiver_timeout 30000 备库检测超时(ms)
热门推荐
01GitHub 镜像站点02如何新建文件夹？ 电脑新建文件夹的4种方法032026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片04国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）05幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南06AI科技热点日报 | 2026年07月01日07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路082026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新10【解构】DeepSeek V4 发布：技术报告深度解读 + 横向对比六大开源模型，我们的判断是……