单机高可用性

概述

高可用性（High Availability，简称 HA）是指通过技术手段减少因日常维护或突发故障导致的服务中断时间，从而提升系统的整体可用性。KaiwuDB 通过主备复制机制，在单机部署场景下实现高可用能力。

相比多副本集群的高可用功能，主备复制仅需两台服务器即可完成高可用配置，同时保持较高的数据写入性能。

用户可通过配置主备角色，灵活管理主备复制服务的生命周期，包括启动、暂停、恢复和删除等操作。启用主备复制后，主库支持读写操作，备库仅支持读操作，不支持预测分析设置或集群参数配置。

备库发生故障时，主库的读写操作可正常进行，不会影响用户业务。主库发生故障后，用户可手动将备库切换成主库，待主库恢复后重新建立主备关系，也可以将备库转为普通节点，进行数据读写。

KaiwuDB 主备复制实现以下性能目标：

计划内主备切换：恢复时间目标（RTO）< 10 秒，恢复点目标（RPO）= 0（无数据丢失）。
计划外停机主备切换：RTO < 10 秒，RPO < 30 秒。

使用说明：

KaiwuDB 采用异步复制方式，备库数据可能存在一定延迟。
在以下情况下执行主备复制相关操作时，系统响应时间可能较长：
- 主库存在大量历史数据需要复制
- 混合执行 INSERT、DELETE、UPDATE 及 DDL 语句
- 执行跨多表的高并发单条写入操作
当前版本限制：
- 不支持关系数据的主备复制。
- 不支持在三权分立模式下使用主备复制。
- 2.2.1 之前版本如果现有用户数据，升级后使用主备复制可能受影响。建议搭建新版本主备环境，再通过导入导出功能迁移旧版本数据。
- 极小概率出现因单条 DDL 语句复制失败导致主备复制失败，如果遇到此问题请联系 KaiwuDB 技术支持。

基础概念

概念	描述
计划性场景	可预见的业务操作，如软件升级导致的计划性停机或主备切换。
非计划性场景	因软硬件故障引发的突发性停机，如设备断电导致的主库非计划性停机。
恢复时间目标（RTO）	系统从停机恢复到可提供服务的时间。例如，RTO = 0 表示业务不受影响；RTO = 1 分钟表示最长中断 1 分钟。
恢复点目标（RPO）	停机期间可能丢失的数据量（以秒为单位）。例如，RPO = 0 表示无数据丢失；RPO = 1 秒表示最多丢失 1 秒数据。
普通节点（Default）	默认数据库角色，适用于非高可用场景。主库非计划性停机后，备库可切换为普通节点继续提供服务。
主库（Primary）	主备架构中的主节点，支持读写及 DDL 操作。启用主备复制后，系统自动将指定节点设为主库。
备库（Secondary）	主备架构中的备节点，仅支持读，不支持写、DDL、DCL、集群设置或预测分析配置。启用主备复制后，系统自动将指定节点设为备库。主备复制相关操作均需在备库执行。
历史数据	主备初始化前主库现有的数据，包括用户数据、元数据及压缩策略生成的数据。
实时数据	主备关系建立后主库新增的数据，包括用户数据、元数据及压缩数据。
断点续传	主备连接中断后复制暂停，恢复连接时从中断点继续同步的机制。目前仅支持主备切换前的断点续传。

操作流程

主备初始化

主备初始化是建立主备关系的第一步。如果主库中已存在历史数据，需要先完成历史数据迁移，再进行主备初始化。

停机和恢复

停机分为计划性和非计划性停机。

计划性停机包括：

硬件维护和软件升级等不需要更改 IP 地址和端口的计划性停机
更改 IP 地址或端口的计划性停机

非计划性停机通常由网络波动或备库环境不稳定引发。

计划性停机和恢复

执行计划性停机前，用户可根据项目实际情况选择是否将主库设置为只读模式，以确保复制暂停期间无数据写入。

暂停主备复制后，主库会自动进入只读模式，进行历史数据复制，待主备数据达到一致后，解除只读模式，返回操作成功提示。

如果需要更改 IP 地址，在安全部署模式下，如果现有证书中未包含新 IP 地址，用户需要重新生成主备库共享的安全证书，并重启主备库以使证书生效。

