Apache Kvrocks 2.17.0 Docker Compose 部署指南

使用官方 apache/kvrocks 镜像以 Docker Compose 部署 Apache Kvrocks 2.17.0，覆盖镜像选型、数据持久化、配置挂载、等价 docker run 与常见故障排查。

Apache KvrocksApache Kvrocks2026/10/12

Apache Kvrocks 2.17.0 Docker Compose 部署指南

目标：使用官方 apache/kvrocks 镜像通过 Docker Compose 从零部署 Apache Kvrocks 2.17.0 单实例，完成数据持久化、配置文件挂载、等价 docker run 与日常运维验证，已在 Docker 29.8.1 + Docker Compose v5.5.1 环境实测通过，服务端口 6666。

一、环境信息

  • Apache Kvrocks 镜像：apache/kvrocks:2.17.0（官方镜像，镜像内 kvrocks version 2.17.0 (commit 185d4221)）
  • Docker Engine：29.8.1
  • Docker Compose：v5.5.1（docker compose 插件形态）
  • 宿主系统：Ubuntu 22.04 LTS（x86_64）
  • 服务端口：6666（容器内默认监听，镜像已 EXPOSE 6666）
  • 数据卷：/var/lib/kvrocks（镜像内数据与配置目录）
  • 部署目录：/srv/kvrocks（docker-compose.yml 所在目录）
  • 示例认证口令：q1w2e3r4

二、镜像选型说明

2.1 官方镜像

Kvrocks 官方（Apache）在 Docker Hub 维护 apache/kvrocks 镜像，与 GitHub Releases 版本同步发布，选型即选它，无需自行构建。实测可拉取的版本标签：

镜像标签实测结果说明
apache/kvrocks:2.17.0实测拉取成功（162MB）当前最新稳定版，本文实测版本
apache/kvrocks:2.16.0实测拉取成功上一稳定版
apache/kvrocks:latest实测拉取成功，当前指向 2.17.0滚动最新，生产不建议使用（版本漂移）

拉取命令：

docker pull apache/kvrocks:2.17.0

实测回显：

docker.io/apache/kvrocks:2.17.0

2.2 镜像关键信息（实测）

项目值说明
启动入口 ENTRYPOINTkvrocks -c /var/lib/kvrocks/kvrocks.conf --dir /var/lib/kvrocks --pidfile /var/run/kvrocks/kvrocks.pid --bind 0.0.0.0完整启动命令，覆盖时需覆盖整个 entrypoint
运行用户999（kvrocks）挂载宿主目录需保证 UID 999 可写
内置配置文件/var/lib/kvrocks/kvrocks.conf与数据同目录
数据目录/var/lib/kvrocks持久化挂载点
暴露端口6666/tcpRedis 协议
内置健康检查redis-cli -p 6666 PING | grep -E '(PONG|NOAUTH)'，间隔 30s，超时 3s，启动等待 30s，重试 3 次Ps 列显示 (healthy)
环境变量仅 PATH 与 MALLOC_CONF（jemalloc 参数）镜像不支持环境变量注入业务配置

三、前置条件

3.1 安装 Docker 与 Compose 插件

curl -fsSL https://get.docker.com | bash
docker compose version

实测回显：

Docker Compose version v5.5.1

3.2 创建部署目录

mkdir -p /srv/kvrocks/data
cd /srv/kvrocks

⚠️ 注意：bind 挂载的 data 目录必须让容器内 UID 999 可写，否则 kvrocks 无法创建 RocksDB 文件：chown 999:999 /srv/kvrocks/data。

四、部署步骤

4.1 导出镜像自带配置文件

镜像把默认 kvrocks.conf 放在 /var/lib/kvrocks/ 内。若直接把空宿主目录挂到 /var/lib/kvrocks，会遮蔽该文件导致启动失败（详见 FAQ）。因此先将镜像内默认配置导出到宿主 data 目录：

