Migration Guide

# Preface

This document is the migration guide for Apusic Key-Value Database (KVDB) V2.0. It describes in detail how to migrate from Redis to KVDB, and how to migrate earlier KVDB versions to V2.0.

# Intended Audience

This document is intended for KVDB product operations engineers, IT system operations engineers, development engineers, software architects, R&D managers, and other personnel.

For more information about Apusic KVDB V2.0, please refer to the following Apusic KVDB V2.0 product manual set:

No. Manual Description
1 Apusic Key-Value Database V2.0 Quick Start Guide Briefly introduces how to quickly get started with KVDB.
2 Apusic Key-Value Database V2.0 Installation Guide Describes in detail how to install KVDB on various operating systems, as well as KVDB service start/stop operations and the product registration process.
3 Apusic Key-Value Database V2.0 Key-Value Core User Manual Describes in detail the use, configuration, and management of KVDB features and the usage of supporting tools.
4 Apusic Key-Value Database V2.0 Console User Manual Describes in detail the use of KVDB console features and operation instructions.
5 Apusic Key-Value Database V2.0 Development Guide Describes in detail how to develop KVDB client applications based on various programming languages.
6 Apusic Key-Value Database V2.0 Migration Guide Describes how to migrate and upgrade earlier KVDB versions to V2.0, as well as how to migrate from Redis to KVDB.
7 Apusic Key-Value Database V2.0 Operations Guide Describes KVDB monitoring, operations, security hardening, and other operations instructions.
8 Apusic Key-Value Database V2.0 Performance Tuning Guide Describes KVDB performance tuning.

# Technical Support

KVDB provides comprehensive technical support services. You can obtain technical support in the following ways:

  • Website: www.apusic.com

  • Phone: 400-855-5800

  • Email: support@apusic.com

  • Kingdee Cloud Community: https://vip.kingdee.com/?productId=73&productLineId=14&lang=zh-CN

When requesting technical support, please provide the following information:

  1. Your name

  2. Company information and contact details

  3. Operating system and its version

  4. Product version number

  5. Detailed information such as logs and screenshots of any exceptions or errors

# Overview

This manual describes two migration procedures to Apusic KVDB V2.0:

  1. Migrating KVDB V2.0.2 and earlier versions to Apusic KVDB V2.0: use kvdb-conf-conv to convert the configuration files of KVDB V2.0.2 and earlier versions to an Apusic KVDB V2.0-compatible format, reuse the original configuration and data files, and verify functionality after startup;

  2. Migrating Redis 8.6 and earlier versions to Apusic KVDB V2.0: relies on KVDB's ability to directly load Redis configurations (redis.conf, etc.) and data files (RDB/AOF, etc.).

# Migrating KVDB V2.0.2 and Earlier Versions to V2.0

# Preparation

# Environment Check

  • Apusic KVDB V2.0 is installed (must match the tool version), and the installation directory permissions are normal (readable and executable);

  • The KVDB V2.0.2 or earlier service to be migrated is accessible, or its RDB cache files and configuration files (YAML format) have been obtained;

  • The migration target server (the server where Apusic KVDB V2.0 is deployed) has sufficient disk space to store the migrated cache data and configuration files;

# Tool and File Preparation

# Required Tools

  • kvdb-check-rdb: used to verify and repair RDB cache files of KVDB V2.0.2 and earlier versions (deployed with the Apusic KVDB V2.0 installation package, located in the /kvdb/ directory);

  • kvdb-check-aof: used to verify and repair AOF files of KVDB V2.0.2 and earlier versions (deployed in the same directory);

  • kvdb-conf-conv: used to convert configuration files of KVDB V2.0.2 and earlier versions to an Apusic KVDB V2.0-compatible format (deployed in the same directory);

# Collecting Files to Migrate

  • Configuration files of KVDB V2.0.2 and earlier versions: server configuration (such as conf.yaml) or Sentinel configuration (such as sentinel_go.yaml);

  • RDB snapshot files of KVDB V2.0.2 and earlier versions: named dump.rdb by default, usually located in the installation directory (confirm the actual path);

  • If AOF persistence is enabled in KVDB V2.0.2 and earlier versions, prefer the AOF files as the migration data source, with the RDB files as the backup migration data source;

# Standalone Mode Migration

Standalone mode migration applies to scenarios where only a single KVDB service is deployed. The core process is "file preparation -> configuration conversion -> data verification and repair -> deployment and startup -> verification". The operation is simple with no dependencies. The specific steps are as follows:

# Migration Prerequisites

  • Apusic KVDB V2.0 is installed on the target server, and the installation directory permissions are normal (readable and executable);

  • The configuration file (such as conf.yaml) and RDB snapshot file (dump.rdb) of KVDB V2.0.2 and earlier versions have been collected; if AOF persistence is enabled, obtain the AOF files first;

  • The target server has sufficient disk space, at least 2 times the size of the source data files (reserving space for backup and operation).

# Preparation

# Tools and Configuration Prerequisites

  • kvdb-check-rdb: used to verify and repair RDB cache files of KVDB V2.0.2 and earlier versions (deployed with the Apusic KVDB V2.0 installation package, located in the /kvdb/ directory);

  • kvdb-check-aof: used to verify and repair AOF files of KVDB V2.0.2 and earlier versions (deployed in the same directory);

  • kvdb-conf-conv: used to convert configuration files of KVDB V2.0.2 and earlier versions to an Apusic KVDB V2.0-compatible format (deployed in the same directory);

# Back Up Data and Stop the KVDB V2.0.2 or Earlier Standalone Node (Full Downtime)

  • After stopping write operations on the KVDB V2.0.2 or earlier standalone node, run the bgsave command again to generate the latest RDB file; back up the source KVDB configuration;

  • The KVDB V2.0.2 or earlier standalone node must be stopped first, and any data writes are forbidden, to ensure the final consistency of the source data files.

# Execute on the node: stop the KVDB process of KVDB V2.0.2 and earlier versions
ps -ef | grep kvdb-server | grep -v grep | awk '{print $2}' | xargs kill -9

# Verify the process has stopped (no output means success)
ps -ef | grep kvdb-server | grep -v grep
1
2
3
4
5

# Migration Steps

# Configuration File Migration

Use the kvdb-conf-conv tool to convert the server configuration of KVDB V2.0.2 and earlier versions to an Apusic KVDB V2.0-compatible format, as follows:

  1. Back up the default Apusic KVDB V2.0 configuration file on the target server (to avoid loss by overwriting):
cp /kvdb/kvdb.yaml /kvdb/kvdb.yaml.bak
1
  1. Perform the configuration conversion (specify the --server parameter to adapt to server configuration):
kvdb-conf-conv --server --go-yaml /path/to/conf.yaml --c-yaml /kvdb/kvdb.yaml
1
  1. Verify the conversion result: open /kvdb/kvdb.yaml and confirm that the core configuration items (such as port, password, data directory, memory limit, etc.) have been inherited correctly with no syntax errors;
# Cache Data Migration
  1. Verify and repair the source RDB or AOF files (process AOF files first, as the data is more complete):
# If using AOF files
kvdb-check-aof /path/to/appendonlydir/appendonly.aof.manifest

# If using RDB files
kvdb-check-rdb /path/to/dump.rdb

# If a file is corrupted, perform repair
kvdb-check-aof --fix /path/to/appendonlydir/appendonly.aof.1.base.rdb /
kvdb-check-aof --fix /path/to/appendonlydir/appendonly.aof.1.base.aof /
kvdb-check-aof --fix /path/to/appendonlydir/appendonly.aof.1.incr.aof

kvdb-check-rdb --fix /path/to/dump.rdb
1
2
3
4
5
6
7
8
9
10
11
12
  1. Copy the repaired files to the Apusic KVDB V2.0 installation directory:
