Apache ResilientDB 配置参数详解

目标：详解 Apache ResilientDB 的核心配置——服务端 server.config（副本拓扑、存储、共识开关）、客户端 service.config（接入入口）、证书与配置的批量生成脚本，以及构建期选项，并给出可直接套用的生产模板。参数取值与真实环境实测一致。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• 源码：master 分支 commit 4de5cb43686276ace4307f44839a1de920ab524a
• 源码目录：/root/incubator-resilientdb
• 配置文件目录：service/tools/config/（服务端 server/server.config、客户端 interface/service.config）
• 服务端口：副本 10001-10004，客户端代理 10005
• Bazel：6.0.0

二、前置条件

• 已完成源码编译与证书生成（见《Ubuntu 22.04 安装 Apache ResilientDB 指南》）。
• 配置修改后需重启服务进程生效：killall -9 kv_service 后重新执行 service/tools/kv/server_tools/start_kv_service.sh（systemd 环境为 systemctl restart resilientdb-kv）。

三、参数查看与修改方式

ResilientDB 的服务参数集中在两个 JSON 风格配置文件中，直接文本编辑后重启生效：

cd /root/incubator-resilientdb
vi service/tools/config/server/server.config      # 服务端：副本拓扑/存储/共识开关
vi service/tools/config/interface/service.config  # 客户端：接入入口端口

• server.config：每个副本进程启动时以第 1 个参数加载，决定集群拓扑与自身行为。
• service.config：客户端工具与 SDK 以它为入口，只需填写客户端代理（client proxy）地址。
• 修改后核对生效：重启后用 netstat -tlnp | grep 1000 核对新端口监听，客户端 set/get 复核连通。

💡 配置文件支持 JSON 键值与 protocol buffer 风格字段（replica_info : { ... }）两种写法，源码自带文件混用两种风格，保持原格式修改即可。

四、参数总览

4.1 server.config 参数

4.2 service.config 参数

五、核心参数分类详解

5.1 副本拓扑参数（region.replica_info）

每个 replica_info 描述一个副本，id 从 1 连续编号，id=1 默认为主副本（primary）。扩容副本时同步追加条目、生成对应证书并保持 3f+1 数量：

replica_info : {
  id:1,
  ip:"127.0.0.1",
  port: 10001,
},

• id：副本唯一编号，与证书文件（node1.key.pri/cert_1.cert）序号对应，启动脚本按证书序号传参。
• ip：副本监听/互联地址，多机部署时写各机真实 IP。
• port：副本共识通信端口，默认 10001-10004，被占用时改用其他端口并同步客户端侧可达性。

5.2 区域参数（region_id / self_region_id）

• region.region_id：区域编号，跨地域（GeoBFT 等分区共识）部署时用于分区划分；单区域固定 1。
• self_region_id：本进程所属区域，须与其所在 region 定义一致。

5.3 存储参数（leveldb_info）

仅当服务端以 LevelDB 存储编译时生效（bazel build //service/kv:kv_service --define=enable_leveldb=True，默认关闭、使用内存存储）：

leveldb_info : {
  write_buffer_size_mb:128,
  write_batch_size:1,
  enable_block_cache: true,
  block_cache_capacity: 100
}

• write_buffer_size_mb：memtable 写缓冲大小，写入密集场景可上调至 256。
• write_batch_size：批量提交大小，保持 1 即可。
• enable_block_cache / block_cache_capacity：读缓存开关与容量（MB），读多写少场景保持 true。

⚠️ 默认构建（内存存储）重启即丢数据，实测：写入 user1001=alice 后 killall -9 kv_service 并重启，get user1001 返回空（get key = user1001 value =）。需要持久化必须启用 LevelDB 编译开关。

5.4 共识与安全开关

require_txn_validation:true,
enable_viewchange:false,
enable_resview:true,
enable_faulty_switch:false

• require_txn_validation：是否校验客户端交易签名，生产必须保持 true。
• enable_viewchange：视图切换开关，主副本故障时切换主副本；对性能有影响，默认关闭，生产按可用性要求开启。
• enable_resview：ResView 视图管理（ResilientDB 研究成果的视图切换路径），默认开启。
• enable_faulty_switch：检测到故障副本时主动切换，默认关闭。

