ScyllaDB 6.x 配置参数详解

详解 ScyllaDB 6.2（实测 6.2.3）的核心配置：`/etc/scylla/scylla.yaml` 的集群/存储/端口参数、`/etc/scylla.d/` 下的 cpu/io/内存配置文件，以及与 Cassandra 的配置差异。所有参数值均来自真实安装（apt 官方源）后的实测读取

ScyllaDBScyllaDB参数调优宽列存储NoSQL2026/09/27

ScyllaDB 6.x 配置参数详解

目标：详解 ScyllaDB 6.2（实测 6.2.3）的核心配置：/etc/scylla/scylla.yaml 的集群/存储/端口参数、/etc/scylla.d/ 下的 cpu/io/内存配置文件，以及与 Cassandra 的配置差异。所有参数值均来自真实安装（apt 方式）后的实测读取。

环境信息

信息项值
ScyllaDB 版本6.2.3-0.20250119.bff9ddde1283
主配置文件/etc/scylla/scylla.yaml
辅助配置目录/etc/scylla.d/（cpu.conf、io.conf、memory.conf、dev-mode.conf、cpuset.conf）
配置归属scylla 用户（uid=100），目录 /etc/scylla、/etc/scylla.d
数据目录/var/lib/scylla/data（默认）
Commitlog 目录/var/lib/scylla/commitlog（默认）

配置文件总览

