Apache Kvrocks 2.17.0 配置参数详解

目标：逐项讲清 Apache Kvrocks 2.17.0 配置文件 kvrocks.conf 的参数含义、默认值与调优要点，并给出 CONFIG 动态修改方式与生产配置模板，已在 Ubuntu 22.04 + Kvrocks 2.17.0（配置文件 /opt/kvrocks/conf/kvrocks.conf）环境实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Apache Kvrocks：2.17.0（kvrocks version 2.17.0，内核存储引擎 RocksDB 11.8.1）
• 配置文件：/opt/kvrocks/conf/kvrocks.conf（随源码包发布，共 1221 行，有效参数项 55 个）
• 服务端口：6666
• 数据目录：/opt/kvrocks/data
• 示例认证口令：q1w2e3r4

二、前置条件

• 已按《Ubuntu 22.04 安装 Apache Kvrocks 2.17.0 指南》完成安装，服务处于运行状态（systemctl is-active kvrocks 为 active）
• 已安装 redis-cli（redis-tools 包），可执行 redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning PING 返回 PONG

三、参数查看与修改方式

3.1 静态配置文件

Kvrocks 启动时读取 -c 指定的配置文件（默认随包发布的 kvrocks.conf），绝大多数参数修改后需重启生效：

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

3.2 CONFIG GET 动态查看

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG GET port
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG GET dir
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG GET workers
redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG GET requirepass

实测回显：

port
6666
dir
/opt/kvrocks/data
workers
8
requirepass
q1w2e3r4

3.3 CONFIG SET 动态修改

redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG SET requirepass q1w2e3r4

实测回显：

OK

⚠️ 注意：与 Redis 不同，Kvrocks 的 CONFIG SET 修改会自动追加持久化到配置文件尾部（实测在 kvrocks.conf 末尾生成 requirepass q1w2e3r4 等行），重启后仍然生效。因此动态调参后无需手工回写配置文件，但要留意文件尾部的追加段会覆盖同名默认值。

3.4 启动参数覆盖

kvrocks 进程支持 --<config-key> <config-value> 形式的任意配置项覆盖（优先级高于配置文件）：

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

例如 --port 6667 --requirepass q1w2e3r4 可在不改文件的情况下临时起一个差异化实例。

四、参数总览

以下为 kvrocks.conf 2.17.0 全部有效参数（实测从配置文件提取）及其默认值：

五、核心参数分类详解

5.1 网络与监听参数

• bind：监听地址，支持多地址与 IPv6（如 bind 192.168.1.100 10.0.0.1、bind 127.0.0.1 ::1、bind 0.0.0.0）。默认仅本机，生产对外服务改为 0.0.0.0 或指定内网 IP。实测 CONFIG GET bind 与连接行为一致。
• port：Kvrocks 默认端口 6666（区别于 Redis 的 6379），实测 CONFIG GET port 返回 6666。
• timeout：客户端空闲 N 秒后关闭连接，0 表示不超时（默认）。长连接业务保持 0，网关型接入可设 300~900。
• tcp-backlog：监听队列长度，默认 511。高并发新建连接场景受内核 somaxconn 上限约束，需同时调大内核参数。
• maxclients：最大并发连接数，默认 10000；进程文件描述符不足时会被压到 ulimit 附近，systemd 单元中 LimitNOFILE=100000 配合。
• workers：工作线程数，默认 8，决定命令并发处理能力，建议接近 CPU 核数。该参数支持动态调整（CONFIG SET workers 后服务自动重建线程池）。
• client-output-buffer-limit：三类客户端（normal/slave/pubsub）输出缓冲区限制，格式 <class> <hard> <soft> <soft-seconds>，支持 k/m/g 单位；默认全部为 0（不限）。订阅型业务建议 client-output-buffer-limit pubsub 32m 8m 60。

5.2 进程与守护参数

• daemonize：是否守护进程化。systemd 托管时必须 no（由 systemd 拉起管理）；手工裸跑后台可设 yes（此时生成 pidfile）。
• supervised：与 upstart/systemd 的就绪信号交互，取值 no/upstart/systemd/auto。systemd Type=notify 单元必须配 supervised auto 或 supervised systemd，否则服务启动超时失败（实测复现）。
• pidfile：pid 文件路径，默认写入数据目录下的 kvrocks.pid（实测为 /opt/kvrocks/data/kvrocks.pid）；daemonize=yes 或 systemd 场景使用。

5.3 数据目录与日志参数

