ScyllaDB 升级指南：从 2026.x 到 2026.3 的滚动升级、回滚与指标变更全解析

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

ScyllaDB 是一个基于 Seastar 框架、兼容 Apache Cassandra 与 Amazon DynamoDB 的 NoSQL 数据存储，其升级体系以“逐节点滚动执行”为核心，支持在集群不整体停机的前提下完成小版本（Patch）与次版本（Minor）升级。本文以仓库内 docs/upgrade 文档体系为骨架，完整讲解 ScyllaDB 2026.x → 2026.3 的升级前检查、分步操作、验证手段、失败回滚流程，以及 2026.3 引入的新指标与重命名指标，并结合仓库源码说明关键命令与配置项的底层实现。读完本文，你将能够独立规划并执行一次可回滚、可验证的 ScyllaDB 滚动升级。

升级文档体系与适用范围

仓库 docs/upgrade 目录下的文档体系分为三层：

入口页 docs/upgrade/index.rst 与 docs/upgrade/upgrade-guides/index.rst，将升级主题路由到具体指南；
次版本升级指南 upgrade-guide-from-2026.x-to-2026.3.rst，覆盖 2026.x → 2026.3 的完整升级与回滚过程；
补丁（Patch）升级指南 upgrade-guide-from-2026.x.y-to-2026.x.z.rst，覆盖同一 2026.x 系列内小版本间的升级与回滚；
云镜像升级说明 ami-upgrade.rst，面向 EC2 / GCP / Azure 上的官方镜像与自建镜像；
公共警示片段 warning.rst 与 warning_rollback.rst，强调升级/回滚必须逐节点串行执行。

两份升级指南覆盖的操作系统均为 Red Hat Enterprise Linux (RHEL)、CentOS、Debian 和 Ubuntu，同时适用于 EC2、GCP、Azure 上的 ScyllaDB 官方镜像。补丁升级指南特别说明：补丁升级无需更换 DEB 或 RPM 软件仓库，直接使用原有仓库即可拉取到新补丁版本；而 2026.x → 2026.3 这类次版本升级则必须先将仓库源切换到新版本。

升级前检查与准备工作

在动手升级之前，官方文档要求依次完成以下三类检查：

升级驱动（Driver）：如果使用 ScyllaDB 官方驱动连接集群，应先将驱动升级到与目标版本兼容的版本，官方支持每个驱动的最新两个版本。

升级监控栈（Monitoring Stack）：若使用 ScyllaDB Monitoring Stack，需要先确认其版本支持将要升级到的 ScyllaDB 版本，官方建议将监控栈升级到最新版本。由于 2026.3 引入了一批新指标（见下文“指标更新”一节），旧版监控栈可能无法正确渲染新仪表盘。

核对特性更新：查阅 ScyllaDB Release Notes，确认目标版本中与自身业务相关的功能变化。

升级前还应记录当前版本：在任一节点执行scylla --version，把输出的版本号记下来，这个版本号将用于回滚时的版本定位。

升级核心流程：逐节点滚动执行

ScyllaDB 升级是滚动式（rolling）过程，不需要整个集群停机。对集群中的每个节点，依次完成以下 7 个步骤，并且必须串行执行——只有确认当前节点已成功运行新版本后，才能继续下一个节点：

检查集群 Schema 是否同步；
Drain 节点并备份数据；
备份配置文件；
停止 ScyllaDB；
下载并安装新版本软件包；
启动 ScyllaDB；
验证升级成功。

滚动升级期间，官方强烈建议不要执行以下操作：

使用新版本（2026.3）引入的新特性；
执行管理类操作，如 repair、refresh、rebuild、添加或移除节点（可使用sctool暂停 ScyllaDB Manager 中已调度或正在运行的 repair 任务）；
应用 Schema 变更。

1. 检查集群 Schema 同步

升级过程在节点间存在 Schema 不一致时会失败，因此第一步是在升级前确认所有节点的 Schema 已同步：

nodetool describecluster

该命令的输出会列出集群中每个节点的 Schema 版本，全部一致后才可继续。该命令由仓库内的 tools/scylla-nodetool.cc 实现。

2. Drain 节点并备份数据