# Check the Apusic KVDB V2.0 data directory (confirm via the dir configuration item in kvdb.yaml; default path as follows), and copy the RDB file
cp /path/to/dump.rdb/ kvdb/

# If using AOF files, first enable the AOF configuration (set appendonly yes in kvdb.yaml), then copy
cp /path/to/appendonlydir /kvdb/
1
2
3
4
5
# Starting the Apusic KVDB V2.0 Service
  1. Start the Apusic KVDB V2.0 service, loading the converted configuration file:
kvdb-server /kvdb/kvdb.yaml
1
  1. Verify the service startup status:
# View the service process
ps -ef | grep kvdb-server

# View the log (default log path: /kvdb/server.log)
tail -100f /kvdb/server.log
1
2
3
4
5
# Verifying the Startup
  1. Connect to the Apusic KVDB V2.0 service and verify data integrity:
# Connect using kvdb-cli (default port 6359; add the -a option if a password is configured)
kvdb-cli -p 6359 -a <密码># 示例值，非真实数据

# View keyspace statistics
info keyspace
1
2
3
4
5
  1. Verify functional availability: perform write, modify, delete, and other operations, and confirm that the service responds normally with no configuration- or data-related errors:

# Notes

  • During migration, the KVDB V2.0.2 or earlier service must be stopped to avoid source file corruption caused by data writes;

  • After migration, observe the service running for 10-20 minutes and confirm there are no log errors or other exceptions.

# Master-Slave Mode Migration

Master-slave mode migration applies to scenarios where KVDB V2.0.2 and earlier versions cannot establish master-slave replication across versions with Apusic KVDB V2.0. The core principle is full downtime -> migrate the master node first -> then migrate the slave nodes -> data consistency verification. Migration is completed by importing full data via RDB or AOF, and a short downtime is required throughout (there is no cross-version synchronization phase). The specific steps are as follows:

# Migration Prerequisites

  • Apusic KVDB V2.0 is installed on both the master and slave target servers, the installation directory permissions are normal (readable, writable, and executable), and the master and slave nodes can communicate over the network (no firewall blocking port 6359);

  • The configuration files (conf.yaml), AOF files (preferred, as the data is more complete), or RDB snapshot files of the KVDB V2.0.2 or earlier master and slave nodes have been collected, with a full backup made;

  • Inform the business side of the downtime window in advance; it is recommended to operate during off-peak hours. The downtime is approximately the time for "data file copy + service startup" (adjust according to the data volume, generally 5-30 minutes);

  • The target server has sufficient disk space, at least 2 times the size of the source data files (reserving space for backup and operation).

# Preparation

# Tools and Configuration Prerequisites

  • kvdb-check-rdb: used to verify and repair RDB cache files of KVDB V2.0.2 and earlier versions (deployed with the Apusic KVDB V2.0 installation package, located in the /kvdb/ directory);

  • kvdb-check-aof: used to verify and repair AOF files of KVDB V2.0.2 and earlier versions (deployed in the same directory);

  • kvdb-conf-conv: used to convert configuration files of KVDB V2.0.2 and earlier versions to an Apusic KVDB V2.0-compatible format (deployed in the same directory);

# Back Up Data and Stop the KVDB V2.0.2 or Earlier Master-Slave Cluster (Full Downtime)

  • After stopping write operations on the KVDB V2.0.2 or earlier nodes, run the bgsave command again to generate the latest RDB file; back up the source KVDB configuration;

  • All KVDB V2.0.2 or earlier master and slave nodes must be stopped first, and any data writes are forbidden, to ensure the final consistency of the source data files.

# Execute uniformly on the master node + all slave nodes: stop the KVDB processes of KVDB V2.0.2 and earlier versions
ps -ef | grep kvdb-server | grep -v grep | awk '{print $2}' | xargs kill -9

# Verify the processes have stopped (no output means success)
ps -ef | grep kvdb-server | grep -v grep
1
2
3
4
5

# Migration Steps (Execute in the Order of "Master Node -> All Slave Nodes")

# Master Node Migration

The master node is the data core. Configuration conversion, data verification and import, and service startup must be completed first, as it serves as the synchronization source for the subsequent slave nodes.

Step 1: Configuration File Conversion and Optimization

  1. Back up the default configuration of the Apusic KVDB V2.0 master node (to avoid overwriting):
cp /kvdb/kvdb.yaml /kvdb/kvdb-master.yaml.bak
1
  1. Convert the master node configuration of KVDB V2.0.2 and earlier versions to the dedicated Apusic KVDB V2.0 master node configuration (named kvdb-master.yaml for easy distinction):
kvdb-conf-conv --server --go-yaml /path/to/conf.yaml --c-yaml /kvdb/kvdb-master.yaml
1
  1. Check the Apusic KVDB V2.0 master node configuration, enable the master identity (no replicaof configuration), and confirm the core configuration items:
vi /kvdb/kvdb-master.yaml
1

Key configuration confirmation/modification:

  • port: 6359 (unified port; if it needs to be changed, synchronize all nodes);

  • requirepass: your password (if the source master node has a password, keep it; slave nodes will need to configure masterauth later);

  • dir: /kvdb/ (data directory, consistent with the actual plan);

  • appendonly: yes (it is recommended to enable AOF, consistent with the source; set to no if the source uses only RDB);

  • logfile: kvdb-master.log (independent log for the master node, convenient for troubleshooting).

Step 2: Data File Verification, Repair, and Import

  1. Verify and repair the source KVDB V2.0.2 or earlier master node data files (executed on the master node; skip repair if the files are not corrupted):
# If using AOF files (recommended)
kvdb-check-aof /path/to/appendonlydir/appendonly.aof.manifest

# If using RDB files
kvdb-check-rdb /path/to/dump.rdb

# If a file is corrupted, perform repair
kvdb-check-aof --fix /path/to/appendonlydir/appendonly.aof.1.base.rdb /
kvdb-check-aof --fix /path/to/appendonlydir/appendonly.aof.1.base.aof /
kvdb-check-aof --fix /path/to/appendonlydir/appendonly.aof.1.incr.aof

kvdb-check-rdb --fix /path/to/dump.rdb
1
2
3
4
5
6
7
8
9
10
11
12
  1. Copy the repaired clean data files to the Apusic KVDB V2.0 master node data directory and modify permissions:
# Copy the AOF files (recommended; if using RDB, execute the next line instead)
cp /path/to/appendonlydir/ /kvdb/

# Copy the RDB file
cp /path/to/dump.rdb /kvdb/

# Grant permissions (to prevent the service from being unable to read)
chmod 644 /kvdb/{appendonlydir/, dump.rdb}
1
2
3
4
5
6
7
8

Step 3: Start the Apusic KVDB V2.0 Master Node Service

# Start the master node with the dedicated configuration file
kvdb-server /kvdb/kvdb-master.yaml

# Verify the master node startup status
ps -ef | grep kvdb-server | grep master # View the process
tail -100f /kvdb/kvdb-master.log # View the log
1
2
3
4
5
6

The log showing "Ready to accept connections" indicates that the master node has started successfully;

Connect to the master node to verify data integrity (critical, to ensure the data import succeeded):

kvdb-cli -p 6359 -a <password>  # Connect to the master node

info keyspace  # View keyspace statistics (confirm the data volume)
1
2
3
# Slave Node Migration (Execute on All Slave Nodes Simultaneously)

Slave nodes do not need to import data separately. After startup, they pull the full data from the already-started Apusic KVDB V2.0 master node through Apusic KVDB V2.0 internal master-slave synchronization, ensuring the data is completely consistent with the master node.