• dir：工作目录，DB、日志、备份的根路径，默认 /tmp/kvrocks。生产必改为持久盘路径（实测改为 /opt/kvrocks/data 后，其下自动生成 db/、backup/、kvrocks_YYYY-MM-DD.log）。
• db-name：数据库逻辑标识，主从复制时主从必须一致，否则拒绝同步；默认 change.me.db 必须改名（实测改为 kvrocks-ops.db）。
• log-dir：日志目录，可多目的地逗号分隔并逐目的地带级别（如 /var/log/kvrocks:info,stdout:warning）；默认使用 dir 且同时输出到 stdout。
• log-level：debug/info/warning/error/fatal，默认 info。
• log-retention-days：INFO 级日志保留天数，-1（默认）为永久保留，生产建议 7~30。

5.4 安全与认证参数

• requirepass：访问口令。生产必配（Kvrocks 官方警示可被高速爆破）。实测 CONFIG SET requirepass q1w2e3r4 后，未认证 PING 返回 NOAUTH Authentication required.，AUTH 后恢复 PONG。namespace 令牌机制要求 requirepass 非空（实测空密码时 NAMESPACE SET 报 forbidden）。
• masterauth：主从场景从节点访问主节点用的口令，与主节点 requirepass 配对。
• rename-command：高危命令改名或禁用（如 rename-command KEYS "" 彻底禁用 KEYS）。

5.5 namespace 与 Redis 兼容参数

• repl-namespace-enabled：namespace 是否随主从复制传播（默认 no，即各节点独立维护；开启后从节点 namespace 被主节点覆盖且不可关闭）。
• redis-databases：Redis 式多 DB 兼容。0（默认）表示禁用 SELECT、namespace 机制生效；设为正数 N（如 16）后 SELECT 0..N-1 可用、namespace 机制自动禁用，二者二选一。
• redis-cursor-compatible：SCAN 游标兼容模式（默认 yes，游标为 64 位整数）。保持默认即可，SDK 兼容性最好。
• proto-max-bulk-len：单条 bulk string 上限，默认 512MB，最小 1MiB。
• max-bitmap-to-string-mb：BITFIELD 类 bitmap 转字符串的最大体积限制，默认 16MB。
• json-max-nesting-depth：JSON 嵌套深度上限，默认 1024。
• json-storage-format：JSON 存储格式 json/cbor，默认 json；cbor 体积更小、解析更快，仅影响新写入数据。
• resp3-enabled：RESP3 协议开关，默认 yes。

5.6 主从复制参数

• slaveof：从节点指主，格式 slaveof <masterip> <masterport>。
• slave-read-only：从节点只读，默认 yes，生产保持。
• slave-priority：Sentinel 选主优先级，默认 100，0 表示永不升主。
• replication-connect-timeout-ms / replication-recv-timeout-ms / replication-send-timeout-ms：复制链路建连/收/发超时（默认 3100/3200/30000 毫秒），跨机房复制可适当调大。
• replication-delay-bytes / replication-delay-updates：主节点向从节点打包发送前的聚合阈值（默认 16KB / 16 条更新），影响复制吞吐与实时性的平衡。
• max-replication-lag：从节点落后序列数上限，超过即被主节点断开（默认 0 不限制）；WAL 空间紧张时可设置。
• use-rsid-psync：更严格的 PSYNC 校验（复制 ID + 序列号），默认 no；开启可避免不同复制历史误部分同步，代价是更易触发全量。
• slave-serve-stale-data / slave-empty-db-before-fullsync / purge-backup-on-fullsync：全量同步期间从节点行为与磁盘空间取舍，默认 yes/no/no（保留旧数据、保留备份，更安全但更占磁盘）。
• master-use-repl-port：兼容旧版本主节点使用 port+1 复制端口的场景，默认 no。
• max-replication-mb：复制流量限速（MB/s），0 不限。

5.7 备份、容量与 compaction 参数

