Ubuntu 22.04 安装 Apache Kvrocks 2.17.0 指南

在 Ubuntu 22.04 上从 0 到 1 编译安装 Apache Kvrocks 2.17.0 并以 systemd 托管开机自启，含双方案安装、redis-cli 验证回显与常见问题排查。

Apache KvrocksApache Kvrocks2026/10/12

Ubuntu 22.04 安装 Apache Kvrocks 2.17.0 指南

目标：在 Ubuntu 22.04 服务器上从零完成 Apache Kvrocks 2.17.0 的下载、编译、安装、配置、systemd 托管与 redis-cli 连通验证，已在 Ubuntu 22.04.5 LTS（x86_64）环境实测通过，安装目录 /opt/kvrocks，服务端口 6666。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Apache Kvrocks：2.17.0（当前最新稳定版，编译产物 kvrocks version 2.17.0）
  • 编译工具链：gcc 11.4.0、cmake 3.22.1、git 2.34.1
  • 存储引擎：RocksDB 11.8.1（编译时由构建脚本自动拉取）
  • 服务端口：6666（Kvrocks 默认端口，兼容 Redis 协议）
  • 安装目录：/opt/kvrocks（二进制 bin/、配置 conf/、数据 data/）
  • 实测账号密码：示例认证口令 q1w2e3r4

二、前置条件

2.1 系统与网络要求

  • Ubuntu 22.04（20.04 及以上亦可，需 gcc 9+/cmake 3.16+）
  • 服务器可访问 GitHub（下载源码包与编译依赖，编译阶段会自动拉取 RocksDB、jemalloc 等依赖包）
  • 内存：编译期建议 ≥ 8GB（RocksDB 源码编译为内存大户）；运行期 2GB 起步
  • 磁盘：编译期约需 10GB 空闲空间（依赖源码 + 中间产物约 5GB，二进制约 1.2GB）；运行期按数据量规划 SSD

2.2 安装编译依赖

apt-get update
apt-get install -y build-essential cmake autoconf automake libtool python3 git wget curl redis-tools

实测版本确认：

gcc --version | head -1
cmake --version | head -1
git --version
redis-cli --version

实测回显：

gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0
cmake version 3.22.1
git version 2.34.1
redis-cli 6.0.16

💡 说明：redis-cli 由 redis-tools 包提供，仅作为兼容 Redis 协议的客户端验证工具，不与 Kvrocks 端口冲突。

2.3 创建运行用户与目录

useradd -r -s /sbin/nologin kvrocks
mkdir -p /opt/kvrocks/bin /opt/kvrocks/conf /opt/kvrocks/data

三、版本选型说明

Kvrocks 官方发布渠道为 GitHub Releases（apache/kvrocks），官方不提供预编译二进制包，Release 资产中仅有源码标签，需自行编译。查询最新稳定版本：

curl -s https://api.github.com/repos/apache/kvrocks/releases/latest | grep -E '"tag_name"|"name"' | head -2

实测回显（2026-10-11 查询）：

  "tag_name": "v2.17.0",
  "name": "2.17.0",

近期版本发布时间线（实测查询 GitHub API）：

版本发布日期说明
v2.17.02026-09-19当前最新稳定版，本文实测版本
v2.16.02026-06-21上一稳定版
v2.15.02026-02-27上一稳定版
v2.14.02025-11-11旧稳定版

💡 说明：Kvrocks 内置 RocksDB 引擎（2.17.0 锁定 RocksDB v11.8.1），编译脚本会自动下载依赖，无需手动安装。兼容 Redis 协议（INFO 中 redis_version 显示 7.0.0），可直接用 redis-cli 连接。

四、方案 A：官方源码包编译安装（推荐）

4.1 下载官方源码包

cd /tmp
wget https://github.com/apache/kvrocks/archive/refs/tags/v2.17.0.tar.gz -O kvrocks-2.17.0.tar.gz

校验完整性（实测本包 sha256）：

sha256sum kvrocks-2.17.0.tar.gz

实测回显：

1e47c9b561e618f154ee7a610bb03b8636332cc239a4d6cbf72e301de654f6eb  kvrocks-2.17.0.tar.gz

4.2 解压源码

tar xzf kvrocks-2.17.0.tar.gz
cd kvrocks-2.17.0

⚠️ 注意：若服务器直连 GitHub 超时，可先为 wget 配置可用的 HTTP 代理（wget 会读取环境变量 http_proxy/https_proxy），或提前将源码包下载后上传至内网制品库再执行本节步骤。

4.3 编译（官方构建脚本 x.py）

官方提供 x.py 构建脚本（内部执行 cmake 配置 + 编译，目标产物为 kvrocks 与 kvrocks2redis）：

./x.py build -j $(nproc)

实测编译末尾回显（依赖自动拉取 RocksDB 11.8.1、jemalloc、libevent、spdlog、tbb 等）：

[100%] Linking CXX executable kvrocks

确认产物：

ls -la build/kvrocks build/kvrocks2redis

实测回显：