Step 1: Configuration File Conversion and Master-Slave Association

  1. Back up the default configuration of the Apusic KVDB V2.0 slave node:
cp /kvdb/kvdb.yaml /kvdb/kvdb-slave.yaml.bak
1
  1. Convert the slave node configuration of KVDB V2.0.2 and earlier versions to the dedicated Apusic KVDB V2.0 slave node configuration (named kvdb-slave.yaml):
kvdb-conf-conv --server --go-yaml /path/to/conf.yaml --c-yaml /kvdb/kvdb-slave.yaml
1
  1. Check the Apusic KVDB V2.0 slave node configuration, specify the master node information, and enable the slave identity:
vi /kvdb/kvdb-slave.yaml
1

Key configuration confirmation/modification:

  • port: 6360 (unified port; if it needs to be changed, synchronize all nodes);

  • requirepass: your password (if the source master node has a password, keep it; slave nodes will need to configure masterauth later);

  • dir: /kvdb/ (data directory, consistent with the actual plan);

  • appendonly: yes (it is recommended to enable AOF, consistent with the source; set to no if the source uses only RDB);

  • replicaof: # points to the IP and port of the Apusic KVDB V2.0 master node;

  • logfile: kvdb-slave.log (independent log for the slave node, convenient for troubleshooting).

Step 2: Start the Apusic KVDB V2.0 Slave Node Services

No source data files need to be copied to the slave node data directory; the Apusic KVDB V2.0 slave nodes automatically synchronize from the master node:

# Start the slave node with the dedicated configuration file
kvdb-server /kvdb/kvdb-slave.yaml

# Verify the slave node startup status
ps -ef | grep kvdb-server   # View the process
tail -100f /kvdb/kvdb-slave.log  # View the log
1
2
3
4
5
6

The log showing "MASTER <-> REPLICA sync: Finished with success" indicates that the slave node has successfully connected to the master node and started synchronizing.

Step 3: Verify the Slave Node Synchronization Status

Connect to a slave node and confirm that synchronization is complete and the data is consistent with the master node:

kvdb-cli -p 6360 -a <password>  # Connect to the slave node

info replication  # View the synchronization status
1
2
3

Key status confirmations:

  • role: slave: the slave node identity is normal;

  • master_host: the master node IP, masterport: 6359: the master node pointing is correct;

  • master_link_status: up: the master-slave connection is normal.

# Notes

  • Throughout the migration, all KVDB V2.0.2 or earlier master-slave nodes must be fully stopped first, and data writes are forbidden; otherwise the source data files will be inconsistent and data will be lost after import;

  • After importing the master node data, data integrity must be verified before starting the slave nodes, to prevent slave nodes from synchronizing erroneous data;

  • Slave nodes do not need any source data files copied; this is completed by Apusic KVDB V2.0 internal master-slave synchronization. Manual copying will cause synchronization conflicts;

  • The core configurations of the master and slave nodes must be consistent (AOF switch, port, password, etc.), otherwise connection failures or synchronization exceptions will occur;

  • After migration, observe the cluster running for 10-20 minutes and confirm that master-slave synchronization has no delay, there are no log errors, and business access is normal.

# Sentinel Mode Migration

For scenarios where KVDB V2.0.2 and earlier versions cannot perform master-slave synchronization across versions with Apusic KVDB V2.0 and Sentinels cannot monitor cross-version nodes, the core principle is full downtime -> migrate the master-slave nodes first (same as Chapter 6) -> then migrate the Sentinel nodes -> re-associate monitoring. Migration is completed through "Apusic KVDB V2.0 master-slave cluster rebuild + Sentinel re-monitoring", and a short business downtime is required throughout. The specific steps are as follows:

# Migration Prerequisites

  • Apusic KVDB V2.0 is installed on all master-slave nodes and Sentinel nodes, and the network is interconnected (open service port 6359 and Sentinel port 26359);

  • The master-slave node configurations, data files, and Sentinel configuration files (sentinel_go.yaml) of KVDB V2.0.2 and earlier versions have been collected, with a full backup made;

  • Plan the downtime window in advance (off-peak hours). The downtime is the time for "KVDB V2.0.2 and earlier shutdown + Apusic KVDB V2.0 master-slave startup + Sentinel startup" (generally 10-40 minutes);

  • All target nodes are time-synchronized and have sufficient disk space (reserve 2 times the source data space in the master node data directory).

# Preparation

# Tools and Configuration Prerequisites

  • kvdb-check-rdb: used to verify and repair RDB cache files of KVDB V2.0.2 and earlier versions (deployed with the Apusic KVDB V2.0 installation package, located in the /kvdb/ directory);

  • kvdb-check-aof: used to verify and repair AOF files of KVDB V2.0.2 and earlier versions (deployed in the same directory);

  • kvdb-conf-conv: used to convert configuration files of KVDB V2.0.2 and earlier versions to an Apusic KVDB V2.0-compatible format (deployed in the same directory);

# Back Up Data and Fully Stop the KVDB V2.0.2 or Earlier Sentinel + Master-Slave Cluster

  • After stopping write operations on the KVDB V2.0.2 or earlier nodes, run the bgsave command again to generate the latest RDB file; back up the source KVDB configuration;

  • All KVDB V2.0.2 or earlier Sentinel nodes and master-slave nodes must be stopped first, and data writes and Sentinel monitoring are forbidden, to ensure source data consistency.

# Execute uniformly on all nodes: stop the KVDB master-slave + Sentinel processes of KVDB V2.0.2 and earlier versions
ps -ef | grep -E 'kvdb-server | kvdb-sentinel' | grep -v grep | awk '{print $2}' | xargs kill -9

# Verify the processes have stopped (no output means success)
ps -ef | grep -E 'kvdb-server | kvdb-sentinel' | grep -v grep
1
2
3
4
5
6

# Migration Steps (Execute in the Order of "Apusic KVDB V2.0 Master-Slave Cluster -> Apusic KVDB V2.0 Sentinel Cluster")

# Rebuild the Apusic KVDB V2.0 Master-Slave Cluster (Critical, Same as the Complete Steps in the Previous Chapter)

  • Strictly follow all the steps of master-slave mode migration in the previous chapter to complete the setup of the Apusic KVDB V2.0 master-slave cluster:

  • Migrate the Apusic KVDB V2.0 master node: configuration conversion -> data verification and import -> startup -> verify data integrity;

  • Migrate all Apusic KVDB V2.0 slave nodes: configuration conversion (associate with the master node) -> startup -> verify master-slave synchronization;

  • Complete the overall verification of the master-slave cluster: data consistency, master-slave functionality, and no log exceptions.

This step is the foundation of Sentinel migration. The Apusic KVDB V2.0 master-slave cluster must be running completely normally before proceeding with the subsequent Sentinel migration.

# Sentinel Node Migration (Execute on All Sentinel Nodes Simultaneously)

Sentinel nodes do not need to import data. You only need to convert the Sentinel configuration of KVDB V2.0.2 and earlier versions to an Apusic KVDB V2.0-compatible format, and change the monitoring target to the already-built Apusic KVDB V2.0 master node.

Step 1: Configuration File Conversion and Monitoring Target Modification

  1. Back up the default Apusic KVDB V2.0 Sentinel configuration:
cp /kvdb/sentinel.yaml /kvdb/sentinel-c.yaml.bak
1
  1. Convert the Sentinel configuration of KVDB V2.0.2 and earlier versions to the dedicated Apusic KVDB V2.0 Sentinel configuration (named sentinel-c.yaml):
kvdb-conf-conv --sentinel --go-yaml /path/to/sentinel_go.yaml --c-yaml /kvdb/sentinel.yaml
1
  1. Check the Apusic KVDB V2.0 Sentinel configuration and confirm the key Sentinel configuration:
