向现有 ScyllaDB 集群添加新数据中心（DC）：完整操作指南与源码级原理解析-酒店常州论坛

向现有 ScyllaDB 集群添加新数据中心（DC）：完整操作指南与源码级原理解析

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

本指南系统讲解如何在单数据中心、多可用区（Multi-AZ）或多数据中心部署中，为正在运行的 ScyllaDB 集群平滑新增一个数据中心（DC），涵盖前置条件、snitch 与cassandra-rackdc.properties配置、keyspace 复制策略（Replication Strategy）更新、nodetool rebuild数据重建、全集群 repair 以及客户端流量隔离等完整流程。读完本文，你将掌握一套可复制、可验证的多数据中心扩容方案，并能理解NetworkTopologyStrategy、tablets 键空间与 rack list 复制因子在扩容中的底层行为。

为什么需要"往现有集群添加 DC"

为正在运行的 ScyllaDB 集群新增一个数据中心（DC）是一种典型的**横向扩展（out-scaling）**操作，它把数据副本分布到更多、通常是地理上更远的节点集合中。这样做带来的收益包括：

更高可用性（HA）：多副本跨数据中心分布后，单个 DC 的整体故障（如区域断电、网络分区）不会导致数据不可用；
更低的跨区延迟：把数据副本放在靠近用户的 DC，配合LOCAL_*一致性级别，客户端可以就近读取；
为多可用区（multi-AZ）或多地域（multi-region）容灾架构打基础。

该过程在官方文档中与以下操作并列，属于集群管理（cluster management）系列：创建集群（create-cluster.rst）、创建多 DC 集群（create-cluster-multidc.rst）、移除数据中心（decommissioning-data-center.rst）以及向集群添加节点（add-node-to-cluster.rst）。本文聚焦"在已有集群上新增一个 DC"这一增量场景。

整体流程包含以下阶段：

在新 DC 安装节点；
将新节点加入集群；
更新所选 keyspace 的复制策略，使其覆盖新 DC；
对新节点执行 rebuild；
执行全集群 repair；
更新监控栈（Monitoring stack）。

重要提示：必须在全部流程完成之前、开始从新数据中心读取数据之前，读完本指南。默认情况下，新 DC 加入后会被用于读操作，这一点需要特别留意。

前置条件（Prerequisites）

在开始动手之前，需要逐项确认以下条件：

1. 收集现有集群信息

登录集群中的任意一个节点，收集以下信息（来源见 _common/prereq.rst）：

信息项	获取命令
cluster_name	`grep cluster_name /etc/scylla/scylla.yaml`
seeds	`grep seeds: /etc/scylla/scylla.yaml`
endpoint_snitch	`grep endpoint_snitch /etc/scylla/scylla.yaml`
ScyllaDB 版本	`scylla --version`
Authenticator	`grep authenticator /etc/scylla/scylla.yaml`

其中cluster_name、seeds、endpoint_snitch三项在配置新 DC 节点时必须与现有集群完全一致（详见下文）。

2. 客户端一致性级别切换为 LOCAL_*

在所有客户端应用上，将一致性级别（Consistency Level）切换到LOCAL_*系列（LOCAL_ONE、LOCAL_QUORUM等），以防止协调节点（coordinator）访问正在添加的数据中心。

3. 安装"干净"的新 ScyllaDB 节点

在新数据中心安装全新的、无任何数据的 ScyllaDB 节点（关于"干净"的要求见下文清理节点数据），节点数量按需创建。安装步骤参见入门指南，但只执行到scylla.yaml配置阶段为止，不要提前启动节点。

如果节点在安装过程中自动启动了，请参照节点自动启动的处理：先停止服务、清空数据、再启动，以确保系统表反映正确的状态。

4. 集群拓扑变更需要 quorum

更新集群拓扑要求集群中至少有一半以上（quorum）节点可用。如果 quorum 已丢失，必须先恢复它再变更拓扑（参见处理节点故障）。可以使用nodetool status检查集群中节点的状态（命令文档见 nodetool status）。这一要求源自 _common/quorum-requirement.rst，是保证拓扑变更期间集群元数据一致性的前提。

