Apache Kvrocks 2.17.0 常用 CLI 命令与工具详解

汇总 Apache Kvrocks 2.17.0 日常运维的命令与工具用法，覆盖服务启停、redis-cli 数据操作、namespace 管理、INFO/CONFIG 监控、备份恢复与 kvrocks2redis 同步。

Apache KvrocksApache Kvrocks2026/10/12

Apache Kvrocks 2.17.0 常用 CLI 命令与工具详解

目标：整理 Apache Kvrocks 2.17.0 日常运维命令与工具的实战用法，含服务管理、redis-cli 数据操作、namespace 多租户管理、监控与慢日志、备份恢复、kvrocks2redis 数据同步，全部命令已在 Ubuntu 22.04 + Kvrocks 2.17.0 单实例（端口 6666）实测并附真实回显。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Apache Kvrocks：2.17.0（安装目录 /opt/kvrocks，RocksDB 引擎 11.8.1）
  • redis-cli：6.0.16（redis-tools 包）
  • 服务端口：6666（认证口令 q1w2e3r4）
  • 数据目录：/opt/kvrocks/data（配置文件 /opt/kvrocks/conf/kvrocks.conf）
  • 服务托管：systemd（单元名 kvrocks）

二、工具概览

工具路径用途
kvrocks/opt/kvrocks/bin/kvrocks服务主程序（启动/版本/参数覆盖）
kvrocks2redis/opt/kvrocks/bin/kvrocks2redis将 Kvrocks 数据同步到 Redis 的离线/准实时工具
redis-cli/usr/bin/redis-cliRedis 协议客户端，执行全部数据/运维命令
systemctl/usr/bin/systemctlsystemd 服务生命周期管理
journalctl/usr/bin/journalctlsystemd 服务日志查询

主程序命令行用法（/opt/kvrocks/bin/kvrocks --help 实测）：

kvrocks implements the Redis protocol based on RocksDB
Usage:
    -c, --config <filename>         set config file to <filename>, or `-` for stdin
    -v, --version                   print version information
    -h, --help                      print this help message
    --<config-key> <config-value>   overwrite specific config option <config-key> to <config-value>

三、前置条件

  • 服务已安装并运行：systemctl is-active kvrocks 返回 active
  • redis-cli 可连接：redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning PING 返回 PONG
  • 涉及 namespace 的操作要求 requirepass 已设置（空口令时 NAMESPACE 命令会被拒绝）

四、服务管理命令

4.1 版本与启动

查看版本：

/opt/kvrocks/bin/kvrocks --version

实测回显：

kvrocks version 2.17.0

启动（生产走 systemd，手工调试可用前台方式观察日志）：

/opt/kvrocks/bin/kvrocks -c /opt/kvrocks/conf/kvrocks.conf

实测启动首行日志：

[2026-10-11T14:53:07.780198+00:00][I][main.cc:171] kvrocks version 2.17.0

带参数临时覆盖启动（优先级高于配置文件）：

/opt/kvrocks/bin/kvrocks -c /opt/kvrocks/conf/kvrocks.conf --port 6667 --bind 127.0.0.1

4.2 停止与优雅下线

推荐用 redis-cli 的 SHUTDOWN（优雅关闭，等待 RocksDB 落盘后退出，需数秒）：

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning SHUTDOWN

执行后确认进程退出与端口释放：

ps -ef | grep kvrocks | grep -v grep
redis-cli -p 6666 PING

实测回显（进程已退出、端口已释放）：

Could not connect to Redis at 127.0.0.1:6666: Connection refused

💡 说明：如配置了 daemonize yes，也可 kill $(cat /opt/kvrocks/data/kvrocks.pid) 触发同样的优雅关闭流程。

4.3 systemd 服务管理

systemctl start kvrocks
systemctl stop kvrocks
systemctl restart kvrocks
systemctl status kvrocks --no-pager -n 3
systemctl is-active kvrocks
systemctl is-enabled kvrocks

实测 status 回显：