不更改 IP 地址:

更改 IP 地址:

非计划性停机和恢复

非计划性停机是指主库或备库发生异常宕机的情况。在大多数非计划性停机场景中，只需重启宕机节点，系统会自动处理主备之间的重连及数据同步，无需执行额外操作。

主库宕机：

当主库发生非计划性宕机时，通常只需重新启动宕机的主库节点，备库会自动重新连接建立主备复制关系。

对于更复杂的情况，用户也可以选择手动将备库提升为新主库，待原主库恢复后重建主备关系；或者将备库转换为独立节点，同时删除主备关系。

注意：如果主库宕机前备库存在数据延迟，主库恢复时，由于主备数据不一致，可能导致主备复制启动失败，主库在宕机前尚未同步至备库的数据将无法保留，存在数据丢失风险。

备库宕机：

备库宕机会导致主备数据复制中断，但主库的读写操作不受影响，业务可以正常进行。最简单的恢复方式是重启备库节点，备库会根据配置的 IP 地址自动尝试重新连接主库并恢复数据同步。

用户也可以选择等待备库自动恢复并重新建立复制关系，或者将主库转为默认独立节点，完全删除主备复制关系。备库恢复后，系统会优先复制停机期间积累的历史数据，在数据同步期间服务可正常运行。

主备切换

主备切换分为计划性和非计划性主备切换：

计划性主备切换适用于以下场景：
- 主库或备库需要进行维护；
- 主库或备库较长时间不可用；
- 为保障业务连续性需要进行主备切换。
非计划性主备切换通常由主库意外停机引发。

计划性主备切换

执行计划性主备切换前，用户需要将主库设置为只读模式，以确保复制暂停期间无数据写入。

主备切换过程中不支持数据写入。在切换过程中如果发生非计划性故障，主备切换可能会失败，且无法回滚到原始的主备关系。

非计划性主备切换

非计划性主备切换通常由主库意外停机引发。用户可将备库手动切换为主库，原主库恢复后可作为新备库加入主备复制，系统将以新主库数据为基础进行断点续传。

删除主备复制

删除主备复制适用于解除主备关系或变更高可用配置的场景。

删除主备复制后，KaiwuDB 将中断主备之间的数据复制，删除相应的元数据。如需恢复主备关系，必须重新进行主备初始化。

主备高可用配置

注意

为避免因资源环境、硬件环境等不一致影响高可用功能的正常运行以及 RTO 和 RPO 时间，建议主库和备库使用相同硬件资源、配置文件和启动命令。
如果采用安全部署模式，主库和备库需要通过以下命令重新生成节点证书，确保主备节点的 IP 共享同一份节点证书。
```
./kwbase cert create-node --certs-dir=<path-to-kaiwudb-certs-dir> --ca-key=<path-to-ca-key> <primary_node_IP> <secondary_node_IP>
```

主备初始化

历史数据迁移

KaiwuDB 推荐使用 rsync 工具进行文件拷贝，以实现历史数据的迁移。rsync 具备高效、灵活和可靠的特点，广泛应用于数据同步与备份场景。

前提条件：

已正确配置主库和备库服务器，且网络连接正常。
已在主库和备库上安装 rsync 工具。
主库和备库的系统版本和 KaiwuDB 版本一致。
备库有足够的存储空间。
当前用户具有主库和备库的访问权限。

步骤：

停止主库和备库：
```
systemctl stop kaiwudb
```
登录主库服务器，使用 rsync 或其他工具拷贝数据文件：
- 推荐：使用校验和方式进行同步，并删除目标目录中多余文件
```
rsync -arzv --checksum --delete /source/data/ user@remote:/target/data/
```
- 不推荐：未使用校验和，也不删除多余文件
```
rsync -arzv /source/data/ user@remote:/target/data/
```

数据复制完成后，校验数据传输是否完整：

rsync -arzv --dry-run /source/data/ user@remote:/target/data/

启动主库和备库：
```
systemctl start kaiwudb
```

启用主备复制

前提条件：

