企业官网建设流程全解析

ScyllaDB 节点无响应（Unresponsive Nodes）排查与修复：Swap 与内存预留实战指南

【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb

导读

本文面向 ScyllaDB 运维与 DBA，围绕「节点无响应（Unresponsive Nodes）」这一典型故障，给出从现象定位、根因分析（swap 与内存预留）到修复落地的完整闭环方案。你将掌握：如何用top快速判断节点级还是 ScyllaDB 级故障、理解 ScyllaDB 默认预留 93% 内存的机制、通过--reserve-memory调整内存预留、以及使用scylla_swap_setup脚本或手工方式为生产环境配置合理的 swap 空间。文中所有操作均可直接在仓库对应的源码脚本中找到实现依据。

问题现象与初步判断

当集群中出现如下症状时，即属于本文讨论的「节点无响应」故障：

• ScyllaDB 节点被标记为 down；
• 无法建立新的 SSH 连接，已有连接响应缓慢；
• 节点整体运行迟滞。

需要区分两类不同性质的故障（参见 unresponsive-nodes.rst）：

关键判断依据：当节点作为一个整体开始变慢，甚至 SSH 连接都困难时，问题通常出在操作系统层面，而非 ScyllaDB 本身。这是本 KB 文章给出的首要排查定位原则。

根因：swap 与内存管理的两种极端情况

最常见的根因与 swap（交换分区/交换文件）直接相关，存在两种相反的情况：

1. 系统配置了 swap，但被实际使用

如果系统启用了 swap 且发生换页，ScyllaDB 的内存页可能被换出到磁盘。此后任何对这些内存的访问都要经历磁盘 I/O，性能急剧下降，节点表现为缓慢、无响应。

2. 系统没有配置 swap

没有 swap 时，内核在内存压力下会反复尝试回收页面却始终无法成功，最终陷入 CPU 忙循环（CPU-hog），拖垮 ScyllaDB 乃至所有其他进程的执行。这种"无 swap"场景往往比"有 swap 但偶发使用"更具破坏性。

从源码看 ScyllaDB 的内存预分配模型

理解上述根因，需要先理解 ScyllaDB 的内存管理策略：ScyllaDB 默认预分配节点 93% 的内存，并且从不使用超过该额度；剩余的 7% 留给操作系统和其他任务使用。仓库中的内存配置脚本 scylla_memory_setup 印证了这一管理模型——它通过写/etc/scylla.d/memory.conf（内容形如MEM_CONF="--lock-memory=1"或--memory=4G、--reserve-memory=...）来固化启动参数，其中：

• --memory：指定 ScyllaDB 使用的内存量（如4G，默认 all）；
• --reserve-memory：指定为 OS 预留的内存（当未指定--memory时生效）；
• --lock-memory：锁定全部内存，防止换出。

在 Docker 部署场景下，dist/docker/commandlineparser.py 同样提供了--reserve-memory参数（如--reserve-memory 1G预留 1GB RAM），说明该参数在容器化部署中同样可用。

修复步骤一：评估内存占用并优化节点负载

理想状态下，一个健康的系统不应该发生换页（swap）。因此首要任务是确认 7% 的预留是否被其他进程挤占：

1. 使用top工具检查是否存在其他高内存消耗进程；
2. 若存在非必需的高内存进程：建议将其迁移到其他机器，把内存归还给操作系统使用；
3. 若存在必需的高内存进程（如监控 Agent、备份代理等）：说明默认的 7% 预留可能不够，需要按下文调整内存预留。

关于 swap 的配置方式，可参考仓库 KB 文章 How to Set up a Swap Space，其推荐优先使用scylla_setup脚本（内部调用scylla_swap_setup）完成配置。

修复步骤二：调整 ScyllaDB 内存预留（--reserve-memory）

当节点上存在必需的其他进程、默认预留不足时，通过--reserve-memory增大 OS 预留量：

• 在RHEL 系发行版：编辑/etc/sysconfig/scylla-server；
• 在Debian 系发行版：编辑/etc/defaults/scylla-server。

在启动参数中加入：