-rwxr-xr-x 1 root root 560569128 Oct 11 14:38 build/kvrocks
-rwxr-xr-x 1 root root 556989536 Oct 11 15:00 build/kvrocks2redis

⚠️ 注意：编译内存受限（如 8GB 以下）时，-j 并发数过高会触发 cc1plus 被内核 Kill（OOM），报错形如 c++: fatal error: Killed signal terminated program cc1plus。此时改用低并发续编即可（增量编译不会重头开始）：./x.py build -j 2。实测在 4GB 内存上限环境中以 -j 12 失败、-j 4 编译 RocksDB 通过、最终以 -j 2 完成全部编译。

4.4 安装到 /opt/kvrocks

cp build/kvrocks build/kvrocks2redis /opt/kvrocks/bin/
cp kvrocks.conf /opt/kvrocks/conf/
chown -R kvrocks:kvrocks /opt/kvrocks

验证版本：

/opt/kvrocks/bin/kvrocks --version

实测回显：

kvrocks version 2.17.0

查看命令行用法：

/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>

五、方案 B：git clone 官方仓库编译安装

适合需要固定 tag 或后续跟进源码改动的场景：

cd /opt
git clone https://github.com/apache/kvrocks.git
cd kvrocks
git checkout v2.17.0
./x.py build -j $(nproc)

编译产物位于 /opt/kvrocks（仓库目录）下的 build/ 子目录，后续安装步骤与方案 A 的 4.4 节完全一致。

💡 说明：方案 A 与方案 B 编译产物完全一致，仅源码获取方式不同。离线服务器推荐方案 A（单包下载），开发调试推荐方案 B。

六、多方案对比与选择建议

维度方案 A：官方源码包编译方案 B：git clone 编译
版本固定 tag v2.17.0任意 tag/分支
是否需联网需（下载 1 包 + 编译依赖）需（完整仓库 + 编译依赖）
安装方式tar 解压 + x.py 编译git clone + x.py 编译
产物kvrocks、kvrocks2redis与方案 A 一致
服务托管手写 systemd 单元（见第八章）同左
监听端口6666（可配置）同左
优点包小（约 1.2MB）、可校验 sha256可跟踪分支与补丁
缺点升级需重新下载仓库体积大

选择建议：可联网生产服务器选方案 A；需要频繁切换源码版本或参与二次开发选方案 B；完全离线的环境在能上网的机器按方案 A 编译后，将 build/kvrocks、build/kvrocks2redis、kvrocks.conf 三个文件拷贝至目标服务器按 4.4 节布局落位即可。

七、配置说明

7.1 关键配置项

编辑 /opt/kvrocks/conf/kvrocks.conf，生产单实例最简修改（其余保持默认）：

bind 0.0.0.0
port 6666
workers 8
daemonize no
db-name kvrocks-ops.db
dir /opt/kvrocks/data
requirepass q1w2e3r4

关键项说明：

配置项默认值说明
bind127.0.0.1监听地址，远程访问需改为 0.0.0.0 或指定网卡 IP
port6666监听端口（Kvrocks 默认 6666，非 Redis 的 6379）
workers8工作线程数，建议与 CPU 核数相近
daemonizenosystemd 托管时必须保持 no（由 systemd 管理进程）
db-namechange.me.db数据库名标识，主从复制时主从必须一致，建议按业务命名
dir/tmp/kvrocks数据目录，务必改为持久磁盘路径（本例 /opt/kvrocks/data）
requirepass未启用访问口令，生产必配（示例口令 q1w2e3r4）

7.2 目录布局与权限

/opt/kvrocks/
├── bin/
│   ├── kvrocks           # 服务主程序
│   └── kvrocks2redis     # 数据同步工具
├── conf/
│   └── kvrocks.conf      # 配置文件
└── data/                 # 数据目录（首次启动自动生成）
    ├── db/               # RocksDB 数据文件
    ├── backup/           # BGSAVE 备份目录
    └── kvrocks_YYYY-MM-DD.log

7.3 手工启动与停止（验证配置可用）

启动（daemonize no 时配合后台符，验证配置是否正确）：

/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

生产守护方式建议直接用 systemd（见第八章）；若临时以 daemonize yes 方式运行，停止可使用 redis-cli 的 SHUTDOWN 命令（优雅停机，RocksDB 关闭约需数秒）：

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

八、systemd 开机自启

8.1 编写服务单元

源码包内自带单元模板（utils/systemd/kvrocks.service），按实际路径适配后写入 /etc/systemd/system/kvrocks.service：

[Unit]
Description=Apache Kvrocks SSD key-value database
Documentation=https://kvrocks.apache.org
Wants=network-online.target
After=network-online.target

[Service]
Type=notify
User=kvrocks
Group=kvrocks
ExecStart=/opt/kvrocks/bin/kvrocks -c /opt/kvrocks/conf/kvrocks.conf
Restart=on-failure
RestartSec=10s
LimitNOFILE=100000
TimeoutSec=300

[Install]
WantedBy=multi-user.target

8.2 适配 supervised 模式

