文档下载建议反馈入口

  • 概述
  • 基础概念
  • 操作流程
    • 主备初始化
    • 停机和恢复
    • 主备切换
    • 删除主备复制
  • 主备复制配置
    • 主备初始化
    • 停机和恢复
    • 主备切换
    • 删除主备复制
  • 监控
    • 查看备库最近 100 条数据延迟
    • 查看后台主备复制任务
  • 故障排查
    • 常见故障信息
    • 故障定位

单机高可用性

概述

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

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

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

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

KaiwuDB 主备复制支持完整的关系数据复制和时序数据复制，包括：

  • 显示/隐式事务场景
  • DDL/DML 混合场景
  • prepare/非 prepare 场景
  • 通过 JDBC 协议写入的数据

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

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

使用说明：

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

特殊场景说明：

  • 导入导出复制：导入导出的复制要求主库和备库的导入导出路径保持一致。如果主备库导入导出位置不同，需按以下顺序操作：

    1. 停止复制进程
    2. 将 CSV 文件复制到备库的导入导出目录
    3. 在主库执行导入数据操作
    4. 重新启动复制进程

  • 随机函数复制：主库执行包含 random() 函数的插入操作时，备库会重新生成随机数据，而不是复制主库生成的随机值，导致主备库数据不一致。建议在需要保持主备一致的场景中避免使用随机函数。

  • 物化视图并发写入：在创建物化视图过程中，如果对原始表进行并发的 INSERT 操作，可能导致主备库物化视图数据不一致。此时需要在主库手动执行物化视图刷新以确保主备一致：

    -- 在主库执行刷新语句保证主备一致
REFRESH MATERIALIZED VIEW [IF EXISTS] <view_name>;

基础概念

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

操作流程

主备初始化

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

img

停机和恢复

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

计划性停机包括：

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

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

计划性停机和恢复

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

停止主备复制后，主库会先进行历史数据复制，待主备数据达到一致后，返回操作成功提示。

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

不更改 IP 地址:

img

更改 IP 地址:

img

非计划性停机和恢复

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

主库宕机：

当主库发生非计划性宕机时，用户可选择以下恢复策略：

  • 重启恢复（推荐优先尝试）：重新启动原主库节点，备库会自动重新连接
  • 主备切换：手动将备库提升为新主库，适用于主库长时间无法恢复的情况
  • 转为独立节点：将备库转换为普通节点，删除主备关系

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

img

备库宕机：

备库宕机会导致主备数据复制中断，但主库的读写操作不受影响，业务可以正常进行。恢复策略包括：

  • 重启备库（推荐）：重启备库节点，系统会自动重新建立复制关系
  • 等待自动恢复：备库会根据配置的 IP 地址自动尝试重新连接主库
  • 转换为独立节点：将主库转为默认独立节点，删除主备复制关系

备库恢复后，系统会优先复制停机期间积累的历史数据，在数据同步期间服务可正常运行。如果备库故障期间主库写入了大量数据，可能存在少量数据丢失或者不一致问题。

img

主备切换

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

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

计划性主备切换

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

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

img

非计划性主备切换

非计划性主备切换通常由主库意外停机引发。用户可将备库手动切换为主库，原主库恢复后可作为新备库加入主备复制，系统将以新主库数据为基础进行断点续传。如果新主库在原主库停机期间写入大量数据，则需要先进行历史数据迁移，待数据一致后重新建立主备复制关系。

img

删除主备复制

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

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

img

主备复制配置

注意

  • 为避免因资源环境、硬件环境等不一致影响高可用功能的正常运行以及 RTO 和 RPO 时间，建议主库和备库使用相同硬件资源、配置文件和启动命令。

  • 为保证主备复制的可用性，需要对主备物理机进行时钟校时，要求主备物理机时间差不大于 500ms。

  • 网络延迟应不超过 100ms。

  • 如果采用安全部署模式，主库和备库需要通过以下命令重新生成节点证书，确保主备节点的 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 版本一致。
  • 备库有足够的存储空间。
  • 当前用户具有主库和备库的访问权限。