docker run --rm -v /srv/kvrocks/data:/out --entrypoint sh apache/kvrocks:2.17.0 -c "cp /var/lib/kvrocks/kvrocks.conf /out/ && ls -la /out"

实测回显：

total 60
drwxr-xr-x 2 kvrocks kvrocks  4096 Oct 11 14:13 .
drwxr-xr-x 19 root    root    4096 Oct 11 14:13 ..
-rw-r--r-- 1 kvrocks kvrocks 51347 Oct 11 14:13 kvrocks.conf

4.2 编写 docker-compose.yml

services:
  kvrocks:
    image: apache/kvrocks:2.17.0
    container_name: kvrocks
    ports:
      - "6666:6666"
    volumes:
      - ./data:/var/lib/kvrocks
    restart: unless-stopped

4.3 启动与状态确认

cd /srv/kvrocks
docker compose up -d

实测回显：

 Container kvrocks Started

docker compose ps

实测回显：

NAME      IMAGE                   COMMAND                  SERVICE   CREATED          STATUS                    PORTS
kvrocks   apache/kvrocks:2.17.0   "kvrocks -c /var/lib…"   kvrocks   27 seconds ago   Up 26 seconds (healthy)   0.0.0.0:6666->6666/tcp, [::]:6666->6666/tcp

4.4 连通性与读写验证

redis-cli -h 127.0.0.1 -p 6666 SET greeting "hello-kvrocks"
redis-cli -h 127.0.0.1 -p 6666 GET greeting
redis-cli -h 127.0.0.1 -p 6666 INFO server | grep -E "kvrocks_version|tcp_port"

实测回显：

OK
hello-kvrocks
kvrocks_version:2.17.0
tcp_port:6666

五、数据持久化说明

5.1 数据目录结构

Kvrocks 的数据落在挂载的 /var/lib/kvrocks（宿主 ./data）下：

/srv/kvrocks/data/
├── db/                        # RocksDB 数据文件（SST/WAL/CURRENT 等）
├── kvrocks.conf               # 服务配置文件
└── kvrocks_2026-10-11.log     # 服务日志

5.2 down/up 持久化实测

cd /srv/kvrocks
docker compose down
docker compose up -d

实测回显：

 Network kvrocks_default Removing
 Network kvrocks_default Removed
 Container kvrocks Started

redis-cli -h 127.0.0.1 -p 6666 GET greeting

实测回显（容器重建后数据完好）：

hello-kvrocks

5.3 两种持久化方案

方案compose 片段特点
bind 挂载宿主目录- ./data:/var/lib/kvrocks数据位置直观可控；空目录会遮蔽镜像自带 conf，需按 4.1 预先导出
named volume- kvrocks-data:/var/lib/kvrocks首次启动自动把镜像内 conf 播种进卷，开箱即用；数据由 Docker 管理

named volume 完整写法（实测开箱即用，启动即 healthy）：

services:
  kvrocks:
    image: apache/kvrocks:2.17.0
    container_name: kvrocks
    ports:
      - "6666:6666"
    volumes:
      - kvrocks-data:/var/lib/kvrocks
    restart: unless-stopped

volumes:
  kvrocks-data:

六、常用环境变量表

官方镜像不提供业务配置类环境变量，配置只能通过配置文件挂载或启动参数覆盖实现。镜像内置的环境变量仅以下一项，通常无需改动：

环境变量实测默认值说明
MALLOC_CONFprof:true,prof_active:false,background_thread:truejemalloc 内存分配器参数，排查内存问题时开启采样用

💡 说明：若习惯 Redis 官方镜像那种 REDIS_PASSWORD 式环境变量，Kvrocks 官方镜像目前不支持；密码等配置改用第八章的启动参数覆盖方式。

七、常用配置参数说明（entrypoint/command 覆盖）

镜像 ENTRYPOINT 是一条完整的 kvrocks 启动命令，--<config-key> <config-value> 形式的参数可直接覆盖任意配置项。常用覆盖示例：

