Apache ResilientDB 常用 CLI 命令与工具详解

详解 Apache ResilientDB 命令行工具：kv_service_tools 读写、版本化、范围与历史命令，kv_service 服务端进程，证书与启停脚本及端口排查，参数含义与真实回显均实测

Apache ResilientDBApache ResilientDB2026/10/12

Apache ResilientDB 常用 CLI 命令与工具详解

目标：详解 Apache ResilientDB 的常用命令行工具——kv_service_tools 客户端全部读写命令、kv_service 服务端进程、证书/启停脚本与端口排查工具，覆盖参数含义与真实回显。所有命令与回显均在 Ubuntu 22.04.5 实测环境逐条执行。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • 源码：master 分支 commit 4de5cb43686276ace4307f44839a1de920ab524a
  • 源码目录：/root/incubator-resilientdb
  • Bazel：6.0.0
  • 服务端口：副本 10001-10004，客户端代理 10005
  • 客户端工具：bazel-bin/service/tools/kv/api_tools/kv_service_tools
  • 运行用户：root

二、工具概览

工具位置用途
kv_service_toolsbazel-bin/service/tools/kv/api_tools/KV 读写客户端（set/get/版本化/范围/历史/Top/SQL）
kv_servicebazel-bin/service/kv/服务端进程（副本与客户端代理同一二进制，按证书区分角色）
generate_keys_and_certs.shservice/tools/kv/server_tools/生成节点证书与公私钥
start_kv_service.shservice/tools/kv/server_tools/编译并启动 4 副本 + 1 客户端代理
killall / netstat / pgrep系统自带（psmisc / net-tools / procps）进程与端口排查

三、前置条件

  • 已按《Ubuntu 22.04 安装 Apache ResilientDB 指南》完成源码编译、证书生成与服务启动，netstat -tln | grep -c 1000 返回 5。
  • 以下命令均在源码目录 /root/incubator-resilientdb 内执行；客户端配置统一使用 service/tools/config/interface/service.config（指向客户端代理 10005）。
  • 客户端工具首次连接会在 STDERR 打印一行 glog 配置解析提示（WARNING: Logging before InitGoogleLogging() 与 parse json id:1 ip:127.0.0.1 port:10005），属正常现象，下文回显中省略该行。

四、工具详解

4.1 kv_service_tools 客户端

查看用法：

./bazel-bin/service/tools/kv/api_tools/kv_service_tools --help

回显：

--config: config path
--cmd set/get/set_with_version/get_with_version/get_key_range/get_key_range_with_version/get_top/get_history/sql
--key key
--value value, if cmd is a get operation
--sql SQL text, if cmd is sql
--version version of the value, if cmd is vesion based
--min_key the min key if cmd is get_key_range
--max_key the max key if cmd is get_key_range
--min_version, if cmd is get_history
--max_version, if cmd is get_history
--top, if cmd is get_top

More examples can be found from README.

参数速查：

参数说明备注
--config客户端入口配置文件路径必填，缺省时打印 usage 后报 Failed to open file. No such file or directory
--cmd子命令，取值见上方 usage必填
--key / --value键与值set 写入；get 读取
--version版本号，版本化函数使用0 表示读取最新版本
--min_key / --max_key范围查询的键区间get_key_range / get_key_range_with_version 使用
--min_version / --max_version历史查询的版本区间get_history 使用
--top返回条数get_top 使用
--sqlSQL 语句文本sql 子命令使用

💡 每条命令一次执行完成即退出（非交互式），便于脚本化运维与监控探测。

4.1.1 set：写入键值

./bazel-bin/service/tools/kv/api_tools/kv_service_tools \
    --config service/tools/config/interface/service.config \
    --cmd set --key user1001 --value alice

回显：

set key = user1001, value = alice done, ret = 0

4.1.2 get：读取键值

./bazel-bin/service/tools/kv/api_tools/kv_service_tools \
    --config service/tools/config/interface/service.config \
    --cmd get --key user1001

回显：

get key = user1001 value = alice

读取不存在的键不报错，value 为空：

./bazel-bin/service/tools/kv/api_tools/kv_service_tools \
    --config service/tools/config/interface/service.config \
    --cmd get --key nosuchkey

回显：

get key = nosuchkey value =

4.1.3 set_with_version：按版本写入