主库和备库网络延迟小于 100 ms。
主库和备库已完成时钟校时，且物理机时间差小于 500 ms。
主库和备库均已启动，且启动命令一致。
如果主库存在历史数据，已完成历史数据迁移。
备库为空库。
用户拥有 admin 权限。

步骤：

登录备库，添加主库地址：
```
REPLICATE SET PRIMARY <primary_url>；
```
参数说明：
- primary_url：主库的连接地址，格式遵循 JDBC 连接协议，支持安全和非安全模式。安全模式下需采用证书认证方式，证书对应地址应为备库证书地址并且要保证主备证书配置一致。
示例：
- 非安全模式：
```
REPLICATE SET PRIMARY postgresql://root@192.168.111.128:26257?sslmode=disable;
```
- 安全模式：
```
REPLICATE SET PRIMARY postgresql://root@localhost:26267/defaultdb?sslmode=verify-ca&sslcert=./certs/client.root.crt&sslkey=./certs/client.root.key&sslrootcert=./certs/ca.crt;
```
创建主备复制：
```
REPLICATE SET SERVICE CREATE;
```
启动主备复制:
```
REPLICATE SET SERVICE START;
```

停机和恢复

计划性停机和恢复

暂停和恢复主备复制

暂停和恢复主备复制适用于硬件维护、软件升级等计划性停机场景。

前提条件：

用户拥有 admin 权限。

步骤：

登录主库，将主库设为只读，以确保复制暂停期间无数据写入：
```
SET CLUSTER SETTING default_transaction_read_only.enabled = true;
```
在备库停止主备复制：
```
REPLICATE SET SERVICE STOP;
```
完成硬件维护、软件升级后，在备库启动主备复制：
```
REPLICATE SET SERVICE START;
```

登录主库，解除只读模式：

SET CLUSTER SETTING default_transaction_read_only.enabled = false;

更改 IP 地址的停机和恢复

更改主库 IP 地址

前提条件：

用户拥有 admin 权限。

步骤：

登录主库，将主库设置为只读模式，以确保复制暂停期间无数据写入：
```
SET CLUSTER SETTING default_transaction_read_only.enabled = true;
```
在备库停止主备复制：
```
REPLICATE SET SERVICE STOP;
```
（可选）如果采用安全部署模式，检查是否需要更新节点证书：
1. 检查现有节点证书是否已包含新 IP 地址。
```
./kwbase cert list --certs-dir=./certs
```
2. 如已包含，可跳过以下子步骤。
3. 如未包含，需删除现有节点证书并创建新证书：
  - 删除现有节点证书：
```
rm certs/node.key certs/node.crt 
```
  - 为主库和备库重新生成节点证书：
```
./kwbase cert create-node <primary_node> <secondary_node> [<other_ip> ...] --certs-dir=./certs --ca-key=./certs/ca.key
```
重启主库，在 ./kwbase start 启动命令中指定新 IP 地址并加载更新后的证书（如需要）。
（可选）如需更新节点证书，通过 ./kwbase start 启动命令重启备库，加载更新后的证书。
登录备库，设置主库新地址，恢复主备复制：
1. 设置主库新地址：
```
REPLICATE SET PRIMARY <primary_URL>;
```
2. 启动主备复制：
```
REPLICATE SET SERVICE START;
```

登录主库，解除只读模式：

SET CLUSTER SETTING default_transaction_read_only.enabled = false;

更改备库 IP 地址

前提条件：

用户拥有 admin 权限。

步骤：

登录主库，将主库设置为只读模式，以确保复制暂停期间无数据写入：
```
SET CLUSTER SETTING default_transaction_read_only.enabled = true;
```
在备库停止主备复制：
```
REPLICATE SET SERVICE STOP;
```
（可选）如果采用安全部署模式，检查是否需要更新节点证书：
1. 检查现有节点证书是否已包含新 IP 地址。
```
./kwbase cert list --certs-dir=./certs
```
2. 如已包含，可跳过以下子步骤。
3. 如未包含，需删除现有节点证书并创建新证书：
  - 删除现有节点证书：
```
rm certs/node.key certs/node.crt 
```
  - 为主库和备库重新生成节点证书：