• max-backup-to-keep：保留的 BGSAVE 备份份数，仅支持 0 或 1，默认 1。
• max-backup-keep-hours：备份保留时长，默认 24 小时，0 表示不清理。
• max-db-size：RocksDB 可用空间上限（GB），0 不限；超出后写入失败，配合监控使用。
• max-io-mb：flush+compaction 聚合写盘限速（MB/s），0 不限；与业务高峰争 IO 时设置。
• enable-blob-cache：是否缓存 blob 文件到块缓存，默认 no。
• compaction-checker-cron：compaction 检查器活动时段 crontab 表达式，默认 * 0-7 * * *（每日 0-7 点）。该时段内周期性挑选删除占比最高的 SST 做空间回收。
• compact-cron：定时全量 compaction（如 compact-cron 0 3 * * * 每日 3 点），默认未启用。
• bgsave-cron：定时 BGSAVE（如 bgsave-cron 0 4 * * * 每日 4 点），默认未启用。
• dbsize-scan-cron：key 数量估算扫描计划（如 dbsize-scan-cron 0 * * * * 每小时），默认未启用。Kvrocks 不直接维护 key 计数，DBSIZE 依赖该扫描校准（实测未启用时 DBSIZE 返回 0 而 SCAN 可扫到 key）。
• force-compact-file-age / force-compact-file-min-deleted-percentage：SST 文件删除占比超阈值且存在超龄时强制 compaction（默认 172800 秒 / 10%）。

5.8 RocksDB 存储引擎参数

• rocksdb.block_cache_size：块缓存容量（MB），默认 4096；读多场景按内存预算调大，配合 block_cache_type。
• rocksdb.block_cache_type：lru 或 hcc，默认 hcc（Hyper Clock Cache，高并发下 CPU 效率更好）。
• rocksdb.write_buffer_size：单列族 memtable 容量（MB），默认 64；批量写入大可到 128~256，内存占用 ≈ write_buffer_size × max_write_buffer_number × 列族数。
• rocksdb.max_write_buffer_number：memtable 最大个数，默认 4。
• rocksdb.max_background_jobs：后台 flush/compaction 总线程，默认 4（flush 占 1/4）；NVMe 高写入可到 8。
• rocksdb.max_subcompactions：单个 compaction 任务的并行子任务数，默认 2。
• rocksdb.max_total_wal_size：WAL 总量触发 flush 的阈值（MB），默认 512；调大 write_buffer_size 时应同步调大。
• rocksdb.wal_ttl_seconds / rocksdb.wal_size_limit_mb：WAL 保留时长（默认 3 小时）与总量（默认 16GB）。WAL 同时承担复制序列，主从场景不宜过小。
• rocksdb.compression：SST 压缩算法 no/snappy/lz4/zstd/zlib，默认 snappy。
• rocksdb.compression_start_level：从第 N 层开始压缩，默认 2（L0/L1 不压缩保热点读性能）。
• rocksdb.level0_slowdown_writes_trigger / level0_stop_writes_trigger / level0_file_num_compaction_trigger：L0 文件数触发减速/停写/compaction 的阈值，默认 20/40/4。
• rocksdb.delayed_write_rate：触发减速后的写速率上限（B/s），0 表示自动推断。
• rocksdb.enable_blob_files / min_blob_size / blob_file_size：BlobDB（KV 分离）开关与阈值，大 value（如 >4KB）场景开启可降写放大，默认 no/4096/256MB。
• rocksdb.enable_blob_garbage_collection / blob_garbage_collection_age_cutoff：blob 垃圾回收开关与回收年龄切点，默认 yes/25。
• rocksdb.write_options.sync：每次写入强制 fsync，默认 no（依赖 WAL，整机掉电可能丢最近写入；金融级强一致才开）。
• rocksdb.write_options.disable_wal：关闭 WAL，默认 no。使用复制功能必须保持 WAL 开启。
• rocksdb.rate_limiter_auto_tuned：后台 IO 速率限制器自动调优，默认 yes。
• rocksdb.partition_filters：分区过滤器（每个 SST 独立 bloom filter 分区），默认 yes。
• rocksdb.max_open_files：最大打开文件数，默认 8096；需低于进程 ulimit。
• rocksdb.stats_dump_period_sec：rocksdb.stats 打印到 LOG 的周期，默认 0（不打印）。

5.9 慢日志与性能诊断参数

• slowlog-log-slower-than：慢命令阈值（微秒），默认 100000（100ms），0 记录所有命令，-1 关闭。实测设 0 后 SET 等全部入慢日志，SLOWLOG LEN 计数增长。
• slowlog-max-len：慢日志环形队列长度，默认 128。
• slowlog-dump-logfile-level：慢日志是否落盘及级别，默认 off。
• profiling-sample-ratio / profiling-sample-commands / profiling-sample-record-max-len / profiling-sample-record-threshold-ms：基于 RocksDB Perf Context 的命令级性能采样，仅在排查性能瓶颈时开启（默认 0 关闭，开启有性能损耗）。