步骤：

  1. 停止备库：

    systemctl stop kaiwudb

  2. 首次数据同步：登录主库服务器，使用 rsync 或其他工具将历史数据文件拷贝到备库数据目录：

    • 推荐：使用校验和方式进行同步，并删除目标目录中多余文件

      rsync -arzv --checksum --delete /source/data/ user@remote:/target/data/

    • 不推荐：未使用校验和，也不删除多余文件

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

  3. 停止主库：

    systemctl stop kaiwudb

  4. 最终数据同步：登录主库服务器，使用 rsync 或其他工具将剩余数据拷贝到备库数据目录。

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

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

  6. 登录备库服务器，进入 kwbase 所在目录，更新节点标识：

    # 节点标识需与主库不同，可自定义，建议使用 UUID 格式, 例如 255a0f0d-35ba-4aa3-a1a1-11533fee273d
./kwbase debug update /target/data <cluster-id>

  7. 依次启动备库和主库。

    systemctl start kaiwudb

启用主备复制

前提条件：

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

步骤：

  1. 登录备库，添加主库地址：

    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;

  2. 创建主备复制：

    REPLICATE SET SERVICE CREATE;

  3. 启动主备复制:

    REPLICATE SET SERVICE START;

停机和恢复

计划性停机和恢复

暂停和恢复主备复制

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

前提条件：

用户拥有 admin 权限。

步骤：

  1. 登录主库，将主库设为只读模式，以确保复制暂停期间无数据写入：

    SET CLUSTER SETTING default_transaction_read_only.enabled = true;

  2. 在备库停止主备复制：

    REPLICATE SET SERVICE STOP;

  3. 完成硬件维护、软件升级后，在备库启动主备复制：

    REPLICATE SET SERVICE START;

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

    SET CLUSTER SETTING default_transaction_read_only.enabled = false;
更改 IP 地址的停机和恢复
更改主库 IP 地址

前提条件：

用户拥有 admin 权限。

步骤：

  1. 登录主库，将主库设置为只读模式，以确保复制暂停期间无数据写入：

    SET CLUSTER SETTING default_transaction_read_only.enabled = true;

  2. 在备库停止主备复制：

    REPLICATE SET SERVICE STOP;

  3. （可选）如果采用安全部署模式，检查是否需要更新节点证书：

    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

  4. 重启主库，在 ./kwbase start 启动命令中指定新 IP 地址并加载更新后的证书（如需要）。

  5. （可选）如需更新节点证书，通过 ./kwbase start 启动命令重启备库，加载更新后的证书。

  6. 登录备库，设置主库新地址，恢复主备复制：

    1. 设置主库新地址：

      REPLICATE SET PRIMARY <primary_URL>;

    2. 启动主备复制：

      REPLICATE SET SERVICE START;

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

    SET CLUSTER SETTING default_transaction_read_only.enabled = false;
更改备库 IP 地址

前提条件：

用户拥有 admin 权限。

步骤：

  1. 登录主库，将主库设置为只读模式，以确保复制暂停期间无数据写入：

    SET CLUSTER SETTING default_transaction_read_only.enabled = true;

  2. 在备库停止主备复制：

    REPLICATE SET SERVICE STOP;

  3. （可选）如果采用安全部署模式，检查是否需要更新节点证书：

    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

  4. 重启备库，在 ./kwbase start 启动命令中指定新 IP 地址并加载更新后的证书（如需要）。

  5. （可选）如需更新节点证书，通过 ./kwbase start 启动命令重启主库，加载更新后的证书。

  6. 登录备库，启动主备复制：

    REPLICATE SET SERVICE START;

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

    SET CLUSTER SETTING default_transaction_read_only.enabled = false;

非计划性停机后恢复

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

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

  • 将备库提升为新主库：待原主库恢复后重建主备关系，具体操作可参见非计划性主备切换。 注意：如果主库宕机前备库存在数据延迟，主库恢复时，由于主备数据不一致，主库在宕机前尚未同步至备库的数据将无法保留，存在数据丢失风险。
  • 将备库转为独立节点：删除主备服务关系，具体操作可参见删除主备复制。

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