先写入 v1，再用版本化写入 v2（--version 0 表示以当前最新版本为基准做乐观更新）：

./bazel-bin/service/tools/kv/api_tools/kv_service_tools \
    --config service/tools/config/interface/service.config \
    --cmd set --key alpha --value v1

回显：

set key = alpha, value = v1 done, ret = 0

./bazel-bin/service/tools/kv/api_tools/kv_service_tools \
    --config service/tools/config/interface/service.config \
    --cmd set_with_version --key alpha --version 0 --value v2

回显：

set key = alpha, value = v2, version = 0 done, ret = 0

current value = value: "v2"
version: 1

若请求的 --version 与当前版本不匹配，写入会被忽略（乐观锁语义）。实测对已处于 version 1 的 alpha 再提交 --version 0 --value stale：

set key = alpha, value = stale, version = 0 done, ret = 0

current value = value: "v2"
version: 1

⚠️ 第一行 done, ret = 0 只表示事务已提交处理，实际是否生效以 current value / version 两行为准；版本冲突时当前值保持不变。

4.1.4 get_with_version：按版本读取

--version 0 返回最新版本：

./bazel-bin/service/tools/kv/api_tools/kv_service_tools \
    --config service/tools/config/interface/service.config \
    --cmd get_with_version --key alpha --version 0

回显：

get key = alpha, value = value: "v2"
version: 1

4.1.5 get_history：键的版本历史

./bazel-bin/service/tools/kv/api_tools/kv_service_tools \
    --config service/tools/config/interface/service.config \
    --cmd get_history --key alpha --min_version 1 --max_version 2

回显：

get history key = alpha, min version = 1, max version = 2
 value = item {
  key: "alpha"
  value_info {
    value: "v2"
    version: 1
  }
}

4.1.6 get_key_range / get_key_range_with_version：范围查询

带版本的范围查询返回区间内带版本信息的项：

./bazel-bin/service/tools/kv/api_tools/kv_service_tools \
    --config service/tools/config/interface/service.config \
    --cmd get_key_range_with_version --min_key alpha --max_key gamma

回显：

min key = alpha max key = gamma
getrange min key = alpha, max key = gamma
 value = item {
  key: "alpha"
  value_info {
    value: "v2"
    version: 1
  }
}

非版本范围查询 get_key_range 在本版本对仅经非版本 set 写入的键返回空列表（实测 --min_key user1001 --max_key user1002 且两键均存在时）：

getrange min key = user1001, max key = user1002
 value = []

⚠️ 需要范围语义时优先使用 get_key_range_with_version；get_key_range 的空结果不代表键不存在，可用 get 单键复核。

4.1.7 get_top：按序取前 N 条

./bazel-bin/service/tools/kv/api_tools/kv_service_tools \
    --config service/tools/config/interface/service.config \
    --cmd get_top --top 3

回显（本版本实测对 KV 服务返回空列表）：

key = , top 3
 value =

4.1.8 sql：SQL 查询入口

./bazel-bin/service/tools/kv/api_tools/kv_service_tools \
    --config service/tools/config/interface/service.config \
    --cmd sql --sql "select * from kv"

回显（KV 服务未启用 SQL 模块，仅返回结果头）：

SQL result:

⚠️ SQL 能力面向 SQL 服务形态，KV 服务进程下无数据返回；实际项目中请勿依赖该入口做 KV 查询。

4.2 kv_service 服务端进程

kv_service 为单一二进制，通过命令行参数区分角色：第 1 个参数是服务端配置，第 2、3 个参数分别是本节点私钥与证书。node1-4 为共识副本，node5 为客户端代理：

./bazel-bin/service/kv/kv_service service/tools/config/server/server.config \
    service/tools/data/cert/node1.key.pri service/tools/data/cert/cert_1.cert

💡 日常不建议手工单进程拉起，统一使用 start_kv_service.sh 或 systemd 托管（见 4.3 节）；手工方式仅用于单副本调试。

服务运行期间，进程 stdout 持续输出共识与监控日志。典型片段：

