ScyllaDB Alternator 快速上手指南在 Docker 中启用 DynamoDB 兼容 API【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb导读本指南基于 ScyllaDB 官方文档 docs/alternator/getting-started.md完整演示如何从零搭建一个暴露 DynamoDB 兼容 APIAlternator的 ScyllaDB 集群并用 AWS 官方 Python 驱动 boto3 完成建表、写入、读取的端到端验证。读完本文你将掌握 Alternator 的核心配置参数端口、写隔离策略、HTTPS 加密、认证授权能独立用 Docker 一键启动、用 boto3 脚本测试并能理解其底层表即 keyspace、键即分区键的实现原理为后续迁移 DynamoDB 应用打下基础。什么是 ScyllaDB AlternatorAlternator 是 ScyllaDB 内建的 DynamoDB API 兼容层。DynamoDB 的 API 采用 JSON 编码的请求与响应通过 HTTP/HTTPS 传输。Alternator 的目标是任何为 Amazon DynamoDB 编写的应用都可以不加修改地直接运行在启用了 Alternator 的 ScyllaDB 上见 docs/alternator/alternator.md 的 Introduction 部分。需要特别强调的是Alternator 并不通过 CQL 生成或解析来中转请求——DynamoDB 的 JSON-over-HTTP 请求到达节点后会被直接解析并调用 ScyllaDB 内部的 C 函数执行。在 ScyllaDB 的术语中接收请求的节点扮演coordinator协调者它通常会再把请求转发给持有数据副本的一个或多个replica副本节点。Alternator 的几乎全部源码位于仓库的alternator/子目录如 executor.cc、controller.cc、server.cc而功能测试则集中在test/alternator/子目录全部使用 Python 编写。安装 ScyllaDB用 Docker 启用 Alternator在开始使用 Alternator 之前你需要有一个正在运行、且配置为暴露 Alternator 端口的 ScyllaDB 集群。以下是官方推荐的 Docker 方式与 docs/alternator/getting-started.md 一致。第一步拉取镜像docker pull scylladb/scylla:latest第二步带 Alternator 参数运行容器参照 Docker Hub 上 scylladb/scylla 镜像的常规启动方式但要在每个docker run命令中额外添加两部分镜像名之前加上端口映射-p 8000:8000命令末尾加上--alternator-port8000 --alternator-write-isolationalways。例如官方给出的完整命令docker run --name scylla -d -p 8000:8000 scylladb/scylla:latest \ --alternator-port8000 \ --alternator-write-isolationalways这两个参数的含义参数作用--alternator-port指定 ScyllaDB 监听未加密DynamoDB API 的端口--alternator-write-isolation选择 Alternator 每次写入是否使用 LWT轻量级事务开启 HTTPS可选--alternator-https-port...可以启用加密的 HTTPS 端口。此时必须把 SSL 证书和私钥放入镜像中的/etc/scylla/scylla.crt和/etc/scylla/scylla.key。官方还说明了一个关键前提以这种方式运行的 ScyllaDB默认不启用认证与授权任何 DynamoDB API 请求都会被直接受理不要求签名。如何配置认证与授权参见 ScyllaDB Alternator for DynamoDB users。与源码对应的配置项从 db/config.cc 可以看出alternator_port、alternator_https_port等配置项都有源码级的定义与默认值例如alternator_port默认 0即未启用配置为 8000 即开始监听alternator_https_port默认 0用于 HTTPSalternator_address默认0.0.0.0即默认在所有网络接口上监听如需只在特定接口监听可配置该项见 docs/alternator/alternator.md 的 Running Alternator 一节alternator_port_proxy_protocol与alternator_https_port_proxy_protocol默认 0配合 HAProxy 或 AWS PrivateLink 等反向代理时启用 Proxy Protocol v2以正确报告客户端地址。配置既可以在 YAML 配置文件中写也可以用命令行参数。例如 YAML 形式alternator_port: 8000 alternator_write_isolation: only_rmw_uses_lwt # 可选 always、forbid 或 unsafe与命令行形式完全等价--alternator-port8000 --alternator-write-isolationonly_rmw_uses_lwt重要write isolation 无默认值根据 docs/alternator/alternator.mdalternator_write_isolation目前没有默认值——如果只设置了端口却没配置写隔离策略ScyllaDB 会直接报错并提示你去设置它。因此上述 Docker 命令中的--alternator-write-isolationalways是必须的。深入理解四种写隔离策略write isolation policiesDynamoDB 的很多更新请求实际上是先读后写read-modify-write简称 RMW——例如带条件的更新、基于属性旧值计算的新值、或要求返回旧值的请求。这类读与写必须被当作一个事务与其他并行写入隔离。Alternator 可以用 ScyllaDB 的 LWT轻量级事务为每次写入提供隔离但 LWT 会显著拖慢写入速度对不使用 RMW 的工作负载来说没有必要。为此Alternator 提供了四种写隔离策略详见 docs/alternator/new-apis.md 的 Write isolation policies 一节可以在集群级别用--alternator-write-isolation设置默认值也可以在单表级别覆盖在 CreateTable 时或之后用 TagResource 给表打上键为system:write_isolation的标签值为下列任一取值别名含义特点a/always/always_use_lwt每次写入即使不需要读都走 LWT最慢但唯一保证对所有工作负载都正确的选择f/forbid/forbid_rmw禁止需要先读后写的请求如带 ConditionExpression 的 UpdateItem直接报错纯写入不走 LWT、速度快且仍安全但不适合需要 RMW 的工作负载o/only_rmw_uses_lwt仅对需要 RMW 的更新用 LWT纯写用普通 quorum 写兼顾快写与慢 RMW仅当同一 item 不会被并发地既做 RMW 又做纯写时才安全系统无法验证这一点u/unsafe/unsafe_rmwRMW 拆成独立的读与写无任何隔离保证最快但不安全官方不推荐任何场景使用未来可能移除从测试文件 test/alternator/test_write_isolation.py 的注释可以看到四种模式被分为两类forbid_rmw会禁止所有需要读前写的操作包括带条件的写入、部分更新操作、以及要求返回写前值的写入而always_use_lwt、only_rmw_uses_lwt、unsafe_rmw三种模式则允许任意写操作称为 permit rmw 模式。为什么写入默认要隔离ScyllaDB及其灵感来源 Cassandra之所以写入性能高是因为写入不需要先从磁盘读。但 DynamoDB 的很多请求天然需要读后写。此外DynamoDB 允许属性嵌套——顶层属性可以是 list 或 map元素又可以继续嵌套。Alternator 目前把顶层属性的整个内容作为一个 JSON 对象存储因此像a.b[3].c这样修改非顶层属性的 UpdateItem 请求就必须 RMW先读取整个顶层属性a只修改a.b[3].c再整体写回见 docs/alternator/alternator.md 的 design 一节。底层存储与一致性实现了解存储模型有助于理解上述行为同样来自 docs/alternator/alternator.md每个 Alternator 表存储在 ScyllaDB 的独立 keyspace中该 keyspace 在 CreateTable 请求创建表时初始化keyspace 的复制因子RF在创建时根据集群规模决定3 个及以上节点用 RF3更小的集群用 RF1RF1 只建议测试使用存在数据丢失风险DynamoDB 的 key 列hash 与 sort key类型已知直接映射为 ScyllaDB 表的 partition key 与 clustering key 列其他属性因每行可能不同统一存放在 ScyllaDB 的一个 map 列中而不是单独成列DynamoDB 的最终一致与强一致两种读模式用 ScyllaDB 的一致性级别CL实现所有写入用LOCAL_QUORUM强一致读用LOCAL_QUORUM最终一致读用LOCAL_ONE。测试 DynamoDB APITic Tac Toe 演示应用官方文档给出的第一种验证方式是运行 AWS 官方的 Tic Tac Toe 演示应用按照 AWS 官方 DynamoDB 开发者指南中 TicTacToe 阶段的说明操作将端点的域名指向你的 ScyllaDB 节点即可开始游戏。由于该演示应用使用标准的 AWS DynamoDB SDK只要把 endpoint 指向本地 8000 端口即可验证 Alternator 对真实 DynamoDB 应用的兼容性。测试 DynamoDB APIPython boto3 三步走第二种验证方式是官方提供的三个 Python 脚本这是最直观、可复现的端到端验证流程。准备 Python 环境在你的机器上安装 boto3AWS 官方 Python 库内含 DynamoDB 驱动sudo pip install --upgrade boto3脚本一创建表CreateTable将下面的脚本保存为 Python 文件并运行如果用 Docker把localhost换成你的 docker 节点地址import boto3 dynamodb boto3.resource(dynamodb, endpoint_urlhttp://localhost:8000, region_nameNone, aws_access_key_idNone, aws_secret_access_keyNone) dynamodb.create_table( AttributeDefinitions[ { AttributeName: key, AttributeType: S }, ], BillingModePAY_PER_REQUEST, TableNameusertable, KeySchema[ { AttributeName: key, KeyType: HASH }, ])该脚本创建了一张名为usertable的表主键为字符串类型的key属性键类型为 HASH即分区键计费模式采用按需付费PAY_PER_REQUESTAlternator 中该模式与 DynamoDB 语义一致无需预置吞吐量。脚本二写入数据BatchWriteItemimport boto3 dynamodb boto3.resource(dynamodb, endpoint_urlhttp://localhost:8000, region_nameNone, aws_access_key_idNone, aws_secret_access_keyNone) dynamodb.batch_write_item(RequestItems{ usertable: [ { PutRequest: { Item: { key: test, x : {hello: world} } }, } ] })这条脚本通过batch_write_item向usertable写入了一条hello world记录分区键key的值为test另一个属性x是一个嵌套 map{hello: world}——这也印证了前面提到的非键属性以 JSON 形式整体存储的设计。脚本三读回数据BatchGetItemimport boto3 dynamodb boto3.resource(dynamodb, endpoint_urlhttp://localhost:8000, region_nameNone, aws_access_key_idNone, aws_secret_access_keyNone) print(dynamodb.batch_get_item(RequestItems{ usertable : { Keys: [{ key: test }] } }))运行后你应当能在屏幕上看到第 2 步插入的记录以及一些 HTTP 信息。为什么用 AWS 官方库做测试仓库中的 test/alternator/README.md 说明了这一设计哲学test/alternator/下的测试全部使用 AWS 的 boto3 库和 pytest 框架对 Alternator 的可见功能做黑盒测试。由于用的是真正的 AWS 库同一套测试既可以跑在 ScyllaDB Alternator 上也可以跑在真正的 DynamoDB 上从而验证两者在绝大多数功能上行为一致。如果你想跑完整的官方测试套件可以在 ScyllaDB 源码根目录执行# 在已经运行于 http://localhost:8000 的 Alternator 上跑全部测试 pytest # 在 test/alternator 目录下执行 # 或使用仓库自带的 run 脚本自动编译、启动 ScyllaDB 并跑测试 test/alternator/run # 指定不同地址或用 --aws 跑在真正的 DynamoDB 上 pytest --url http://10.0.0.5:8000 pytest --aws其中run脚本会自动选择build/*/scylla下最近编译的 ScyllaDB 可执行文件可用SCYLLA环境变量覆盖并在临时目录中启动 ScyllaDB测试结束后自动清理。认证与授权从默认放行到 SigV4 签名校验前文 Docker 启动方式默认不校验任何请求签名。官方文档docs/alternator/compatibility.md 的 Authentication and Authorization 一节给出了生产环境的启用路径alternator_enforce_authorization: trueAlternator 实现了与 DynamoDB 及整个 AWS 一致的 SigV4 签名协议客户端照常用 access key ID 和 secret access key 证明身份并保证请求真实性。Alternator 会用它维护的授权密钥对列表校验每个请求。用户创建方式使用 CQLCREATE ROLE命令。客户端签名时角色名作为 access key ID角色密码的加盐哈希salted hash作为 secret key。角色XYZ的密钥可用如下 CQL 查询获取SELECT salted_hash FROM system.roles WHERE role XYZ;官方还给出了平滑切换的建议先把alternator_enforce_authorization保持为false同时设置alternator_warn_authorization: true。后者不会拒绝任何请求但会把潜在的认证/授权失败计数到两个指标scylla_alternator_authentication_failuresscylla_alternator_authorization_failures并产生 WARN 级别日志日志包含字符串alternator_enforce_authorizationtrue以及失败的用户名和客户端地址便于定位问题。当观察到两个指标不再增长、日志消失即可确认应用配置正确再正式开启强制校验。此外Alternator 还支持基于 mTLS 的客户端证书认证在 HTTPS 端口上通过--alternator-encryption-options truststore... require_client_authtrue|optional配置后客户端证书的 Subject DN 或 SAN 会被映射为角色名映射规则由auth_certificate_role_queries配置项控制详见 docs/alternator/alternator.md 的 Mutual TLS 一节。其他值得关注的 Alternator 配置从 db/config.cc 的源码定义中还能看到一些对生产部署有用的参数均可通过 YAML 或命令行配置配置项默认值说明alternator_timeout_in_ms10000Alternator 请求超时时间毫秒alternator_max_items_in_batch_write100单次 BatchWriteItem 允许的最大条目数DynamoDB 本身是 25源码注释说明这是刻意不同的值alternator_ttl_period_in_seconds依赖配置TTL 扫描周期alternator_response_compression_threshold_in_bytes4096响应 gzip 压缩阈值alternator_https_port_proxy_protocol0HTTPS 端口是否启用 Proxy Protocol v2另外官方建议在生产环境把auto_snapshot设置为false因为 ScyllaDB 默认会为删除的表保存快照而 Alternator 没有恢复快照的 API这些快照只会浪费磁盘空间——删除表并不会回收任何空间见 docs/alternator/alternator.md。总结本文完整走通了 ScyllaDB Alternator 的上手路径docker pull拉镜像 → 带--alternator-port与--alternator-write-isolation参数启动 → 用 boto3 三个脚本完成建表、写入、读取的端到端验证。在此基础上我们进一步理解了写隔离策略的四种模式及其适用场景、Alternator 的 keyspace 存储模型与一致性实现、SigV4 认证与授权配置以及若干重要的生产参数。如果你的应用已经基于 DynamoDB API 开发现在只需要把 endpoint 从 AWS 指向运行 Alternator 的 ScyllaDB 集群即可无缝迁移需要进一步了解兼容性边界与 DynamoDB 差异请继续阅读仓库中的 docs/alternator/compatibility.md了解 Alternator 独有的扩展 API如系统表访问、流等参见 docs/alternator/new-apis.md。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考