启动参数等价配置项作用
--bind 0.0.0.0bind监听地址（镜像默认已带）
--dir /var/lib/kvrocksdir数据目录（镜像默认已带）
--port 6667port监听端口
--requirepass q1w2e3r4requirepass访问口令
--workers 4workers工作线程数

实测带密码部署（覆盖 entrypoint 追加 --requirepass）：

services:
  kvrocks:
    image: apache/kvrocks:2.17.0
    container_name: kvrocks
    entrypoint: ["kvrocks", "-c", "/var/lib/kvrocks/kvrocks.conf", "--bind", "0.0.0.0", "--requirepass", "q1w2e3r4", "--dir", "/var/lib/kvrocks"]
    ports:
      - "6666:6666"
    volumes:
      - kvrocks-data:/var/lib/kvrocks
    restart: unless-stopped

volumes:
  kvrocks-data:

验证：

docker compose up -d
redis-cli -h 127.0.0.1 -p 6666 PING
redis-cli -h 127.0.0.1 -p 6666 -a q1w2e3r4 --no-auth-warning PING
redis-cli -h 127.0.0.1 -p 6666 -a q1w2e3r4 --no-auth-warning SET auth-test done
redis-cli -h 127.0.0.1 -p 6666 -a q1w2e3r4 --no-auth-warning GET auth-test

实测回显：

NOAUTH Authentication required.

PONG
OK
done

⚠️ 注意：override 时应覆盖整个 entrypoint:，而不是写 command:。镜像 CMD 为空，command: 里的内容会全部变成 ENTRYPOINT（kvrocks 进程）的尾部参数，末尾多出的位置参数会让 kvrocks 打印 Usage 后退出，容器进入 Restarting（实测复现，见 FAQ Q2）。

八、配置文件持久化（conf 挂载）

将宿主编写好的 kvrocks.conf 单独挂载进容器（conf 与数据分目录管理，改动即时生效于下次重启）：

8.1 准备配置文件

mkdir -p /srv/kvrocks/conf
cp /srv/kvrocks/data/kvrocks.conf /srv/kvrocks/conf/

按需修改关键字段（实测样例：监听 0.0.0.0、workers 调整为 4、数据目录指向容器内持久目录）：

bind 0.0.0.0
port 6666
workers 4
dir /var/lib/kvrocks/db

8.2 compose 挂载并覆盖 entrypoint

services:
  kvrocks:
    image: apache/kvrocks:2.17.0
    container_name: kvrocks
    entrypoint: ["kvrocks", "-c", "/etc/kvrocks/kvrocks.conf", "--dir", "/var/lib/kvrocks/db", "--bind", "0.0.0.0"]
    ports:
      - "6666:6666"
    volumes:
      - ./data:/var/lib/kvrocks
      - ./conf/kvrocks.conf:/etc/kvrocks/kvrocks.conf:ro
    restart: unless-stopped

8.3 验证自定义配置生效

cd /srv/kvrocks
docker compose up -d
docker compose ps --format "table {{.Name}}\t{{.Status}}"
redis-cli -h 127.0.0.1 -p 6666 CONFIG GET workers

实测回显：

NAME      STATUS
kvrocks   Up 8 seconds (healthy)

workers
4

💡 说明：镜像内置用户为 999，:ro 只读挂载的 conf 文件保证容器内不可改写宿主配置；如需在容器内用 CONFIG SET 且让其持久化，请去掉 :ro 并确保文件属主为 999。

九、等价 docker run 运行方式

与第四章 compose 等价（named volume 版）的单命令运行：

docker run -d --name kvrocks-run -p 16379:6666 -v kvrocks-run-data:/var/lib/kvrocks apache/kvrocks:2.17.0

实测回显：

162d9f0e230b9afb617e1b38893fb92afbcd39832b1d9bbd286f64909653d0e8

