Scylla：Seastar 驱动的实时大数据数据库 — 从源码构建到运行实战指南

Scylla：Seastar 驱动的实时大数据数据库 — 从源码构建到运行实战指南

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

导读

Scylla 是一个基于 Seastar 框架、与 Apache Cassandra 和 Amazon DynamoDB 双 API 兼容的实时大数据数据库。它以"无共享（shared-nothing）"架构为核心设计理念，通过直接利用现代硬件能力来提升吞吐量、扩展存储容量并显著降低硬件成本。本文以仓库根目录的 README.md 为主体骨架，结合 HACKING.md、docs/dev/building.md、tools/toolchain/README.md、docs/dev/testing.md 等仓库文档与源码，完整讲解：项目定位与 API 兼容性、使用 frozen toolchain 构建 Scylla 的完整流程、三种构建模式的差异、本地运行与关键启动参数、基于test.py的测试体系，以及 DynamoDB 兼容接口 Alternator 的启用方式。读完后，你将掌握从零构建、运行、测试并接入 Scylla 的完整实操路径。

---

一、Scylla 是什么：定位、架构理念与双 API 兼容

1.1 项目定位

根据 README.md 的定义：

Scylla is the real-time big data database that is API-compatible with Apache Cassandra and Amazon DynamoDB.

Scylla 是一个实时大数据数据库，同时兼容两大主流 API 生态：

• Apache Cassandra：默认即兼容，其 CQL（Cassandra Query Language）API 开箱即用；
• Amazon DynamoDB：作为名为Alternator的功能提供，需要显式启用和配置后才能使用（详见本文第六节）。

1.2 核心架构理念：无共享（shared-nothing）

README 明确阐述了其架构设计取向：

Scylla embraces a shared-nothing approach that increases throughput and storage capacity to realize order-of-magnitude performance improvements and reduce hardware costs.

"无共享"（shared-nothing）意味着：每个 CPU 核心（shard）拥有自己独立的数据、内存与 I/O 路径，核心之间不共享锁和缓存，从根本上消除了多核竞争瓶颈。这一设计直接受益于 Scylla 所基于的 Seastar 框架（仓库中seastar/为子模块目录）——一个面向高性能服务器应用、以 futures 与 sharded 编程模型为核心的高性能 C++ 框架。README 中提到"order-of-magnitude performance improvements"（数量级的性能提升），这是 Scylla 官方对自己架构取向的表述。

从源码结构看，这一理念贯穿整个代码库：dht/（分布式哈希表与分区路由）、replica/（数据副本与存储引擎）、sstables/（SSTable 读写）、locator/（拓扑感知的副本放置策略）等模块共同支撑起分布式存储核心。

---

二、构建前置条件：为什么需要"挑剔"的构建环境

README 中特别强调了一个现实问题：

Scylla is fairly fussy about its build environment, requiring very recent versions of the C++23 compiler and of many libraries to build.

2.1 硬件与编译器要求

HACKING.md 给出了更具体的量化要求：

• 内存：编译 Scylla 保守估计每个本机线程需要 2 GB 内存，链接阶段每个本机线程最多需要 3 GB；
• 编译器：要求 GCC >= 10，且需要支持C++23标准的非常新的编译器（文档举例：Fedora 用户需升级到较新版本，否则 C++ 编译器太旧、不支持 Scylla 使用的 C++23 标准）。

2.2 两条依赖安装路径

HACKING.md 介绍了两种准备构建环境的方式：

1. 本机安装依赖：以 root 身份运行仓库根目录的./install-dependencies.sh，它会调用你所用 Linux 发行版的包管理器安装合适的软件包。但只适用于非常新的发行版；
2. frozen toolchain（冻结工具链）：这是官方极力推荐的方式，也是 ScyllaDB 生产官方发布版本所使用的方式。它通过./tools/toolchain/dbuild脚本，在一个预配置好的容器镜像中执行所有构建/运行命令——容器内恰好包含正确版本的编译器和库，无需改动构建机器的任何配置。

---

三、frozen toolchain：dbuild使用全解

3.1 工作原理

dbuild是一个 bash 脚本（位于 tools/toolchain/dbuild），其核心职责是：