ScyllaDB 的配置由两部分组成：

  1. /etc/scylla/scylla.yaml：主配置（集群、存储、端口、超时等），格式与 Cassandra 的 cassandra.yaml 兼容
  2. /etc/scylla.d/*.conf：scylla 服务启动附加参数（systemd unit 的 ExecStart 中通过 $SEASTAR_IO $DEV_MODE $CPUSET $MEM_CONF 注入）：
文件变量作用apt 安装实测默认值
io.confSEASTAR_IOI/O 队列参数--max-io-requests=1 --num-io-queues=1
cpu.conf / cpuset.confCPUSET绑定 CPU/限制 smp--cpuset 0 --smp 1
memory.confMEM_CONF内存锁定--lock-memory=1
dev-mode.confDEV_MODE开发者模式--developer-mode=0

💡 说明：这些 conf 文件由 scylla_setup 及配套脚本自动生成，安装后自动写入等价参数。

核心参数详解（实测自 /etc/scylla/scylla.yaml）

集群类参数

参数实测默认值说明
cluster_name'Test Cluster'（默认注释）集群名称，同一集群所有节点必须一致；已建集群后不可修改
num_tokens256每个节点在环上的 token 数量，同集群节点应一致
seeds"127.0.0.1"种子节点 IP，新节点加入集群的联络点；单节点填本机即可
listen_addresslocalhost节点间通信地址（内部 gossip/数据传输）
rpc_addresslocalhostCQL 客户端连接地址
endpoint_snitchSimpleSnitch拓扑感知策略，单节点默认 SimpleSnitch
enable_tabletstrue6.0+ 的表分片（tablet）新架构，单节点默认开启
partitionerorg.apache.cassandra.dht.Murmur3Partitioner分区器，默认 Murmur3，与 Cassandra 一致

实测 scylla.yaml 中 seed_provider 段落：

seed_provider:
    - class_name: org.apache.cassandra.locator.SimpleSeedProvider
      parameters:
          - seeds: "127.0.0.1"

💡 说明：多节点时 seeds 写第一个节点 IP，listen_address / rpc_address 改为各节点本机 IP；rpc_address 建议保留 0.0.0.0 或用 listen_on_broadcast_address 配合。

存储与 Commitlog 参数

参数实测默认值说明
data_file_directories/var/lib/scylla/data（默认注释）数据目录，可配置多个目录分摊 IO
commitlog_directory/var/lib/scylla/commitlog（默认注释）commitlog 目录，机械盘上应与数据目录分离
commitlog_syncperiodiccommitlog 同步模式，可选 periodic / batch
commitlog_sync_period_in_ms10000periodic 模式同步周期
commitlog_segment_size_in_mb32单个 commitlog 段大小
schema_commitlog_segment_size_in_mb128schema 专用 commitlog 段大小
commitlog_total_space_in_mb-1commitlog 总空间上限，-1 表示自动计算

端口参数

参数实测默认值说明
native_transport_port9042CQL 原生协议端口（cqlsh 使用）
native_shard_aware_transport_port19042shard-aware CQL 端口（驱动多路复用）
api_port10000REST API 端口（nodetool 走此端口而非 JMX）
api_address127.0.0.1REST API 监听地址

超时与批次参数

参数实测默认值说明
read_request_timeout_in_ms5000读请求超时
write_request_timeout_in_ms2000写请求超时
cas_contention_timeout_in_ms1000CAS（LWT）竞争超时
batch_size_warn_threshold_in_kb128批次大小告警阈值
batch_size_fail_threshold_in_kb1024批次大小失败阈值

memtable 与缓存

ScyllaDB 的 scylla.yaml 没有 memtable 配置项（实测 grep 无结果）——这是与 Cassandra 的关键差异之一：Scylla 使用 Seastar 共享内存模型，memtable 与 row cache 由内存管理器自动分配（可用内存的默认 1/4 用于 cache，实测 nodetool info 中 Row Cache capacity 1.45 GB，可见自动管理已生效）。Cassandra 中 memtable_heap_space_in_mb、row_cache_size_in_mb 等配置在 Scylla 中不存在。

CPU / IO / 内存配置

cpu/io/内存不在 scylla.yaml 中，通过启动参数注入（实测 apt 安装最终启动命令）：

实测 apt 安装最终启动命令（systemd 单元加载 /etc/scylla.d/*.conf 后 scylla-server 实际运行）：

/usr/bin/scylla --log-to-syslog 0 --log-to-stdout 1 --network-stack posix
  --developer-mode=1 --smp 1 --overprovisioned
  --listen-address 172.25.7.2 --rpc-address 172.25.7.2
  --seed-provider-parameters seeds=172.25.7.2 --alternator-address 172.25.7.2
  --blocked-reactor-notify-ms 999999999
参数说明实测结论
--smp Nshard 数量（≈CPU 核数）单节点实测 --smp 1 正常
--memory N内存上限实测必须 ≥1GiB/shard，768M/1024M 启动失败
--developer-mode 1跳过生产校验（IO Scheduler 等）开发/测试机必配，否则启动失败
--overprovisioned声明环境为超卖仅虚拟化/超卖环境按需开启
--lock-memory 1锁定内存（memory.conf）受限环境建议关闭（实测 mlock 受限）

💡 说明：io.conf 的 SEASTAR_IO="--max-io-requests=1 --num-io-queues=1" 是未跑过 scylla_io_setup 时的占位默认；生产环境跑 scylla_setup 后会自动生成带磁盘基准结果的 io.conf。

与 Cassandra 的差异说明

维度CassandraScyllaDB 6.x
主配置cassandra.yamlscylla.yaml（键名基本兼容）
memtable/缓存需手工配置内存项自动内存管理，无对应配置项
运维端口7199（JMX）10000（REST API）
nodetool 连接走 JMX走 REST API（10000）
存储架构每节点固定 token 分区默认 tablets 动态分片（enable_tablets: true）
语言实现Java（JVM 堆/堆外内存）C++（Seastar 共享内存）
release_version与版本一致恒为 3.0.8（CQL 协议版本，实测）

注意事项

  • cluster_name 建集群后不可修改，生产环境务必先规划
  • ScyllaDB 最低内存 1GiB/shard（实测低于此值启动失败）
  • 端口 9042/10000 需在防火墙放行
  • 自定义 scylla.yaml 时必须显式保留 api_address: 127.0.0.1，否则默认值丢失导致 nodetool 连接失败（实测踩坑，详见部署文档）

常见问题

问题 1：修改配置后如何生效

原因： scylla.yaml 启动时读取。

解决：

systemctl restart scylla-server        # 系统服务重启

问题 2：nodetool 报 Connection refused（自定义 yaml）

原因： 自定义 scylla.yaml 覆盖了默认 api_address: 127.0.0.1，API 监听了节点内网 IP（实测日志 API server listening on 172.25.7.2:10000），nodetool 连 127.0.0.1:10000 被拒。

解决： 在自定义 yaml 中显式加上 api_address: 127.0.0.1。

问题 3：I/O Scheduler is not properly configured 导致启动失败

原因： 未生成 io.conf（未跑过 scylla_io_setup）。

解决： 开发环境 --developer-mode 1；生产环境运行 scylla_setup。

参考链接

本文档由 www.quzuo.net 平台开发

ScyllaDB 6.x 配置参数详解 - Quzuo