5.10 集群模式与 slot 迁移参数

• cluster-enabled：是否启用类 Redis Cluster 的 slot 集群，默认 no。注意：开启后 key 按 CRC16 slot 编码，standalone 与 cluster 数据格式互不兼容，模式切换必须迁移数据，且开启后不能再关闭。
• persist-cluster-nodes-enabled：集群拓扑持久化到 dir 目录下 nodes.conf，默认 yes。
• migrate-sequence-gap：slot 迁移增量追平阈值，低于该值进入禁写窗口，默认 10000。
• migrate-batch-size-kb / migrate-batch-rate-limit-mb：迁移批次大小（默认 16KB）与速率（默认 16MB/s）。

六、生产配置模板

适用场景：16GB 内存服务器、NVMe SSD、单实例通用 OLTP 缓存/KV 存储（预留约 4GB 给 block cache + memtable，其余给系统与页缓存）：

############ 网络 ############
bind 0.0.0.0
port 6666
tcp-backlog 2048
maxclients 20000
timeout 0
workers 8
client-output-buffer-limit normal 0 0 0 slave 0 0 0 pubsub 32m 8m 60

############ 进程（systemd Type=notify 配套） ############
daemonize no
supervised auto

############ 目录与日志 ############
dir /opt/kvrocks/data
db-name kvrocks-ops.db
log-level info
log-retention-days 14

############ 安全 ############
requirepass q1w2e3r4

############ 备份与容量 ############
max-backup-to-keep 1
max-backup-keep-hours 48
max-db-size 800
max-io-mb 200
compact-cron 0 3 * * *
bgsave-cron 0 4 * * *
dbsize-scan-cron 0 * * * *

############ RocksDB（16GB 内存档） ############
rocksdb.block_cache_size 4096
rocksdb.block_cache_type hcc
rocksdb.write_buffer_size 128
rocksdb.max_write_buffer_number 4
rocksdb.max_background_jobs 8
rocksdb.max_subcompactions 4
rocksdb.max_total_wal_size 1024
rocksdb.compression snappy
rocksdb.max_open_files 8096

############ 慢日志 ############
slowlog-log-slower-than 100000
slowlog-max-len 256

模板要点：

七、常见问题（FAQ）

Q1：改了 kvrocks.conf 不生效？ 确认改的是 -c 指定路径的文件（redis-cli -p 6666 -a q1w2e3r4 --no-auth-warning CONFIG GET config_file 可查实际路径），改后需重启；另注意配置文件尾部可能有 CONFIG SET 自动追加的同名参数（后写的覆盖前面的）。

Q2：CONFIG SET 后重启参数还在？ Kvrocks 的 CONFIG SET 会自动把修改持久化到配置文件尾部（实测 requirepass、namespace 修改均被追加写入），这是特性不是异常；如需回退，删除文件尾部的追加行再重启。

Q3：DBSIZE 一直是 0？ key 计数由 dbsize 扫描任务估算（默认未启用 cron），未扫描时 DBSIZE 为 0 但数据完好（SCAN 可验证）。启用 dbsize-scan-cron 0 * * * * 每小时校准，或接受该估算语义。

Q4：systemd 启动超时（TimeoutSec 到期仍 activating）？ Type=notify 要求 kvrocks 上报就绪，配置 supervised 必须为 auto/systemd；默认值 no 会导致永远等不到 READY 信号。

Q5：NAMESPACE SET 报 forbidden？ namespace 令牌依赖访问口令：先设置 requirepass（非空）再执行 NAMESPACE 子命令。

Q6：cluster-enabled 能开开又关关吗？ 不能。cluster 模式的 key 编码与 standalone 不兼容，官方明确：首次开启后不可关闭，模式互换必须迁移数据，否则数据错乱。

Q7：磁盘写放大严重怎么办？ 依次评估：开启 BlobDB（rocksdb.enable_blob_files yes，大 value 场景）、调大 compaction-checker-cron 活动窗口、增加 rocksdb.max_background_jobs/max_subcompactions、必要时 compact-cron 定期全量压实。

八、参考链接

• 官方配置文档：https://kvrocks.apache.org/docs/config
• 源码内配置文件（2.17.0）：https://github.com/apache/kvrocks/blob/v2.17.0/kvrocks.conf
• Kvrocks 主页：https://kvrocks.apache.org
• RocksDB 调优 Wiki：https://github.com/facebook/rocksdb/wiki