清理节点数据（Clean Data from Nodes）

警告：新加入的节点必须是"干净"的（无任何数据），否则有数据丢失风险。

官方提供的清理命令如下（来源：clean-data-code.rst）：

sudo rm -rf /var/lib/scylla/data sudo find /var/lib/scylla/commitlog -type f -delete sudo find /var/lib/scylla/hints -type f -delete sudo find /var/lib/scylla/view_hints -type f -delete

说明：该命令依次清空数据目录（data）、提交日志（commitlog）、hint 文件（hints）与物化视图 hint 文件（view_hints）。执行前请确认该节点不是现有集群中的任何节点——它必须是一台全新安装、从未承载过数据的机器。若只是"启动过早"导致的脏状态，可参照 clear-data.rst 中"停止服务 → 清理数据 → 启动服务 →nodetool status验证"的流程处理。

添加新 DC 的完整步骤（Add New DC）

步骤一：确认所有 keyspace 使用 NetworkTopologyStrategy

警告：请确保所有** keyspace 都使用NetworkTopologyStrategy。** 如果不是，请先执行从 Simple 拓扑策略升级到 Network 策略：

检查用户 keyspace 与系统 keyspace（system_distributed、system_traces、system_audit）是否使用了SimpleStrategy；
满足"所有节点在同一 rack"或"RF 等于节点总数"等条件时可选择无停机流程，否则需按文档执行停机流程（停止流量 → 全量 repair → 改策略 → 再次 repair →nodetool cleanup→ 恢复流量）。

原因在于SimpleStrategy不感知数据中心与 rack 布局，无法把副本定向放置到新 DC，跨 DC 复制必须依赖NetworkTopologyStrategy。

步骤二：为现有数据中心配置正确的 Snitch

对现有数据中心的每个节点，编辑scylla.yaml中的endpoint_snitch，二选一：

Ec2MultiRegionSnitch—— 用于AWS 云上、跨多数据中心的部署；
GossipingPropertyFileSnitch—— 用于裸金属（bare metal）以及 AWS 之外的云部署。

从源码看，这两种 snitch 的实现分别位于 locator/ec2_multi_region_snitch.cc 与 locator/gossiping_property_file_snitch.cc。其中Ec2MultiRegionSnitch需要公网 IP 作为broadcast_address以支持跨 region 通信，并通过 AWS metadata 服务（/latest/meta-data/public-ipv4、/latest/meta-data/local-ipv4）获取地址信息（见 ec2_multi_region_snitch.cc#L16-L20）；它还会在 gossip 阶段向集群广播DC与RACK应用状态（见 ec2_multi_region_snitch.cc#L83-L89），这是跨 DC 节点能够识别彼此拓扑的关键机制。

步骤三：设置 DC 与 Rack 名称

编辑cassandra-rackdc.properties文件（位于/etc/scylla/下，仓库中的模板见 conf/cassandra-rackdc.properties），按所选 snitch 配置：

Ec2MultiRegionSnitch

该 snitch 会给每个 DC 和 rack 提供默认名称：region 名作为数据中心名，可用区（Availability Zone）作为 DC 内的 rack。

例如：位于us-east-1region 的节点，us-east是数据中心名，1是 rack 位置。

可以通过dc_suffix为数据中心名追加后缀。例如：

regionus-east，配置dc_suffix=_1_scylla→ 数据中心名为us-east_1_scylla
regionus-west，配置dc_suffix=_1_scylla→ 数据中心名为us-west_1_scylla

这一后缀机制在源码中有直接体现：ec2_snitch会调用 AWS metadata 服务获取可用区（如us-east-1a），将其解析为us-east（DC）+1a（rack），然后从属性文件读取dc_suffix追加到 DC 名后（见 locator/ec2_snitch.cc#L27-L51 与 locator/ec2_snitch.cc#L142-L152）。