REPLICATE SET ROLE DEFAULT;

主备切换

计划性主备切换

前提条件：

用户拥有 admin 权限。

步骤：

  1. 登录主库，将主库设置为只读模式，以确保复制暂停期间无数据写入：

    SET CLUSTER SETTING default_transaction_read_only.enabled = true;

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

    1. 暂停主备服务：

      REPLICATE SET SERVICE STOP;

    2. 将备库设为主库：

      REPLICATE SET ROLE PRIMARY;

    3. 启用 WAL 日志功能：

      SET cluster setting ts.wal.wal_level = 1;

    4. 解除只读模式：

      SET CLUSTER SETTING default_transaction_read_only.enabled = false;

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

    1. 将原主库设置为备库：

      REPLICATE SET ROLE SECONDARY;

    2. 关闭 WAL 日志功能：

      SET cluster setting ts.wal.wal_level = 0;

    3. 设置只读模式：

      SET CLUSTER SETTING default_transaction_read_only.enabled = true;

    4. 启动主备服务：

      REPLICATE SET SERVICE START;

非计划性主备切换

前提条件：

用户拥有 admin 权限。

步骤：

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

    1. 将备库设为主库：

      REPLICATE SET ROLE PRIMARY;

    2. 启用 WAL 日志功能：

      SET cluster setting ts.wal.wal_level = 1;

    3. 解除只读模式：

      SET CLUSTER SETTING default_transaction_read_only.enabled = false;

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

    1. 登录原主库，设为备库：

      REPLICATE SET ROLE SECONDARY;

    2. 关闭 WAL 日志功能：

      SET cluster setting ts.wal.wal_level = 0;

    3. 设置只读模式：

      SET CLUSTER SETTING default_transaction_read_only.enabled = true;

    4. 重启主备服务：

      REPLICATE SET SERVICE STOP;
REPLICATE SET SERVICE START;

  3. (可选) 如果系统报错启动失败，进行历史数据迁移，重建主备关系：

    1. 停止新主库：

      systemctl stop kaiwudb

    2. 使用 rsync 或其他工具将数据拷贝到新备库数据目录。

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

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

    4. 登录新备库服务器，进入 kwbase 所在目录，更新数据目录的节点标识：

      # 节点标识需与主库不同，可自定义，建议使用 UUID 格式, 例如 255a0f0d-35ba-4aa3-a1a1-11533fee273d
./kwbase debug update /target/data <cluster-id>

    5. 依次启动新备库和新主库：

      systemctl start kaiwudb

    6. 登录新备库，重建主备关系

      -- 删除已有主备服务：
REPLICATE SET SERVICE DROP;
--添加主库地址：
REPLICATE SET PRIMARY <primary_url>；
-- 创建主备复制
REPLICATE SET SERVICE CREATE;
-- 启动主备复制
REPLICATE SET SERVICE START;

删除主备复制

前提条件：

用户拥有 admin 权限。

步骤：

  1. 登录备库，停止主备服务：

    REPLICATE SET SERVICE STOP;

  2. 将备库设为默认节点：

    REPLICATE SET ROLE DEFAULT;

  3. 删除主备服务：

    REPLICATE SET SERVICE DROP;

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

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

  5. （可选）如需提供对外服务，启用 WAL 日志功能，解除只读模式：

    1. 启用 WAL 日志功能：

      SET cluster setting ts.wal.wal_level = 1;

    2. 解除只读模式：

      SET CLUSTER SETTING default_transaction_read_only.enabled = false;

监控

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

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

前提条件：

用户拥有 admin 权限。

步骤：

  1. 登录备库，查看备库最近 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 权限。

步骤：

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

    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 权限。

步骤：

  1. 分别登录主库和备库，执行以下命令，检查主备高可用状态：

    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：一致性对齐时间。

  2. 如果状态异常，检查主备通信网络。