• 自动探测本机可用的容器工具：优先使用 Podman，其次使用 Docker（通过DBUILD_TOOL环境变量可强制指定）；
• 从 tools/toolchain/image 文件读取当前工具链镜像名（当前仓库记录为docker.io/scylladb/scylla-toolchain:fedora-44-20260728），如需手动拉取可执行docker pull $(<tools/toolchain/image)；
• 以当前工作目录为挂载点启动容器，使你在容器内执行的命令直接操作仓库文件；
• 自动绑定挂载~/.cache、~/.config、~/.cargo、~/.m2等目录，使 sccache 等缓存跨运行持久化；
• 将主机用户/组 ID 传入容器（通过挂载/etc/passwd、/etc/group并配合setpriv降权），保证容器内产生的文件属主正确。

从 tools/toolchain/README.md 可知，该工具链镜像基于Fedora 发行版的包构建，并补充了 pip（Python）、cargo（Rust）等仓库中 Fedora 未打包的项目，还内置了一个 ScyllaDB 为加快编译而自行打包优化的 clang（见 tools/toolchain/optimized_clang.sh）。

3.2 基本用法

在仓库根目录下，用dbuild前缀任何命令即可：

$ ./tools/toolchain/dbuild ./configure.py $ ./tools/toolchain/dbuild ninja build/release/scylla $ ./tools/toolchain/dbuild ./build/release/scylla --developer-mode 1

• 交互式 shell：不带任何参数运行./tools/toolchain/dbuild会进入容器内的交互式 shell，工具链中的全部工具可直接使用；
• 跨目录使用：脚本也支持在其他目录下运行，例如你同时 check out 了scylla-ccm，可以写../scylla/tools/toolchain/dbuild ./ccm ...，容器内可同时访问两个项目；
• 重要提醒（来自 HACKING.md）：不要混用环境——要么全部用dbuild，要么全部在主机上原生执行，混用会导致构建状态不一致。

3.3 向docker run传递额外参数

dbuild允许你在要执行的命令前插入 Docker 参数，用--分隔参数与命令：

# 挂载额外卷（如 /var/lib/scylla）并设置环境变量 ./tools/toolchain/dbuild -e MYVAR=foo -v $HOME/data:/var/lib/scylla:z -- ninja

若想让某些参数对每次dbuild都生效，可把它们写入~/.config/scylladb/dbuild文件（内容为一个 bash 数组赋值）：

SCYLLADB_DBUILD=(-e PATH=/usr/lib64/ccache:/usr/bin:/usr/local/bin -v $HOME/.ccache:$HOME/.ccache:z)

该文件会被 tools/toolchain/dbuild 脚本自动 source；同时脚本也支持通过环境变量SCYLLADB_DBUILD传递同样的参数。

3.4 常见问题排查

tools/toolchain/README.md 记录了一个典型故障：容器内执行sudo失败并报sudo: unknown uid 1000: who are you?。解决方法是先在宿主机临时关闭 SELinux：

$ sudo setenforce 0

---

四、构建 Scylla：从源码到可执行文件

4.1 完整构建流程

README 给出的标准构建流程（配合 frozen toolchain）为：

$ git submodule update --init --force --recursive $ ./tools/toolchain/dbuild ./configure.py $ ./tools/toolchain/dbuild ninja build/release/scylla

三个步骤各司其职：

1. 同步子模块：Scylla 用 Git submodule 管理对 Seastar 等项目的依赖（见 HACKING.md），--force --recursive确保所有子模块按锁定版本完整拉取；
2. configure.py生成构建文件：configure.py 是一个 Python 脚本，根据配置选项生成 Ninja 构建文件build.ninja（类似 Makefile 的规则文件）。注意：源文件与构建目标是在configure.py中手工维护的，新增/删除文件或目标时需同步更新该脚本（见 HACKING.md）。可用./configure.py --help查看全部配置选项，其中最重要的一个是--enable-dpdk（DPDK 高速包处理库，开发阶段通常无需启用）；
3. ninja执行构建：Ninja 是底层基于规则的低级构建系统，构建产物输出到build/<mode>/目录。

4.2 三种构建模式

docs/dev/building.md 对构建模式给出了权威定义，可通过./configure.py --mode=<mode>指定：

模式	定位	编译速度	执行速度	特点
release	发布构建	慢	快	面向最快执行速度，优化充分，仍保留调试信息
dev	开发构建	快	尚可	面向最快编译速度，用于补丁迭代初期
debug	调试构建	慢	慢	面向错误发现，启用 AddressSanitizer 等健全性检查，无优化，便于 GDB 调试；但对象文件更大、运行更慢

HACKING.md 进一步说明：ninja <mode>可一次性构建该模式下的全部目标；debug模式启用 AddressSanitizer 等检查，release模式检查更少、优化更多。

不指定--mode时，build.ninja会包含所有构建模式的配置，之后可用ninja <mode>或ninja <mode>-build按需构建。