GossipingPropertyFileSnitch

dc—— 设置数据中心名；
rack—— 设置 rack 名。

示例（文件模板来自 conf/cassandra-rackdc.properties）：

# cassandra-rackdc.properties # # The lines may include white spaces at the beginning and the end. # The rack and data center names may also include white spaces. # All trailing and leading white spaces will be trimmed. # dc=thedatacentername rack=therackname # prefer_local=<false | true> # dc_suffix=<Data Center name suffix, used by EC2SnitchXXX snitches>

源码中production_snitch_base定义了这些属性键：dc、rack、prefer_local、dc_suffix（见 locator/production_snitch_base.hh#L34-L37），并允许从属性文件中加载 DC/rack 名称（见 locator/production_snitch_base.cc#L48-L60）。GossipingPropertyFileSnitch通过 gossip 把本地 DC/rack 信息传播给其他节点，使整个集群获得一致的拓扑视图；默认prefer_local为false（见 locator/gossiping_property_file_snitch.cc#L130-L131），配置为true可让节点优先使用同 DC 内的节点进行通信。

注意：属性文件中 DC/rack 名称允许包含首尾空白，ScyllaDB 读取时会自动 trim。

步骤四：逐个重启现有数据中心节点

在现有数据中心中，逐个重启 ScyllaDB 节点（不要同时重启全部节点），使新的 snitch / DC / rack 配置生效：

支持的操作系统（OS）：

sudo systemctl restart scylla-server

Docker 部署（不重启容器，仅重启容器内的 scylla 服务）：

docker exec -it some-scylla supervisorctl restart scylla

步骤五：配置新数据中心的节点

对新数据中心的每个节点，编辑/etc/scylla/scylla.yaml中的以下参数：

参数	含义	要求
`cluster_name`	集群名称	必须与现有集群一致
`seeds`	现有集群中一个（或多个）节点的 IP	必须指向现有集群节点
`listen_address`	ScyllaDB 用于连接集群内其他节点的 IP	按节点实际网络配置
`endpoint_snitch`	选择的 snitch	必须与现有集群一致
`rpc_address`	CQL 客户端连接地址	按节点实际网络配置

其中seeds、cluster_name和endpoint_snitch必须与现有集群匹配。这些参数在源码 db/config.cc 中有明确定义：

cluster_name："用于防止不同逻辑集群中的机器互相加入；同一集群的所有节点必须使用相同值"（db/config.cc#L764-L765）；
listen_address：节点绑定用于与其他 ScyllaDB 节点通信的 IP/主机名，多节点部署必须修改默认值（db/config.cc#L766-L767）；
endpoint_snitch：决定节点定位与请求路由，GossipingPropertyFileSnitch被官方推荐用于生产环境（db/config.cc#L824-L834）；
rpc_address：原生传输（CQL）的监听地址（db/config.cc#L835-L842）。

此外，若使用Ec2MultiRegionSnitch，还需把broadcast_address设为公网 IP、listen_address设为私网 IP，并确保种子地址使用公网 IP、存储端口（storage_port或ssl_storage_port）在公网防火墙放行（见 db/config.cc#L1071-L1073 与 endpoint_snitch 说明）。

步骤六：设置新 DC 的 DC 与 Rack 名称

在新数据中心的每个节点上，按步骤三的方法设置 DC 与 Rack 名称（编辑/etc/scylla/cassandra-rackdc.properties）。建议新 DC 使用与现有 DC 不同的 DC 名（例如ASIA-DC），以便NetworkTopologyStrategy按 DC 区分副本放置。

步骤七：逐个启动新数据中心节点

在新数据中心中，逐个启动 ScyllaDB 节点：

支持的操作系统（OS）：

sudo systemctl start scylla-server

Docker 部署（容器已运行，仅启动容器内的 scylla 服务）：

docker exec -it some-scylla supervisorctl start scylla

步骤八：验证节点已加入集群