```
./kwbase cert create-node <primary_node> <secondary_node> [<other_ip> ...] --certs-dir=./certs --ca-key=./certs/ca.key
```
重启备库，在 ./kwbase start 启动命令中指定新 IP 地址并加载更新后的证书（如需要）。
（可选）如需更新节点证书，通过 ./kwbase start 启动命令重启主库，加载更新后的证书。
登录备库，启动主备复制：
```
REPLICATE SET SERVICE START;
```

登录主库，解除只读模式：

SET CLUSTER SETTING default_transaction_read_only.enabled = false;

非计划性停机后恢复

大多数非计划性停机情况下，用户只需重启宕机节点，系统会自动处理主备重连及数据同步，无需额外操作。

如果主库持续无法恢复，也可以选择以下处理方式：

将备库提升为新主库：待原主库恢复后重建主备关系，具体操作可参见非计划性主备切换。注意：如果主库宕机前备库存在数据延迟，主库恢复时，由于主备数据不一致，可能导致主备复制启动失败。如果主库宕机时主备数据保持一致，主库恢复后可作为备库重新加入。
将备库转为独立节点：删除主备服务关系，具体操作可参见删除主备复制。

如果备库持续无法恢复，用户也可以执行以下命令，将主库转为默认节点：

REPLICATE SET ROLE DEFAULT;

主备切换

计划性主备切换

前提条件：

用户拥有 admin 权限。

步骤：

登录主库，将主库设置为只读模式，以确保复制暂停期间无数据写入：
```
SET CLUSTER SETTING default_transaction_read_only.enabled = true;
```

登录备库，将备库设为主库：

暂停主备服务：
```
REPLICATE SET SERVICE STOP;
```
将备库设为主库：
```
REPLICATE SET ROLE PRIMARY;
```

启用 WAL 日志功能：

SET cluster setting ts.wal.flush_interval='0';

解除只读模式：

SET CLUSTER SETTING default_transaction_read_only.enabled = false;

登录原主库，将原主库设置为备库：

将原主库设置为备库：
```
REPLICATE SET ROLE SECONDARY;
```

关闭 WAL 日志功能：

SET cluster setting ts.wal.flush_interval='-500ms';

设置只读模式：

SET CLUSTER SETTING default_transaction_read_only.enabled = true;

启动主备服务：
```
REPLICATE SET SERVICE START;
```

非计划性主备切换

前提条件：

用户拥有 admin 权限。

步骤：

登录备库，将备库设为主库：

将备库设为主库：
```
REPLICATE SET ROLE PRIMARY;
```

启用 WAL 日志功能：

SET cluster setting ts.wal.flush_interval='0';

解除只读模式：

SET CLUSTER SETTING default_transaction_read_only.enabled = false;

（可选）待原主库恢复后，恢复主备关系：

登录原主库，设为备库：
```
REPLICATE SET ROLE SECONDARY;
```

关闭 WAL 日志功能：

SET cluster setting ts.wal.flush_interval='-500ms';

设置只读模式：

SET CLUSTER SETTING default_transaction_read_only.enabled = true;

启动主备服务：
```
REPLICATE SET SERVICE START;
```

删除主备复制

前提条件：

用户拥有 admin 权限。

步骤：

登录备库，停止主备服务：
```
REPLICATE SET SERVICE STOP;
```
将备库设为默认节点：
```
REPLICATE SET ROLE DEFAULT;
```
删除主备服务：
```
REPLICATE SET SERVICE DROP;
```

（可选）验证备库是否已转为默认节点：

SELECT role,status FROM system.kwdb_replication_info ORDER BY address;

（可选）如需提供对外服务，启用 WAL 日志功能，解除只读模式：
1. 启用 WAL 日志功能：
```
SET cluster setting ts.wal.flush_interval='0';
```
2. 解除只读模式：
```
SET CLUSTER SETTING default_transaction_read_only.enabled = false;
```

监控

查看备库最近 100 条数据延迟

KaiwuDB 支持通过 SQL 语句查看备库最近 100 条数据的延迟。

前提条件：

用户拥有 admin 权限。

步骤：

