ScyllaDB 对象存储实战将 SSTable 直接存放在 S3/GCS 上以及备份、布局与手工运维【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb本文基于 ScyllaDB 仓库内 docs/dev/object_storage.md 编写系统讲解 ScyllaDB 的三种对象存储S3/GCS数据写入机制CREATE KEYSPACE存储选项、/storage_service/backup快照备份 REST API、Scylla Manager 备份。读完后你将掌握如何在scylla.yaml中配置 AWS S3 与 GCS 端点及凭证解析链路、如何创建对象存储支持的 keyspace、备份数据在桶中的目录布局与manifest.json各字段含义、SSTable 共享引用refs/nodes/的生命周期以及在 SSTable 损坏需要离线 scrub 时用 AWS CLI 手工下载/删除/上传的操作命令。功能概览与启用方式对象存储的两种核心用法是把 SSTable 直接作为对象存放在 S3/GCS 上由 keyspace 级存储选项驱动以及把本地data/目录下的 SSTable 备份上传到对象存储。对象存储支持的 keyspace开箱即用无需任何实验性 feature flag只需在scylla.yaml中配置好对象存储端点然后用CREATE KEYSPACE的存储扩展参数创建 keyspace 即可。把 SSTable 通过/storage_service/backupAPI 上传到 S3 的好处在于该操作所需的磁盘 IO 带宽与 IOPS、CPU 时间、网络带宽等资源都受 Seastar 控制调度器层面限流常规 Scylla 工作负载不会被打扰。从源码看端点配置项在 db/config.cc 中定义object_storage_endpoints是LiveUpdate级别的配置项与之配套的还有两个相关参数配置项默认值说明object_storage_endpoints空对象存储端点列表每项为 S3 或 GS 配置object_storage_connections_per_shard128每个 shard 的对象存储连接数上限object_storage_clients_memory_fraction0.01对象存储客户端占用的内存比例端点参数的类型定义在 db/object_storage_endpoint_param.hh它是一个std::variants3_storage, gs_storage其中s3_storageendpoint、region、iam_role_arnSTS 用以及legacy_format标记gs_storageendpoint可为default/空或完整 URI、可选的credentials_file。这与下文配置章节一一对应。在 scylla.yaml 中配置对象存储端点配置 AWS S3 访问在scylla.yaml中定义端点细节例如object_storage_endpoints: - name: https://s3.us-east-1.amazonaws.com:443 aws_region: us-east-1配置 GCP Storage 访问与 AWS 类似在scylla.yaml中定义端点object_storage_endpoints: - name: https://storage.googleapis.com type: gs credentials_file: gcp account credentials json file通常 GCS 只使用同一个端点 URI除非使用私有代理或 mock server因此name也可以直接用default这个约定名。关于 GS 凭证的几种情况credentials_file可以省略此时使用机器上的默认凭证解析当前用户的凭证或在 GCP 实例上回退到机器实例凭证环境变量GOOGLE_APPLICATION_CREDENTIALS可以指向一个凭证文件如果未设置任何凭证文件则按 GCP 默认规则搜索即 GCP 本地数据目录中的application_default_credentials.json也可以把credentials_file设为none以完全跳过认证在对 mock server 做测试时很有用。本地/开发环境的凭证在本地或开发环境中通常需要通过环境变量设置 AWS 认证令牌客户端才能正常工作例如export AWS_ACCESS_KEY_IDEXAMPLE_ACCESS_KEY_ID export AWS_SECRET_ACCESS_KEYEXAMPLE_SECRET_ACCESS_KEY还可以包含aws_session_token尽管本地/开发环境通常不需要export AWS_ACCESS_KEY_IDEXAMPLE_ACCESS_KEY_ID export AWS_SECRET_ACCESS_KEYEXAMPLE_SECRET_ACCESS_KEY export AWS_SESSION_TOKENEXAMPLE_TEMPORARY_SESSION_TOKEN对于 GS使用本地 mock server 时一般不做认证。生产环境凭证解析顺序重要说明上面的环境变量方式只适合开发或本地环境生产环境绝不应使用这种方式。Scylla 的 S3 客户端会优先尝试从环境变量读取凭证获取失败后再尝试从 AWS Security Token ServiceSTS或 EC2 Instance Metadata ServiceIMDS获取。对于 EC2 IMDS无需任何额外配置即可工作对于 STS需要在scylla.yaml中定义 IAM Role ARNobject_storage_endpoints: - name: https://s3.us-east-1.amazonaws.com:443 aws_region: us-east-1 iam_role_arn: arn:aws:iam::123456789012:instance-profile/my-instance-instance-profile这个iam_role_arn字段正对应 db/object_storage_endpoint_param.hh 中s3_storage结构体的iam_role_arn成员。创建对象存储 keyspaceSSTable 位置是 keyspace 作用域的。要用 S3 存储创建 keyspace需使用CREATE KEYSPACE并附加STORAGE { type: S3, endpoint: $endpoint_name, bucket: $bucket }参数其中$endpoint_name必须匹配scylla.yaml中已配置端点的name。S3 示例在scylla.yaml中object_storage_endpoints: - name: https://s3.us-east-2.amazonaws.com:443 aws_region: us-east-2创建 keyspace 时CREATE KEYSPACE ks WITH REPLICATION { class : NetworkTopologyStrategy, replication_factor : 1 } AND STORAGE { type : S3, endpoint : s3.us-east-2.amazonaws.com, bucket : bucket-for-testing };GS 示例GS 的配置与 AWS S3 一一对应。在scylla.yaml中object_storage_endpoints: - name: default credentials_file: credentials file|none创建 keyspace 时CREATE KEYSPACE ks WITH REPLICATION { class : NetworkTopologyStrategy, replication_factor : 1 } AND STORAGE { type : GS, endpoint : default, bucket : bucket-for-testing };这些 CQL 扩展的完整语法可参考 ScyllaDB CQL 扩展文档。从源码结构看STORAGE选项最终被解析为 data_dictionary/storage_options.hh 中的data_dictionary::storage_options它是std::variantlocal, object_storage其中object_storage携带bucket、endpoint、可选的location前缀和type字段并提供S3_NAME/GS_NAME常量与from_map/to_map用于与 CQL map 互相转换。也就是说 keyspace 的存储选项是模式的一部分在 schema 层面持久化。通过 /storage_service/backup 上传 SSTable 快照备份可以把data/目录中的 SSTable 通过 API 上传到 S3/GS。如前所述该操作的全部资源开销磁盘 IO 带宽与 IOPS、CPU 时间、网络带宽都在 Seastar 的控制之下不会随机冲击常规工作负载。API 端点名为/storage_service/backup其 Swagger 描述见 api/api-doc/storage_service.json。接受的参数为keyspace要复制 SSTable 的 keyspacetable要复制 SSTable 的表snapshot要复制 SSTable 的快照名endpoint对象存储配置中的键可以是 AWS 或 GCP 端点bucket存放 SSTable 文件的 bucket 名prefixSSTable 文件存放的前缀从 api/api-doc/storage_service.json 的规范中还可以确认endpoint、bucket、prefix、keyspace、table为必填 query 参数snapshot与move_files以移动代替复制组件文件为可选参数。目前只支持快照备份因此需要先执行 snapshot。keysapce 中所有表都会被上传目标对象名形如s3://bucket/some/prefix/to/store/data/.../sstable或gs://bucket/some/prefix/to/store/data/.../sstable对象存储相关的系统表对象存储相关代码需要读写几张系统表system_distributed.snapshot_sstables —— 恢复期间由 worker 节点使用用于获取需要从对象存储下载并恢复到本地的 SSTable 列表system.sstables —— 当一个以对象存储为存储选项的 keyspace 被创建后用来跟踪存放在对象存储上的 SSTable。从源码看db/system_keyspace.hh 中提供了sstables_registry_*一族操作sstables_registry_create_entry登记新 SSTable 条目、sstables_registry_update_entry_status/sstables_registry_update_entry_state更新 status/state、sstables_registry_delete_entry删除条目、sstables_registry_list按 table 与 node owner 遍历条目与下文布局章节中system.sstables的作用相互印证。手工运维 S3 上的数据本节说明 Scylla 在何时、何处、以何种方式把数据写入 S3/GS并给出一组快速命令以便在需要人工介入时获取对数据的本地访问。绝大多数情况下不需要直接触碰 S3 上的数据——存在透明的 REST API 与 Scylla Manager 命令来完成备份和恢复且 Scylla 配合 ScyllaDB CQL 扩展 中记载的CREATE KEYSPACE可以正常工作。但是如果 SSTable 损坏、在重新上传之前需要离线 scrub或者排查 bug 需要分析备份数据则按下面的说明访问数据。三种向 S3/GS 写入数据的机制1. Scylla Manager 备份使用sctool执行备份时会在作为参数传入的 bucket 内创建backup前缀该前缀下 Scylla Manager 按集群名、数据中心、keyspace 等维度组织所有备份任务的备份数据。backup前缀下的精确布局请参考 Scylla Manager 官方文档的备份规范说明原文档给出的外部链接此处不再列出。2. /storage_service/backup REST API使用/storage_service/backupREST API 时数据存放在作为参数传入的前缀之下。该前缀下的结构与典型的 Scylla 快照相同有一个 manifest 文件列出每个 SSTable 的数据文件清单另有 schema 文件和所有 SSTable 组件平铺存放在前缀下scylla-bucket/prefix/ │ ├── manifest.json ├── schema.cql │ ├── me-3gqe_1lnj_4sbpc2ezoscu9hhtor-big-Data.db ├── me-3gqe_1lnj_4sbpc2ezoscu9hhtor-big-Index.db ├── me-3gqe_1lnj_4sbpc2ezoscu9hhtor-big-Summary.db ├── ... │ ├── ma-1abx_k29m_9fyug3sdtjwj8krpqh-big-Data.db ├── ma-1abx_k29m_9fyug3sdtjwj8krpqh-big-Index.db ├── ma-1abx_k29m_9fyug3sdtjwj8krpqh-big-Summary.db ├── ... │ └── ... (更多 SSTable 组件)snapshot 的 manifest.json每个表快照目录都包含一个manifest.json文件列出快照内容与元数据。JSON 结构如下{ manifest: { version: 1.0, scope: node }, node: { host_id: UUID, datacenter: mydc, rack: myrack }, snapshot: { name: snapshot name, created_at: seconds_since_epoch, expires_at: seconds_since_epoch | null, }, table: { keyspace_name: my_keyspace, table_name: my_table, table_id: UUID, tablets_type: none|powof2, tablet_count: N }, sstables: [ { id: 67e35000-d8c6-11f0-9599-060de9f3bd1b, toc_name: me-3gw7_0ndy_3wlq829wcsddgwha1n-big-TOC.txt, data_size: 75, index_size: 8, first_token: -8629266958227979430, last_token: 9168982884335614769, }, { id: 67e35000-d8c6-11f0-85dc-0625e9f3bd1b, toc_name: me-3gw7_0ndy_3wlq821a6cqlbmxrtn-big-TOC.txt, data_size: 73, index_size: 8, first_token: 221146791717891383, last_token: 7354559975791427036, }, ... ], files: [ ... ] }各成员含义manifestversion—— manifest 自身结构的版本当成员被增删时递增scope—— 该 manifest 文件存储元数据的范围当前支持node—— 该 manifest 描述本节点在此快照中拥有的全部 SSTable。node本节点的元数据用于支持数据中心/机架感知的恢复。host_id—— 节点唯一 host_idUUIDdatacenter—— 节点所在数据中心rack—— 节点所在机架。snapshot快照元数据。name—— 快照名即tagcreated_at—— 快照创建时间expires_at—— 可选快照过期可删除时间若设置了 TTL无 TTL 时可省略、为 null 或为 0。table被快照表的元数据。keyspace_name与table_name—— 表名与 keyspace 名table_id—— 建表时设置的 UUIDtablets_typenone—— keyspace 使用 vnode 复制powof2—— keyspace 使用 tablet 复制且 tablet token 区间基于 2 的幂arbitrary—— keyspace 使用 tablet 复制且 tablet token 区间与数量可以是任意值tablet_count—— 可选。tablets_type非none时表示表中分配的 tablet 数量tablets_type为powof2时该值是 2 的幂。sstables快照中 SSTable 的元数据列表。id—— SSTable 唯一 idUUID在 tablet 迁移以流式方式搬运 SSTable 时会随之携带即使生成了新的 generationtoc_name—— SSTable 目录TOC组件名data_size与index_size—— 数据组件与索引组件的大小可用于估算恢复所需磁盘空间first_token与last_token—— SSTable 的首末 token可用于判断 SSTable 是否完全包含在某个tablettoken 区间内从而启用高效的基于文件的 SSTable 流式传输。files可选快照目录中非 SSTable 文件的列表不含 manifest.json 与 schema.cql。该 manifest 的序列化/反序列化实现位于 db/snapshot/manifest.cc 与 db/snapshot/manifest.hh字段名version/scope/host_id/tablets_type/toc_name/first_token等与上文 JSON 结构一一对应快照备份的上传/下载流程实现在 db/snapshot/cluster_backup.cc。3. CREATE KEYSPACE 使用 S3/GS 存储创建带 S3/GS 存储的 keyspace 时数据存放在CREATE KEYSPACE语句传入的 bucket 之下。语句发出后Scylla 会透明地使用该 S3/GS bucket 作为该 keyspace SSTable 的存放位置。自动管理的对象存储表采用 S3 与 GS 共享的统一布局SSTable 组件存放在静态的sstables/前缀下并按**稳定的 SSTable 标识符sstable_id**分组而不是按节点本地的 generation 名分组scylla-sstables-bucket/ │ └── sstables/ ├── 4f4d0a90-d8c6-11f0-8b18-060de9f3bd1b/ │ ├── Data.db │ ├── Index.db │ ├── Summary.db │ ├── TOC.txt │ ├── ... │ └── refs/ │ └── nodes/ │ ├── 7adf1ca2-6783-40ab-aa1f-ef1e0b5d98ba/ │ │ └── 3gqe_1lnj_4sbpc2ezoscu9hhtor │ └── 10e68be1-d352-4173-bf34-2249dbb7329e/ │ └── 4c5s_0281_0v5kg2b4gri84iggoz ├── 87a72290-d8c6-11f0-a5ea-060de9f3bd1b/ │ ├── Data.db │ ├── Index.db │ ├── Summary.db │ ├── TOC.txt │ ├── ... │ └── refs/ │ └── nodes/ │ └── 7adf1ca2-6783-40ab-aa1f-ef1e0b5d98ba/ │ └── 5n8a_03tw_2jv4g2a4k2m33sq8ah └── ...关键路径约定托管 SSTable 前缀sstables/每个 SSTable 位于sstables/{sstable_id}/SSTable 组件的对象名即本地 SSTable 格式的组件后缀如Data.db、Index.db、Summary.db、Scylla.db、TOC.txt引用对象sstables/{sstable_id}/refs/nodes/{host_id}/{generation}—— 记录哪些节点仍持有对该 SSTable 数据的引用对象体为空对象名本身就是元数据{host_id}标识节点{generation}是该节点对共享 SSTable 的本地 generation 名。{sstable_id}标识共享的对象存储 SSTable 数据本地{generation}标识system.sstables中的节点本地 SSTable 条目。新建 SSTable 的sstable_id通常由其 generation 派生经过 tablet 迁移或引用共享后多个本地 SSTable 条目可以拥有不同 generation但通过同一个sstable_id指向同一份对象存储数据。对象存储 SSTable 的生命周期创建Scylla 在{sstable_id}下上传组件对象并在封住sealsystem.sstables中的本地行之前创建本节点的refs/nodes/{host_id}/{generation}引用共享当 tablet 迁移能够共享对象存储数据时接收方节点创建一个以自己 generation 命名的新本地 SSTable 条目并在既有{sstable_id}前缀下新增节点引用而不复制所有组件对象本地移除节点移除本地 SSTable 时先删除自己的引用对象若仍有其他引用组件对象保持完好最终清理只有当某个sstable_id下不再有任何引用对象时才删除组件对象。这防止一个节点删掉另一个节点仍引用的共享数据。system.sstables中的status与state字段描述的是本地 SSTable 条目的生命周期而不是sstable_id标识的对象存储组件集合的全局生命周期状态。从源码结构看refs/nodes/引用对象的读写逻辑位于 sstables/storage.cc。用 AWS CLI 下载、删除、上传 SSTable手工管理 S3 上的 SSTable 可以使用 AWS CLI。前提已安装 awscli见 AWS 官方安装指南此处不列外部链接且~/.aws/credentials指向一组有效的 S3 凭证——如果是基于 OKTA 的凭证获取工具则刷新凭证或确保凭证指向拥有 S3 访问权限的有效 IAM 用户。确认前置条件满足的标准是能够执行aws s3 ls s3://your-bucket/并且能看到内容如果 bucket 为空则至少不报错。之后即可执行以下命令注意先对照上文各用法的前缀布局。下载 SSTable逐个复制组件aws s3 cp s3://your-bucket/path/to/sstable/me-3gqb_1izi_0pxn421yzymfw5c8zf-big-Data.db /local/path/to/sstable/component或用 glob 下载整个 SSTableaws s3 cp s3://your-bucket/path-to-sstables/ /local/path/for/sstables --exclude * --include some-sstable-generation-big-* --recursive删除 SSTable逐个删除组件aws s3 rm s3://your-bucket/path/to/sstable/me-3gqb_1izi_0pxn421yzymfw5c8zf-big-Data.db或用 glob 删除整个 SSTableaws s3 rm s3://your-bucket/path-to-sstables/ --exclude * --include some-sstable-generation-big-* --recursive上传 SSTable逐个上传组件aws s3 cp /local/path/to/sstable/me-3gqb_1izi_0pxn421yzymfw5c8zf-big-Data.db s3://your-bucket/path/to/sstable/component或用 glob 上传整个 SSTableaws s3 cp /local/path/for/sstables s3://your-bucket/path-to-sstables/ --exclude * --include some-sstable-generation-big-* --recursive元数据修正Metadata touchupsScylla Manager 备份场景如果需要手工 scrub 并重新上传 SSTable多处内容都需要改动若要彻底丢弃某些 SSTable 也一样。如 Scylla Manager 备份规范文档所述每个节点维护一个 JSON manifest其中包含大量依赖 SSTable 的信息本节点拥有的每表 SSTable 列表本节点拥有的表中每个 chunk 的 SSTable 总大小本节点拥有的所有表 chunk 的总大小本节点拥有的 token 列表上述字段名都暗示这些信息依赖 SSTable 内容因此任何本地修复损坏 SSTable 后重新上传的尝试很可能都要求同步更新该节点 manifest 文件中的这些字段——scrub 后的 SSTable 在上述各字段的值上大概率都会变化。/storage_service/backupREST API 场景理论上只有从备份中整体移除一个 SSTable时才需要修改 manifest 文件并删除对应条目其他情况下无需改动元数据。CREATE KEYSPACE使用 S3/GS 存储场景Scylla 在system.sstables中跟踪对象存储 SSTable并依据 SSTable 前缀下的引用对象决定何时可以删除组件对象。对该布局对象的手工修改必须保持三者一致system.sstables条目、组件对象、以及refs/nodes/{host_id}/{generation}引用对象。提示重新上传 scrub 过的 SSTable 意味着重新上传它的所有组件因为其中大多数组件大概率都已变化。相关端到端行为可以在 test/cluster/object_store/test_backup.py 等测试中查看快照 manifest 结构的单元测试参见 test/boost/tablet_aware_restore_test.cc。小结端点配置scylla.yaml的object_storage_endpoints支持 S3aws_region、iam_role_arn与 GStype: gs、credentials_file可设为none两类端点凭证解析顺序为环境变量 → IMDS/STSS3与本地/GCE 默认凭证GS。keyspace 存储CREATE KEYSPACE ... AND STORAGE { type: S3|GS, endpoint: ..., bucket: ... }使 SSTable 透明存放在桶的sstables/{sstable_id}/布局下refs/nodes/{host_id}/{generation}引用对象保障共享数据的引用计数式清理。快照备份/storage_service/backup在 Seastar 资源控制下把快照 SSTable 平铺上传附带manifest.json与schema.cql恢复与共享依赖system_distributed.snapshot_sstables与system.sstables两张系统表。手工运维先按三种写入机制确认前缀布局再用aws s3 cp/rm配合 generation glob 操作组件凡改动 SSTable 内容务必同步评估 manifest /system.sstables/ 引用对象的一致性。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ScyllaDB 对象存储实战：将 SSTable 直接存放在 S3/GCS 上，以及备份、布局与手工运维
ScyllaDB 对象存储实战将 SSTable 直接存放在 S3/GCS 上以及备份、布局与手工运维【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb本文基于 ScyllaDB 仓库内 docs/dev/object_storage.md 编写系统讲解 ScyllaDB 的三种对象存储S3/GCS数据写入机制CREATE KEYSPACE存储选项、/storage_service/backup快照备份 REST API、Scylla Manager 备份。读完后你将掌握如何在scylla.yaml中配置 AWS S3 与 GCS 端点及凭证解析链路、如何创建对象存储支持的 keyspace、备份数据在桶中的目录布局与manifest.json各字段含义、SSTable 共享引用refs/nodes/的生命周期以及在 SSTable 损坏需要离线 scrub 时用 AWS CLI 手工下载/删除/上传的操作命令。功能概览与启用方式对象存储的两种核心用法是把 SSTable 直接作为对象存放在 S3/GCS 上由 keyspace 级存储选项驱动以及把本地data/目录下的 SSTable 备份上传到对象存储。对象存储支持的 keyspace开箱即用无需任何实验性 feature flag只需在scylla.yaml中配置好对象存储端点然后用CREATE KEYSPACE的存储扩展参数创建 keyspace 即可。把 SSTable 通过/storage_service/backupAPI 上传到 S3 的好处在于该操作所需的磁盘 IO 带宽与 IOPS、CPU 时间、网络带宽等资源都受 Seastar 控制调度器层面限流常规 Scylla 工作负载不会被打扰。从源码看端点配置项在 db/config.cc 中定义object_storage_endpoints是LiveUpdate级别的配置项与之配套的还有两个相关参数配置项默认值说明object_storage_endpoints空对象存储端点列表每项为 S3 或 GS 配置object_storage_connections_per_shard128每个 shard 的对象存储连接数上限object_storage_clients_memory_fraction0.01对象存储客户端占用的内存比例端点参数的类型定义在 db/object_storage_endpoint_param.hh它是一个std::variants3_storage, gs_storage其中s3_storageendpoint、region、iam_role_arnSTS 用以及legacy_format标记gs_storageendpoint可为default/空或完整 URI、可选的credentials_file。这与下文配置章节一一对应。在 scylla.yaml 中配置对象存储端点配置 AWS S3 访问在scylla.yaml中定义端点细节例如object_storage_endpoints: - name: https://s3.us-east-1.amazonaws.com:443 aws_region: us-east-1配置 GCP Storage 访问与 AWS 类似在scylla.yaml中定义端点object_storage_endpoints: - name: https://storage.googleapis.com type: gs credentials_file: gcp account credentials json file通常 GCS 只使用同一个端点 URI除非使用私有代理或 mock server因此name也可以直接用default这个约定名。关于 GS 凭证的几种情况credentials_file可以省略此时使用机器上的默认凭证解析当前用户的凭证或在 GCP 实例上回退到机器实例凭证环境变量GOOGLE_APPLICATION_CREDENTIALS可以指向一个凭证文件如果未设置任何凭证文件则按 GCP 默认规则搜索即 GCP 本地数据目录中的application_default_credentials.json也可以把credentials_file设为none以完全跳过认证在对 mock server 做测试时很有用。本地/开发环境的凭证在本地或开发环境中通常需要通过环境变量设置 AWS 认证令牌客户端才能正常工作例如export AWS_ACCESS_KEY_IDEXAMPLE_ACCESS_KEY_ID export AWS_SECRET_ACCESS_KEYEXAMPLE_SECRET_ACCESS_KEY还可以包含aws_session_token尽管本地/开发环境通常不需要export AWS_ACCESS_KEY_IDEXAMPLE_ACCESS_KEY_ID export AWS_SECRET_ACCESS_KEYEXAMPLE_SECRET_ACCESS_KEY export AWS_SESSION_TOKENEXAMPLE_TEMPORARY_SESSION_TOKEN对于 GS使用本地 mock server 时一般不做认证。生产环境凭证解析顺序重要说明上面的环境变量方式只适合开发或本地环境生产环境绝不应使用这种方式。Scylla 的 S3 客户端会优先尝试从环境变量读取凭证获取失败后再尝试从 AWS Security Token ServiceSTS或 EC2 Instance Metadata ServiceIMDS获取。对于 EC2 IMDS无需任何额外配置即可工作对于 STS需要在scylla.yaml中定义 IAM Role ARNobject_storage_endpoints: - name: https://s3.us-east-1.amazonaws.com:443 aws_region: us-east-1 iam_role_arn: arn:aws:iam::123456789012:instance-profile/my-instance-instance-profile这个iam_role_arn字段正对应 db/object_storage_endpoint_param.hh 中s3_storage结构体的iam_role_arn成员。创建对象存储 keyspaceSSTable 位置是 keyspace 作用域的。要用 S3 存储创建 keyspace需使用CREATE KEYSPACE并附加STORAGE { type: S3, endpoint: $endpoint_name, bucket: $bucket }参数其中$endpoint_name必须匹配scylla.yaml中已配置端点的name。S3 示例在scylla.yaml中object_storage_endpoints: - name: https://s3.us-east-2.amazonaws.com:443 aws_region: us-east-2创建 keyspace 时CREATE KEYSPACE ks WITH REPLICATION { class : NetworkTopologyStrategy, replication_factor : 1 } AND STORAGE { type : S3, endpoint : s3.us-east-2.amazonaws.com, bucket : bucket-for-testing };GS 示例GS 的配置与 AWS S3 一一对应。在scylla.yaml中object_storage_endpoints: - name: default credentials_file: credentials file|none创建 keyspace 时CREATE KEYSPACE ks WITH REPLICATION { class : NetworkTopologyStrategy, replication_factor : 1 } AND STORAGE { type : GS, endpoint : default, bucket : bucket-for-testing };这些 CQL 扩展的完整语法可参考 ScyllaDB CQL 扩展文档。从源码结构看STORAGE选项最终被解析为 data_dictionary/storage_options.hh 中的data_dictionary::storage_options它是std::variantlocal, object_storage其中object_storage携带bucket、endpoint、可选的location前缀和type字段并提供S3_NAME/GS_NAME常量与from_map/to_map用于与 CQL map 互相转换。也就是说 keyspace 的存储选项是模式的一部分在 schema 层面持久化。通过 /storage_service/backup 上传 SSTable 快照备份可以把data/目录中的 SSTable 通过 API 上传到 S3/GS。如前所述该操作的全部资源开销磁盘 IO 带宽与 IOPS、CPU 时间、网络带宽都在 Seastar 的控制之下不会随机冲击常规工作负载。API 端点名为/storage_service/backup其 Swagger 描述见 api/api-doc/storage_service.json。接受的参数为keyspace要复制 SSTable 的 keyspacetable要复制 SSTable 的表snapshot要复制 SSTable 的快照名endpoint对象存储配置中的键可以是 AWS 或 GCP 端点bucket存放 SSTable 文件的 bucket 名prefixSSTable 文件存放的前缀从 api/api-doc/storage_service.json 的规范中还可以确认endpoint、bucket、prefix、keyspace、table为必填 query 参数snapshot与move_files以移动代替复制组件文件为可选参数。目前只支持快照备份因此需要先执行 snapshot。keysapce 中所有表都会被上传目标对象名形如s3://bucket/some/prefix/to/store/data/.../sstable或gs://bucket/some/prefix/to/store/data/.../sstable对象存储相关的系统表对象存储相关代码需要读写几张系统表system_distributed.snapshot_sstables —— 恢复期间由 worker 节点使用用于获取需要从对象存储下载并恢复到本地的 SSTable 列表system.sstables —— 当一个以对象存储为存储选项的 keyspace 被创建后用来跟踪存放在对象存储上的 SSTable。从源码看db/system_keyspace.hh 中提供了sstables_registry_*一族操作sstables_registry_create_entry登记新 SSTable 条目、sstables_registry_update_entry_status/sstables_registry_update_entry_state更新 status/state、sstables_registry_delete_entry删除条目、sstables_registry_list按 table 与 node owner 遍历条目与下文布局章节中system.sstables的作用相互印证。手工运维 S3 上的数据本节说明 Scylla 在何时、何处、以何种方式把数据写入 S3/GS并给出一组快速命令以便在需要人工介入时获取对数据的本地访问。绝大多数情况下不需要直接触碰 S3 上的数据——存在透明的 REST API 与 Scylla Manager 命令来完成备份和恢复且 Scylla 配合 ScyllaDB CQL 扩展 中记载的CREATE KEYSPACE可以正常工作。但是如果 SSTable 损坏、在重新上传之前需要离线 scrub或者排查 bug 需要分析备份数据则按下面的说明访问数据。三种向 S3/GS 写入数据的机制1. Scylla Manager 备份使用sctool执行备份时会在作为参数传入的 bucket 内创建backup前缀该前缀下 Scylla Manager 按集群名、数据中心、keyspace 等维度组织所有备份任务的备份数据。backup前缀下的精确布局请参考 Scylla Manager 官方文档的备份规范说明原文档给出的外部链接此处不再列出。2. /storage_service/backup REST API使用/storage_service/backupREST API 时数据存放在作为参数传入的前缀之下。该前缀下的结构与典型的 Scylla 快照相同有一个 manifest 文件列出每个 SSTable 的数据文件清单另有 schema 文件和所有 SSTable 组件平铺存放在前缀下scylla-bucket/prefix/ │ ├── manifest.json ├── schema.cql │ ├── me-3gqe_1lnj_4sbpc2ezoscu9hhtor-big-Data.db ├── me-3gqe_1lnj_4sbpc2ezoscu9hhtor-big-Index.db ├── me-3gqe_1lnj_4sbpc2ezoscu9hhtor-big-Summary.db ├── ... │ ├── ma-1abx_k29m_9fyug3sdtjwj8krpqh-big-Data.db ├── ma-1abx_k29m_9fyug3sdtjwj8krpqh-big-Index.db ├── ma-1abx_k29m_9fyug3sdtjwj8krpqh-big-Summary.db ├── ... │ └── ... (更多 SSTable 组件)snapshot 的 manifest.json每个表快照目录都包含一个manifest.json文件列出快照内容与元数据。JSON 结构如下{ manifest: { version: 1.0, scope: node }, node: { host_id: UUID, datacenter: mydc, rack: myrack }, snapshot: { name: snapshot name, created_at: seconds_since_epoch, expires_at: seconds_since_epoch | null, }, table: { keyspace_name: my_keyspace, table_name: my_table, table_id: UUID, tablets_type: none|powof2, tablet_count: N }, sstables: [ { id: 67e35000-d8c6-11f0-9599-060de9f3bd1b, toc_name: me-3gw7_0ndy_3wlq829wcsddgwha1n-big-TOC.txt, data_size: 75, index_size: 8, first_token: -8629266958227979430, last_token: 9168982884335614769, }, { id: 67e35000-d8c6-11f0-85dc-0625e9f3bd1b, toc_name: me-3gw7_0ndy_3wlq821a6cqlbmxrtn-big-TOC.txt, data_size: 73, index_size: 8, first_token: 221146791717891383, last_token: 7354559975791427036, }, ... ], files: [ ... ] }各成员含义manifestversion—— manifest 自身结构的版本当成员被增删时递增scope—— 该 manifest 文件存储元数据的范围当前支持node—— 该 manifest 描述本节点在此快照中拥有的全部 SSTable。node本节点的元数据用于支持数据中心/机架感知的恢复。host_id—— 节点唯一 host_idUUIDdatacenter—— 节点所在数据中心rack—— 节点所在机架。snapshot快照元数据。name—— 快照名即tagcreated_at—— 快照创建时间expires_at—— 可选快照过期可删除时间若设置了 TTL无 TTL 时可省略、为 null 或为 0。table被快照表的元数据。keyspace_name与table_name—— 表名与 keyspace 名table_id—— 建表时设置的 UUIDtablets_typenone—— keyspace 使用 vnode 复制powof2—— keyspace 使用 tablet 复制且 tablet token 区间基于 2 的幂arbitrary—— keyspace 使用 tablet 复制且 tablet token 区间与数量可以是任意值tablet_count—— 可选。tablets_type非none时表示表中分配的 tablet 数量tablets_type为powof2时该值是 2 的幂。sstables快照中 SSTable 的元数据列表。id—— SSTable 唯一 idUUID在 tablet 迁移以流式方式搬运 SSTable 时会随之携带即使生成了新的 generationtoc_name—— SSTable 目录TOC组件名data_size与index_size—— 数据组件与索引组件的大小可用于估算恢复所需磁盘空间first_token与last_token—— SSTable 的首末 token可用于判断 SSTable 是否完全包含在某个tablettoken 区间内从而启用高效的基于文件的 SSTable 流式传输。files可选快照目录中非 SSTable 文件的列表不含 manifest.json 与 schema.cql。该 manifest 的序列化/反序列化实现位于 db/snapshot/manifest.cc 与 db/snapshot/manifest.hh字段名version/scope/host_id/tablets_type/toc_name/first_token等与上文 JSON 结构一一对应快照备份的上传/下载流程实现在 db/snapshot/cluster_backup.cc。3. CREATE KEYSPACE 使用 S3/GS 存储创建带 S3/GS 存储的 keyspace 时数据存放在CREATE KEYSPACE语句传入的 bucket 之下。语句发出后Scylla 会透明地使用该 S3/GS bucket 作为该 keyspace SSTable 的存放位置。自动管理的对象存储表采用 S3 与 GS 共享的统一布局SSTable 组件存放在静态的sstables/前缀下并按**稳定的 SSTable 标识符sstable_id**分组而不是按节点本地的 generation 名分组scylla-sstables-bucket/ │ └── sstables/ ├── 4f4d0a90-d8c6-11f0-8b18-060de9f3bd1b/ │ ├── Data.db │ ├── Index.db │ ├── Summary.db │ ├── TOC.txt │ ├── ... │ └── refs/ │ └── nodes/ │ ├── 7adf1ca2-6783-40ab-aa1f-ef1e0b5d98ba/ │ │ └── 3gqe_1lnj_4sbpc2ezoscu9hhtor │ └── 10e68be1-d352-4173-bf34-2249dbb7329e/ │ └── 4c5s_0281_0v5kg2b4gri84iggoz ├── 87a72290-d8c6-11f0-a5ea-060de9f3bd1b/ │ ├── Data.db │ ├── Index.db │ ├── Summary.db │ ├── TOC.txt │ ├── ... │ └── refs/ │ └── nodes/ │ └── 7adf1ca2-6783-40ab-aa1f-ef1e0b5d98ba/ │ └── 5n8a_03tw_2jv4g2a4k2m33sq8ah └── ...关键路径约定托管 SSTable 前缀sstables/每个 SSTable 位于sstables/{sstable_id}/SSTable 组件的对象名即本地 SSTable 格式的组件后缀如Data.db、Index.db、Summary.db、Scylla.db、TOC.txt引用对象sstables/{sstable_id}/refs/nodes/{host_id}/{generation}—— 记录哪些节点仍持有对该 SSTable 数据的引用对象体为空对象名本身就是元数据{host_id}标识节点{generation}是该节点对共享 SSTable 的本地 generation 名。{sstable_id}标识共享的对象存储 SSTable 数据本地{generation}标识system.sstables中的节点本地 SSTable 条目。新建 SSTable 的sstable_id通常由其 generation 派生经过 tablet 迁移或引用共享后多个本地 SSTable 条目可以拥有不同 generation但通过同一个sstable_id指向同一份对象存储数据。对象存储 SSTable 的生命周期创建Scylla 在{sstable_id}下上传组件对象并在封住sealsystem.sstables中的本地行之前创建本节点的refs/nodes/{host_id}/{generation}引用共享当 tablet 迁移能够共享对象存储数据时接收方节点创建一个以自己 generation 命名的新本地 SSTable 条目并在既有{sstable_id}前缀下新增节点引用而不复制所有组件对象本地移除节点移除本地 SSTable 时先删除自己的引用对象若仍有其他引用组件对象保持完好最终清理只有当某个sstable_id下不再有任何引用对象时才删除组件对象。这防止一个节点删掉另一个节点仍引用的共享数据。system.sstables中的status与state字段描述的是本地 SSTable 条目的生命周期而不是sstable_id标识的对象存储组件集合的全局生命周期状态。从源码结构看refs/nodes/引用对象的读写逻辑位于 sstables/storage.cc。用 AWS CLI 下载、删除、上传 SSTable手工管理 S3 上的 SSTable 可以使用 AWS CLI。前提已安装 awscli见 AWS 官方安装指南此处不列外部链接且~/.aws/credentials指向一组有效的 S3 凭证——如果是基于 OKTA 的凭证获取工具则刷新凭证或确保凭证指向拥有 S3 访问权限的有效 IAM 用户。确认前置条件满足的标准是能够执行aws s3 ls s3://your-bucket/并且能看到内容如果 bucket 为空则至少不报错。之后即可执行以下命令注意先对照上文各用法的前缀布局。下载 SSTable逐个复制组件aws s3 cp s3://your-bucket/path/to/sstable/me-3gqb_1izi_0pxn421yzymfw5c8zf-big-Data.db /local/path/to/sstable/component或用 glob 下载整个 SSTableaws s3 cp s3://your-bucket/path-to-sstables/ /local/path/for/sstables --exclude * --include some-sstable-generation-big-* --recursive删除 SSTable逐个删除组件aws s3 rm s3://your-bucket/path/to/sstable/me-3gqb_1izi_0pxn421yzymfw5c8zf-big-Data.db或用 glob 删除整个 SSTableaws s3 rm s3://your-bucket/path-to-sstables/ --exclude * --include some-sstable-generation-big-* --recursive上传 SSTable逐个上传组件aws s3 cp /local/path/to/sstable/me-3gqb_1izi_0pxn421yzymfw5c8zf-big-Data.db s3://your-bucket/path/to/sstable/component或用 glob 上传整个 SSTableaws s3 cp /local/path/for/sstables s3://your-bucket/path-to-sstables/ --exclude * --include some-sstable-generation-big-* --recursive元数据修正Metadata touchupsScylla Manager 备份场景如果需要手工 scrub 并重新上传 SSTable多处内容都需要改动若要彻底丢弃某些 SSTable 也一样。如 Scylla Manager 备份规范文档所述每个节点维护一个 JSON manifest其中包含大量依赖 SSTable 的信息本节点拥有的每表 SSTable 列表本节点拥有的表中每个 chunk 的 SSTable 总大小本节点拥有的所有表 chunk 的总大小本节点拥有的 token 列表上述字段名都暗示这些信息依赖 SSTable 内容因此任何本地修复损坏 SSTable 后重新上传的尝试很可能都要求同步更新该节点 manifest 文件中的这些字段——scrub 后的 SSTable 在上述各字段的值上大概率都会变化。/storage_service/backupREST API 场景理论上只有从备份中整体移除一个 SSTable时才需要修改 manifest 文件并删除对应条目其他情况下无需改动元数据。CREATE KEYSPACE使用 S3/GS 存储场景Scylla 在system.sstables中跟踪对象存储 SSTable并依据 SSTable 前缀下的引用对象决定何时可以删除组件对象。对该布局对象的手工修改必须保持三者一致system.sstables条目、组件对象、以及refs/nodes/{host_id}/{generation}引用对象。提示重新上传 scrub 过的 SSTable 意味着重新上传它的所有组件因为其中大多数组件大概率都已变化。相关端到端行为可以在 test/cluster/object_store/test_backup.py 等测试中查看快照 manifest 结构的单元测试参见 test/boost/tablet_aware_restore_test.cc。小结端点配置scylla.yaml的object_storage_endpoints支持 S3aws_region、iam_role_arn与 GStype: gs、credentials_file可设为none两类端点凭证解析顺序为环境变量 → IMDS/STSS3与本地/GCE 默认凭证GS。keyspace 存储CREATE KEYSPACE ... AND STORAGE { type: S3|GS, endpoint: ..., bucket: ... }使 SSTable 透明存放在桶的sstables/{sstable_id}/布局下refs/nodes/{host_id}/{generation}引用对象保障共享数据的引用计数式清理。快照备份/storage_service/backup在 Seastar 资源控制下把快照 SSTable 平铺上传附带manifest.json与schema.cql恢复与共享依赖system_distributed.snapshot_sstables与system.sstables两张系统表。手工运维先按三种写入机制确认前缀布局再用aws s3 cp/rm配合 generation glob 操作组件凡改动 SSTable 内容务必同步评估 manifest /system.sstables/ 引用对象的一致性。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考