5.5 客户端入口参数（service.config）

客户端只感知客户端代理，port 必须与启动脚本第 5 个进程（node5 证书）实际监听端口一致：

{
"replica_info":[
{
"id":1,
"ip":"127.0.0.1",
"port":10005
}
],
"region_id":1
}

实测客户端连接时，工具会先打印代理解析结果（glog 提示行）：

E20261012 14:36:10.798208 19633 resdb_config_utils.cpp:146] parse json id:1 ip:127.0.0.1 port:10005

5.6 构建期选项

• --define=enable_leveldb=True：启用 LevelDB 落盘存储（默认内存存储），见 5.3 节。
• .bazelrc 中 build --cxxopt='-std=c++17' --copt=-O3 --jobs=40：C++17、O3 优化、并行度 40；编译机内存有限时可调低 --jobs。

六、生产配置模板

适用场景：4 台 8 核 16GB 内存、SSD 磁盘服务器组成的 PBFT 集群（f=1），交易签名校验开启、视图切换开启、LevelDB 落盘，客户端经独立代理端口接入。

服务端 server.config（各节点保持相同副本列表，ip 按实际机器填写）：

{
  region : {
    replica_info : {
      id:1,
      ip:"10.0.0.11",
      port: 10001,
    },
    replica_info : {
      id:2,
      ip:"10.0.0.12",
      port: 10001,
    },
    replica_info : {
      id:3,
      ip:"10.0.0.13",
      port: 10001,
    },
    replica_info : {
      id:4,
      ip:"10.0.0.14",
      port: 10001,
    },
    region_id: 1,
  },
  self_region_id:1,
  leveldb_info : {
    write_buffer_size_mb:256,
    write_batch_size:1,
    enable_block_cache: true,
    block_cache_capacity: 200
  },
  require_txn_validation:true,
  enable_viewchange:true,
  enable_resview:true,
  enable_faulty_switch:false
}

客户端 service.config（部署在独立客户端代理节点或应用侧）：

{
"replica_info":[
{
"id":1,
"ip":"10.0.0.11",
"port":10005
}
],
"region_id":1
}

💡 内存说明：ResilientDB 为 C++ 常驻进程，空载单进程实测 RSS 约 95MB（systemctl status 显示 Memory: 94.9M），16GB 机器内存主要消耗在 LevelDB 缓存与共识队列，按上表配置即可支撑常规 KV 负载；吞吐压测建议配合官方 benchmark/ 工具。

七、常见问题

7.1：改了 server.config 端口后服务没变化

解决：配置在进程启动时加载，需 killall -9 kv_service 后重新执行 start_kv_service.sh（systemd 环境 systemctl restart resilientdb-kv），再用 netstat -tlnp | grep 1000 核对新端口。

7.2：副本启动即退出

定位：副本 id 与证书序号不匹配，或证书文件缺失。启动脚本按 node1.key.pri/cert_1.cert 顺序传参，新增副本需先重新生成证书。 解决：重新执行 ./service/tools/kv/server_tools/generate_keys_and_certs.sh，确认 service/tools/data/cert/ 下证书齐全后再启动。

7.3：客户端连接被拒

定位：service.config 的 ip/port 与客户端代理进程实际监听不一致。 解决：核对 netstat -tlnp | grep 10005；多机部署时 service.config 填客户端代理所在机器的真实 IP，并确认防火墙放行。

7.4：副本间不通、共识日志不推进

定位：多机部署时 server.config 副本 ip 写错或防火墙拦截 10001-10004。 解决：逐台核查 server.config 中各副本 ip 为真实 IP（本机默认拓扑为 127.0.0.1），放行副本端口后重启全部副本。

八、参考链接

• 源码仓库：https://github.com/apache/incubator-resilientdb
• 配置解析源码：platform/config/resdb_config_utils.cpp
• 存储编译开关定义：chain/storage/setting/BUILD
• 官方快速上手博客：https://blog.resilientdb.com/2022/09/28/GettingStartedNexRes.html