ScyllaDB Gossiper 管理 API 完全指南节点状态查询与故障处理实战【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb本文是 ScyllaDB基于 Seastar 框架、兼容 Apache Cassandra 与 Amazon DynamoDB 的 NoSQL 数据存储中 Gossiper REST API 的实战参考。Gossiper 负责集群成员关系发现与故障检测本文围绕其对外暴露的 7 个 HTTP 接口逐一讲解接口语义、参数、源码实现与 curl 调用示例帮助你掌握查询存活/不可达节点、查看心跳与世代号、强制移除故障节点等日常运维技能。Gossiper 在 ScyllaDB 集群中的角色在 ScyllaDB 中gms::gossiper组件位于 gms/gossiper.hh 与 gms/gossiper.cc承担两项核心职责集群成员关系发现通过节点间交换gossip_digest_syn/ack/ack2消息让每个节点都能掌握全集群其他节点的存活状态故障检测维护_live_endpoints存活节点与_unreachable_endpoints不可达节点集合并为每个端点记录心跳版本号heartbeat version与世代号generation number。对外这些内部状态通过 HTTP API 暴露给运维人员与监控系统。接口定义位于 Swagger 规范文件 api/api-doc/gossiper.json路由注册实现在 api/gossiper.cc对应的 API 文档页即 docs/reference/api/gossiper.rst。API 总览该组接口的basePath为{{Protocol}}://{{Host}}即 ScyllaDB 节点对外监听的 REST 地址默认协议为 HTTP端口 10000resourcePath为/gossiper所有接口均produces: application/json且不需要额外的鉴权头由节点自身的访问控制策略决定。方法路径说明返回类型GET/gossiper/endpoint/down/获取所有不可达down节点的地址列表arraystringGET/gossiper/endpoint/live/获取所有存活live节点的地址列表arraystringGET/gossiper/downtime/{addr}查询指定节点的停机时长long微秒GET/gossiper/generation_number/{addr}查询指定节点的当前世代号longGET/gossiper/heart_beat_version/{addr}查询指定节点的当前心跳版本号longPOST/gossiper/assassinate/{addr}终结assassinate一个端点voidPOST/gossiper/force_remove_endpoint/{addr}从 gossip 中强制移除一个端点void从源码结构看这些接口在 api/gossiper.cc 的set_gossiper(http_context, routes, gms::gossiper)函数中完成注册并通过unset_gossiper()反注册节点关闭时会调用unset_gossiper清理路由。节点状态查询存活与不可达列表获取不可达节点列表GET /gossiper/endpoint/down/返回当前被故障检测器判定为不可达的节点 IP 地址数组。其实现api/gossiper.cc调用g.get_unreachable_members_synchronized()将结果转换为字符串数组返回。所谓synchronized见 gms/gossiper.cc该函数强制invoke_on(0)到 shard 0先获取lock_endpoint_update_semaphore()锁再结合_address_map把 host id 映射为inet_address输出。这样做的目的是确保跨 shard 的数据一致——ScyllaDB 的 Seastar 模型下每个 shard 有自己的状态副本读接口必须先同步。获取存活节点列表GET /gossiper/endpoint/live/返回当前存活节点的地址数组。实现api/gossiper.cc调用g.get_live_members_synchronized()对应 gms/gossiper.cc同样先拿锁再读取_live_endpoints映射后的地址集合。实战意义这两个接口是集群健康度最直接的观测入口。监控脚本可以周期轮询/gossiper/endpoint/live/与/gossiper/endpoint/down/对比两次结果即可发现节点上下线事件结合nodetool status的结果可做交叉校验。查询节点停机时长GET /gossiper/downtime/{addr}路径参数addr为端点 IP 地址必填类型string。返回该节点的停机时长单位为微秒long。实现api/gossiper.cc会先同步所有 shard 的unreachable_members再调用g.get_endpoint_downtime(g.get_host_id(ep))。核心逻辑在 gms/gossiper.cc若端点存在于_unreachable_endpoints中则返回now() - downtime即从进入不可达状态到当前时刻的微秒差若端点不在不可达集合中即存活或未知返回0。注意返回 0 并不能区分节点从未宕机与节点不在 gossip 视图内需要结合 live/down 列表综合判断。节点元信息查询世代号与心跳版本号Gossip 协议中每个节点维护两个关键单调递增计数器定义在gms::heart_beat_state中世代号generation number节点每次重启时递增用于标识这是第几代实例从而让其他节点识别并丢弃上一代残留的过时状态心跳版本号heartbeat version节点每次应用新的应用状态application state时递增用于 gossip 消息去重与状态新旧判断。查询世代号GET /gossiper/generation_number/{addr}路径参数addr为端点 IP。返回long。实现api/gossiper.cc先通过g.get_host_id(ep)将 IP 解析为 host id再调用g.get_current_generation_number()其源码在 gms/gossiper.ccreturn const_castgossiper*(this)-container().invoke_on(0, [endpoint] (const gossiper gossiper) { return gossiper.get_endpoint_state(endpoint).get_heart_beat_state().get_generation(); });即强制在 shard 0 上读取该端点的endpoint_state中heart_beat_state的 generation 值。查询心跳版本号GET /gossiper/heart_beat_version/{addr}路径参数addr为端点 IP。返回long。实现api/gossiper.cc对应 gms/gossiper.cc读取get_heart_beat_version()。实战意义当怀疑某节点状态迟迟不更新时可以连续两次调用本接口观察心跳版本号是否在增长——长期不增长说明该节点可能已停止发送 gossip 心跳而世代号跳变则说明节点发生了重启。结合这两者可以快速定位僵尸节点或频繁重启的节点。故障处理强制移除与终结端点这两个 POST 接口属于危险操作用于清理集群中无法正常退出的故障节点使用时需格外谨慎。强制移除端点POST /gossiper/force_remove_endpoint/{addr}路径参数addr为要移除的端点 IP。返回void。实现api/gossiper.cc将 IP 解析为 host id 后调用g.force_remove_endpoint(g.get_host_id(ep), gms::null_permit_id)。核心逻辑在 gms/gossiper.cc切换到 gossip 调度组gossip_scheduling_group避免影响其他任务invoke_on(0)在 shard 0 上执行先通过lock_endpoint(id, pid)获取该端点的操作许可permit保证并发操作互斥自保护若id gossiper.my_host_id()抛出异常Can not force remove node {} itself即不允许移除自己若端点不存在于_endpoint_state_map仅记录 debug 日志并直接返回幂等依次调用remove_endpoint(id, pid)与evict_from_membership(id, pid)完成移除与成员资格驱逐。其中remove_endpointgms/gossiper.cc会先通知所有i_endpoint_state_change_subscriber订阅者执行on_remove回调再从_seeds、live/unreachable 集合、_syn_handlers、_ack_handlers中清除该端点若该端点此前被视为存活还会触发on_dead通知并记录日志。使用场景当一台节点彻底宕机且无法恢复如硬件损坏但残留状态仍被其他节点感知、影响集群健康时使用本接口将其从 gossip 视图中彻底清除。终结端点assassinatePOST /gossiper/assassinate/{addr}路径参数addr为端点 IP。返回void。这是一个兼容性接口从源码看当前版本中 gms/gossiper.cc 的实现直接抛出异常future gossiper::assassinate_endpoint(sstring address) { throw std::runtime_error(Assassinating endpoint is not supported in topology over raft mode); }也就是说在**基于 Raft 的拓扑管理模式topology over raft mode**下终结端点操作已不被支持。可以推断该接口是历史遗留早期版本中它用于强制击杀一个故障端点模拟其彻底消失防止其复活后以旧身份重新加入在新拓扑模式下节点身份与成员资格由 Raft 组管理gossip 不再拥有单方面终结端点的权限因此该操作被禁用。建议当前版本进行节点故障清理时应使用force_remove_endpoint而非assassinate调用后者会收到运行时错误。实战完整的 curl 调用示例以下示例假设 ScyllaDB 节点 REST API 监听在127.0.0.1:10000。# 1. 查看当前存活节点 curl -s http://127.0.0.1:10000/gossiper/endpoint/live/ | python3 -m json.tool # 预期输出示例[192.168.1.10, 192.168.1.11] # 2. 查看当前不可达节点 curl -s http://127.0.0.1:10000/gossiper/endpoint/down/ | python3 -m json.tool # 3. 查询某节点的停机时长微秒存活节点返回 0 curl -s http://127.0.0.1:10000/gossiper/downtime/192.168.1.12 # 预期输出12500000即约 12.5 秒 # 4. 查询某节点的世代号重启会递增 curl -s http://127.0.0.1:10000/gossiper/generation_number/192.168.1.10 # 5. 查询某节点的心跳版本号状态更新会递增 curl -s http://127.0.0.1:10000/gossiper/heart_beat_version/192.168.1.10 # 6. 强制移除一个故障端点危险操作谨慎使用 curl -s -X POST http://127.0.0.1:10000/gossiper/force_remove_endpoint/192.168.1.12 # 7. 终结端点当前版本在 raft 拓扑模式下会返回错误 curl -s -X POST http://127.0.0.1:10000/gossiper/assassinate/192.168.1.12使用注意事项与限制接口一致性所有查询接口的返回值都以application/json编码且down/、live/返回的地址为字符串数组便于直接喂给监控与告警系统。同步语义endpoint/down/、endpoint/live/与downtime三个接口内部都会先同步各 shard 的 gossip 状态通过 shard 0 信号量锁因此读到的结果在任意时刻是一致的不需要调用方再做额外处理。危险操作识别force_remove_endpoint与assassinate均为 POST 且会改变集群成员视图切勿在自动化脚本中无差别调用force_remove_endpoint自带禁止移除自身的保护但调用前仍应确认目标确实已永久失效。版本差异assassinate在基于 Raft 的拓扑管理模式下不可用直接抛异常这是该接口与 Cassandra 行为的重要差异升级到新拓扑模式后相关运维流程应迁移到force_remove_endpoint。文档与规范对应接口字段与类型均以 api/api-doc/gossiper.json 为准路由实现见 api/gossiper.cc底层 gms 逻辑见 gms/gossiper.cc 与 gms/gossiper.hh排查问题时可按规范 → 路由 → gms 核心的链路逐层深入。总结ScyllaDB 的 Gossiper 管理 API 以极简的 7 个端点覆盖了集群成员管理最常用的运维操作两个列表接口用于观测存活/不可达节点两个元信息接口用于诊断节点心跳健康度两个写接口用于清理故障节点。理解其背后的gms::gossiper同步机制shard 0 聚合 信号量锁与 Raft 拓扑模式带来的行为差异能帮助你更安全、更精准地在生产环境使用这套接口。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ScyllaDB Gossiper 管理 API 完全指南：节点状态查询与故障处理实战
ScyllaDB Gossiper 管理 API 完全指南节点状态查询与故障处理实战【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb本文是 ScyllaDB基于 Seastar 框架、兼容 Apache Cassandra 与 Amazon DynamoDB 的 NoSQL 数据存储中 Gossiper REST API 的实战参考。Gossiper 负责集群成员关系发现与故障检测本文围绕其对外暴露的 7 个 HTTP 接口逐一讲解接口语义、参数、源码实现与 curl 调用示例帮助你掌握查询存活/不可达节点、查看心跳与世代号、强制移除故障节点等日常运维技能。Gossiper 在 ScyllaDB 集群中的角色在 ScyllaDB 中gms::gossiper组件位于 gms/gossiper.hh 与 gms/gossiper.cc承担两项核心职责集群成员关系发现通过节点间交换gossip_digest_syn/ack/ack2消息让每个节点都能掌握全集群其他节点的存活状态故障检测维护_live_endpoints存活节点与_unreachable_endpoints不可达节点集合并为每个端点记录心跳版本号heartbeat version与世代号generation number。对外这些内部状态通过 HTTP API 暴露给运维人员与监控系统。接口定义位于 Swagger 规范文件 api/api-doc/gossiper.json路由注册实现在 api/gossiper.cc对应的 API 文档页即 docs/reference/api/gossiper.rst。API 总览该组接口的basePath为{{Protocol}}://{{Host}}即 ScyllaDB 节点对外监听的 REST 地址默认协议为 HTTP端口 10000resourcePath为/gossiper所有接口均produces: application/json且不需要额外的鉴权头由节点自身的访问控制策略决定。方法路径说明返回类型GET/gossiper/endpoint/down/获取所有不可达down节点的地址列表arraystringGET/gossiper/endpoint/live/获取所有存活live节点的地址列表arraystringGET/gossiper/downtime/{addr}查询指定节点的停机时长long微秒GET/gossiper/generation_number/{addr}查询指定节点的当前世代号longGET/gossiper/heart_beat_version/{addr}查询指定节点的当前心跳版本号longPOST/gossiper/assassinate/{addr}终结assassinate一个端点voidPOST/gossiper/force_remove_endpoint/{addr}从 gossip 中强制移除一个端点void从源码结构看这些接口在 api/gossiper.cc 的set_gossiper(http_context, routes, gms::gossiper)函数中完成注册并通过unset_gossiper()反注册节点关闭时会调用unset_gossiper清理路由。节点状态查询存活与不可达列表获取不可达节点列表GET /gossiper/endpoint/down/返回当前被故障检测器判定为不可达的节点 IP 地址数组。其实现api/gossiper.cc调用g.get_unreachable_members_synchronized()将结果转换为字符串数组返回。所谓synchronized见 gms/gossiper.cc该函数强制invoke_on(0)到 shard 0先获取lock_endpoint_update_semaphore()锁再结合_address_map把 host id 映射为inet_address输出。这样做的目的是确保跨 shard 的数据一致——ScyllaDB 的 Seastar 模型下每个 shard 有自己的状态副本读接口必须先同步。获取存活节点列表GET /gossiper/endpoint/live/返回当前存活节点的地址数组。实现api/gossiper.cc调用g.get_live_members_synchronized()对应 gms/gossiper.cc同样先拿锁再读取_live_endpoints映射后的地址集合。实战意义这两个接口是集群健康度最直接的观测入口。监控脚本可以周期轮询/gossiper/endpoint/live/与/gossiper/endpoint/down/对比两次结果即可发现节点上下线事件结合nodetool status的结果可做交叉校验。查询节点停机时长GET /gossiper/downtime/{addr}路径参数addr为端点 IP 地址必填类型string。返回该节点的停机时长单位为微秒long。实现api/gossiper.cc会先同步所有 shard 的unreachable_members再调用g.get_endpoint_downtime(g.get_host_id(ep))。核心逻辑在 gms/gossiper.cc若端点存在于_unreachable_endpoints中则返回now() - downtime即从进入不可达状态到当前时刻的微秒差若端点不在不可达集合中即存活或未知返回0。注意返回 0 并不能区分节点从未宕机与节点不在 gossip 视图内需要结合 live/down 列表综合判断。节点元信息查询世代号与心跳版本号Gossip 协议中每个节点维护两个关键单调递增计数器定义在gms::heart_beat_state中世代号generation number节点每次重启时递增用于标识这是第几代实例从而让其他节点识别并丢弃上一代残留的过时状态心跳版本号heartbeat version节点每次应用新的应用状态application state时递增用于 gossip 消息去重与状态新旧判断。查询世代号GET /gossiper/generation_number/{addr}路径参数addr为端点 IP。返回long。实现api/gossiper.cc先通过g.get_host_id(ep)将 IP 解析为 host id再调用g.get_current_generation_number()其源码在 gms/gossiper.ccreturn const_castgossiper*(this)-container().invoke_on(0, [endpoint] (const gossiper gossiper) { return gossiper.get_endpoint_state(endpoint).get_heart_beat_state().get_generation(); });即强制在 shard 0 上读取该端点的endpoint_state中heart_beat_state的 generation 值。查询心跳版本号GET /gossiper/heart_beat_version/{addr}路径参数addr为端点 IP。返回long。实现api/gossiper.cc对应 gms/gossiper.cc读取get_heart_beat_version()。实战意义当怀疑某节点状态迟迟不更新时可以连续两次调用本接口观察心跳版本号是否在增长——长期不增长说明该节点可能已停止发送 gossip 心跳而世代号跳变则说明节点发生了重启。结合这两者可以快速定位僵尸节点或频繁重启的节点。故障处理强制移除与终结端点这两个 POST 接口属于危险操作用于清理集群中无法正常退出的故障节点使用时需格外谨慎。强制移除端点POST /gossiper/force_remove_endpoint/{addr}路径参数addr为要移除的端点 IP。返回void。实现api/gossiper.cc将 IP 解析为 host id 后调用g.force_remove_endpoint(g.get_host_id(ep), gms::null_permit_id)。核心逻辑在 gms/gossiper.cc切换到 gossip 调度组gossip_scheduling_group避免影响其他任务invoke_on(0)在 shard 0 上执行先通过lock_endpoint(id, pid)获取该端点的操作许可permit保证并发操作互斥自保护若id gossiper.my_host_id()抛出异常Can not force remove node {} itself即不允许移除自己若端点不存在于_endpoint_state_map仅记录 debug 日志并直接返回幂等依次调用remove_endpoint(id, pid)与evict_from_membership(id, pid)完成移除与成员资格驱逐。其中remove_endpointgms/gossiper.cc会先通知所有i_endpoint_state_change_subscriber订阅者执行on_remove回调再从_seeds、live/unreachable 集合、_syn_handlers、_ack_handlers中清除该端点若该端点此前被视为存活还会触发on_dead通知并记录日志。使用场景当一台节点彻底宕机且无法恢复如硬件损坏但残留状态仍被其他节点感知、影响集群健康时使用本接口将其从 gossip 视图中彻底清除。终结端点assassinatePOST /gossiper/assassinate/{addr}路径参数addr为端点 IP。返回void。这是一个兼容性接口从源码看当前版本中 gms/gossiper.cc 的实现直接抛出异常future gossiper::assassinate_endpoint(sstring address) { throw std::runtime_error(Assassinating endpoint is not supported in topology over raft mode); }也就是说在**基于 Raft 的拓扑管理模式topology over raft mode**下终结端点操作已不被支持。可以推断该接口是历史遗留早期版本中它用于强制击杀一个故障端点模拟其彻底消失防止其复活后以旧身份重新加入在新拓扑模式下节点身份与成员资格由 Raft 组管理gossip 不再拥有单方面终结端点的权限因此该操作被禁用。建议当前版本进行节点故障清理时应使用force_remove_endpoint而非assassinate调用后者会收到运行时错误。实战完整的 curl 调用示例以下示例假设 ScyllaDB 节点 REST API 监听在127.0.0.1:10000。# 1. 查看当前存活节点 curl -s http://127.0.0.1:10000/gossiper/endpoint/live/ | python3 -m json.tool # 预期输出示例[192.168.1.10, 192.168.1.11] # 2. 查看当前不可达节点 curl -s http://127.0.0.1:10000/gossiper/endpoint/down/ | python3 -m json.tool # 3. 查询某节点的停机时长微秒存活节点返回 0 curl -s http://127.0.0.1:10000/gossiper/downtime/192.168.1.12 # 预期输出12500000即约 12.5 秒 # 4. 查询某节点的世代号重启会递增 curl -s http://127.0.0.1:10000/gossiper/generation_number/192.168.1.10 # 5. 查询某节点的心跳版本号状态更新会递增 curl -s http://127.0.0.1:10000/gossiper/heart_beat_version/192.168.1.10 # 6. 强制移除一个故障端点危险操作谨慎使用 curl -s -X POST http://127.0.0.1:10000/gossiper/force_remove_endpoint/192.168.1.12 # 7. 终结端点当前版本在 raft 拓扑模式下会返回错误 curl -s -X POST http://127.0.0.1:10000/gossiper/assassinate/192.168.1.12使用注意事项与限制接口一致性所有查询接口的返回值都以application/json编码且down/、live/返回的地址为字符串数组便于直接喂给监控与告警系统。同步语义endpoint/down/、endpoint/live/与downtime三个接口内部都会先同步各 shard 的 gossip 状态通过 shard 0 信号量锁因此读到的结果在任意时刻是一致的不需要调用方再做额外处理。危险操作识别force_remove_endpoint与assassinate均为 POST 且会改变集群成员视图切勿在自动化脚本中无差别调用force_remove_endpoint自带禁止移除自身的保护但调用前仍应确认目标确实已永久失效。版本差异assassinate在基于 Raft 的拓扑管理模式下不可用直接抛异常这是该接口与 Cassandra 行为的重要差异升级到新拓扑模式后相关运维流程应迁移到force_remove_endpoint。文档与规范对应接口字段与类型均以 api/api-doc/gossiper.json 为准路由实现见 api/gossiper.cc底层 gms 逻辑见 gms/gossiper.cc 与 gms/gossiper.hh排查问题时可按规范 → 路由 → gms 核心的链路逐层深入。总结ScyllaDB 的 Gossiper 管理 API 以极简的 7 个端点覆盖了集群成员管理最常用的运维操作两个列表接口用于观测存活/不可达节点两个元信息接口用于诊断节点心跳健康度两个写接口用于清理故障节点。理解其背后的gms::gossiper同步机制shard 0 聚合 信号量锁与 Raft 拓扑模式带来的行为差异能帮助你更安全、更精准地在生产环境使用这套接口。【免费下载链接】scylladbNoSQL data store using the Seastar framework, compatible with Apache Cassandra and Amazon DynamoDB项目地址: https://gitcode.com/GitHub_Trending/sc/scylladb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考