使用nodetool status验证新节点是否已成功加入集群。示例输出：

$ nodetool status Datacenter: US-DC ========================= Status=Up/Down |/ State=Normal/Leaving/Joining/Moving -- Address Load Tokens Owns Host ID Rack UN 54.191.2.121 120.97 KB 256 ? c84b80ea-cb60-422b-bc72-fa86ede4ac2e RACK1 UN 54.191.72.56 109.54 KB 256 ? 129087eb-9aea-4af6-92c6-99fdadb39c33 RACK1 UN 54.187.25.99 104.94 KB 256 ? 0540c7d7-2622-4f1f-a3f0-acb39282e0fc RACK1 Datacenter: ASIA-DC ======================= Status=Up/Down |/ State=Normal/Leaving/Joining/Moving -- Address Load Tokens Owns Host ID Rack UN 54.160.174.243 109.54 KB 256 ? c7686ffd-7a5b-4124-858e-df2e61130aaa RACK1 UN 54.235.9.159 109.75 KB 256 ? 39798227-9f6f-4868-8193-08570856c09a RACK1 UN 54.146.228.25 128.33 KB 256 ? 7a4957a1-9590-4434-9746-9c8a6f796a0c RACK1

解读：UN表示节点处于Up（在线）且状态为Normal（正常）；每行按Datacenter分组展示地址、负载、token 数、所有权（Owns）、Host ID 与 Rack。所有节点都应显示为UN才算加入成功。

步骤九：ALTER keyspace 复制策略（核心步骤）

当所有节点都已上线后，需要在新节点上执行ALTER KEYSPACE，把以下 keyspace 的复制策略扩展到新 DC：

用户创建的 keyspace（需要复制到新 DC 的那些）；
系统 keyspace：system_distributed、system_traces（例如在新 DC 复制 3 份）；
audit（若已启用）——在新 DC 复制 3 份。

vnode keyspace 示例（使用数字 RF）：

Before：

DESCRIBE KEYSPACE mykeyspace; CREATE KEYSPACE mykeyspace WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : 3};

ALTER 命令：

ALTER KEYSPACE mykeyspace WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : 3, '<new_dc>' : 3}; ALTER KEYSPACE system_distributed WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : 3, '<new_dc>' : 3}; ALTER KEYSPACE system_traces WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : 3, '<new_dc>' : 3};

After：

DESCRIBE KEYSPACE mykeyspace; CREATE KEYSPACE mykeyspace WITH REPLICATION = {'class': 'NetworkTopologyStrategy', '<existing_dc>' : 3, '<new_dc>' : 3}; CREATE KEYSPACE system_distributed WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : 3, '<new_dc>' : 3}; CREATE KEYSPACE system_traces WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : 3, '<new_dc>' : 3};

tablets keyspace（数字 RF）：复制因子要一步一步地加。

Before：

DESCRIBE KEYSPACE mykeyspace2; CREATE KEYSPACE mykeyspace2 WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : 3} AND tablets = { 'enabled': true };

逐步 ALTER（每次只加 1）：

ALTER KEYSPACE mykeyspace2 WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : 3, '<new_dc>' : 1} AND tablets = { 'enabled': true }; ALTER KEYSPACE mykeyspace2 WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : 3, '<new_dc>' : 2} AND tablets = { 'enabled': true }; ALTER KEYSPACE mykeyspace2 WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : 3, '<new_dc>' : 3} AND tablets = { 'enabled': true };

说明：tablets 是 ScyllaDB 的新一代数据分布机制，把每个表的数据按 range 切分为 tablet，并在节点间自动均衡（见 docs/architecture/tablets.rst）。tablets keyspace 在ALTER KEYSPACE后会触发后台的 tablet 迁移/复制，因此官方文档强调"逐次递增 RF"，避免一次性大幅变更带来的复制压力。

启用rf_rack_valid_keyspaces时的 rack list 场景：如果设置了rf_rack_valid_keyspaces选项，tablet keyspace 必须使用rack list 复制因子，这样新的 DC（rack）才能被加入。具体转换流程参见 CQL DDL 文档中的 conversion-to-rack-list-rf 小节：迁移时 rack 列表中的 rack 数量必须等于当前数字 RF，且同一语句中不允许同时做 RF 增减。此时添加数据中心的操作为：

Before（现有 DC 使用 rack list）：

DESCRIBE KEYSPACE mykeyspace3; CREATE KEYSPACE mykeyspace3 WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : ['<existing_rack1>', '<existing_rack2>', '<existing_rack3>']} AND tablets = { 'enabled': true };

先把所有节点加入新数据中心，然后逐步 ALTER：

ALTER KEYSPACE mykeyspace3 WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : ['<existing_rack1>', '<existing_rack2>', '<existing_rack3>'], '<new_dc>' : ['<new_rack1>']} AND tablets = { 'enabled': true }; ALTER KEYSPACE mykeyspace3 WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : ['<existing_rack1>', '<existing_rack2>', '<existing_rack3>'], '<new_dc>' : ['<new_rack1>', '<new_rack2>']} AND tablets = { 'enabled': true }; ALTER KEYSPACE mykeyspace3 WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : ['<existing_rack1>', '<existing_rack2>', '<existing_rack3>'], '<new_dc>' : ['<new_rack1>', '<new_rack2>', '<new_rack3>']} AND tablets = { 'enabled': true };

After：

DESCRIBE KEYSPACE mykeyspace3; CREATE KEYSPACE mykeyspace3 WITH REPLICATION = {'class': 'NetworkTopologyStrategy', '<existing_dc>' : ['<existing_rack1>', '<existing_rack2>', '<existing_rack3>'], '<new_dc>' : ['<new_rack1>', '<new_rack2>', '<new_rack3>']} AND tablets = { 'enabled': true };

可以考虑把rf_rack_valid_keyspaces升级为enforce_rack_list选项，以确保所有 tablet keyspace 都使用 rack list（转换流程与启用条件见 docs/architecture/tablets.rst#L208-L223：enforce_rack_list只有在所有 tablet keyspace 都已使用 rack list 时才能开启，开启后需重启所有节点，且重启期间不要执行任何 CREATE/ALTER KEYSPACE）。

rack list 场景下的 ALTER 规则（一次ALTER KEYSPACE语句内必须遵守）：

现有数据中心必须保持当前复制因子不变；
新数据中心可以被赋予复制因子（0 到 N）；
现有数据中心可以被移除（N 到 0）。

错误示例——同一语句既修改了<existing_dc>的 rack 列表（加入了<existing_rack4>），又添加了新 DC，这是不允许的：

ALTER KEYSPACE mykeyspace4 WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : ['<existing_rack1>', '<existing_rack2>', '<existing_rack3>', '<existing_rack4>'], '<new_dc>' : ['<new_rack1>', '<new_rack2>', '<new_rack3>']} AND tablets = { 'enabled': true };

正确做法：先把所有节点加入新数据中心，然后单独执行一条只新增<new_dc>rack list 的语句：

ALTER KEYSPACE mykeyspace4 WITH replication = { 'class' : 'NetworkTopologyStrategy', '<existing_dc>' : ['<existing_rack1>', '<existing_rack2>', '<existing_rack3>'], '<new_dc>' : ['<new_rack1>', '<new_rack2>', '<new_rack3>']} AND tablets = { 'enabled': true };

After：

DESCRIBE KEYSPACE mykeyspace4; CREATE KEYSPACE mykeyspace4 WITH REPLICATION = {'class': 'NetworkTopologyStrategy', '<existing_dc>' : ['<existing_rack1>', '<existing_rack2>', '<existing_rack3>'], '<new_dc>' : ['<new_rack1>', '<new_rack2>', '<new_rack3>']} AND tablets = { 'enabled': true };