单元使用 Type=notify，要求 kvrocks 向 systemd 上报就绪信号，配置文件中 supervised 必须设为 auto（或 systemd），否则服务会在超时后启动失败：

supervised auto

8.3 启用并启动

systemctl daemon-reload
systemctl enable kvrocks
systemctl start kvrocks

实测 systemctl enable kvrocks 回显：

Created symlink /etc/systemd/system/multi-user.target.wants/kvrocks.service → /etc/systemd/system/kvrocks.service.

8.4 状态与自启确认

systemctl is-active kvrocks
systemctl is-enabled kvrocks
systemctl status kvrocks --no-pager -n 3

实测回显：

active
enabled
● 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.

重启与停止验证：

systemctl restart kvrocks
systemctl stop kvrocks
systemctl is-active kvrocks
systemctl start kvrocks

实测回显（stop 后为 inactive，start 后恢复 active）：

inactive
active

⚠️ 注意：systemd 托管依赖真实 systemd 环境（服务器默认满足）。若 systemctl start 后长时间卡在 activating 直至超时，检查配置文件 supervised 是否已设为 auto（见第十一章 FAQ）。

九、安装验证与基础使用

9.1 连通性验证

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

实测回显：

PONG

9.2 五大基础数据类型实测

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 HSET user:1001 name admin age 18 city hangzhou
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning HGETALL user:1001
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
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

实测回显：

OK
hello-kvrocks
3
name
admin
age
18
city
hangzhou
3
task3
task2
task1
3
apache
kvrocks
redis
2
bob
95
alice
100

9.3 服务端信息确认

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

9.4 重启持久化验证

systemctl restart kvrocks
sleep 3
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning GET greeting

实测回显（重启后数据完好，基于 RocksDB 持久化）：

hello-kvrocks

十、注意事项

  1. Kvrocks 默认端口是 6666 而非 6379，客户端连接务必带 -p 6666。
  2. dir 默认指向 /tmp/kvrocks，重启即丢数据风险，安装后第一件事改为持久磁盘路径。
  3. 主从复制要求主从 db-name 一致，从默认值 change.me.db 改为业务标识。
  4. systemd 单元为 Type=notify，配置中 supervised 须设为 auto，二者必须配套。
  5. 生产必须配置 requirepass（Kvrocks 密码爆破速率极高，官方文档明确警示），且建议配合 namespace 做多租户隔离。
  6. 编译产物约 1.1GB/个（含调试符号），磁盘紧张时可用 strip /opt/kvrocks/bin/kvrocks 瘦身。
  7. Kvrocks 未对 AUTH 做连接级防爆破限速，公网环境建议再加防火墙白名单。

十一、常见问题（FAQ）

Q1：编译报错 c++: fatal error: Killed signal terminated program cc1plus？ 内存不足导致编译进程被 OOM Kill。解决：降低并发续编 ./x.py build -j 2（增量编译，已编译对象不重复），内存 8GB 以上机器建议直接 -j $(nproc)。

Q2：GitHub Releases 找不到二进制包？ 官方不发布预编译二进制，Release 资产仅含源码标签，所有平台均需源码编译（方案 A/B）。这是官方分发策略，非下载故障。

Q3：systemctl start 卡在 activating 后报超时？ 单元 Type=notify 与配置 supervised no 不匹配，kvrocks 从未向 systemd 发送就绪信号。解决：在 kvrocks.conf 中设置 supervised auto 后 systemctl restart kvrocks。

Q4：启动失败 Failed to load config. Error: failed to open file '/opt/kvrocks/conf/kvrocks.conf': No such file or directory？ -c 指定的配置文件路径不存在或运行用户（kvrocks）无读取权限。逐一确认：文件存在、属主 chown kvrocks:kvrocks、SELinux/AppArmor 未拦截。

Q5：DBSIZE 返回 0 但 SCAN 能扫到 key？ Kvrocks 不直接维护 key 计数，DBSIZE 依赖 dbsize 扫描任务（配置 dbsize-scan-cron 定时触发，如 dbsize-scan-cron 0 * * * * 每小时校准）。属正常现象，以 SCAN/业务计数为准。

Q6：NAMESPACE SET 报 ERR forbidden to add namespace when requirepass was empty？ namespace 令牌机制依赖访问口令，先 CONFIG SET requirepass q1w2e3r4（或写入配置文件）后再管理 namespace。

Q7：redis-cli SHUTDOWN 后端口仍短暂拒绝但进程残留？ 优雅停机需等待 RocksDB 落盘完成（数秒），进程随即退出；若父进程未回收子进程可能出现 defunct 僵尸项，不影响端口释放与数据安全，systemd 托管时由 systemd 自动回收，无此现象。

十二、卸载方式

systemctl stop kvrocks
systemctl disable kvrocks
rm -f /etc/systemd/system/kvrocks.service
systemctl daemon-reload
userdel kvrocks
rm -rf /opt/kvrocks
rm -rf /tmp/kvrocks-2.17.0 /tmp/kvrocks-2.17.0.tar.gz

数据如需保留，先备份 /opt/kvrocks/data/db 目录再执行删除。

十三、参考链接