vi /kvdb/sentinel.yaml
1

Key configuration modification or confirmation (the core is the monitor configuration item, pointing to the Apusic KVDB V2.0 master node):

# Core Sentinel monitoring configuration (replace with the Apusic KVDB V2.0 master node information; keep the remaining parameters consistent with the source)

SENTINEL:

sentinel monitor: mymaster 10.0.1.100 (example IP; replace with the actual IP) 6359 2 # mymaster: monitoring name (consistent with the source), followed by the master node IP, port, and quorum threshold

sentinel down-after-milliseconds: mymaster 30000  # Subjective down timeout (consistent with the source)

sentinel failover-timeout: mymaster 180000  # Failover timeout (consistent with the source)

sentinel auth-pass: mymaster <password>   # Consistent with the master node's requirepass; omit if there is no password
1
2
3
4
5
6
7
8
9
10
11

Other configuration confirmations:

  • port: 26359 (Sentinel default port, consistent with the source);

  • logfile: sentinel.log (independent Sentinel log);

  • dir: /kvdb/ (Sentinel data directory, storing monitoring state).

# Start all Sentinel nodes simultaneously with the dedicated configuration file
kvdb-sentinel /kvdb/sentinel.yaml

# Verify the Sentinel startup status
ps -ef | grep kvdb-sentinel   # View the process
tail -100f /kvdb/sentinel.log   # View the log
1
2
3
4
5
6

Step 2: Start the Apusic KVDB V2.0 Sentinel Services

The log showing "Sentinel ID is xxxxxxxxxxxxxxxxxxxxxxx" indicates that the Sentinel has started successfully.

Key verification: the Sentinel has successfully discovered all nodes of the Apusic KVDB V2.0 master-slave cluster

# Connect to the Sentinel port (26359) and query the monitoring status

kvdb-cli -p 26359

info sentinel  # View Sentinel monitoring information

sentinel slaves mymaster  # View the list of monitored slave nodes
1
2
3
4
5
6
7

Verification result requirements:

  • The IPs and ports shown in the slave node list are all Apusic KVDB V2.0 slave node information, with status online.

# Notes

  • Before migration, all KVDB V2.0.2 or earlier Sentinel + master-slave nodes must be fully stopped, to prevent Sentinels from continuously monitoring stopped nodes, or data writes from causing source file inconsistency;

  • The Apusic KVDB V2.0 master-slave cluster must be set up and verified before starting the Sentinel nodes; otherwise the Sentinels will not be able to monitor valid nodes, causing the migration to fail;

  • It is recommended that the monitoring name (such as mymaster), quorum threshold, and timeout in the Sentinel configuration remain consistent with the source, to reduce client configuration changes;

  • The monitoring configuration of all Sentinel nodes must be completely consistent (monitoring target, password, thresholds, etc.), otherwise the Sentinel cluster will split and failover will be abnormal;

  • After migration, observe for 10-20 minutes, focusing on: no errors in the Sentinel log, no abnormalities in master-slave switching, synchronization delay within an acceptable range, and no interruption of business access.

# Cluster Mode Migration

Cluster mode migration applies to scenarios where KVDB V2.0.2 and earlier versions cannot establish a cluster across versions with Apusic KVDB V2.0 and cannot synchronize shard data across versions. The core principle is full downtime -> full export of shard data -> Apusic KVDB V2.0 cluster initialization -> batch import of shard data -> cluster verification. Because a cluster is a multi-master multi-slave sharding architecture, cross-version synchronization is not possible; the entire cluster must be migrated through "full data export-import", and business downtime is required throughout. The specific steps are as follows:

# Migration Prerequisites

  • Apusic KVDB V2.0 is installed on all nodes of the target cluster (same number of nodes as the source cluster: M masters and N slaves), and the network is interconnected (open service port 6359 and cluster gossip communication port 16359);

  • The configuration files, AOF, and RDB data files of all nodes of the KVDB V2.0.2 or earlier cluster have been collected, and the source cluster topology information has been recorded (execute cluster nodes to obtain slot allocation and master-slave relationships);

  • Plan a long downtime window in advance (adjust according to the data volume; off-peak hours recommended). The downtime is the time for "data export + cluster initialization + data import + verification" (approximately 30-60 minutes for data volumes within 10G);

  • All target nodes have sufficient disk space (reserve 2 times the source node data space on each node), are time-synchronized, and have ports 6359 and 16359 allowed through the firewall.

# Preparation

# Tools and Configuration Prerequisites

  • kvdb-check-rdb: used to verify and repair RDB cache files of KVDB V2.0.2 and earlier versions (deployed with the Apusic KVDB V2.0 installation package, located in the /kvdb/ directory);

  • kvdb-check-aof: used to verify and repair AOF files of KVDB V2.0.2 and earlier versions (deployed in the same directory);

  • kvdb-conf-conv: used to convert configuration files of KVDB V2.0.2 and earlier versions to an Apusic KVDB V2.0-compatible format (deployed in the same directory);

# Unify the Environment and Record the Source Topology

  1. Create a unified directory on all target nodes and grant permissions:

  2. Observe the core topology of the KVDB V2.0.2 or earlier cluster:

Connect to any node of the KVDB V2.0.2 or earlier cluster, execute the following command, and save the output (it will be fully reused in the subsequent Apusic KVDB V2.0 cluster initialization):

kvdb-cli cluster nodes  # Record: master-slave node IPs and ports, node IDs, slot allocation (e.g., 0-5460)
1

Or view the node.conf file, which records the cluster node IPs, ports, node IDs, slot allocation, and other information.

29755a26cc60c056b3af39eb66dc5ccbfbdd20c1 127.0.0.1:6383@16383 slave 882b57434ef8c361fcea44c327379880181afla6 0 1769505692837 2 connected

882b57434ef8c361fcea44c327379880181afla6 127.0.0.1:6380@16380 master - 0 1769505692432 2 connected 5461-10922

980c1df981902c2df617ca81d4df7219b1e86a8b 127.0.0.1:6384@16384 myself,slave 2793d6ad527eee582aa30890d7c8407e9c112b4f003 connected

43d25d48fac16f9b8f6b519f88a889179b8a6e87 127.0.0.1:6382@16382 slave ac9f0c10e742b4570f6436db8af281c1d51ea570 0 1769505692331 1 connected

2793d6ad527eee582aa30890d7c8407e9c112b4f 127.0.0.1:6381@16381 master - 0 1769505692332 3 connected 10923-16383

ac9f0c10e742b4570f6436db8af281c1d51ea570 127.0.0.1:6359@16359 master - 0 1769505692228 1 connected 0-5460
1
2
3
4
5
6
7
8
9
10
11

Record the IP and port of each master node of KVDB V2.0.2 and earlier versions, and back up the AOF or RDB files on the corresponding machines for subsequent data migration to the Apusic KVDB V2.0 cluster:

# Back Up Data and Fully Stop the KVDB V2.0.2 or Earlier Cluster (No Writes Allowed)
  • After stopping write operations on the KVDB V2.0.2 or earlier nodes, run the bgsave command again to generate the latest RDB file; back up the source KVDB configuration;
# Execute uniformly on all cluster nodes of KVDB V2.0.2 and earlier versions: stop the processes
ps -ef | grep kvdb-server | grep -v grep | awk '{print $2}' | xargs kill -9

# Verify the processes have stopped (no output means success)
ps -ef | grep kvdb-server | grep -v grep
1
2
3
4
5
# Data File Preprocessing (Execute on All Source Nodes)

Verify and repair the AOF or RDB files of each KVDB V2.0.2 or earlier master node to ensure clean data files, avoiding data corruption after import into Apusic KVDB V2.0:

# Prefer AOF files (process each node separately; the cluster uses sharded storage and each node's data is independent)
kvdb-check-aof /path/to/nodeX/appendonlydir/appendonly.aof.manifest

# If there is no AOF, use the RDB file
kvdb-check-rdb /path/to/nodeX/dump.rdb

# If a file is corrupted, perform repair
kvdb-check-aof --fix /path/to/appendonlydir/appendonly.aof.1.base.rdb /
kvdb-check-aof --fix /path/to/appendonlydir/appendonly.aof.1.base.aof /
kvdb-check-aof --fix /path/to/appendonlydir/appendonly.aof.1.incr.aof

kvdb-check-rdb --fix /path/to/nodeX/dump.rdb
1
2
3
4
5
6
7
8
9
10
11
12

# Migration Steps (Execute in the Order of "Configuration Conversion -> Apusic KVDB V2.0 Cluster Initialization -> Shard Data Import -> Cluster Status Verification")

# Initialize the Apusic KVDB V2.0 Empty Cluster

Step 1: Configuration Conversion and Cluster Enablement on All Apusic KVDB V2.0 Nodes

  1. Configuration conversion:
kvdb-conf-conv --server --go-yaml /path/to/nodeX/conf.yaml --c-yaml /kvdb/kvdb.yaml
1
  1. Check the configuration file:
vi /kvdb/kvdb.yaml
1

Key configuration:

  • port: 6359 (cluster service port, consistent with the source);

  • logfile: kvdb-cluster-XXX.log (independent log for each node);

  • dir: /kvdb/ (unified data directory);

  • requirepass: password (consistent with the source, the same on all nodes);

  • cluster-enabled: yes (enable Cluster mode);

  • cluster-config-file: nodes-XXX.conf (a separate cluster configuration file for each node);

  • cluster-node-timeout: 15000 (cluster node timeout, consistent with the source);

  • cluster-require-full-coverage: yes (enable full slot coverage check).

  1. After all nodes are configured, start all Apusic KVDB V2.0 nodes (only start the services; the cluster is not yet formed):
kvdb-server /kvdb/kvdb-cluster-XXX.yaml
1

# Verify that all nodes started successfully (the log shows "Ready to accept connections")

Step 2: Perform Cluster Initialization (Slot + Master-Slave Allocation)

Select any Apusic KVDB V2.0 master node and execute the kvdb-cli --cluster create command, strictly specifying the node IPs, ports, and slot allocation according to the source topology. The example uses 3 masters and 3 slaves (source topology slots 0-5460, 5461-10922, 10923-16383):

# Command format: kvdb-cli --cluster create master1 master2 master3 slave1 slave2 slave3 --cluster-replicas 1
# --cluster-replicas 1: means 1 master and 1 slave, consistent with the source

kvdb-cli --cluster create 10.0.1.10 (example IP; replace with the actual IP):6359 10.0.1.11 (example IP; replace with the actual IP):6359 192.168.1.12:6359 192.168.1.13:6359 192.168.1.14:6359 192.168.1.15:6359 --cluster-replicas 1
1
2
3
4

After successful execution, verify the cluster initialization status:

kvdb-cli -p 6359 -a <password> cluster nodes
1

Requirements: all slots are properly allocated to the cluster nodes, all nodes are in myself, master, or slave status, and no node is in fail status.

# Shard Data Import

First start an Apusic KVDB V2.0 standalone node to load the RDB or AOF file, then use the Apusic KVDB V2.0 kvdb-cli --cluster import command to automatically remap and import the data from the standalone node into the cluster. This command is the standardized cluster import method; there is no need to manually manipulate data files, avoiding issues such as file permissions and format incompatibility.

# Core command format (executed on one line; the line break \ is only for formatting)

kvdb-cli --cluster import <cluster master node IP>:<cluster master node port> \

--cluster-from <standalone node IP>:<standalone node port> \

--cluster-copy \

--cluster-replace \

-a <cluster password>
1
2
3
4
5
6
7
8
9
10
11

Parameter details:

  • --cluster-copy: a required parameter; preserves the original data of the source standalone node when copying data, preventing the source data from being deleted;

  • --cluster-replace: an optional parameter; if keys with the same name as those on the source node exist in the cluster, they are overwritten directly (it is recommended to add this during migration to ensure the data is consistent with the source; choose according to business needs).

Because the cluster uses sharded storage, each source shard of KVDB V2.0.2 and earlier versions only stores the data of its corresponding slots. The import command must be executed shard by shard in the order of "source shard master node -> Apusic KVDB V2.0 corresponding shard master node". The whole process can be executed on any operable node of the Apusic KVDB V2.0 cluster; there is no need to operate locally on the target master node.

Example: using a 3-master 3-slave cluster (source master 1 -> target master 1, source master 2 -> target master 2, source master 3 -> target master 3)

# Import shard 1: source master 1 (192.168.1.1:6359) -> Apusic KVDB V2.0 master 1 (10.0.1.10 (example IP; replace with the actual IP):6359)

kvdb-cli --cluster import 10.0.1.10 (example IP; replace with the actual IP):6359 \

--cluster-from 192.168.1.1:6359 \

--cluster-copy \

--cluster-replace \

-a <cluster password>

# Import shard 2: source master 2 (192.168.1.2:6359) -> Apusic KVDB V2.0 master 2 (10.0.1.11 (example IP; replace with the actual IP):6359)

kvdb-cli --cluster import 10.0.1.11 (example IP; replace with the actual IP):6359 \

--cluster-from 192.168.1.2:6359 \

--cluster-copy \

--cluster-replace \

-a <cluster password>

# Import shard 3: source master 3 (192.168.1.3:6359) -> Apusic KVDB V2.0 master 3 (192.168.1.12:6359)

kvdb-cli --cluster import 192.168.1.12:6359 \

--cluster-from 192.168.1.3:6359 \

--cluster-copy \

--cluster-replace \

-a <cluster password>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# Cluster Status Repair and Data Verification

Because the data was imported manually, a cluster status repair must be performed to ensure that slots and data match, with no missing slots or data disorder:

# Verify slot coverage (must show that all 16384 slots are allocated)
kvdb-cli -p 6359 -a <password> cluster info
cluster_slots_assigned:16384 in the cluster info output means all slots are allocated with no omissions.
1
2
3

# Notes

  • Cluster migration requires full downtime, and all nodes of the source cluster must be forbidden from writing, because the cluster uses sharded storage and a data write to a single node will cause shard data inconsistency;

  • The cluster gossip communication port 16359 (6359+10000) must be allowed through the firewall; otherwise nodes cannot discover the cluster topology, causing the cluster to split;

  • When executing the kvdb-cli --cluster import command, --cluster-copy is a required parameter; omitting this parameter will directly delete the original data of the KVDB V2.0.2 or earlier source node, causing irreversible source data loss. It is recommended to add --cluster-replace during migration to ensure that same-named test keys in the Apusic KVDB V2.0 cluster are overwritten and the data is completely consistent with the source;

  • If the source cluster has data skew (one shard has an excessively large data volume), evaluate the disk and memory resources of the corresponding Apusic KVDB V2.0 cluster nodes before import; after migration, promptly scale out the skewed shards to avoid cluster performance bottlenecks that affect business access speed;

  • After migration is complete, it is recommended to observe the cluster running for 10-20 minutes, focusing on: no data loss in each shard, automatic triggering of master failover, normal execution of cross-shard operations, no persistent delay in master-slave synchronization, and business access latency meeting expectations.

# Migrating Redis 8.6 and Earlier Versions to Apusic KVDB V2.0

# Preparation