E20261012 14:35:48.372143 19063 consensus_manager.cpp:228] receive public size:5 primary:1 version:1 from region:1 sender:3 last send:0 current v:0
E20261012 14:35:36.410799 18814 stats.cpp:424] =========== monitor =========
server call:0 server process:0 socket recv:0 client call:0 client req:0 broad_cast:0 send broad_cast:0 per send broad_cast:0 propose:0 prepare:0 commit:0 pending execute:0 execute:0 execute done:0 seq gap:0 total request:0 txn:0 total geo request:0 total geo request per:0 geo request:0 seq fail:0 time:470
--------------- monitor ------------
  • consensus_manager 行中的 primary:1 表示 id=1 的副本为当前主副本，receive public size:5 表示 5 个进程互相可见。
  • monitor 段按周期滚动输出统计计数（client req、commit、execute done 等），可作为轻量健康观测。

4.3 服务启停脚本与 systemd

4.3.1 生成证书：generate_keys_and_certs.sh

./service/tools/kv/server_tools/generate_keys_and_certs.sh

脚本先编译 //tools:certificate_tools 与 //tools:key_generator_tools，再按 5 个 127.0.0.1 节点生成密钥，输出 service/tools/data/cert/ 下的 node1-5.key.pri/.pub、cert_1-5.cert 与 admin.key.pri/.pub（完整回显见《Ubuntu 22.04 安装 Apache ResilientDB 指南》4.4 节）。

4.3.2 启动与停止：start_kv_service.sh

./service/tools/kv/server_tools/start_kv_service.sh

脚本内部依次执行：killall -9 kv_service 清理旧进程 → bazel build //service/kv:kv_service 增量编译（已编译时为秒级 no-op）→ 以 nohup 逐个拉起 4 个副本与 1 个客户端代理。停止服务用 killall：

killall -9 kv_service
pgrep -c kv_service

回显（已全部停止时）：

0

4.3.3 systemd 托管

生产环境建议用 systemd 托管（单元文件与 ExecStart=/bin/bash 调用方式见《Ubuntu 22.04 安装 Apache ResilientDB 指南》4.8 节），常用命令逐条执行：

systemctl start resilientdb-kv
systemctl is-active resilientdb-kv
systemctl stop resilientdb-kv

实测 systemctl is-active 在运行时返回 active（systemctl status 显示 Memory: 94.9M），停止后返回 inactive。

4.4 进程与端口排查工具

4.4.1 端口监听核查

netstat -tlnp | grep 1000

正常应看到 10001-10005 五个 LISTEN（回显见《Ubuntu 22.04 安装 Apache ResilientDB 指南》4.5 节）。快速计数：

netstat -tln | grep -c 1000

回显：

5

4.4.2 进程核查

ps aux | grep [k]v_service | wc -l

回显：

5

五、注意事项

  • 版本化函数与非版本函数使用两套存储：实测对同一键 alpha，get 返回非版本写入的 v1，get_with_version 返回版本化写入的 v2（version 1）。官方明确两者不可混用于同一应用。
  • get_key_range 非版本范围查询在仅存非版本键时返回空列表（实测行为），判断键是否存在用 get 单键复核。
  • 客户端工具每条命令独立执行、即用即退；对线上集群操作时逐条执行并核对回显，避免批量循环。
  • 服务端默认内存存储，进程重启后数据清空；killall 停止即丢数据，生产需 --define=enable_leveldb=True 编译并配置 leveldb_info。
  • 日志以进程 stdout 落在启动目录（server0.log ~ server3.log、client.log），排障优先看这里而非退出码。

六、常见问题

6.1：执行客户端命令打印 usage 并报 Failed to open file. No such file or directory

定位：--config 未传或路径错误。 解决：在源码目录内执行并使用相对路径 service/tools/config/interface/service.config，或改用绝对路径。

6.2：set/get 卡顿或超时无回显

定位：客户端代理（10005）未启动或副本共识未就绪。 解决：netstat -tlnp | grep 1000 核对 5 个端口；查看 server0.log 是否出现 receive public size:5 primary:1 共识就绪日志；必要时重启服务。

6.3：killall -9 kv_service 报无进程

定位：服务未启动，属正常提示。 解决：先执行 start_kv_service.sh 或 systemctl start resilientdb-kv 再做运维操作。

6.4：set_with_version 返回 done, ret = 0 但值没有更新

定位：乐观锁版本冲突，请求的 --version 与当前版本不一致时写入被忽略（实测回显见 4.1.3 节）。 解决：先用 get_with_version --version 0 取最新版本号，再以该版本号提交更新。

七、参考链接