--reserve-memory [memory]

例如预留 10GB：

--reserve-memory 10G

该参数与--memory的配合关系可从 memory-usage.rst 中看到完整示例：

SCYLLA_ARGS="--log-to-syslog 1 --log-to-stdout 0 --default-log-level info \ --collectd-address=127.0.0.1:25826 --collectd=1 --collectd-poll-period 3000 \ --network-stack posix --memory 2G --reserve-memory 2G"

注意该 KB 的提醒：留给操作系统的内存量必须足以满足外部 ScyllaDB 模块（external scylla modules）的需求——如果预留过小，外部模块同样可能引发内存压力。

修复步骤三：为生产环境配置 Swap

经验法则（见 set-up-swap.rst）："有 swap 但用不上，好过需要 swap 时却没有"。生产部署务必配置文件或分区形式的 swap。

swap 大小建议取total_mem/3与16GB中的较小值：

方式 A：使用脚本 scylla_swap_setup（推荐）

官方推荐通过scylla_setup运行，也可直接调用脚本。先查看帮助：

scylla_swap_setup --help usage: scylla_swap_setup [-h] [--swap-directory SWAP_DIRECTORY] [--swap-size SWAP_SIZE] Configure swap for ScyllaDB. optional arguments: -h, --help show this help message and exit --swap-directory SWAP_DIRECTORY specify swapfile directory --swap-size SWAP_SIZE specify swapfile size in GB

执行配置（指定目录与大小）：

sudo scylla_swap_setup --swap-directory /tmp/swp --swap-size 500

从源码 scylla_swap_setup 可以看到脚本内部的实际逻辑：

• 自动计算默认大小：min(16GB, total_mem/3)，即GB(16) if GB(16) < memtotal/3 else memtotal/3，与文档经验法则一致；
• 限制 swap 不超过磁盘可用空间的一半，磁盘不足时中止；
• 在 ext4 文件系统上使用fallocate创建，否则回退到dd；
• 将 swapfile 权限设为0600并执行mkswap -f；
• 生成 systemd swap unit（带DefaultDependencies=no，避免在云环境如 Azure 上产生依赖环），并 enable/start。

方式 B：手工配置 Swap 文件（通用 Linux 流程）

适用于任何 Linux 发行版，以下示例添加 6GB swap（可按需替换6G）：

# 1. 创建 swap 文件 sudo fallocate -l 6G /swapfile # 2. 收紧权限，仅 root 可读写 sudo chmod 600 /swapfile # 3. 格式化为 Linux swap 区域 sudo mkswap /swapfile # 4. 启用 swap sudo swapon /swapfile # 5. 持久化：追加到 /etc/fstab /swapfile swap swap defaults 0 0 # 6. 验证 sudo swapon --show NAME TYPE SIZE USED PRIO /swapfile file 6024M 507.4M -1

移除 Swap 文件

# 1. 停用 swap sudo swapoff -v /swapfile # 2. 编辑 /etc/fstab，删除 /swapfile swap swap defaults 0 0 行 # 3. 删除 swap 文件 sudo rm /swapfile

小结：从无响应到健康的完整检查清单

1. 定位层级：SSH 都慢 → 节点级问题；仅 ScyllaDB down → 优先查 ScyllaDB 自身；
2. 查内存占用：用top确认 7% OS 预留是否被挤占；
3. 区分进程：非必需进程迁移走；必需进程则调大--reserve-memory（如--reserve-memory 10G），修改/etc/sysconfig/scylla-server（RHEL）或/etc/defaults/scylla-server（Debian）后重启生效；
4. 配置 swap：生产环境必须配置，优先scylla_swap_setup，大小取min(total_mem/3, 16GB)；
5. 验证：swapon --show确认 swap 生效，并持续观察节点响应与内存压力。

遵循以上步骤，即可将「节点无响应」从 swap 与内存配置维度系统性消除。相关实现细节可继续阅读仓库中的 scylla_memory_setup、scylla_swap_setup 及 KB 文章 How to Set up a Swap Space、memory-usage.rst。

【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb