Ceph RADOS Gateway 灾难恢复实战rgw-restore-bucket-index 桶索引重建工具完全指南【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/ceph本文聚焦 Ceph 分布式存储中 RADOS GatewayRGW的极端故障场景——bucket index 灾难性丢失后如何使用rgw-restore-bucket-index工具扫描数据池、找回 head object 并重建桶索引。文章将以 官方手册 为核心骨架结合仓库中的 工具源码 与 radosgw-admin 实现 深入讲解其工作原理、全部命令行参数、执行流程与安全警告帮助运维工程师在索引彻底丢失时安全、准确地执行最后手段的恢复操作。一、工具定位bucket index 丢失后的最后手段在 Ceph RADOS Gateway 的架构中bucket index维护着桶内对象的索引条目对象名、版本信息、元数据指针等是对象枚举、版本管理、生命周期操作的基础。正常情况下bucket index 由 RGW 在写入对象时同步维护并通过索引分片shard扩展以支撑海量对象。rgw-restore-bucket-index是一个EXPERIMENTAL实验性的 RADOS Gateway 用户管理工具。当 bucket index灾难性catastrophic丢失——即整个索引分片数据不可用、桶内对象失联时它可以作为最后手段last resort扫描数据池data pool中属于该桶的所有 head object解析出 RGW 对象名并尝试将其逐条添加回 bucket index。工具的使用场景非常明确且罕见它不是日常运维工具而是灾难恢复工具箱中的最后一根救命稻草。从源码的安装配置可以看到它与rgw-gap-list、rgw-gap-list-comparator、rgw-orphan-list等 RGW 辅助工具一同通过 src/rgw/CMakeLists.txt 安装到bin目录install(PROGRAMS rgw-gap-list rgw-gap-list-comparator rgw-orphan-list rgw-restore-bucket-index DESTINATION bin)该工具支持三类桶普通桶un-versioned未开启版本控制的桶版本化桶versioned启用了版本控制的桶版本控制已暂停的桶suspended曾开启版本控制后被暂停的桶。与部分丢失场景的区分需要特别强调的是rgw-restore-bucket-index只适用于整个 bucket index 全部丢失的场景。如果只是桶中部分对象的索引条目缺失例如某个分片损坏但其他分片完好官方明确警告结果将是不可预测的unpredictable。此时应改用radosgw-admin的object reindex子命令逐个对象地恢复索引条目详见下文与 radosgw-admin 的关系一节。二、必读警告使用前必须知晓的安全须知由于该工具直接操作存储层数据并会改写 bucket index官方在 手册 中列出了严格的警告在使用前务必逐条确认实验性状态工具当前被视为EXPERIMENTAL未经大规模生产环境验证使用风险自担。运行期间桶必须空闲如果工具运行期间桶仍在被活跃使用有读写请求结果不可预测。恢复操作应在完全停服/只读窗口内进行。部分丢失场景禁止使用若仅部分对象缺失于索引结果不可预测请改用radosgw-admin object reindex逐个恢复。版本化桶的删除标记delete marker行为对于版本化桶若最新版本是删除标记delete marker该删除标记会被恢复若删除标记已被新版本覆盖则该删除标记不会被恢复官方评估此行为影响极小因为恢复的是最新版本且之前的版本均可访问。这些警告在源码 src/rgw/rgw-restore-bucket-index 中也得到呼应——脚本在执行恢复前会强制打印 NOTICE: This tool is currently considered EXPERIMENTAL. 并要求用户交互确认。三、工作原理从数据池扫描到索引重建的完整链路结合源码 src/rgw/rgw-restore-bucket-index该工具的核心流程可分为六个阶段阶段一依赖与环境校验脚本启动后首先校验三个必备工具是否存在于PATHtool_listradosgw-admin ceph-dencoder jqradosgw-adminRGW 管理命令用于读取元数据、执行最终的重建动作ceph-dencoderCeph 对象编码/解码工具用于解析版本化桶的 OLHObject Layout Header信息jqJSON 处理工具脚本全程依赖它解析元数据 JSON。同时校验ceph-dencoder是否支持RGWOLHInfo类型解码dencode_listRGWOLHInfo for t in $dencode_list ;do if ceph-dencoder list_types | grep -q $t ;then : else echo ERROR: ceph-dencoder lacking module to decode ${t}. exit_code1 fi doneRGWOLHInfo是版本化桶中 OLH 对象的核心信息结构其定义位于 src/rgw/driver/rados/rgw_rados.h相关实现见 src/rgw/driver/rados/rgw_rados.cc。阶段二读取桶元数据确定 marker 与 bucket_id脚本通过radosgw-admin metadata get读取桶的 entry-point 元数据eval radosgw-admin metadata get bucket:$bucket $debugging_rgwadmin $multisite_spec $bkt_entry export marker$(jq -r .data.bucket.marker $bkt_entry) export bucket_id$(jq -r .data.bucket.bucket_id $bkt_entry)marker桶的唯一标识前缀RGW 存储在数据池中的对象名均以{marker}_开头是后续扫描数据池的过滤依据bucket_id桶实例 ID用于读取 bucket instance 元数据。若读取失败marker 或 bucket_id 为空脚本会提示检查 bucket 名及多站点参数realm/zonegroup/zone是否正确。随后读取 bucket instance 元数据并输出关键信息eval radosgw-admin metadata get bucket.instance:${bucket}:$bucket_id $multisite_spec $debugging_rgwadmin $bkt_inst num_shards$(jq .data.bucket_info.num_shards $bkt_inst) echo number of bucket index shards is $num_shards阶段三确定数据池数据池的确定遵循三级优先级见源码get_pool()函数命令行-p参数最高优先级bucket instance 中的explicit_placement.data_pool显式放置策略指定的数据池placement_rule从放置规则中解析出 placement pool 与 storage class默认STANDARD再通过radosgw-admin zone get查询 zone 配置中的placement_pools映射得到实际数据池radosgw-admin zone get $multisite_spec $zone_info pool$(jq -r .placement_pools [] | select(.key | contains(\${plmt_pool}\)) .val .storage_classes.${plmt_class}.data_pool $zone_info)如果三者均无法确定脚本报错退出。阶段四扫描数据池提取 RGW 对象名脚本用rados -p pool ls列出整个数据池并过滤出以{marker}_开头的 head object( rados -p $pool ls | grep ^${marker}_ $marker_ls ) 2/dev/null之后通过 sed 处理提取 RGW 对象名去掉对象名中的 locatortab 之后的部分排除命名空间对象{marker}__开头的多下划线形式表示带有命名空间/前缀的对象剥离 marker 前缀处理转义RGW 中初始下划线会以双下划线转义需将首对双下划线还原为单下划线( sed -E s/\t.*// $marker_ls | grep -v -E ^${marker}__[^_]_ | sed -E s/^${marker}_(.*)/\1/ | sed s/^__/_/ $obj_list ) 2/dev/null重要优化数据池的完整rados ls是昂贵且耗时的操作。若需恢复多个桶的索引可通过-l rados-ls-output-file参数复用同一次 listing 输出避免反复全池扫描。阶段五版本化桶的特殊处理脚本通过 bucket instance 元数据中的flags字段判断桶的类型位掩码export bkt_flags$(jq .data.bucket_info.flags $bkt_inst) export is_versioned$(( $bkt_flags 2)) # bit 1: 版本化桶 export is_suspended$(( $bkt_flags 4)) # bit 2: 版本控制已暂停普通桶直接沿用阶段四提取的对象列表硬链接复用版本化/已暂停桶进入handle_versioned()特殊路径逻辑为对每个对象定位其 OLHObject Layout Header对象命名空间__:形式通过rados getxattr读取 OLH 对象的user.rgw.olh.info扩展属性再用ceph-dencoder解码为 JSONrados -p $pool getxattr $olh_obj user.rgw.olh.info --object-locator $olh_loc $olh_info_enc ceph-dencoder import $olh_info_enc type RGWOLHInfo decode dump_json $olh_info_json从解码结果中提取最新实例target.key.instance若为空则说明最新条目是删除标记对版本化 head objects 按 mtime 排序rados stat2可获取 mtime过滤掉非最终版本的实例通过filter_out_last_instance变量最终把最新实例可能是删除标记追加到对象列表尾部。这段逻辑与官方警告中的删除标记行为一一对应最新版本如果是删除标记会被恢复作为$last_instance追加已被覆盖的旧删除标记则不会恢复。阶段六交互确认与执行恢复恢复动作本身通过radosgw-admin object reindex完成由脚本统一拼接参数执行eval radosgw-admin object reindex --bucket$bucket --objects-file$obj_list_ver $multisite_spec --yes-i-really-mean-it $debugging_rgwadmin默认情况下脚本是交互式的它会打印 EXPERIMENTAL 提示、显示待恢复对象列表文件路径并循环等待用户输入Type proceed! to proceed, view to view object list, or q to quit:输入proceed!开始执行恢复输入view用less查看待恢复对象列表便于执行前人工核对输入q退出清理临时文件不执行任何操作。若指定-y参数脚本跳过确认直接执行官方强烈建议慎用。收尾与清理执行完成后脚本清理所有临时文件并输出Done。临时文件默认存放在/tmp可用-t参数指定其他目录临时文件的大小与 bucket 条目数量高度相关所在分区的容量应足够。四、命令行参数全解析以下为 官方手册 中的全部命令行参数结合源码 src/rgw/rgw-restore-bucket-index 的getopts解析逻辑源码还额外支持-d调试参数参数是否必选说明-b bucket必选指定要重建索引的桶名-p pool可选指定包含该桶 head object 的数据池省略时工具自动推断优先级见阶段三-r realm-name可选指定 realm多站点配置下非默认 realm 时使用-g zonegroup-name可选指定 zonegroup非默认 zonegroup 时使用-z zone-name可选指定 zone非默认 zone 时使用-l rados-ls-output-file可选指定包含rados ls输出的文件用于多桶恢复时复用数据池 listing避免重复全池扫描-t temporary-directory可选指定临时文件目录默认/tmp分区大小需与 bucket 条目规模匹配-y可选跳过交互确认直接执行请谨慎使用调试参数源码独有手册未收录-d开启调试输出此时脚本会打印详细日志到rgwrbi-debug-log.*文件并保留临时文件clean_temps0便于排障。多站点参数-r/-g/-z在源码中会拼接为 radosgw-admin 的--rgw-realm...、--rgw-zonegroup...、--rgw-zone...选项multisite_spec$multisite_spec --rgw-realm${OPTARG} multisite_spec$multisite_spec --rgw-zonegroup${OPTARG} multisite_spec$multisite_spec --rgw-zone${OPTARG}五、实战示例基本用法恢复名为summer-2023-photos的桶官方示例$ rgw-restore-bucket-index -b summer-2023-photos执行过程示例输出marker is 6a0f6ec5-... bucket_id is 6a0f6ec5-... number of bucket index shards is 11 data pool is default.rgw.buckets.data NOTICE: This tool is currently considered EXPERIMENTAL. The list of objects that we will attempt to restore can be found in /tmp/rgwrbi-object-list-ver.12345. Please review the object names in that file (either below or in another window/terminal) before proceeding. Type proceed! to proceed, view to view object list, or q to quit:多桶恢复复用数据池 listing# 第一步生成一次数据池 listing $ rados ls -p default.rgw.buckets.data /var/tmp/pool-listing.txt # 第二步对多个桶分别执行恢复复用同一 listing $ rgw-restore-bucket-index -b summer-2023-photos -l /var/tmp/pool-listing.txt $ rgw-restore-bucket-index -b winter-2023-photos -l /var/tmp/pool-listing.txt指定数据池与非默认 zone$ rgw-restore-bucket-index -b summer-2023-photos \ -p default.rgw.buckets.data \ -r my-realm -g my-zonegroup -z my-zone无人值守谨慎$ rgw-restore-bucket-index -b summer-2023-photos -y注意-y会跳过对象列表复核环节。官方强烈建议在自动化或紧急恢复场景使用前先以交互模式跑一次确认对象列表无误。六、与 radosgw-admin 的关系底层恢复机制rgw-restore-bucket-index是编排脚本真正执行索引条目写入的是radosgw-admin object reindex子命令。在 radosgw-admin.cc 中命令注册{ object reindex, OPT::OBJECT_REINDEX }L1109参数支持--objects-filefileL422即从文件批量读取对象名安全开关--yes-i-really-mean-itL508reindex 属破坏性/写操作必须显式确认核心调用store-reindex_obj(driver, bucket-get_info(), obj-get_obj(), dpp(), null_yield)L9152经 SAL 层Storage Abstraction Layer将对象重新写入 bucket index。object reindex支持--object单个对象与--objects-file批量列表两种指定方式且二者互斥源码 L9126 会拒绝同时指定。这正是部分丢失场景的推荐路径当仅个别对象索引缺失时可直接使用$ radosgw-admin object reindex --bucketmy-bucket --objectmy-object $ radosgw-admin object reindex --bucketmy-bucket --objects-fileobj-list.txt七、执行注意事项与最佳实践基于源码分析与官方警告梳理以下实践建议停机窗口执行工具运行期间桶必须处于静默状态建议先暂停对该桶的读写或整个 RGW 服务只读恢复完成后再恢复服务。先备份、后执行恢复前建议对 bucket instance 元数据、zone 配置等重要信息留档如条件允许可先复制数据池 listing 到安全位置。确保依赖就绪radosgw-admin、ceph-dencoder含RGWOLHInfo解码支持、jq三者缺一不可缺失任一脚本会立即报错退出。临时目录容量临时文件大小与 bucket 条目数量强相关。脚本内部还会通过df实时检查临时目录的数据/索引使用率达到 100% 时会中止见源码test_temp_space()函数。建议为-t指定的分区预留充足空间。先交互、后自动化首次执行务必走交互模式用view核对待恢复对象列表确认无误后再用-y用于批量/无人值守场景。排序确定性脚本显式设置LC_ALLC以保证sort与ceph-diff-sorted的排序一致源码注释特别强调该依赖请勿在环境中覆盖此行为。恢复后验证恢复完成后建议通过radosgw-admin bucket stats、对象列举接口如 S3 ListObjects或rgw-gap-list仓库中的索引对比工具与rgw-restore-bucket-index一同安装验证索引完整性。八、适用边界与限制该工具仅重建 bucket index 条目不涉及对象数据本身的修复数据池中的 head object 必须完好否则无从恢复。它是EXPERIMENTAL工具官方未承诺生产级稳定性任何恢复操作都应在充分评估风险、具备回退方案的前提下进行。恢复的索引仅包含扫描到的 head object未匹配 marker、位于命名空间内的对象不在此工具处理范围内。多站点multisite环境必须通过-r/-g/-z指定正确的 realm/zonegroup/zone否则元数据读取将失败脚本会在 marker/bucket_id 为空时明确报错提示。参见radosgw-admin(8) 手册RGW 管理命令全集包含object reindex、bucket reindex、metadata get、zone get等本工具依赖的命令工具源码本文所有流程分析的直接依据bash 实现radosgw-admin 命令实现object reindex子命令的参数解析与底层调用安装配置rgw-restore-bucket-index与rgw-gap-list、rgw-orphan-list等辅助工具的安装定义【免费下载链接】cephCeph is a distributed object, block, and file storage platform项目地址: https://gitcode.com/gh_mirrors/ce/ceph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考