RustFS 分层存储Tier与 ILM 转换故障排查指南从 xl.meta 到管理 API 的全链路调试手册【免费下载链接】rustfs2.3x faster than MinIO for 4KB object payloads. RustFS is an open-source, S3-compatible high-performance object storage system supporting migration and coexistence with other S3-compatible platforms such as MinIO and Ceph.项目地址: https://gitcode.com/GitHub_Trending/rus/rustfsTier / ILM Transition分层存储与生命周期转换是 RustFS 对象存储中风险最高、链路最长的后台操作对象被迁移到远端 S3/MinIO/GCS 等温层、被本地优先过期、再异步清理远端副本中间涉及持久化事务、可恢复任务、双键元数据与版本语义。本指南面向这样三类场景被分层transitioned的对象返回NoSuchVersion或恢复restore失败、转换运行看起来卡住、以及需要直接检查xl.meta并追踪发送到远端 tier 的versionId。读完本文你将掌握从元数据键约定、磁盘级检查、运行时日志、手动转换管理 API到恢复记录处置与遗留元数据协调的完整排障方法。本文是 docs/operations/tier-ilm-debugging.md 的深度展开版所有结论均可回溯到仓库源码与测试。一、代码地图先定位再动手排障的第一步是知道每个环节的代码在哪里。下表是 RustFS 中 Tier / ILM 转换链路的权威代码地图关注点位置ILM 动作transition_object、expire_transitioned_object、get_transitioned_object_reader、gen_transition_objnamebucket_lifecycle_ops.rs纠删集转换/恢复入口点set_disk 与 storeWarmBackendtraitput/get/remove/in_usewarm_backend.rs按厂商划分的 tier 后端S3、MinIO、GCS、Azure、阿里云、腾讯云、华为云、Wasabi、Cloudflare R2、RustFS 自身等services/tier/warm_backend_*.rs远端 tier 清扫delete_object_from_remote_tiertier_sweeper.rs持久化 free-version 扫描与本地优先过期后的重新入队tier_free_version_recovery.rs带围栏fenced的 free-version 远端删除、本地 marker 清理与重扫cleanup_free_version_exactbucket_lifecycle_ops.rs持久化手动转换 job/task/result 记录manual_transition_job.rs休眠的 tier 校验探测意图格式与只读核心检查tier_probe_intent.rs手动运行/状态/取消与转换事务协调管理路由ilm_transition.rsObjectInfo/TransitionedObject类型object_api/types.rsFileMeta/FileInfo/ 版本元数据crates/filemeta双键内部元数据辅助insert_bytes/get_bytesmetadata_compat.rs从源码结构看转换链路的完整形态是生命周期评估器evaluator.rs→ ILM 动作bucket_lifecycle_ops.rs→WarmBackend远端写入warm_backend_*.rs→ 本地xl.meta元数据提交 → 过期时本地优先删除并留下 free-version → 由专用恢复回路或 tier sweeper 异步清理远端。任何一个环节断裂都会表现为对象不见了或远端在泄漏。二、Lifecycle 规则限制与评估语义在动手排障前必须理解 RustFS 生命周期规则施加的硬性约束——很多看起来坏了的现象其实是规则本身不允许的用法。2.1 转换链的限制每条生命周期规则至多支持一个Transition和一个NoncurrentVersionTransition。一个版本只能做一次初始转换到达complete状态后不支持继续链接到更多 tier。试图用多条规则重叠分段来实现转换链是无效的——PutBucketLifecycleConfiguration会在任一 transition 数组中出现多个条目时直接拒绝InvalidArgument包括被禁用规则中的多条目。已存储的历史多条目数组不会被执行必须用单个预期目的地替换。注意规则中独立的过期expiration动作不受此限制仍然有效。2.2 过期与转换的优先级Expiration.Days与Expiration.Date互斥同时包含两者会被拒绝而不是静默选择日期。当过期和转换同时到期时过期优先一次失败的前序转换不会让一个已过期的对象无限期存活。期限deadline在同一动作类别内选择最早的到期动作。2.3 非当前版本Noncurrent的限制非当前版本的过期与转换各自拥有独立的NewerNoncurrentVersions限制。带正数限制的转换必须等待一次完整的版本组评估以确认剩余的新版本数足够。单对象评估路径包括当前手动转换与立即入队路径会保守地把这类计数转换推迟给生命周期扫描器处理。一个未满足的过期保留限制不会抑制另一个独立到期的转换。2.4 对象锁下的过期清理在 Object Lock 开启时过期的已恢复本地副本可以被清理因为保留的逻辑版本与远端数据仍然完好。前提是转换已完成并且仍需等待挂起或失败的复制replication结束。存储层在删除本地副本前会重新验证源身份与恢复restore元数据——仅有 restore 请求头不足以授权清理。三、Free-version 恢复控制默认开启的独立修复回路分层的对象过期后本地元数据先被删除远端副本的清理责任以一个持久化的 free-version 记录下来。专门负责恢复这些记录的回路是独立于数据扫描器scanner与 heal 开关的。3.1 开关语义务必区分设置RUSTFS_SCANNER_ENABLEDfalse不会停止 free-version 恢复回路——该回路默认启用。只有RUSTFS_TIER_FREE_VERSION_RECOVERY_ENABLEDfalse进程启动前设置才能单独禁用持久化 marker 遍历。但禁用该设置不会禁用生命周期 worker也不会阻止其他 scanner 路径发现 free-version它只会让远端清理 marker 挂起更久。因此它应被当作破窗break-glass压力控制手段而非清理机制。源码佐证环境变量RUSTFS_TIER_FREE_VERSION_RECOVERY_ENABLED在 bucket_lifecycle_ops.rs 中被定义。3.2 为什么不能跳过没有规则的桶正常的分层删除会把提交后回执post-commit receipt直接传给生命周期队列。命名空间遍历是崩溃、队列压力、混合版本与历史记录场景的回退手段。它不能因为某桶当前没有生命周期规则、或引用的 tier 已被移除就安全跳过一条更老的xl.metafree-version 可能是某个必需远端 DELETE 的唯一所有者。3.3 页面预算与退避参数单个后台恢复页最多完成10,000 个逻辑对象、覆盖最多 100 个桶最多入队1,000 个可恢复 free-version。scanner 可以额外解码一个对象来检测截断continuation marker 保存第一个未扫描的桶或最后一个完整扫描的对象。每个截断页及后续清扫在上一页完成后至少等待 60 秒失败页从 60 秒指数退避到 10 分钟完整空闲清扫指数退避到 10 分钟并带抖动jitter。单次遍历没有固定总超时但继承驱动器遍历停滞超时RUSTFS_DRIVE_WALKDIR_STALL_TIMEOUT_SECS体系因此大而健康的桶可以持续推进而不会重现旧的超时-重启循环。以上常量在 tier_free_version_recovery.rs 中均有对应定义入队上限DEFAULT_FREE_VERSION_RECOVERY_LIMIT 1_000L34、扫描上限DEFAULT_FREE_VERSION_RECOVERY_SCAN_LIMIT 10_000L37、桶上限DEFAULT_FREE_VERSION_RECOVERY_BUCKET_LIMIT 100L38间隔与抖动在 bucket_lifecycle_ops.rs基础间隔 60 秒、最大空闲间隔 10 分钟、抖动 10%。该模块的单元测试recovery_walk_disables_total_timeout_and_inherits_stall_timeout与recovery_scan_limit_is_independent_from_enqueue_limit还明确固定了遍历预算与入队预算互相独立总时间预算被禁用、只继承停滞预算的契约。3.4 可观测性结构化的lifecycle_worker_state恢复事件会报告duration_ms、scanned_entries、buckets_scanned、队列计数、截断与 continuation markers。指标侧rustfs_internal_stage_duration_ms{stagelifecycle_free_version_recovery}记录成功页耗时stagelifecycle_free_version_recovery_failed记录失败耗时。四、元数据键约定双键写入RustFS 优先读取RustFS 的内部元数据以x-rustfs-internal-suffix与x-minio-internal-suffix双键形式存储以保持与 MinIO 的互操作性get_bytes读取时优先 RustFS 键回退 MinIO 键。这两条前缀常量定义在 metadata_compat.rs所有 tier 相关后缀L60-L92同样是该模块的权威定义。后缀含义transition-status值为complete表示已分层transitioned-objecttier 键路径不含 tier 前缀存储get_dest会补上transitioned-versionID远端版本标识符可能是当前精确 UTF-8 文本、遗留 RustFS 原始 UUID 字节、MinIO 的空未版本化值或某些历史未版本化记录中缺失。必须结合transitioned-version-state或一次实时兼容探测来解释transition-tiertier 名称tier-free-versionIDfree-version 清扫用的删除标记版本4.1 遗留 UUID 值的读取契约遗留原始 UUID 值必须拒绝空值、畸形值与 nil UUID回归测试覆盖在 crates/filemeta/src/filemeta/version.rs 的测试中。合法读取模式get_bytes(self.meta_sys, SUFFIX_TRANSITIONED_VERSION_ID) .and_then(|v| Uuid::from_slice(v.as_slice()).ok()) .filter(|u| !u.is_nil()) // None for: absent key, wrong-length bytes, nil UUID关键语义transition_version_id None只说明不存在可用的遗留 UUID 投影不能证明远端桶的版本化模型。只有显式的KnownDisabled状态才授权普通 GET/DELETE 省略versionId。状态缺失且版本键缺失或为空 → 仍为Unknown需要有界的兼容性探测或已批准的协调工作流它永远不能直接授权清理。nil UUID00000000-...作为?versionId发送会导致NoSuchVersion。禁止使用Uuid::from_slice(..).unwrap_or_default()它会把空元数据值转换为Uuid::nil()——而这正是NoSuchVersion失败的根源。在 version.rs 中可以看到版本状态的持久化编码known-disabled对应TransitionVersionState::KnownDisabled、suspended-null对应TransitionVersionState::SuspendedNullL268-L269状态与版本值的合法性由TransitionVersionState::matches_version类逻辑约束Unknown | KnownDisabled要求版本为NoneSuspendedNull要求版本恰为字面量null。五、直接检查 xl.meta当对象表现为不见了或无法恢复时最直接的证据在磁盘上的xl.meta。RustFS 提供了现成的 dump 工具cargo build -p rustfs-filemeta --example dump_fileinfo ./target/debug/examples/dump_fileinfo /srv/rustfs/data/disk0/{bucket}/{object}/xl.meta # Shows: transition_status, transition_tier, transitioned_obj, transition_ver_id输出含义transition_ver_id: none不存在可用的遗留 UUID 投影。检查transitioned-version-state与原始兼容键不要推断为未版本化语义transition_ver_id: uuid遗留 UUID 表示解码成功。除非持久化状态或协调证据确立了精确的远端模型否则它不是破坏性操作的授权注意每个纠删分片磁盘各有一份xl.meta路径为{disk}/{bucket}/{object}/xl.meta健康对象的全部分片应完全一致。同一 crate 的dump_versions示例会列出文件中的每个版本可用于对比分片间差异。六、运行时追踪 versionId日志是定位发送给远端的 versionId 到底是什么的最快手段。以 debug 级别开启生命周期组件日志RUST_LOGrustfs_ecstore::bucket::lifecycledebug rustfs ...日志行级别含义fetching transitioned object from tierDEBUG在发起 tier 请求之前输出tier GET failedERROR包含tier_version_id判读规则如果版本键为空而transitioned-version-state缺失记录具有历史 MinIO 未版本化形态但仍然属于Unknown只有兼容性探测或协调协议可以证明KnownDisabled。如果状态显式为KnownDisabled则不发送versionId。在 warm_backend.rs 中还可以看到探测结果枚举TransitionCandidateProbeMissing/UnversionedPresent/VersionedPresent(String)/Ambiguous/Unsupported它是后续所有协调流程判定远端到底有没有这个版本的基础。七、手动转换运行Manual Transition Run手动转换运行是操作员对现有生命周期转换评估器的触发器。它不会强制转换尚未到期的对象也不会绕过版本化、复制、删除标记、目录标记、tier 或进行中转换等检查。7.1 请求与参数POST /rustfs/admin/v3/ilm/transition/run?bucketbucketprefixprefixtiertierdryRuntruemaxObjects10000maxDurationSeconds30参数契约bucket必填prefix、tier、dryRun收窄运行范围mode默认enqueue_only设为async可运行持久化后台任务async选择持久化异步模式的兼容布尔值不得与mode冲突maxObjects默认10000上限100000maxDurationSeconds可选上限3600在列举的版本与页之间检查的最佳努力预算进行中的列举调用不会被取消这些边界在 ilm_transition.rs 中直接以常量形式固定DEFAULT_MANUAL_TRANSITION_MAX_OBJECTS 10_000、MAX_MANUAL_TRANSITION_OBJECTS 100_000、MAX_MANUAL_TRANSITION_DURATION_SECONDS 3600。此外同一文件实现了运行作用域准入ManualTransitionRunScope含桶/前缀/tier 大写化/dry-run 与prefixes_overlap判定对同一桶、前缀、tier、dry-run 类别的并发手动转换会返回OperationAborted避免多个有界扫描互相踩踏。7.2enqueue_only模式默认响应报告这次有界扫描评估并注入了内存转换队列的内容statecompleted有界扫描在当前范围内走到了末尾没有遇到队列压力或预算截断。注意这不代表每个远端 tier PUT 都已完成。statepartial运行因maxObjects、maxDurationSeconds或队列压力skipped_queue_full、skipped_queue_closed、skipped_queue_timeout提前停止。该响应的响应中不包含任务端点。7.3async持久化任务模式使用modeasync或asynctrue时成功请求返回202 Accepted、modedurable_job、UUIDjob_id以及状态/取消端点GET /rustfs/admin/v3/ilm/transition/jobs/job-id DELETE /rustfs/admin/v3/ilm/transition/jobs/job-id持久化模式提供桶级持久化准入、重启恢复、租约围栏的列举检查点、任务先于入队记录、worker 结果记录、持久化取消。它仍然把每个对象委托给正常生命周期评估器与转换事务——任务永远不会绕过对象资格判定也不拥有远端删除权。GET 返回持久化任务状态与报告。DELETE 持久化cancel_requested对活动执行器停止新的扫描工作。启动恢复仅在scan_completed true时先协调任务/结果。过期任务若扫描未完成且已请求取消则直接 CAS 终结为cancelled其计数可能过期范围释放随后以最佳努力的精确删除进行。未取消的恢复改为 CAS 接管租约、替换范围准入、重放挂起任务并从持久化 token 恢复对象版本扫描。同一桶与运行/dry-run 类别的冲突持久化任务会返回活动任务及其端点。混合舰队注意异步端点本身不查询舰队能力门控直接请求即可创建持久化任务。在混合舰队启用持久化模式前调用方/操作员编排必须在每个所需节点上检查manual_transition_jobs运行时能力任何响应未知或不支持时必须失败关闭。持久化状态、所有权与恢复规则详见 docs/architecture/ilm-tiering-persistence-contracts.md。终结的 job/task/result 历史当前没有自动保留上限在未来的协议级收集器定义前状态数据一直可用。7.4 推荐操作流程# 先干跑dry-run观察会评估什么 rc admin ilm transition run local/mybucket --prefix logs/ --tier cold --dry-run --max-objects 1000 --max-duration-seconds 30 # 正式运行 rc admin ilm transition run local/mybucket --prefix logs/ --tier cold --max-objects 1000 --max-duration-seconds 30八、验证探测的崩溃恢复状态休眠但未启用当前 Tier 的 Add/Edit/Verify 使用唯一的rustfs-tier-probe-uuid对象验证目的地并在进程存活期间执行有界补偿。但是rustfs-tier-probe-intent-v1解码器、规范持久化命名空间、条件存储原语、状态机与 crate 级检查类型目前只是休眠基础dormant foundation。没有任何验证路径写入该记录没有启动或周期恢复扫描它也没有管理 HTTP 路由暴露它。V1 要求所有者始终等于不可变创建者接管需要带显式证明的新 schema。持久化写入与破坏性恢复在舰队能力、操作代次重新验证、提供方超时、保留与操作员契约批准前均保持禁用。排障中的两条硬性规则不要到内部元数据桶搜索这些记录作为验证可崩溃恢复的证据——当前服务器不会创建它们。如果进程在远端探测 PUT 之后、清理之前被杀请手动检查目的地提供方并保留模棱两可的候选。永远不要删除空的或猜测的版本不要手工创建探测意图来授权清理。另外排查 tier 问题时如果RUSTFS_RPC_SECRET或其他凭据被粘贴进 issue、聊天、日志或工单请在每个节点轮换、用新值重启集群并在共享更多诊断前对暴露副本脱敏。九、协调未知转换上传两阶段工作流历史转换事务处于upload_outcome_unknown状态时若 tier 探测模棱两可且提供方支持精确版本删除可以使用显式的两阶段操作员工作流。该端点拒绝仍在其所有权窗口内、或处于任何其他状态的事务。9.1 两种合法的 v1 状态形态当前舰队可产生两种合法 v1 状态形态遗留形态始于upload_started1通常到达upload_outcome_unknown2、uploaded、local_commit_started、committed。紧凑形态仅在每个当前成员都能证明transition_transaction_compaction_v1时才被接纳始于upload_outcome_unknown1直接携带已知远端版本进入local_commit_started2。判读语义upload_outcome_unknown1是PUT 之前的围栏pre-PUT fence不是 PUT 已运行的证明local_commit_started2是精确提交围栏——若匹配的xl.meta元组完整恢复只移除记录否则保留所有者证据。不要手工重写任一状态。不可用或更老的节点会自动让新转换使用遗留形态。9.2 工作流步骤步骤 1只读检查事务不改变任何东西GET /rustfs/admin/v3/ilm/transition/reconcile/transaction-id步骤 2若独立提供方证据确认了要移除的精确远端版本提交该不透明版本标识符并显式确认。这只执行精确版本删除响应会报告事务日志随后是否仍被观察到后台恢复可能并发终结了同一事务POST /rustfs/admin/v3/ilm/transition/reconcile/transaction-id { action: delete_candidate, confirm: true, remote_version_id: exact-provider-version }步骤 3若日志仍在再次检查并且仅在实时提供方探测证明候选已缺失后终结POST /rustfs/admin/v3/ilm/transition/reconcile/transaction-id { action: finalize_missing, confirm: true }finalize_missing会重跑提供方探测并对unversioned_present、versioned_present、ambiguous、unsupported或探测错误失败关闭。它从不接受操作员断言来代替实时missing结果。没有权威探测或精确版本删除能力的提供方保持 pending端点不会推断提供方能力、不会接受外部缺失断言、也不会自动选择候选。十、检查并处置保留的恢复记录当前服务器暴露以下路由用于保留的恢复控制。不要手工移除内部元数据对象那会丢失 ETag、全池all-pool、退役decommission、导出与审计保证。10.1 有界只读清单与检查GET /rustfs/admin/v3/ilm/recovery/records?protocolprotocolclassificationclassificationlimitnmarkeropaque GET /rustfs/admin/v3/ilm/recovery/records/control-id清单与脱敏检查需要admin:ListTier。服务器会重建规范源身份、强读每份权威副本并报告一条逻辑记录及其schema、分类retrying、retained_ambiguous、corrupt、operator_required、abandoned或terminal、稳定原因码、副本/内容摘要、重试期限/计数器、舰队就绪度、扫描完整性与退役覆盖。默认 JSON不返回原始遗留字节、对象/版本名、端点、凭据或提供方错误文本。池覆盖不完整、副本分歧、缺少 ETag、损坏或没有 continuation marker 的截断页会失败关闭无法产出可操作的收据。检查返回一张15 分钟不透明观察收据。它绑定已认证操作者、规范记录、每份源副本/ETag/摘要、拓扑/舰队代次、请求的动作类别、签发/过期时间与 nonce。收据防止过期请求扩大目标它不是清理授权。该 TTL 在 ilm_transition.rs 定义为ILM_RECOVERY_OBSERVATION_RECEIPT_TTL Duration::minutes(15)。10.2 证据保全流程严格解码的 v1/v2 tier 删除日志步骤 1精确检查记录独立判断保留本地清理义务是否仍有价值。步骤 2持admin:SetTier从当前观察收据创建不可变服务端导出。导出包含精确原始日志字节与副本清单以规范摘要派生的导出 ID只创建一次安装强读回并通过 no-store 附件响应下载POST /rustfs/admin/v3/ilm/recovery/records/control-id { action: export, observation_receipt: opaque } GET /rustfs/admin/v3/ilm/recovery/exports/export-id步骤 3仅在保全导出后持admin:SetTier提交全新的精确处置POST /rustfs/admin/v3/ilm/recovery/records/control-id { action: abandon_remote_cleanup, confirm: true, acknowledge_remote_cleanup_abandoned: true, observation_receipt: opaque, export_id: export-id, export_sha256: sha256, reason_code: bounded-operator-reason }10.3 处置语义与崩溃安全性最后这个动作只移除精确的本地 v1/v2 日志代次对每份副本按If-Match执行且必须先有持久的Prepared处置收据与全新的全成员能力证明。收据推进Prepared - Applying - Completed并记录单调递增的每副本confirmed_absent集合。若服务器删除副本 A 后在记录进度前崩溃恢复可在源/控制、拓扑、进程纪元、迁移与退役证明均未变化的前提下确认 A 缺失持久化该进度并继续处理仍然精确的副本 B。替换的 ETag 永远是冲突恢复从不扩大不可变副本清单。该动作从不创建 tier 客户端、探测后端、或发起远端 PUT/GET/DELETE。其含义刻意收窄操作者接受远端存储可能泄漏并在保全证据后放弃 RustFS 清理。副本变化、活动退役、成员缺失、拓扑/进程重启、读取不完整或替换证明不确定都会保留证据。成功要求每份绑定副本都被持久确认缺失、全新全成员/退役证明、且处置收据持久Completed响应丢失只会以同一规范操作 ID 恢复。10.4 配额与并发限制规范回放相同导出/处置不消耗新配额。新操作需要完整工件清单当预计保留总量含完整编码候选超过10,000 个导出、10,000 张处置收据、1 GiB 编码导出数据、或 256 MiB 编码控制/处置数据时在源变更前即被拒绝。配额决策、只创建安装与精确回读共享一个集群范围的准入 WRITE 锁——该锁总是在控制/源/处置与物理元数据锁之前获取并在处置Applying或任何源删除之前释放调用方持内层保护时从不获取它。安装前崩溃不消耗容量丢失的安装响应在同一串行化顺序下由规范回读解决因此并发节点无法超额订阅过期快照。准入还限制为每操作者每分钟 10 次创建、集群每分钟 100 次、32 个并发导出、8 个并发处置。容量压力从不驱逐恢复证据也不阻塞普通对象 I/O收集器每分钟最多检查 100 个终结工件。10.5 保留与自动重试畸形/不支持记录与 v3-v6 日志不能使用 abandon。已知版本与 v6 清单所有权必须通过各自的正常精确恢复协议收敛。操作者可以检查、导出并请求有界重试但不能绕过源/free-version 证明、清单成员、拓扑或版本语义。自动重试状态跨重启存活。可重试的传输/法定人数失败使用60 秒指数基数、封顶 1 小时并带80%–100% 的确定性乘数——抖动永远不会增加封顶延迟。连续失败 32 次或自首次持久化失败起 7 天后自动工作停在operator_required。不支持或模棱两可的证据直接进入retained_ambiguous/operator_required仅凭时间过去永远不会删除它。已解决控制、不可变导出与已完成处置收据分别有最少 30 天、90 天、365 天保留期且仅在精确源缺失、退役、后继与审计检查通过后被收集。十一、重试保留的转换事务对于transition_transaction控制当精确事务源与恢复控制代次仍然一致时检查会额外返回一个transition_retry对象包含retry_ready、control_revision、source_generation_sha256、当前分类与计数器以及有界拒绝原因。若transition_retry缺失且transition_retry_not_ready_reasonsource_or_control_not_ready说明服务器无法重建精确实时证据——不要用旧响应重试。先干跑使用最新检查返回的精确修订号与源代次摘要POST /rustfs/admin/v3/ilm/recovery/records/control-id { action: retry_transition_recovery, mode: dry_run, expected_control_revision: 7, expected_source_generation_sha256: sha256 }修复报告中的存储、tier 或能力问题后再次检查并干跑然后使用新观察值执行POST /rustfs/admin/v3/ilm/recovery/records/control-id { action: retry_transition_recovery, mode: execute, expected_control_revision: 7, expected_source_generation_sha256: sha256, confirm: true }执行会对精确的无主retained_ambiguous或operator_required控制做一次 ETag-CAS 更新到retrying。它保留生命周期尝试计数与失败历史只清除连续失败退避并且不修改事务源、不发起 tier PUT/GET/探测/DELETE。之后正常恢复 worker 获取新的有界所有者租约并在任何副作用前重放每个源与远端证明。分类语义历史 v1UploadStarted记录可能回到retained_ambiguous因为其字节不能证明 PUT 是否到达提供方LocalCommitStarted仅当本地对象仍匹配记录的版本 ID、数据目录、修改时间、大小、ETag 与精确转换远端元组时才变为终态否则回到operator_required。因此重试是底层修复后的有界再评估而不是对缺失证据的覆盖。完整的 schema、租约、混合版本、重试、隐私与指标要求见 docs/architecture/ilm-tiering-persistence-contracts.md。十二、协调遗留转换版本元数据已批准但未实现本节描述一个已批准但尚未实现的目标。当前服务器没有回填xl.meta中缺失transitioned-version-state的管理路由。不要为此使用上面的事务协调路由该路由拥有一个上传事务候选并可能删除它而遗留元数据协调是非破坏性的只能更新精确的本地元数据版本。已批准接口是同步的且恰好接受一个桶/对象/本地版本元组GET /rustfs/admin/v3/ilm/transition/state/reconcile?bucketbucketobjectobjectversionIdlocal-version-id POST /rustfs/admin/v3/ilm/transition/state/reconcile?bucketbucketobjectobjectversionIdlocal-version-idversionId必填本地未版本化对象使用字面量null。省略或空的选择器无效。GET 需要admin:ListTier报告权威全池元组、目的地身份、舰队/拓扑就绪度、实时探测分类、不透明期望元组摘要与机器可读诊断。由于 GET 是只读的缺失状态可被证明时返回ready-to-migrate而非migrated。POST 需要admin:SetTier、confirm: true以及 GET 返回的完整不可变源元组、原始每 set 缺失状态表示、建议目标与协调摘要。服务器会重读每份权威副本并重复有界实时后端探测提供方控制台输出或操作者提供的状态只是诊断证据绝不是写入授权。重试只接受仍匹配其摘要绑定原始表示、或已等于精确证明目标的副本任何其他分歧都是过期或损坏的。服务器只能持久化下列精确状态/版本对之一连同绑定目的地身份证明的远端模型状态版本值版本化已禁用KnownDisabled空/缺失后续请求省略versionId版本化挂起的 null 对象SuspendedNull字面量null恰好一个精确版本Exact精确的非空、非null不透明标识符响应结果为migrated、retained-ambiguous、corrupt或backend-unavailablemigrated意味着强全池回读在每份权威副本上都证明了相同状态与目的地身份可以幂等地以changedfalse出现。模棱两可/缺失/多个探测结果被保留显式Unknown、畸形或冲突双键、nil 标识符、部分元组或位于精确{原始缺失表示, 证明目标}重试子集之外的副本会失败关闭。后端不可用、tier 代次、元数据法定人数或所需强回读失败时报告backend-unavailable单调的部分写入保留以供重试从不回滚。POST不发起远端 DELETE 或 PUT、不删除本地数据、不创建 free-version、不清理事务/日志、也不改变 tier 配置。它在权威重读与有界探测期间持有已批准的舰队/拓扑、桶生命周期、精确 tier 代次/目的地与稳定全池对象版本围栏并在法定人数写入前与强回读后重新检查。包含无法保持显式状态/目的地绑定的节点的舰队仅可检查inspect-only跨池的首次匹配永远不够。刻意没有桶、前缀或舰队选择器。批量修复需要单独的持久化可恢复任务协议属于未来工作。在该单记录路由实现前保留受影响的元数据、仅用外部检查做诊断绝不手工编辑xl.meta也不要通过假定空版本字段意味着未版本化 tier 来启用远端清理。完整已批准围栏、法定人数、跨 set 重试、目的地绑定与混合版本契约见 docs/architecture/ilm-tiering-persistence-contracts.md。十三、核心不变式本地优先过期顺序理解这条不变式是避免NoSuchVersion竞态的关键expire_transitioned_object先删除本地元数据使对象不可达并留下一个持久化 free-version 供远端 tier 清理。tier_free_version_recovery.rs扫描并重新入队该记录生命周期 worker 的cleanup_free_version_exact在bucket_lifecycle_ops.rs中执行带围栏的远端删除、本地 marker 清理与重扫。硬性规则当活动本地元数据仍指向它时绝不删除远端 tier 版本——否则并发 GET 会读取一个其远端版本已消失的 stored version_id并以NoSuchVersion失败。回归测试serial_tests::test_expire_transitioned_object_never_races_concurrent_get位于 crates/scanner/tests/lifecycle_integration_test.rs运行于 CI 的 ILM Integration 串行通道同时固定了两件事本地优先删除顺序以及并发 GET 永远看不到NoSuchVersion的契约。此外tier_free_version_recovery.rs 的is_recoverable_tier_free_version及其单测还确立了一个易被忽略的细节未版本化远端 tier 合法携带空version_id此类 free-version 仍必须可恢复以便发起无版本远端删除否则会在远端永久泄漏——对象名与 tier 才是判定可恢复性的承重字段。十四、排障决策速查症状首先检查关键依据分层对象 GET 返回NoSuchVersionxl.meta的transitioned-versionID与transitioned-version-statenil UUID 是否被当versionId发送version.rs 读取契约本文第四、五、六节恢复restore失败fetching transitioned object from tier/tier GET failed日志远端版本是否仍存在第六节日志表转换运行看似卡住检查statecompleted与statepartial的区别队列压力 skip 计数第七节enqueue_only语义远端对象泄漏检查 free-version 恢复开关与页面预算、lifecycle_worker_state事件第三、十三节未知转换上传需要清理两阶段协调工作流确认探测结果第九节恢复记录需要处置检查→导出→abandon 的证据保全流程第十节遗留版本状态缺失单记录协调接口尚未实现保留元数据等待未来路由第十二节在扩大任何操作范围之前先检查聚合计数器完整对象键列表刻意不返回。若 tier 排障期间有凭据被粘贴到任何共享渠道请按第八节所述轮换所有节点。【免费下载链接】rustfs2.3x faster than MinIO for 4KB object payloads. RustFS is an open-source, S3-compatible high-performance object storage system supporting migration and coexistence with other S3-compatible platforms such as MinIO and Ceph.项目地址: https://gitcode.com/GitHub_Trending/rus/rustfs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