docker ps --filter name=kvrocks-run --format "{{.Names}} {{.Status}}"
redis-cli -h 127.0.0.1 -p 16379 SET run-test ok
redis-cli -h 127.0.0.1 -p 16379 GET run-test

实测回显：

kvrocks-run Up 8 seconds (healthy)
OK
ok

清理测试实例：

docker rm -f kvrocks-run
docker volume rm kvrocks-run-data

十、常用运维命令

以下命令均在 /srv/kvrocks（docker-compose.yml 所在目录）内执行。

查看实时状态：

docker compose ps

查看与跟踪日志：

docker compose logs --tail 20 kvrocks
docker compose logs -f kvrocks

实测日志片段：

kvrocks  | [2026-10-11T14:18:11.979815+00:00][I][worker.cc:646] [worker] Thread #129981407831744 started
kvrocks  | [2026-10-11T14:18:11.979878+00:00][I][worker.cc:646] [worker] Thread #129980614833856 started
kvrocks  | [2026-10-11T14:18:11.980090+00:00][I][server.cc:246] [server] Ready to accept connections

查看容器内进程：

docker compose top

实测回显：

SERVICE  #   UID  PID   PPID  C   STIME  TTY  TIME      CMD
kvrocks  1   999  6472  6449  0   14:18  ?    00:00:00  kvrocks -c /var/lib/kvrocks/kvrocks.conf --dir /var/lib/kvrocks --pidfile /var/run/kvrocks/kvrocks.pid --bind 0.0.0.0

重启 / 停止 / 启动：

docker compose restart
docker compose stop
docker compose start

实测回显（restart）：

 Container kvrocks Restarting
 Container kvrocks Started

进入容器排查：

docker compose exec kvrocks sh

在容器内查看数据目录：

docker compose exec kvrocks ls /var/lib/kvrocks

实测回显：

db
kvrocks.conf
kvrocks_2026-10-11.log

升级镜像版本：

docker compose pull
docker compose up -d

停止并移除（保留数据卷）：

docker compose down

实测回显：

 Network kvrocks_default Removing
 Network kvrocks_default Removed

十一、常见问题（FAQ）

Q1：容器不断 Restarting，日志报 Failed to load config. Error: failed to open file '/var/lib/kvrocks/kvrocks.conf': No such file or directory？ 用空宿主目录 bind 挂载 /var/lib/kvrocks，遮蔽了镜像自带的 kvrocks.conf。解决：按 4.1 节先把镜像内配置导出到宿主目录（或改用 named volume，首启自动播种配置）。

Q2：写了 command: 覆盖参数后容器重启循环，日志只有一段 Usage: 帮助信息？ 镜像 ENTRYPOINT 本身就是完整启动命令、CMD 为空，command: 的内容被当作 ENTRYPOINT 的尾部位置参数，kvrocks 收到未知位置参数即打印 Usage 退出。解决：改用 entrypoint: 整体覆盖（见第七、八章）。

Q3：容器反复重启且数据目录没有生成 db 文件？ 宿主 data 目录属主不是 UID 999，kvrocks 无写权限。解决：宿主执行 chown 999:999 /srv/kvrocks/data 后 docker compose up -d。

Q4：Ps 状态一直是 (health: starting)？ 镜像健康检查含 30s 启动等待期（start_period），首次启动 rocksdb 初始化需数秒至数十秒，属正常；持续 starting 超过 2 分钟再用 docker compose logs 排查启动错误。

Q5：未带密码时 PING 返回 NOAUTH Authentication required.？ 服务端配置了 requirepass（配置文件或启动参数）。客户端使用 redis-cli -a <口令> 连接，或去掉 requirepass 配置（生产不建议）。

Q6：如何修改监听端口？ 两处同步改：compose 的 ports 映射（如 "6667:6666" 宿主侧换端口）与配置/启动参数中的 port（容器内端口）。仅改宿主映射端口即可满足绝大多数场景，容器内端口无需动。

十二、参考链接