登录备库，查看备库最近 100 条数据的延迟情况：
```
SELECT * FROM kwdb_internal.stat_replication;
```
返回字段说明：
- sent_lsn：WAL 发送进程最近发送的日志位置。
- active_addr：主库 IP。
- standby_addr：备库 IP。
- state：WAL 发送状态：
  - startup：落盘中
  - catchup：备库追赶中
  - streaming：备库已追上。
- apply_lag：主库 WAL 日志应用时间。
- write_lag：主库 WAL 发送至备库且备库确认的时间。
- flush_lag：备库写入 WAL 日志成功的时间。
- replay_lag：备库回放完成数据的时间。此时在备库可以查询到复制过来的数据。
- sync_state：同步状态（async 表示异步同步）。

查看后台主备复制任务

前提条件：

用户拥有 admin 权限。

步骤：

查看后台运行的主备复制任务：

SELECT * FROM [SHOW JOBS] WHERE job_type = 'REPLICATION STREAM';

故障排查

常见故障信息

故障信息	描述	建议措施
`Replication Error: no connection to the server`	无法连接指定的 URL	检查主库地址是否正确
`Replication Error: not allow primary set primary address`	主库不支持设置相关地址	需在备库或默认节点设置主库地址
`ReplicationSetError: replication set role failed`	当前角色与设置角色不匹配	检查角色配置是否正确
`ReplicationSetError: secondary access failed`	主库访问备库失败	检查网络或备库状态
`ReplicationSetError: Replication CREATE failed`	创建主备复制失败	根据具体错误检查主备信息
`ReplicationSetError: Replication START failed`	启动主备复制失败	根据具体错误检查主备信息
`ReplicationSetError: Replication STOP failed`	停止主备复制失败	根据具体错误检查主备信息
`ReplicationSetError: Replication DROP failed`	删除主备复制失败	根据具体错误检查主备信息
`ReplicationSetError: replication is already running`	主备复制已启动	无需操作

故障定位

主备初始化失败

根据报错检查：

主库地址和格式是否正确。
备库是否为非空数据库。
主库是否存在未清除的旧主备信息。
主库或备库角色是否为非默认角色。

主备复制中断

前提条件：

用户拥有 admin 权限。

步骤：

分别登录主库和备库，执行以下命令，检查主备高可用状态：
```
SELECT * FROM system.kwdb_replication_info;
```
返回字段说明：
- cluster_id：节点 ID（主键）。
- address：节点地址。
- role：节点角色（0：Default；1：Primary；2：Secondary）。
- status：高可用状态（0：终止；1：运行中；2：暂停）。
- consistency_map：一致性信息（<表 ID，lsn> 序列化）。
- last_update：一致性对齐时间。
如果状态异常，检查主备通信网络。

# 单机高可用性

# 概述

# 基础概念

# 操作流程

# 主备初始化

# 停机和恢复

# 计划性停机和恢复

# 非计划性停机和恢复

# 主备切换

# 计划性主备切换

# 非计划性主备切换

# 删除主备复制

# 主备高可用配置

# 主备初始化

# 历史数据迁移

# 启用主备复制

# 停机和恢复

# 计划性停机和恢复

# 暂停和恢复主备复制

# 更改 IP 地址的停机和恢复

# 更改主库 IP 地址

# 更改备库 IP 地址

# 非计划性停机后恢复

# 主备切换

# 计划性主备切换

# 非计划性主备切换

# 删除主备复制

# 监控

# 查看备库最近 100 条数据延迟

# 查看后台主备复制任务

# 故障排查

# 常见故障信息

# 故障定位

# 主备初始化失败

# 主备复制中断

单机高可用性

概述

基础概念

操作流程

主备初始化

停机和恢复

计划性停机和恢复

非计划性停机和恢复

主备切换

计划性主备切换

非计划性主备切换

删除主备复制

主备高可用配置

主备初始化

历史数据迁移

启用主备复制

停机和恢复

计划性停机和恢复

暂停和恢复主备复制

更改 IP 地址的停机和恢复

更改主库 IP 地址

更改备库 IP 地址

非计划性停机后恢复

主备切换

计划性主备切换

非计划性主备切换

删除主备复制

监控

查看备库最近 100 条数据延迟

查看后台主备复制任务

故障排查

常见故障信息

故障定位

主备初始化失败

主备复制中断