官方推荐使用 ScyllaDB Manager 创建备份；如不使用 Manager，可以基于nodetool snapshot手工备份。对每一个节点依次执行：

nodetool drain nodetool snapshot

nodetool drain让节点停止接收新的写入并将内存中的 memtable 刷新（flush）到磁盘，保证快照的一致性；
nodetool snapshot为节点数据目录生成快照。执行后请记录 nodetool 输出的快照目录名，并把/var/lib/scylla下所有以该名称命名的目录复制到外部备份设备；
全部节点升级完成后，用nodetool clearsnapshot -t 删除快照，防止磁盘空间被占满。

3. 备份配置文件

升级前需要备份scylla.yaml配置文件和软件仓库源文件，供回滚时恢复。按发行版执行：

Debian/Ubuntu：

sudo cp -a /etc/scylla/scylla.yaml /etc/scylla/scylla.yaml.backup sudo cp /etc/apt/sources.list.d/scylla.list ~/scylla.list-backup

RHEL/CentOS：

sudo cp -a /etc/scylla/scylla.yaml /etc/scylla/scylla.yaml.backup sudo cp /etc/yum.repos.d/scylla.repo ~/scylla.repo-backup

/etc/scylla/scylla.yaml即 ScyllaDB 主配置文件，仓库内提供了该配置的完整模板，见 conf/scylla.yaml。

4. 优雅停止节点

sudo service scylla-server stop

注意使用service而非直接 kill 进程，以确保 ScyllaDB 完成优雅停机（flush、关闭 SSTable 等）。

5. 下载并安装新版本

补丁升级（2026.x.y → 2026.x.z）：无需更换仓库，直接升级即可。

Debian/Ubuntu：

sudo apt-get clean all sudo apt-get update sudo apt-get dist-upgrade scylla

前两个询问均回答y。

RHEL/CentOS：

sudo yum clean all sudo yum update scylla\* -y

次版本升级（2026.x → 2026.3）：需要先把仓库源切换到新版本。

Debian/Ubuntu先更新 deb 仓库，再安装：

sudo wget -O /etc/apt/sources.list.d/scylla.list https://downloads.scylladb.com/deb/debian/<你的发行版对应列表> sudo apt-get clean all sudo apt-get update sudo apt-get dist-upgrade scylla

RHEL/CentOS先更新 rpm 仓库，再安装：

sudo curl -o /etc/yum.repos.d/scylla.repo -L https://downloads.scylladb.com/rpm/centos/<你的发行版对应repo> sudo yum clean all sudo yum update scylla\* -y

（仓库地址中的<...>占位符请替换为与实际 OS 版本及目标 ScyllaDB 版本匹配的下载列表。）

6. 启动节点

sudo service scylla-server start

7. 验证升级成功

升级完成后必须验证节点确实运行了新版本且工作正常：

执行nodetool status，确认所有节点（包括刚升级的节点）都处于UN（Up/Normal）状态；
用 REST API 查询版本号，确认与目标版本一致：

curl -X GET "http://localhost:10000/storage_service/scylla_release_version"

该 API 端点定义在 api/api-doc/storage_service.json 中，昵称为get_scylla_release_version，由storage_service模块暴露在 10000 端口的 HTTP API 上； 3. 检查日志确认没有新增错误：

journalctl _COMM=scylla

等待约 2 分钟后再次检查，确认没有新问题出现。

确认当前节点升级成功后，再对下一个节点重复以上全部步骤。

云镜像（EC2/GCP/Azure）的升级注意事项

ScyllaDB 官方镜像基于Ubuntu 22.04（见 ami-upgrade.rst）。官方镜像的升级方式与 Debian/Ubuntu 完全一致，直接参考对应标签页即可。

如果你使用的是自建镜像且手动安装了 Ubuntu/Debian 软件包，则必须执行扩展升级流程：

先按Debian/Ubuntu标签页更新 deb 仓库并安装新版本：

sudo apt-get clean all sudo apt-get update sudo apt-get dist-upgrade scylla sudo apt-get dist-upgrade scylla-machine-image

运行scylla_setup，但不要执行io_setup；

运行：

sudo /opt/scylladb/scylla-machine-image/scylla_cloud_io_setup

回滚时也需要额外处理scylla-machine-image包（见下文）。