# Environment Check

  • Apusic KVDB V2.0 is installed on the target server, and the installation directory permissions are normal (readable and executable);

  • The Redis RDB snapshot file (dump.rdb) has been collected; if AOF persistence is enabled, obtain the AOF files first;

  • The target server has sufficient disk space, at least 2 times the size of the source data files (reserving space for backup and operation).

# Tool and File Preparation

  • kvdb-check-rdb: used to verify and repair RDB cache files of KVDB V2.0.2 and earlier versions (deployed with the Apusic KVDB V2.0 installation package, located in the /kvdb/ directory);

  • kvdb-check-aof: used to verify and repair AOF files of KVDB V2.0.2 and earlier versions (deployed in the same directory);

# Standalone Mode Migration

Standalone mode migration applies to scenarios where only a single KVDB service is deployed. The core process is "file preparation -> data verification and repair -> deployment and startup -> verification". The specific steps are as follows:

# Migration Prerequisites

  • Apusic KVDB V2.0 is installed on the target server, and the installation directory permissions are normal (readable and executable);

  • The Redis RDB snapshot file (dump.rdb) has been collected; if AOF persistence is enabled, obtain the AOF files first;

  • The target server has sufficient disk space, at least 2 times the size of the source data files (reserving space for backup and operation).

# Preparation

# Data and Configuration Backup

  • Check the permissions of the Apusic KVDB V2.0 installation directory and data storage directory (ensure the KVDB user can read and write);

  • Copy the RDB file and the Redis configuration file to the designated backup directory of the target KVDB (e.g., /kvdb with 644), ensuring KVDB can read them.

# Back Up Data and Stop the Redis Standalone Node

  • Stop business writes to Redis, run the bgsave command again to generate the latest RDB file; back up the source Redis configuration (redis.conf);

  • The Redis standalone node must be stopped first, and any data writes are forbidden, to ensure the final consistency of the source data files.

# Execute on the node: stop the Redis process
ps -ef | grep kvdb-server | grep -v grep | awk '{print $2}' | xargs kill -9

# Verify the process has stopped (no output means success)
ps -ef | grep kvdb-server | grep -v grep
1
2
3
4
5

# Migration Steps

# Cache Data Migration
  1. Verify and repair the source RDB or AOF files (process AOF files first, as the data is more complete):
# If using AOF files
kvdb-check-aof /path/to/appendonly.aof

# If using RDB files
kvdb-check-rdb /path/to/dump.rdb

# If a file is corrupted, perform repair
kvdb-check-aof --fix /path/to/appendonly.aof

kvdb-check-rdb --fix /path/to/dump.rdb
1
2
3
4
5
6
7
8
9
10
  1. Copy the repaired files to the Apusic KVDB V2.0 installation directory:
# Check the Apusic KVDB V2.0 data directory (confirm via the dir configuration item in kvdb.yaml; default path as follows), and copy the RDB file
cp /path/to/dump.rdb/ kvdb/

# If using AOF files, first enable the AOF configuration (set appendonly yes in kvdb.yaml), then copy
cp /path/to/appendonly.aof /kvdb/
1
2
3
4
5
# Modifying the redis.conf Configuration
  1. Modify the Redis service configuration file (redis.conf) and append the following configuration item to the bottom of the configuration file:
worker-threads 1
1
# Starting the KVDB Service
  1. Start the Apusic KVDB V2.0 service, loading the Redis configuration file directly:
kvdb-server /kvdb/redis.conf
1
  1. Verify the service startup status:
# View the service process
ps -ef | grep kvdb-server

# View the log (default log path: /kvdb/server.log)
tail -100f /kvdb/server.log
1
2
3
4
5
# Verifying the Startup
  1. Connect to the Apusic KVDB V2.0 service and verify data integrity:
# Connect using kvdb-cli (Redis default port 6359; add the -a option if a password is configured)
kvdb-cli -p 6359 -a <密码># 示例值，非真实数据

# View keyspace statistics
info keyspace
1
2
3
4
5
  1. Verify functional availability: perform write, modify, delete, and other operations, and confirm that the service responds normally with no configuration- or data-related errors:

# Notes

  • During migration, the Redis service must be stopped to avoid source file corruption caused by data writes;

  • After migration, observe the service running for 10-20 minutes and confirm there are no log errors or other exceptions.

# Master-Slave Mode Migration

Master-slave mode migration applies to scenarios where a one-master multi-slave KVDB service is deployed. The core process is "file preparation -> data verification and repair -> deployment and startup -> verification". The specific steps are as follows:

# Migration Prerequisites

  • Apusic KVDB V2.0 is installed on both the master and slave target servers, the installation directory permissions are normal (readable, writable, and executable), and the master and slave nodes can communicate over the network (no firewall blocking port 6359);

  • The configuration files (redis.conf), AOF files (preferred, as the data is more complete), or RDB snapshot files of the Redis master and slave nodes have been collected, with a full backup made;

  • Inform the business side of the downtime window in advance; it is recommended to operate during off-peak hours. The downtime is approximately the time for "data file copy + service startup" (adjust according to the data volume, generally 5-30 minutes);

  • The target server has sufficient disk space, at least 2 times the size of the source data files (reserving space for backup and operation).

# Preparation

# Tool and File Preparation

  • kvdb-check-rdb: used to verify and repair RDB cache files of KVDB V2.0.2 and earlier versions (deployed with the Apusic KVDB V2.0 installation package, located in the /kvdb/ directory);

  • kvdb-check-aof: used to verify and repair AOF files of KVDB V2.0.2 and earlier versions (deployed in the same directory);

# Back Up Data and Stop the Redis Master-Slave Cluster (Full Downtime)

  • Stop business writes to Redis, run the bgsave command again to generate the latest RDB file; back up the source Redis configuration (redis.conf);

  • All Redis master and slave nodes must be stopped first, and any data writes are forbidden, to ensure the final consistency of the source data files.

# Execute uniformly on the master node + all slave nodes: stop the Redis processes
ps -ef | grep kvdb-server | grep -v grep | awk '{print $2}' | xargs kill -9

# Verify the processes have stopped (no output means success)
ps -ef | grep kvdb-server | grep -v grep
1
2
3
4
5

# Migration Steps (Execute in the Order of "Master Node -> All Slave Nodes")

# Cache Data Migration
  1. Verify and repair the source Redis master node data files (executed on the master node; skip repair if the files are not corrupted):
# If using AOF files (recommended)
kvdb-check-aof /path/to/appendonly.aof

# If using RDB files
kvdb-check-rdb /path/to/dump.rdb

# If a file is corrupted, perform repair
kvdb-check-aof --fix /path/to/appendonly.aof

kvdb-check-rdb --fix /path/to/dump.rdb
1
2
3
4
5
6
7
8
9
10
  1. Copy the repaired clean data files to the Apusic KVDB V2.0 master node data directory and modify permissions:
# Copy the AOF files (recommended; if using RDB, execute the next line instead)
cp /path/to/appendonly.aof /kvdb/

# Copy the RDB file
cp /path/to/dump.rdb /kvdb/

# Grant permissions (to prevent the service from being unable to read)
chmod 644 /kvdb/{appendonly.aof, dump.rdb}
1
2
3
4
5
6
7
8
# Configuration File Migration (redis.conf)

  1. Copy the redis.conf of the Redis master/slave nodes to the root directory of the KVDB master/slave nodes.

  2. Modify the Redis service configuration file (redis.conf) and append the following configuration item to the bottom of the configuration file:

worker-threads 1
1
# Starting the KVDB Master-Slave Node Services
  1. Start the KVDB master node first: switch to the master node's KVDB installation directory, execute the startup command, and confirm that the master node service started successfully;
# Start the node with the dedicated configuration file
kvdb-server /kvdb/redis.conf

# Verify the node startup status
ps -ef | grep kvdb-server   # View the process
tail -100f /kvdb/server.log  # View the log
1
2
3
4
5
6
  1. Then start all KVDB slave nodes: start the slave node KVDB services one by one, check the startup log of each slave node, and confirm there are no errors.
# Start the slave node with the dedicated configuration file
kvdb-server /kvdb/redis.conf

# Verify the slave node startup status
ps -ef | grep kvdb-server   # View the process
tail -100f /kvdb/server.log  # View the log
1
2
3
4
5
6
# Master-Slave Relationship Verification

  • Execute the info replication command on the KVDB master node, view the slave node list, and confirm that all slave nodes have connected to the master node normally (master_link_status is up);

  • Execute the info replication command on each KVDB slave node and confirm that synchronization with the master node is normal (offsets are consistent);

  • Perform data read/write tests: set a key on the master node and get the key on a slave node to confirm that data synchronization is normal.

# Notes

  • Throughout the migration, all Redis master-slave nodes must be fully stopped first, and data writes are forbidden; otherwise the source data files will be inconsistent and data will be lost after import;

  • After importing the master node data, data integrity must be verified before starting the slave nodes, to prevent slave nodes from synchronizing erroneous data;

  • Slave nodes do not need any source data files copied; this is completed by Apusic KVDB V2.0 internal master-slave synchronization. Manual copying will cause synchronization conflicts;

  • The core configurations of the master and slave nodes must be consistent (AOF switch, port, password, etc.), otherwise connection failures or synchronization exceptions will occur;

  • After migration, observe the cluster running for 10-20 minutes and confirm that master-slave synchronization has no delay, there are no log errors, and business access is normal.

# Sentinel Mode Migration

Apusic KVDB V2.0 supports loading the Redis configuration files redis.conf and sentinel.conf. The core process is full downtime -> migrate the master-slave nodes first -> then migrate the Sentinel nodes -> re-associate monitoring. Migration is completed through "master-slave cluster rebuild + Sentinel re-monitoring", and a short business downtime is required throughout. The specific steps are as follows:

# Migration Prerequisites

  • Apusic KVDB V2.0 is installed on all master-slave nodes and Sentinel nodes, and the network is interconnected (open service port 6359 and Sentinel port 26359);

  • The Redis master-slave node configurations (redis.conf), data files, and Sentinel configuration files (sentinel.conf) have been collected, with a full backup made;

  • Plan the downtime window in advance (off-peak hours). The downtime is the time for "Redis shutdown + Apusic KVDB V2.0 master-slave startup + Sentinel startup" (generally 10-40 minutes);

  • All target nodes are time-synchronized and have sufficient disk space (reserve 2 times the source data space in the master node data directory).

# Preparation

# Tool and File Preparation

  • kvdb-check-rdb: used to verify and repair RDB cache files of KVDB V2.0.2 and earlier versions (deployed with the Apusic KVDB V2.0 installation package, located in the /kvdb/ directory);

  • kvdb-check-aof: used to verify and repair AOF files of KVDB V2.0.2 and earlier versions (deployed in the same directory);

# Back Up Data and Fully Stop the Redis Sentinel + Master-Slave Cluster

  • Stop business writes to Redis, run the bgsave command again to generate the latest RDB file; back up the source Redis configuration (redis.conf);

  • All Redis Sentinel nodes and master-slave nodes must be stopped first, and data writes and Sentinel monitoring are forbidden, to ensure source data consistency.

# Execute uniformly on all nodes: stop the Redis master-slave + Sentinel processes
ps -ef | grep -E 'redis-server | redis-sentinel' | grep -v grep | awk '{print $2}' | xargs kill -9

# Verify the processes have stopped (no output means success)
ps -ef | grep -E 'redis-server | redis-sentinel' | grep -v grep
1
2
3
4
5
6

# Migration Steps

# Cache Data Migration
  1. Verify and repair the source Redis master node data files (executed on the master node; skip repair if the files are not corrupted):
# If using AOF files (recommended)
kvdb-check-aof /path/to/appendonly.aof

# If using RDB files
kvdb-check-rdb /path/to/dump.rdb

# If a file is corrupted, perform repair
kvdb-check-aof --fix /path/to/appendonly.aof

kvdb-check-rdb --fix /path/to/dump.rdb
1
2
3
4
5
6
7
8
9
10
  1. Copy the repaired clean data files to the Apusic KVDB V2.0 master node data directory and modify permissions:
# Copy the AOF files (recommended; if using RDB, execute the next line instead)
cp /path/to/appendonly.aof /kvdb/

# Copy the RDB file
cp /path/to/dump.rdb /kvdb/

# Grant permissions (to prevent the service from being unable to read)
chmod 644 /kvdb/{appendonly.aof, dump.rdb}
1
2
3
4
5
6
7
8
# Configuration File Migration (redis.conf)

  1. Copy the redis.conf of the Redis master/slave nodes to the root directory of the KVDB master/slave nodes.

  2. Modify the Redis service configuration file (redis.conf) and append the following configuration item to the bottom of the configuration file:

worker-threads 1
1
  1. The Sentinel configuration file (sentinel.conf) does not need to be modified; it can be copied to the root directory of the KVDB Sentinel nodes.
# Starting the KVDB Master-Slave Node Services
  1. Start the KVDB master node first: switch to the master node's KVDB installation directory, execute the startup command, and confirm that the master node service started successfully;
# Start the node with the dedicated configuration file
kvdb-server /kvdb/redis.conf

# Verify the node startup status
ps -ef | grep kvdb-server   # View the process
tail -100f /kvdb/server.log  # View the log
1
2
3
4
5
6
  1. Then start all KVDB slave nodes: start the slave node KVDB services one by one, check the startup log of each slave node, and confirm there are no errors.
# Start the slave node with the dedicated configuration file
kvdb-server /kvdb/redis.conf

# Verify the slave node startup status
ps -ef | grep kvdb-server   # View the process
tail -100f /kvdb/server.log  # View the log
1
2
3
4
5
6
# Starting the KVDB Sentinel Node Services
  1. Then start all KVDB Sentinel nodes, check the Sentinel service processes and log status, and ensure successful startup.
# Start the node with the dedicated configuration file
kvdb-sentinel /kvdb/sentinel.conf

# Verify the node startup status
ps -ef | grep kvdb-sentinel   # View the process
tail -100f /kvdb/sentinel.log  # View the log
1
2
3
4
5
6
# Sentinel Functionality Verification

  • Execute the info sentinel command on any KVDB Sentinel node, view the number and status of master-slave nodes monitored by the Sentinel, and confirm that the Sentinel can correctly identify the KVDB master-slave nodes;

  • Test whether the business can automatically obtain the new master node address through the Sentinel and whether read/write operations are normal; after the test is complete, restore the original KVDB master node service.

# Notes

  • Before migration, all Redis Sentinel + master-slave nodes must be fully stopped, to prevent Sentinels from continuously monitoring stopped nodes, or data writes from causing source file inconsistency;

  • After copying sentinel.conf, if the KVDB master node IP of the source differs from that of the target, the master node IP in the sentinel monitor parameter must be modified; otherwise the Sentinel cannot monitor the target master node;

  • The master-slave nodes must be started before the Sentinel nodes, to ensure that the Sentinels can discover the master-slave nodes normally at startup and avoid monitoring failure.

  • After migration, observe for 10-20 minutes, focusing on: no errors in the Sentinel log, no abnormalities in master-slave switching, synchronization delay within an acceptable range, and no interruption of business access.

# Cluster Mode Migration

Apusic KVDB V2.0 supports loading the Redis configuration files redis.conf and node.conf. The core process is "file preparation -> data verification and repair -> deployment and startup -> verification". The specific steps are as follows:

# Migration Prerequisites

  • Apusic KVDB V2.0 is installed on all nodes of the target cluster (same number of nodes as the source cluster: M masters and N slaves), and the network is interconnected;

  • The configuration files, AOF, and RDB data files of all Redis cluster nodes have been collected, and the source cluster topology information has been recorded (execute cluster nodes to obtain slot allocation and master-slave relationships);

  • Plan a long downtime window in advance (adjust according to the data volume; off-peak hours recommended). The downtime is the time for "data export + cluster initialization + data import + verification" (approximately 30-60 minutes for data volumes within 10G);

  • All target nodes have sufficient disk space (reserve 2 times the source node data space on each node).

# Preparation

# Tool and File Preparation

  • kvdb-check-rdb: used to verify and repair RDB cache files of KVDB V2.0.2 and earlier versions (deployed with the Apusic KVDB V2.0 installation package, located in the /kvdb/ directory);

  • kvdb-check-aof: used to verify and repair AOF files of KVDB V2.0.2 and earlier versions (deployed in the same directory);

# Back Up Data and Fully Stop the Redis Cluster (No Writes Allowed)
  • Stop business writes to Redis, run the bgsave command again to generate the latest RDB file; back up the source Redis configuration (redis.conf);
# Execute uniformly on all Redis cluster nodes: stop the processes
ps -ef | grep kvdb-server | grep -v grep | awk '{print $2}' | xargs kill -9

# Verify the processes have stopped (no output means success)
ps -ef | grep kvdb-server | grep -v grep
1
2
3
4
5

# Migration Steps

# Data File Preprocessing (Execute on All Source Nodes)

Verify and repair the AOF or RDB files of each Redis master node to ensure clean data files, avoiding data corruption after import into KVDB:

# Prefer AOF files (process each node separately; the cluster uses sharded storage and each node's data is independent)
kvdb-check-aof /path/to/nodeX/appendonly.aof

# If there is no AOF, use the RDB file
kvdb-check-rdb /path/to/nodeX/dump.rdb

# If a file is corrupted, perform repair
kvdb-check-aof --fix /path/to/appendonly.aof

kvdb-check-rdb --fix /path/to/nodeX/dump.rdb
1
2
3
4
5
6
7
8
9
10
# Configuration File Migration (redis.conf, node.conf)

  1. Copy the redis.conf of each Redis cluster node to the root directory of the corresponding KVDB cluster node.

  2. Modify the Redis service configuration file (redis.conf) and append the following configuration item to the bottom of the configuration file:

worker-threads 1
1
  1. Copy the node.conf of each Redis cluster node to the root directory of the corresponding KVDB cluster node.
# Starting the KVDB Cluster Nodes
  • Start all KVDB cluster nodes one by one, execute the startup command, check the startup log of each node, and confirm there are no errors (focus on cluster connection and slot loading).
# Start the node with the dedicated configuration file
kvdb-server /kvdb/redis.conf

# Verify the node startup status
ps -ef | grep kvdb-server   # View the process
tail -100f /kvdb/server.log  # View the log
1
2
3
4
5
6
# Cluster Status Verification

  • Execute the cluster info command on any KVDB node, confirm that the cluster status is ok, all slots are fully allocated, and there are no unallocated slots;

  • Execute the cluster slots command, verify that the slot allocation is consistent with the source and that each node is responsible for the correct slots;

  • Perform data read/write tests and cross-shard query tests to confirm that the data is complete and business is normal;

# Notes

  • Cluster migration requires full downtime, and all nodes of the source cluster must be forbidden from writing, because the cluster uses sharded storage and a data write to a single node will cause shard data inconsistency;

  • If the source cluster has data skew (one shard has an excessively large data volume), evaluate the disk and memory resources of the corresponding Apusic KVDB V2.0 cluster nodes before import; after migration, promptly scale out the skewed shards to avoid cluster performance bottlenecks that affect business access speed;

  • After migration is complete, it is recommended to observe the cluster running for 10-20 minutes, focusing on: no data loss in each shard, automatic triggering of master failover, normal execution of cross-shard operations, no persistent delay in master-slave synchronization, and business access latency meeting expectations.

# Troubleshooting Common Issues

# Tool Cannot Run

Issue 1: entering kvdb-check-rdb in the terminal prompts "command not found" (Linux);

  • Cause: the tool path has not been added to the system environment variables;

  • Solution: run with the full path (e.g., /usr/local/kvdb/kvdb-check-rdb), or add the environment variable (echo "export PATH=/usr/local/kvdb/:$PATH" >> /etc/profile, then source /etc/profile).

# File Verification or Repair Fails

Issue 1: kvdb-check-rdb or kvdb-check-aof prompts "Permission denied";

  • Cause: no file read or write permission;

  • Solution: use chmod to modify the file permissions (chmod 644 dump.rdb), or run the tool with sudo (sudo kvdb-check-rdb --fix dump.rdb).

Issue 2: KVDB still cannot start after repair;

  • Cause: the file is too severely corrupted, or the tool version does not match the KVDB version;

  • Solution: restore from a backup file, and upgrade or downgrade the tool version to match the KVDB service version.

# kvdb-cli Cannot Connect to the KVDB Service

Issue 1: connection prompts "Could not connect to KVDB at 127.0.0.1:6359: Connection refused";

  • Cause: the KVDB service is not started;

  • Solution: start the KVDB service (kvdb-server /path/to/kvdb.yaml, Linux).

Issue 2: remote connection prompts "Could not connect to KVDB at 10.0.1.100 (example IP; replace with the actual IP):6359: Connection timed out";

  • Cause: port 6359 is not open in the firewall, or the KVDB configuration does not allow remote connections;

  • Solution: open the firewall port (firewall-cmd --add-port=6359/tcp --permanent, Linux), modify the KVDB configuration (bind 0.0.0.0, protected-mode no), and restart the KVDB service.

Issue 3: executing a command after connecting prompts "NOAUTH Authentication required";

  • Cause: the KVDB service has a password set, but it was not entered when connecting;

  • Solution: enter the password with the -a option when connecting, or enter the AUTH password in interactive mode.

# Summary

This document describes in detail the adaptation and migration processes from KVDB V2.0.2 and earlier versions and Redis 8.6 and earlier versions to Apusic KVDB V2.0. The core summary is as follows:

# Migration Process from KVDB V2.0.2 and Earlier Versions to Apusic KVDB V2.0

  • Before migration, complete the environment check and tool and file preparation, ensuring sufficient permissions and complete files;

  • Configuration file migration is implemented with the kvdb-conf-conv tool; you need to specify the configuration type and the source or target file path, and be sure to back up the target configuration file before conversion;

  • Cache data migration is based on RDB files; first verify file integrity with kvdb-check-rdb, repair corrupted files, and then deploy them to the Apusic KVDB V2.0 installation directory;

  • After migration, verify the service startup status, data integrity, and functional availability to ensure a successful migration;

  • If you encounter issues such as tool execution, file processing, or service startup during migration, refer to the Troubleshooting Common Issues chapter for quick resolution.

# Migration Process from Redis 8.6 and Earlier Versions to Apusic KVDB V2.0

  • Install KVDB: extract the installation package to the target directory and complete the basic installation;

  • Stop the source Redis service, collect the core files of the corresponding mode (configuration files + data files), and back them up;

  • Start the KVDB nodes using the Redis configuration files in the order of the corresponding mode, ensuring there are no errors;

  • Verify that data and functionality are normal, switch business traffic, and keep the source for rollback.

By following the procedures in this document, you can achieve a smooth migration from KVDB V2.0.2 and earlier versions and Redis 8.6 and earlier versions to Apusic KVDB V2.0, ensuring the continuity of the cache service and data security.

编辑页面 (opens new window)
#Migration Guide

← Operations Guide→