● kvrocks.service - Apache Kvrocks SSD key-value database
     Loaded: loaded (/etc/systemd/system/kvrocks.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-11 14:56:11 UTC; 3s ago
       Docs: https://kvrocks.apache.org
   Main PID: 516 (kvrocks)
      Tasks: 17 (limit: 38359)
     Memory: 26.4M
        CPU: 95ms
     CGroup: /system.slice/kvrocks.service
             └─516 /opt/kvrocks/bin/kvrocks -c /opt/kvrocks/conf/kvrocks.conf

Oct 11 14:56:11 b7088df6f895 systemd[1]: Starting Apache Kvrocks SSD key-value database...
Oct 11 14:56:11 b7088df6f895 systemd[1]: Started Apache Kvrocks SSD key-value database.

⚠️ 注意：systemd 单元为 Type=notify，配置文件中 supervised 需为 auto，否则 start 会一直 activating 直至超时（错误写法与修复见安装指南 FAQ）。

4.4 服务日志排查

systemd 托管时用 journalctl 查看最近日志：

journalctl -u kvrocks --no-pager -n 3

实测回显：

Oct 11 14:57:03 b7088df6f895 systemd[1]: Starting Apache Kvrocks SSD key-value database...
Oct 11 14:57:03 b7088df6f895 systemd[1]: Started Apache Kvrocks SSD key-value database.

文件日志位于数据目录（按天滚动），直接查看末尾：

tail -5 /opt/kvrocks/data/kvrocks_2026-10-11.log

实测回显：

[2026-10-11T14:55:03.244350+00:00][I][storage.cc:458] [storage] Success to create new backup
[2026-10-11T14:55:04.489307+00:00][I][compaction_checker.cc:35] [compaction checker] Start to compact the column family: pubsub
[2026-10-11T14:55:04.489931+00:00][I][compaction_checker.cc:38] [compaction checker] Compact the column family: pubsub finished, result: OK
[2026-10-11T14:55:04.489944+00:00][I][compaction_checker.cc:35] [compaction checker] Start to compact the column family: propagate
[2026-10-11T14:55:04.489966+00:00][I][compaction_checker.cc:38] [compaction checker] Compact the column family: propagate finished, result: OK

日志行格式：[时间][级别][源文件:行号] [模块] 消息，异常排查先 grep E/W 级别行：

grep -E "\[E\]|\[W\]" /opt/kvrocks/data/kvrocks_2026-10-11.log | tail -10

五、redis-cli 连接与数据操作

5.1 连接与认证

无认证连接（服务未设 requirepass 时）：

redis-cli -p 6666 PING

设置口令后的连接与认证（示例口令 q1w2e3r4）：

redis-cli -p 6666 PING
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning PING

实测回显（第一行为未带口令的结果，第二行带口令）：

NOAUTH Authentication required.

PONG

交互式会话内认证：

redis-cli -p 6666
127.0.0.1:6666> AUTH q1w2e3r4

实测回显：

OK

5.2 String 字符串

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning SET greeting "hello-kvrocks"
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning GET greeting
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning SET temp-key v1 EX 60
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning TTL temp-key
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning EXISTS greeting
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning DEL temp-key

实测回显：

OK
hello-kvrocks
OK
59
1
1

5.3 Hash 哈希

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning HSET user:1001 name admin age 18 city hangzhou
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning HGET user:1001 name
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning HGETALL user:1001

实测回显：

3
admin
age
18
city
hangzhou
name
admin

5.4 List 列表

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning LPUSH taskqueue task1 task2 task3
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning LRANGE taskqueue 0 -1

实测回显（LPUSH 后进先出）：

3
task3
task2
task1

5.5 Set 与 ZSet 集合

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning SADD tags redis kvrocks apache
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning SMEMBERS tags
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning ZADD leaderboard 100 alice 95 bob
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning ZRANGE leaderboard 0 -1 WITHSCORES

实测回显：

3
apache
kvrocks
redis
2
bob
95
alice
100

5.6 JSON 文档类型

Kvrocks 原生支持 JSON 类型，路径使用 $ 表示根（实测根路径写成 . 会报 ERR Invalid argument: new objects must be created at the root）：

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning JSON.SET user:2001 $ '{"name":"admin","age":18,"tags":["ops","dba"]}'
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning JSON.GET user:2001 $
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning JSON.GET user:2001 $.name

实测回显：

OK
[{"age":18,"name":"admin","tags":["ops","dba"]}]
["admin"]

5.7 键扫描与 DBSIZE 说明

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning SCAN 0 COUNT 100
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning TYPE user:1001
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning DBSIZE

实测回显（DBSIZE 为估算值，见说明）：

greeting
leaderboard
tags
taskqueue
user:1001
hash
0

💡 说明：Kvrocks 不直接维护 key 总数，DBSIZE 依赖 dbsize 扫描任务估算（配置 dbsize-scan-cron 定时校准），未扫描时可能返回 0 而 SCAN 实际可扫到全部 key，以 SCAN 或业务侧计数为准。

六、NAMESPACE 命名空间管理

namespace 是 Kvrocks 的多租户机制：每个 namespace 一个访问令牌，客户端用令牌当作 AUTH 密码连接，即隔离访问对应命名空间的数据；主口令（requirepass）可见所有命名空间。

6.1 创建与查看

⚠️ 前提：requirepass 非空（实测空口令时报 ERR forbidden to add namespace when requirepass was empty）。

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning NAMESPACE SET ns1 token-ns1-12345678
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning NAMESPACE SET ns2 token-ns2-87654321
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning NAMESPACE GET ns1
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning NAMESPACE GET ns2

实测回显：

OK
OK
token-ns1-12345678
token-ns2-87654321

6.2 令牌隔离验证

redis-cli -p 6666 -a token-ns1-12345678 --no-auth-warning SET k1 v1-ns1
redis-cli -p 6666 -a token-ns1-12345678 --no-auth-warning GET k1
redis-cli -p 6666 -a token-ns2-87654321 --no-auth-warning GET k1
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning GET k1

实测回显（ns2 令牌读不到 ns1 的 key，主口令可见）：

OK
v1-ns1

v1-ns1

6.3 当前命名空间与删除

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning NAMESPACE CURRENT
redis-cli -p 6666 -a token-ns2-87654321 --no-auth-warning NAMESPACE CURRENT
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning NAMESPACE DEL ns2
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning NAMESPACE GET ns2
redis-cli -p 6666 -a token-ns2-87654321 --no-auth-warning PING

实测回显（删除后旧令牌立即失效）：

__namespace
ns2
OK

Warning: AUTH failed
NOAUTH Authentication required.

💡 说明：NAMESPACE 子命令为 GET、SET、DEL、ADD、CURRENT（实测不支持通配查询，传其他值报 ERR NAMESPACE subcommand must be one of GET, SET, DEL, ADD and CURRENT）。namespace 配置随 CONFIG SET 机制持久化在配置文件尾部（形如 namespace.ns1 token-ns1-12345678），重启不丢。

七、监控与诊断命令

7.1 INFO 信息查看

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning INFO server | head -20

实测回显：

# Server
version:2.17.0
kvrocks_version:2.17.0
redis_version:7.0.0
git_sha1:
kvrocks_git_sha1:
redis_mode:standalone
kvrocks_mode:standalone
os:Linux 6.8.0-138-generic x86_64
gcc_version:11.4.0
rocksdb_version:11.8.1
arch_bits:64
process_id:35084
tcp_port:6666
server_time_usec:1791730411616118
uptime_in_seconds:24
uptime_in_days:0
executable:/opt/kvrocks/bin/kvrocks
config_file:/opt/kvrocks/conf/kvrocks.conf

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning INFO persistence

实测回显：

# Persistence
loading:0
bgsave_in_progress:0
last_bgsave_time:1791730503
last_bgsave_status:ok
last_bgsave_time_sec:0

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning INFO keyspace

实测回显：

# Keyspace
last_dbsize_scan_timestamp:0
db0:keys=0,expires=0,avg_ttl=0,expired=0
sequence:18
used_db_size:0
max_db_size:0
used_percent:0%
disk_capacity:843834499072
used_disk_size:477180559360
used_disk_percent:56.549069738766946%

7.2 CONFIG 参数查看与修改

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG GET port
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG GET maxclients
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG SET slowlog-log-slower-than 0
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG SET slowlog-log-slower-than 100000

实测回显：

port
6666
maxclients
10000
OK
OK

⚠️ 注意：Kvrocks 的 CONFIG SET 会把修改自动持久化到配置文件尾部，重启仍生效。

7.3 慢日志 SLOWLOG

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG SET slowlog-log-slower-than 0
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning SET slowtest 1
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning SLOWLOG LEN
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning SLOWLOG GET 1
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning SLOWLOG RESET
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG SET slowlog-log-slower-than 100000

实测 SLOWLOG GET 片段（字段依次为序号、时间戳、耗时微秒、命令、参数、客户端地址）：

4
1791730723
3
AUTH
q1w2e3r4
127.0.0.1:41126

7.4 连接与命令统计

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CLIENT LIST
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning COMMAND COUNT

实测回显（CLIENT LIST 含 kvrocks 特有的 namespace 字段）：

id=5 addr=127.0.0.1:34960 fd=51 name= age=0 idle=0 flags=N namespace=__namespace qbuf=0 obuf=0 cmd=client lib-name= lib-ver=
332

7.5 DEBUG 命令

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning DEBUG SLEEP 0.1

子命令清单（实测传非法参数时的提示）：

ERR Syntax error, DEBUG SLEEP <seconds>|PROTOCOL <type>|DBSIZE-LIMIT <0|1>

八、备份与恢复命令

8.1 手工备份 BGSAVE

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning BGSAVE

实测回显：

OK

备份产物落盘到数据目录 backup/（RocksDB checkpoint 形式），确认状态与文件：

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning INFO persistence | grep bgsave
ls /opt/kvrocks/data/backup/ | head -4

实测回显：

bgsave_in_progress:0
last_bgsave_time:1791730503
last_bgsave_status:ok
000014.sst
000015.sst
000016.sst
000017.log

备份保留策略由 max-backup-to-keep（默认 1）与 max-backup-keep-hours（默认 24）控制；定时备份在配置文件中加 bgsave-cron 0 4 * * *（每日 4 点）。

8.2 从备份恢复（实测流程）

停止服务，用备份目录整体替换 db 目录，再启动：

systemctl stop kvrocks
cd /opt/kvrocks/data
mv db db.old
cp -a backup db
systemctl start kvrocks

验证恢复结果：

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning GET greeting
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning LRANGE taskqueue 0 -1

实测回显（备份数据完整恢复）：

hello-kvrocks
task3
task2
task1

确认业务正常后清理旧库：

rm -rf /opt/kvrocks/data/db.old

九、kvrocks2redis 数据同步工具

kvrocks2redis 直接读取 Kvrocks 的 RocksDB 数据目录，把数据同步到目标 Redis 实例（同步前会清空目标库）。查看帮助：

/opt/kvrocks2redis/bin/kvrocks2redis -h

实测回显：

/opt/kvrocks/bin/kvrocks2redis sync kvrocks to redis
        -c <path> specifies the config file, defaulting to ./kvrocks2redis.conf
        -h print this help message
        -v print version information

9.1 同步配置文件

实测样例（同步默认命名空间到本机 6668 端口的目标实例）：

log-level INFO
daemonize yes
data-dir /opt/kvrocks2redis-test
output-dir /opt/kvrocks2redis-test
namespace.__namespace 127.0.0.1 6668

格式说明：namespace.{命名空间} <目标IP> <目标端口> [目标口令 目标DB号]，namespace.__namespace 代表默认命名空间；data-dir 指向 Kvrocks 数据目录（工具按 data-dir/db 读取 RocksDB），output-dir 存放同步位点文件 last_next_seq.txt。

⚠️ 注意：RocksDB 目录同一时刻只允许一个进程持有锁。kvrocks2redis 不能与正在运行的 kvrocks 共用同一 data-dir，应指向备份目录（复制 backup 内容为 data-dir/db）或从节点/停机实例的数据目录。

9.2 启动同步与验证（实测）

准备同步源（以备份为数据源）与目标实例后启动：

/opt/kvrocks/bin/kvrocks2redis -c /opt/kvrocks2redis-test/kvrocks2redis.conf

实测启动日志：

[2026-10-11 15:02:30.760] [kvrocks2redis] [info] [main.cc:117] kvrocks2redis version 2.17.0

验证目标实例（6668）数据：

redis-cli -p 6668 GET greeting
redis-cli -p 6668 LRANGE taskqueue 0 -1

实测回显：

hello-kvrocks
task3
task2
task1

十、注意事项

  1. redis-cli 连接端口务必带 -p 6666（默认 6379 连不上）。
  2. -a 方式传口令会被 redis-cli 提示 Warning，脚本中统一加 --no-auth-warning，或用交互式 AUTH。
  3. BGSAVE 是 checkpoint 快照不是压缩包，恢复时是目录级替换；异机容灾需另行打包传输 backup 目录。
  4. kvrocks2redis 会 FLUSH 目标库，误指生产目标会清空数据。
  5. NAMESPACE 的令牌即认证密码，删除 namespace 即吊销令牌，变更后需同步下发业务方。
  6. CONFIG SET 全部即时持久化到配置文件尾部，多人运维时先查文件尾部追加段再手工编辑，避免互相覆盖。

十一、常见问题（FAQ）

Q1：PING 返回 NOAUTH Authentication required.？ 服务端设置了 requirepass。带 -a q1w2e3r4（或交互式 AUTH）重连即可；namespace 令牌同样以 -a 方式使用。

Q2：DBSIZE 是 0 但 SCAN 有数据？ DBSIZE 是估算值，依赖 dbsize 扫描任务；启用 dbsize-scan-cron 后按周期校准，属 Kvrocks 正常行为，不是数据丢失。

Q3：SHUTDOWN 命令执行后连接报 Connection refused 但 ps 还能看到进程？ 优雅停机等待 RocksDB 落盘需要数秒，期间进程处于退出流程；daemonize 裸跑模式下父进程若未回收子进程可能出现 defunct 条目，不影响数据安全，systemd 托管无此现象。

Q4：JSON.SET 报 ERR Invalid argument: new objects must be created at the root？ Kvrocks 的 JSON 路径语法要求根路径用 $（如 JSON.SET key $ '{"k":"v"}'），用 RedisJSON 风格的 . 会报此错。

Q5：NAMESPACE SET 报 forbidden？ namespace 机制要求 requirepass 已设置；先 CONFIG SET requirepass（或写入配置文件）再操作。

Q6：systemctl stop 后 systemctl start 报 TimeoutSec 超时？ 多为 supervised 未设为 auto（Type=notify 收不到就绪信号），或数据目录属主不是运行用户导致 RocksDB 打开失败，查看 journalctl -u kvrocks 定位具体报错行。

十二、参考链接