回滚流程：升级失败的应急通道

回滚同样采用滚动方式，不需要整个集群停机，但有严格的前提条件：只有当集群中仍有节点尚未升级到新版本时，回滚才可能执行。一旦滚动升级的最后一个节点也已用新版本启动，回滚便不再可行，此时唯一的恢复途径是从备份还原整个集群。因此，任何升级都必须保守地逐节点推进，避免一口气升级全部节点。

回滚同样要求逐节点串行执行，且只对已经升级到新版本的节点执行。每个节点的回滚步骤为：

Drain 节点并停止 ScyllaDB；
恢复旧版本软件包；
恢复配置文件；
重新加载 systemd 配置（如 unit 文件有变更）；
重启 ScyllaDB；
验证回滚成功。

停止节点

nodetool drain sudo service scylla-server stop

恢复并安装旧版本

Debian/Ubuntu（补丁升级回滚）：直接安装指定版本：

sudo apt-get install scylla=<旧版本>\* scylla-server=<旧版本>\* scylla-tools=<旧版本>\* scylla-tools-core=<旧版本>\* scylla-kernel-conf=<旧版本>\* scylla-conf=<旧版本>\*

前两个询问回答y。

RHEL/CentOS（补丁升级回滚）：

sudo yum downgrade scylla\*-<旧版本>-\* -y

Debian/Ubuntu（次版本升级回滚）：先移除新仓库文件，恢复旧仓库，再重新安装：

sudo rm -rf /etc/apt/sources.list.d/scylla.list sudo cp ~/scylla.list-backup /etc/apt/sources.list.d/scylla.list sudo chown root.root /etc/apt/sources.list.d/scylla.list sudo chmod 644 /etc/apt/sources.list.d/scylla.list sudo apt-get update sudo apt-get remove scylla\* -y sudo apt-get install scylla

RHEL/CentOS（次版本升级回滚）：

sudo rm -rf /etc/yum.repos.d/scylla.repo sudo cp ~/scylla.repo-backup /etc/yum.repos.d/scylla.repo sudo chown root.root /etc/yum.repos.d/scylla.repo sudo chmod 644 /etc/yum.repos.d/scylla.repo sudo yum clean all sudo yum remove scylla\* sudo yum install scylla

自建云镜像（EC2/GCP/Azure）：在 Debian/Ubuntu 回滚步骤的基础上，额外恢复scylla-machine-image包：

sudo apt-get update sudo apt-get remove scylla\* -y sudo apt-get install scylla sudo apt-get install scylla-machine-image

恢复配置文件

sudo rm -rf /etc/scylla/scylla.yaml sudo cp /etc/scylla/scylla.yaml.backup /etc/scylla/scylla.yaml

（注意：次版本升级回滚指南中恢复源文件路径写作scylla.yaml-backup，而备份步骤使用的是scylla.yaml.backup，实际操作时请与你备份时生成的文件名保持一致。）

重新加载 systemd 配置并启动

如果 systemd unit 文件在版本间发生变化，必须重载 unit 文件：

sudo systemctl daemon-reload sudo service scylla-server start

最后按“验证”一节的方法确认节点运行的是旧版本且状态正常，然后继续回滚下一个节点。

2026.3 指标更新：新指标与重命名指标

次版本升级指南中专门附有指标更新说明 metric-update-2026.x-to-2026.3.rst。2026.3 的监控仪表盘已包含在最新版监控栈中，旧版监控栈用户升级前应确认兼容性。相比 2026.2，2026.3 新增了以下指标（节选归类如下）：

Alternator（DynamoDB 兼容层）相关：

指标	说明
scylla_alternator_conditional_check_failed	条件条件不满足的请求数（ConditionalCheckFailedException）
scylla_alternator_returned_items	Query/Scan 操作返回的条目数
scylla_alternator_returned_items_histogram	每次 Query/Scan 操作返回条目数的直方图
scylla_alternator_returned_records	GetRecords 操作返回的流记录数
scylla_alternator_system_errors	HTTP 500 内部服务器错误响应数
scylla_alternator_user_errors	HTTP 400 客户端错误响应数（不含 ConditionalCheckFailedException）
scylla_alternator_vector_search_query	带 VectorSearch 的 Query 操作数
scylla_alternator_vector_search_query_items_from_base_table	向量搜索查询从基表读取的条目总数
scylla_alternator_vector_search_query_items_from_vs	向量存储找到的最近邻总数（部分可能被后置过滤而未返回）
scylla_alternator_vector_search_query_returned_items	带向量搜索的 Query 操作返回的条目总数