补充背景：当配置中启用了enforce_rack_list（或已弃用的rf_rack_valid_keyspaces）且 keyspace 基于 tablet 时，数字复制因子会在语句执行时被自动展开为 rack list，这一展开结果可以在随后的DESCRIBE输出中观察到；如果数字 RF 小于 DC 内的 rack 数量，系统会任意选择一部分 rack（见 docs/cql/ddl.rst#L193-L201）。

一致性级别警告：添加新数据中心并 ALTER keyspace 期间，不要执行任何涉及新数据中心的读写操作。尤其要避免使用会把新 DC 纳入操作范围的全局一致性级别（如ALL、EACH_QUORUM）；在新 DC 完全就绪之前，请一直使用LOCAL_*一致性级别（如LOCAL_QUORUM、LOCAL_ONE）。

任务管理：keyspace 变更可能耗时较长，你可以使用 Task manager 中止正在进行的 keyspace 变更。Task manager 会跟踪压缩（compaction）等长时间运行的后台操作，任务以树形结构组织，其中集群级任务（cluster task）对所有节点可见。

步骤十：对新 DC 节点执行 nodetool rebuild

如果任何vnode keyspace被变更过，请在新数据中心的每个节点上运行nodetool rebuild，并指定现有数据中心的名字：

nodetool rebuild <existing_data_center_name>

nodetool rebuild会以类似 bootstrap 的方式，从集群中其他节点流式拉取（stream）数据：先计算本地节点负责的 range，再确定集群中哪些节点持有相同 range，若指定了source-dc-name则优先只从该数据中心的节点拉取（见 docs/operating-scylla/nodetool-commands/rebuild.rst#L4-L14）。rebuild 过程会持续在后台运行，即使 nodetool 命令被 kill 或中断也不会停止（见 rebuild.rst#L19）。rebuild 能确保新加入集群的节点识别出集群中已有的数据中心，从而正确完成数据同步。

注意：nodetool rebuild仅适用于 vnode keyspace。对于 tablet keyspace，请改用nodetool cluster repair（见 rebuild.rst#L28）。

步骤十一：执行全集群 repair

如果任何 vnode keyspace 被变更过，请执行全集群 repair：在每个节点上运行nodetool repair -pr，或使用 ScyllaDB Manager 的 ad-hoc repair 功能。

nodetool repair -pr中的-pr（primary range）只修复本节点作为 primary replica 的 range，这样可以在全集群每个节点依次执行，从而以最小冗余完成全量数据同步（参见 docs/operating-scylla/nodetool-commands/repair.rst）。repair 应定期执行；如果删除数据频繁，执行间隔应短于gc_grace_seconds（默认 10 天）。

步骤十二：更新监控与运维栈

如果使用ScyllaDB Monitoring，请更新监控栈以覆盖新 DC（通过从文件配置 Scylla 节点的方式添加新节点）；
如果使用ScyllaDB Manager，请在新 DC 的节点上安装Manager Agent，并确保 Manager 能够访问新 DC。

配置客户端不连接新 DC

本节提供一种方法，让客户端暂时不要连接刚添加的 DC。以下示例针对 Java driver，请按需调整。

在客户端将操作一致性级别设为CL=LOCAL_*（例如LOCAL_QUORUM），并使用DCAwareRoundRobinPolicy——通过withLocalDc("dcLocalToTheClient")指定客户端本地的 DC，通过withUsedHostsPerRemoteDc(0)禁止使用任何远程 DC 节点：

variable = DCAwareRoundRobinPolicy.builder() .withLocalDc("<name of DC local to the client being configured>") .withUsedHostsPerRemoteDc(0) .build();

一旦新 DC 完全就绪（数据重建、repair 全部完成），就可以从配置中移除withUsedHostsPerRemoteDc(0)，并把一致性级别恢复为之前的取值。

这一客户端策略与前置条件中"把所有客户端切换到LOCAL_*"相呼应：两者共同保证在扩容窗口期内，任何读写流量都不会触达尚未就绪的新 DC。

企业官网建设流程全解析