4.3 只构建指定目标以节省时间

HACKING.md 建议通过指定具体目标避免编译全部单元测试，例如：

$ ninja-build build/release/tests/schema_change_test $ ninja-build build/release/service/storage_proxy.o

注意：默认单元测试二进制是strip 过的，无法用于 GDB 或 seastar-addr2line。如需调试信息，构建带_g后缀的目标：

$ ninja-build build/release/tests/schema_change_test_g

4.4 打包与产物

docs/dev/building.md 描述了构建系统的产物：

• 可执行文件：build/<mode>/scylla
• 测试二进制：build/<mode>/test/**
• 可重定位包（relocatable packages）：执行ninja dist生成。所谓"可重定位"，指包内已包含全部依赖，可在所有 Linux 发行版上直接安装运行；.rpm和.deb都是基于这个 tarball 进一步构建的：
  • build/<mode>/dist/tar/scylla-unified-package.tar.gz、scylla-package.tar.gz、scylla-python3-package.tar.gz、scylla-jmx-package.tar.gz、scylla-tools-package.tar.gz
  • .rpm位于build/dist/<mode>/redhat/RPMS/x86_64/（如scylla-server-*.rpm、scylla-conf-*.rpm、scylla-debuginfo-*.rpm、scylla-kernel-conf-*.rpm、scylla-node-exporter-*.rpm）
  • .deb位于build/dist/<mode>/debian/（如scylla-server_*.deb、scylla-conf_*.deb、scylla-server-dbg_*.deb等）
• 验证包：ninja dist-check（注意：必须在宿主机上运行，因为它需要 Docker 执行验证）

---

五、运行 Scylla：开发环境启动指南

5.1 最小启动命令

README 给出了开发环境的最小启动方式：

$ ./tools/toolchain/dbuild ./build/release/scylla --workdir tmp --smp 1 --developer-mode 1

参数含义：

• --workdir tmp：将数据文件存放在当前目录下的tmp目录（README 原话：data files stored in thetmpdirectory）；
• --smp 1：仅分配1 个 CPU 核心给该节点；
• --developer-mode 1：关闭Scylla 启动时为确保机器已按最大性能配置而执行的各种环境检查（在开发工作站上不相关）。

务必注意：如果用 frozen toolchain 构建的 Scylla，运行时必须同样通过dbuild（README 明确提示）。更多运行选项用--help查看：

$ ./tools/toolchain/dbuild ./build/release/scylla --help

5.2--developer-mode的底层机制

从源码可以确认该参数的实际作用。它在 db/config.cc 中定义：

developer_mode ... "Relax environment checks. Setting to true can reduce performance and reliability significantly."

意即：放宽环境检查，但开启后会显著降低性能与可靠性——因此生产环境不应使用。在 main.cc 中，developer_mode被传递到多个启动验证函数（main.cc 处调用）：

• adjust_and_verify_rlimit()：调整并校验文件描述符等资源限制；
• verify_adequate_memory_per_shard()：校验每个 shard 的内存是否充足；
• verify_seastar_io_scheduler()：校验 Seastar I/O 调度器配置。

同时它也传入 utils/directories.cc 的disk_sanity()磁盘健全性检查，用于放宽对数据目录所在文件系统的检查（如块设备对齐等）。开发者模式下这些检查会放宽或跳过。

5.3 配置文件scylla.yaml

HACKING.md 说明了scylla可执行文件对配置的要求：

• 默认从$SCYLLA_HOME/conf/scylla.yaml读取配置文件；
• 仓库中提供了一个良好的开发起点：conf/scylla.yaml；
• 开发时的推荐做法：为 Scylla 相关文件建立独立目录，然后通过SCYLLA_HOME指向它：

$ mkdir -p $HOME/scylla $HOME/scylla/conf $ cp conf/scylla.yaml $HOME/scylla/conf/scylla.yaml $ # 按需编辑配置项 $ SCYLLA_HOME=$HOME/scylla build/release/scylla

关键注意：仓库中的scylla.yaml默认将所有数据库数据写入/var/lib/scylla（通常需要 root 权限）。开发时应按需修改data_file_directories、commitlog_directory和schema_commitlog_directory三个字段。

5.4 面向低配机器的启动参数

HACKING.md 还推荐了两个开发场景参数：

• --developer-mode：开发时放宽环境要求（也可写作--developer-mode=yes）；
• --overprovisioned：在性能不足的平台（如便携笔记本）上运行时很有用，它告诉 Scylla 机器的计算资源是过配置的，从而调整 I/O 与任务调度策略。

综合示例：

$ SCYLLA_HOME=$HOME/scylla build/release/scylla --overprovisioned --developer-mode=yes

docs/dev/building.md 中的本地启动示例还额外展示了限制内存的方式：

$ ./tools/toolchain/dbuild ./build/dev/scylla --workdir tmp --smp 1 --memory 1G

---

六、启用 DynamoDB 兼容 API（Alternator）

6.1 两种 API 的关系

README.md 明确：

• 默认：Scylla 兼容 Apache Cassandra 的 CQL API；
• 可选：支持 Amazon DynamoDB API（即Alternator功能），需要启用并配置后才能使用。

关于该功能的详细兼容性说明与 Scylla 特有扩展，README 指向两份文档：docs/alternator/alternator.md 和 docs/alternator/getting-started.md。从源码结构看，Alternator 的实现位于 alternator/ 目录（含server.cc、controller.cc、executor.cc等），其 controller.cc 中会将--alternator-write-isolation配置应用到写操作实现上。

6.2 用 Docker 快速启用 Alternator

docs/alternator/getting-started.md 给出了最快捷的路径——拉取官方 Docker 镜像并暴露 DynamoDB API 端口：

docker pull scylladb/scylla:latest

运行容器时，需要在镜像名前加上-p 8000:8000（把宿主机 8000 端口映射到容器内的 Alternator 端口），并在命令末尾追加两个参数：

docker run --name scylla -d -p 8000:8000 scylladb/scylla:latest \ --alternator-port=8000 --alternator-write-isolation=always

参数说明：

• --alternator-port=8000：指定 Scylla 监听DynamoDB API（未加密）的端口；
• --alternator-write-isolation=always：选择 Alternator 对每次写入是否使用 LWT（轻量级事务）。从 alternator/executor.cc 的源码看，该选项有严格的取值校验，非法值会抛出Invalid --alternator-write-isolation错误；
• --alternator-https-port=...：可额外启用加密（HTTPS）端口。此时必须把 SSL 证书与密钥文件/etc/scylla/scylla.crt和/etc/scylla/scylla.key放入镜像。

安全提示：以这种方式默认启动的 Scylla不启用认证/授权，任何 DynamoDB API 请求都会被接受（无需签名）。如何配置认证与授权，参见 docs/alternator/compatibility.md 中的 "Authentication and authorization" 一节。

6.3 用 boto3 验证 DynamoDB API

同样来自 docs/alternator/getting-started.md，安装 AWS 官方 Python SDK：

sudo pip install --upgrade boto3

然后依次运行三个脚本（表创建 → 写入 → 读取）：

1. 创建表（key为字符串类型的 HASH 分区键，计费模式 PAY_PER_REQUEST）：

import boto3 dynamodb = boto3.resource('dynamodb', endpoint_url='http://localhost:8000', region_name='None', aws_access_key_id='None', aws_secret_access_key='None') dynamodb.create_table( AttributeDefinitions=[ { 'AttributeName': 'key', 'AttributeType': 'S' }, ], BillingMode='PAY_PER_REQUEST', TableName='usertable', KeySchema=[ { 'AttributeName': 'key', 'KeyType': 'HASH' }, ])

2. 写入一条记录：

import boto3 dynamodb = boto3.resource('dynamodb', endpoint_url='http://localhost:8000', region_name='None', aws_access_key_id='None', aws_secret_access_key='None') dynamodb.batch_write_item(RequestItems={ 'usertable': [ { 'PutRequest': { 'Item': { 'key': 'test', 'x' : {'hello': 'world'} } }, } ] })

3. 读取并打印：

import boto3 dynamodb = boto3.resource('dynamodb', endpoint_url='http://localhost:8000', region_name='None', aws_access_key_id='None', aws_secret_access_key='None') print(dynamodb.batch_get_item(RequestItems={ 'usertable' : { 'Keys': [{ 'key': 'test' }] } }))

第三步应打印出第二步写入的记录。若使用 Docker 部署，请将脚本中的localhost替换为 Docker 节点的地址。

附带说明：如果使用自编译的 Scylla 构建 Docker 镜像，dist/docker/redhat/README.md 给出了流程：先构建好 Scylla（如 dev 模式），再ninja dist-dev准备发行产物，然后./dist/docker/redhat/build_docker.sh --mode dev生成 OCI 格式镜像文件，可用podman run oci-archive:... --alternator-port=8000 --alternator-write-isolation=always直接运行。

---

七、测试：用test.py驱动 C++/CQL/Python 测试

7.1 测试入口与要求

README 将测试入口指向 docs/dev/testing.md。test.py（位于仓库根目录 test.py）是随仓库分发的回归测试工具，运行C++（Boost）单元测试、CQL 测试和 Python 测试三类测试。

运行前提：

• Python 3.11 或更高；通常./install-dependencies.sh会安装全部所需 Python 模块；
• 或者直接用dbuild运行（此时无需执行 install-dependencies.sh）；
• 默认启用的--gather-metrics通过 cgroup 采集测试期间的 CPU/RAM 用量，要求当前终端进程位于当前用户具备 RW 权限的正确 cgroup 中。若不满足，可改用--no-gather-metrics关闭、用systemd-run --user --scope ./test.py运行，或手动创建 cgroup（详见 docs/dev/testing.md）。

7.2 常用用法

$ ./test.py # 运行所有已配置构建模式下全部测试 $ ./tools/toolchain/dbuild ./test.py # 通过 toolchain 运行 $ ./test.py --mode=dev # 指定构建模式 $ ./test.py test/cqlpy/ # 只跑某个目录 $ ./test.py test/cqlpy/test_null.py # 只跑某个文件 $ ./test.py test/boost/aggregate_fcts_test.cc::test_aggregate_avg # 只跑某个用例 $ ./test.py -k 'test_null or test_empty' # 按名称表达式过滤 $ ./test.py -k 'not test_slow' # 排除匹配项 $ ./test.py --skip test_slow # 跳过匹配项

构建产物、测试输出保存在./testlog，Scylla 数据文件存放在/tmp。test.py是 pytest 的薄封装：启动时调用ninja探测已配置构建模式、组装 pytest 参数，并通过pytest-xdist按 CPU 核数、内存与构建模式并行执行测试；即使某个测试失败，也会继续运行其余测试。

7.3 CQL 测试的"验收测试"机制

docs/dev/testing.md 解释了 CQL 测试的核心思想：测试作者只写要在 Scylla 上执行的 CQL 语句，test.py负责其余一切——语句输出被记录到专属文件，用于事后校验正确性（即 "approval testing" 验收测试方法）。执行时，CqlTest.runtest()读取 CQL 输入文件、对预先启动的 Scylla 执行语句、以表格形式输出到testlog下的临时文件，最后与预录制的test/suitename/testname_test.result比对。不匹配时会生成testname_test.reject文件并输出 diff 前几行；开发者在充分审查 diff 并理解每处变更原因后，可用mv test/suitename/testname.re*更新.result文件。

7.4 稳定性要求

docs/dev/testing.md 对测试质量提出了明确要求：贡献的新测试需 (1) 在debug 模式下运行，且 (2) 用--repeat 100连续运行 100 次全部通过，以证明其稳定（非 flaky）。

7.5 测试报告与度量

• 失败时test.py返回非零退出码，并生成 JUnit XML 汇总报告testlog/report/pytest_cpp_{HOST_ID}.xml，供 Jenkins 等 CI 生成格式化构建报告；
• 指标数据（配合--gather-metrics）存入testlog/sqlite_{HOST_ID}.db，包含tests、test_metrics、system_resource_metrics、cgroup_memory_metrics等表；
• 可选 Allure 报告：安装 allure 后执行allure serve -h localhost .即可查看交互式报告。

---

八、文档地图与进阶资源

README 为不同角色规划了文档入口（以下均为仓库内相对路径，可直接点击）：

需求	文档
构建与开发 Scylla	HACKING.md
构建可执行文件、测试与软件包	docs/dev/building.md
构建 Docker 镜像	dist/docker/redhat/README.md
测试手册（test.py）	docs/dev/testing.md
开发者文档索引	docs/dev/README.md
Alternator（DynamoDB API）兼容性	docs/alternator/alternator.md
Alternator 上手	docs/alternator/getting-started.md
贡献指南	CONTRIBUTING.md

---

结语

本文以 README.md 为核心骨架，串起了 Scylla 从项目定位、构建环境准备、dbuild容器化构建、三种构建模式、开发环境启动与关键参数（--developer-mode、--overprovisioned、--workdir、--smp）、Alternator 的 DynamoDB API 启用与验证，到test.py测试体系的全链路实操路径，并以 HACKING.md、docs/dev/building.md、tools/toolchain/README.md、docs/dev/testing.md 及 main.cc、db/config.cc、alternator/ 等源码作为佐证。无论你是想快速跑通一个开发节点、深入理解其构建系统，还是打算为 DynamoDB 兼容层做二次开发，以上命令与参数均可直接在你的环境中复制运行。

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