数据库大对象告警相关：这三项指标分别统计超过compaction_large_cell_warning_threshold_mb、compaction_collection_elements_count_warning_threshold、compaction_large_row_warning_threshold_mb阈值的超大 cell、超大 collection 和超大行数量。对应配置项在 db/config.cc 中定义，其中compaction_large_cell_warning_threshold_mb默认值为 1（MB），compaction_collection_elements_count_warning_threshold默认值为 10000（个元素），二者均为 LiveUpdate 类型（可在线热更新）。大对象会对性能产生负面影响，官方建议尽量避免。

读取内存池相关：scylla_database_reads_memory_borrowed_from_shared_pool、scylla_database_reads_shared_pool_available_memory、scylla_database_reads_shared_pool_total_memory三项分别反映读取操作从共享池借用的内存、共享 reader 并发信号量池的可用内存与总内存，用于观测读取路径内存水位。

负载均衡与修复任务相关：scylla_group_name_rebuilds_produced、scylla_group_name_repairs_produced统计由 load balancer 产生的 rebuild 与 repair 任务数。

logstor 存储引擎相关：scylla_logstor_sm_separator_buffers_in_use（当前使用中的 separator buffer 数）、scylla_memory_logstor_bytes（logstor 当前占用的内存字节数）。

S3 对象存储客户端相关：针对 S3 HTTP 请求新增了一整套按方法区分的指标，包括scylla_s3_integrated_request_queue_length（随时间积分的排队请求数，单位 request-seconds），以及 CONNECT/DELETE/GET/HEAD/OPTIONS/PATCH/POST/PUT/TRACE 各方法对应的*_requests（请求总数）、*_latency_sec（总耗时秒数）、*_retries（重试次数）。

服务等级（Service Level）相关：scylla_service_level_worktype记录每个 service level 配置的工作负载类型：0 表示未指定，1 表示 batch，2 表示 interactive。

强一致性协调器相关：新增一组读写指标，包括scylla_strong_consistency_coordinator_read/write_errors（失败请求数）、*_latency与*_latency_summary（延迟直方图与摘要）、*_node_bounces（请求被弹回另一节点的次数）、*_shard_bounces（请求被弹回另一 shard 的次数），用于观测强一致性读写路径的协调行为。

CQL 传输层相关：scylla_transport_cql_client_timestamp_drift_histogram统计客户端提供的 CQL 时间戳与请求到达时服务器时间之间的漂移（微秒），可用于检测请求到达 CQL server 之前的传输延迟；scylla_transport_cql_request_latency_histogram统计传输层 CQL 请求延迟（微秒），从请求开始处理到响应写入 socket。

重命名指标：

2026.2 中的名称	2026.3 中的名称
scylla_s3_downloads_blocked_on_memory	scylla_s3_downloads_starving_on_max_concurrency

如果监控告警规则引用了旧指标名scylla_s3_downloads_blocked_on_memory，升级到 2026.3 后需要同步更新为新名称，否则告警将失效。此前 2026.x 系列的历史指标变更（如 2026.1 → 2026.2）同样记录在官方文档中，可在升级前一并核对。

结语

ScyllaDB 的升级体系始终围绕“滚动、串行、可回滚、可验证”四个原则设计：通过逐节点 drain、备份、停服、换源安装、启动、验证，将升级风险控制在单节点范围内；通过保留旧版本包与配置备份，为失败的升级保留了唯一的回滚窗口；通过nodetool status、storage_service/scylla_release_versionAPI 与日志检查三重手段确认节点健康。而 2026.3 的指标更新则提示监控体系需要与数据库版本同步演进。按照本文梳理的流程操作，即可在最小风险下完成 ScyllaDB 的版本升级。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ScyllaDB 升级指南：从 2026.x 到 2026.3 的滚动升级、回滚与指标变更全解析