ScyllaDB 授权缓存Authorization CacheREST API 完全指南接口规范与底层实现解析【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb导读本文以 docs/reference/api/authorization-cache.rst 文档为核心系统讲解 ScyllaDB 授权缓存Authorization CacheREST API 的接口定义、使用方法及其背后的实现原理。你将掌握POST /authorization_cache/reset这一管理接口的完整调用方式理解它为何用于重置授权后的 prepared statements 缓存并通过阅读 auth/cache.cc 等源码弄清缓存失效机制与分布式一致性保证从而在权限变更后能够正确地让集群重新加载角色与权限。1. 文档定位一张 Swagger 驱动的 API 参考页docs/reference/api/authorization-cache.rst是 ScyllaDB 文档集中典型的 Swagger 自动生成型 API 参考页。全文通过 RST 指令内嵌 OpenAPI/Swagger 规范:exclude-doctools: Authorization Cache .. scylladb_swagger_inc:: .. scylladb_swagger:: :spec: api/api-doc/authorization_cache.json其中关键的是.. scylladb_swagger::指令的:spec:参数它指向 api/api-doc/authorization_cache.json。这意味着该页面的全部接口信息路径、方法、参数、返回值都由这个 JSON 文件驱动生成文档正文本身不重复罗列细节而是交由构建工具从规范文件渲染。理解这一点对读者很重要想要了解 API 的精确形态需以 JSON 规范为准而本文接下来的内容正是对该规范的逐项解读与源码级印证。2. 接口规范POST /authorization_cache/reset2.1 Swagger 定义原文api/api-doc/authorization_cache.json 定义了唯一一个 API 端点字段值apiVersion0.0.1swaggerVersion1.2basePath{{Protocol}}://{{Host}}resourcePath/authorization_cacheproducesapplication/jsonAPI 路径/authorization_cache/resetHTTP 方法POST摘要summaryResets authorized prepared statements cache重置已授权 prepared statements 缓存操作昵称nicknameauthorization_cache_reset参数无返回类型void模型models无不涉及自定义请求/响应体从规范可以看出该接口不接收任何请求参数也不返回任何业务数据成功即返回空响应是一个典型的“无状态管理操作”端点。2.2 实际调用示例由于该接口由 REST API 服务器承载且无请求体调用方式非常简洁。假设 ScyllaDB 节点的 REST API 监听在localhost:10000默认端口则可使用curlcurl -X POST http://localhost:10000/authorization_cache/reset成功执行后接口返回空响应HTTP 200无 body。也可以在响应中显式请求 JSON 格式规范声明produces: application/jsoncurl -X POST -H Accept: application/json http://localhost:10000/authorization_cache/reset2.3 接口注册链路该端点并非硬编码在某个 handler 中而是通过 ScyllaDB 的 API 注册框架动态挂载api/authorization_cache.cc 中的set_authorization_cache()将authorization_cache_reset操作绑定到routes上并捕获shardedauth::serviceapi/api.cc 中的set_server_authorization_cache()通过register_api(ctx, authorization_cache, ...)以authorization_cache作为资源名完成统一注册对应地api/api.cc 的unset_server_authorization_cache()在关闭流程中卸载路由这两个函数的声明位于 api/api_init.hh供初始化模块调用。这种“JSON 规范 注册框架 路由绑定”的三层结构也是整个 ScyllaDB API 模块api/、api/api-doc/的统一模式。3. 底层语义重置的究竟是什么缓存接口摘要明确写着 Resets authorized prepared statements cache。要准确理解它的作用需要区分 ScyllaDB 中两类容易混淆的“授权缓存”3.1 授权缓存auth cache与已授权 prepared statements 缓存角色/权限缓存auth cache由 auth/cache.hh 中的auth::cache类实现缓存每个角色的登录能力can_login、超级用户标志is_superuser、角色成员关系member_of/members、角色属性attributes以及角色在各资源上的权限集合cached_permissions。它通过service::get_permissions()见 auth/service.cc在鉴权时被查询。已授权 prepared statements 缓存保存“某个 prepared statement 已被某用户授权”的结论避免每次执行前重复鉴权。接口摘要中的 authorized prepared statements cache 指的就是这一类。3.2reset_authorization_cache()的实现当 REST 请求到达时api/authorization_cache.cc 的处理器会调用auth_service.invoke_on_all(...)在所有 shard 上执行 auth/service.cc 中的reset_authorization_cache()void service::reset_authorization_cache() { _qp.reset_cache(); }_qp是cql3::query_processor。也就是说这个“重置”动作最终作用于CQL 查询处理器持有的 prepared statements 授权缓存而不是直接清空auth::cache中的权限条目。这正是接口摘要措辞的精确来源也是运维时理解其效果边界的关键。3.3 为什么需要“全部 shard”执行ScyllaDB 采用 Seastar 框架的 share-nothing 架构每个 CPU 核一个 shard缓存是 per-shard 的。api/authorization_cache.cc 使用invoke_on_all保证所有 shard 上的缓存被同步重置否则会出现“部分 shard 仍持有旧授权结论”的不一致状态。这一设计与auth::cache中通过container().invoke_on_others()见 auth/cache.cc在角色变更后向其他 shard 分发角色记录的思路一脉相承。4. 使用场景与注意事项4.1 何时需要调用当管理员直接修改了与授权相关的底层数据而这些修改无法被常规机制自动感知时就需要手动重置。典型场景包括通过直接操作system_auth相关系统表角色、角色成员、角色权限来调整权限绕过 CQLGRANT/REVOKE等语句调试或迁移过程中需要强制所有 shard 丢弃缓存的授权结论并重新评估排查“权限已变更但客户端仍按旧权限执行”之类的疑似缓存一致性问题。4.2 与 auth cache 自动失效机制的关系从源码看auth/cache.cc 自身已具备相当完善的自动失效能力多数日常权限变更并不需要手动调用本接口includes_table()auth/cache.cc判断变更是否涉及角色/角色成员/角色属性/角色权限四张系统表load_roles()auth/cache.cc在角色变更时重新拉取角色并清理受继承影响的角色权限gather_inheriting_rolesload_all()auth/cache.cc使用版本号_current_version配合prune_all()实现无缝整体重载reload_all_permissions()auth/cache.cc在权限数据变更时逐资源重新加载所有角色的权限集合。因此POST /authorization_cache/reset更多作为兜底手段与运维诊断工具存在用于处理那些无法被上述机制覆盖或希望强制全局刷新尤其是 prepared statements 授权缓存的场景。4.3 调用注意事项接口无参数调用失败会返回 HTTP 错误状态可通过节点 REST API 日志或返回码确认执行结果由于是invoke_on_all在大集群/多 shard 节点上操作在所有 shard 完成前不会返回极端情况下可能稍有延迟该接口只重置缓存不改变任何实际授权数据若需要真正修改权限仍应使用GRANT/REVOKE或直接操作系统表。5. 监控与验证从指标确认缓存行为除了手动重置ScyllaDB 还提供了缓存运行状态的观测手段。auth/cache.cc 在构造时注册了auth_cache指标组包括两个 gauge指标含义auth_cache_roles当前缓存的角色数量_roles.size()auth_cache_permissions所有角色当前缓存的权限集合总数_cached_permissions_count这些指标可通过 ScyllaDB 的 Prometheus 指标端点观测。调用重置接口后配合这些指标以及系统日志中的auth-cacheloggerauth/cache.cc输出可以验证缓存是否按预期被刷新。6. 从接口到源码完整调用链小结为了便于读者在仓库中继续追踪将完整调用链整理如下curl -X POST /authorization_cache/reset → api/authorization_cache.cc::set_authorization_cache() → auth_service.invoke_on_all() → auth/service.cc::reset_authorization_cache() → cql3::query_processor::reset_cache()相关的仓库路径索引API 文档 RSTdocs/reference/api/authorization-cache.rstSwagger 规范api/api-doc/authorization_cache.jsonAPI 路由实现api/authorization_cache.ccAPI 注册/注销api/api.cc、api/api_init.hh授权服务与重置实现auth/service.cc角色/权限缓存实现auth/cache.cc、auth/cache.hh结语POST /authorization_cache/reset是 ScyllaDB REST API 中一个简洁而重要的运维端点。通过本文的解析可以看到它背后串联了 Swagger 驱动的文档体系、per-shard 缓存架构、invoke_on_all的分布式一致性保证以及query_processor对 prepared statements 授权缓存的直接管理。掌握这一接口的规范形态与底层语义能帮助你在权限变更后做出正确的缓存刷新决策也为你进一步阅读 ScyllaDB 的鉴权与缓存源码提供了清晰的切入点。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考