RustFS 对象容量统计组件 rustfs-object-capacity 深度解析扫描、采样与混合缓存刷新机制【免费下载链接】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导读rustfs-object-capacity是 RustFS 对象存储中负责已用容量统计的核心组件它扫描本地数据盘目录、维护容量缓存、在写入后触发增量刷新并以尽可能低的成本和尽可能高的可用性向管理面Admin提供RustFS 对象数据当前占用多少字节这一关键答案。本文基于该 crate 的官方文档与仓库源码完整讲解其数据模型、扫描算法、HybridCapacityManager 缓存刷新策略、脏盘dirty子集刷新机制、全部环境变量与公共 API帮助读者理解大型对象存储如何在大目录、慢盘与瞬时 I/O 抖动下仍能给出可用且尽量准确的容量结果。定位它不是 du而是对象数据占用计数器组件文档开篇就划清了边界rustfs-object-capacity并不负责测量整个文件系统的容量它的职责是回答一个更具体的问题——RustFS 对象数据当前占用了多少字节以及多少个文件。它需要在三个维度之间做实际取舍准确性扫描结果应尽量贴近真实占用新鲜度写入发生后缓存应尽快反映变化扫描成本在拥有数十万乃至数百万文件的目录上完整遍历的开销必须可控。因此该组件刻意采用精确前缀 采样溢出的策略来降低大目录扫描成本并在超时、遍历停滞或部分目录失败时返回可用的降级结果而不是让整个请求立刻失败。这一点贯穿了从扫描算法到缓存刷新的全部设计。模块布局模块文件职责src/lib.rs模块声明与对外再导出scan_used_capacity_disks、CapacityDiskRef、CapacityScanSummarysrc/types.rs定义扫描输入/输出类型CapacityDiskRef、内部CapacityScanResult、公开CapacityScanSummarysrc/scan.rs目录遍历、采样估算、超时/停滞检测、多盘并发扫描以及到CapacityUpdate的转换src/capacity_manager.rs缓存持有、写频率跟踪、singleflight 刷新协调、后台任务、脏盘子集合并逻辑与全局单例src/capacity_scope.rs跟踪一次写入影响了哪些盘token 绑定的本地作用域 全局脏盘注册表benches/capacity_scan.rs对公开扫描 API 的精确、采样、多盘三类基准场景从 Cargo.toml 可以看到该 crate 依赖rustfs-configconstants 特性、rustfs-io-metrics、rustfs-utils并使用tokio、futures、walkdir作为扫描与并发基础设施criterion作为基准框架。数据模型CapacityDiskRef一次扫描的最小输入单元pub struct CapacityDiskRef { pub endpoint: String, pub drive_path: String, }定义于 src/types.rsendpoint用于区分指标metrics和日志归属标识节点drive_path本地盘根路径即遍历的起点。CapacityScanSummary公开的扫描结果pub struct CapacityScanSummary { pub used_bytes: u64, pub file_count: usize, pub sampled_count: usize, pub is_estimated: bool, pub had_partial_errors: bool, pub scan_duration: Duration, }各字段含义对应 src/types.rsused_bytes计算或估算出的已用容量字节file_count遍历到的普通文件数量sampled_count越过阈值后参与采样的溢出文件数量is_estimated结果是否为估算值而非精确值had_partial_errors遍历过程中是否遇到局部错误但仍产出了结果scan_duration扫描总耗时。值得注意的是内部还存在一个更丰富的CapacityScanResult增加了timed_out、metadata_incomplete等内部状态仅 crate 内部使用公开的CapacityScanSummary通过FromCapacityScanResult转换而来供基准和外部工具消费。扫描算法精确前缀 采样溢出 超时降级目录扫描的核心在 src/scan.rs 的get_dir_size_async整体流程如下异步运行时保护将阻塞式目录遍历包进tokio::task::spawn_blocking避免阻塞 async runtime遍历用WalkDir递归目录树只统计普通文件跳过目录、符号链接与非普通文件精确阶段文件数低于DEFAULT_MAX_FILES_THRESHOLD默认200_000时逐个累加文件大小得到精确结果采样阶段超过阈值后保留前max_files_threshold个文件作为精确前缀之后每隔sample_rate个文件采样一个用采样字节数外推溢出部分进度检查周期性检查进度——若总耗时超过超时值尝试回退到采样估算若在stall_timeout内没有观察到文件进度判定遍历停滞局部失败容忍若部分目录条目或元数据读取失败只要至少有一块盘扫描成功就返回部分成功结果并标记had_partial_errors true。溢出部分的估算与外推采样外推的核心公式在 estimate_overflow_bytessampled_bytes * overflow_count / sampled_count实现上特意使用u128做中间乘法再钳制回u64::MAX。注释与测试如test_estimate_overflow_bytes_realistic_large_disk说明了一个重要的历史回归backlog#1012此前先在u64上做saturating_mul再除一旦乘积溢出分子被钉死在u64::MAX导致盘越大、采样数越多时报告值反而单调偏小约 6000 万文件、平均 1.75 MiB、约 105 TB 的场景会少报近一半。修复后的u128路径保持单调正确。测试还覆盖了sampled_count 0时用.max(1)防除零以及极端值钳制。多盘并发多盘扫描通过buffer_unordered并发执行见 calculate_data_dir_used_capacity_report当前硬编码的最大并发度是4块盘MAX_CAPACITY_SCAN_CONCURRENCY 4src/scan.rs单盘失败不会立即中止其他盘的扫描只要至少一块盘成功就返回部分结果否则返回错误All directories failed to calculate size。超时与估算回退超时不等于硬失败这是该 crate 最重要的设计意图之一src/scan.rs若已收集到足够的采样数据超时或停滞会产出一个估算结果timed_out true、is_estimated true只有在没有任何可用估算时才返回错误估算来源是两个独立估计器的合并已见文件外推保证至少覆盖观察到的数据与文件系统级statvfs用量覆盖遍历未见到的尾部。当两者都存在时取最大值它们是从相反两侧逼近同一真值的下界/上界只有文件系统用量时精确前缀仍作为硬性下限两者都不可用共享文件系统 无样本时返回None调用方传播原始超时错误。超时回退依赖mount_point_used_bytes的一个前提只有当drive_path是专用挂载点时才信任statvfs在共享文件系统上多个逻辑盘共用一个文件系统常见于开发部署statvfs会算入无关数据因此返回None回退到扫描估算。此外还有一层硬外墙钟预算outer_scan_budgetmax_timeout * 2且不低于 5 秒。因为ProgressMonitor的检查是协作式的——只在 walker 产出条目之间运行——一旦 stat/readdir 阻塞在濒死盘或挂起的 NFS 挂载上内层检查永远不会触发外层预算用tokio::time::timeout兜底超时后通过AtomicBool取消标志请求 walker 在下一个条目处退出把线程泄漏限制在单个卡死的系统调用上。相关测试test_outer_scan_budget_bounds、test_scan_dir_blocking_stops_when_cancelled验证了这一行为。动态超时ProgressMonitor支持按目录特征动态调整超时默认开启乘数1.0 sqrt(file_count) * 0.01 log10(avg_file_size) * 0.05上限 5 倍最终钳制在[min_timeout, max_timeout]区间内src/scan.rs。另外当时间预算过半而精确前缀尚未填满时会提前冻结阈值进入采样early_sampling避免慢盘在超时时刻sampled_count 0而丢失整个扫描。符号链接处理默认不跟随符号链接RUSTFS_CAPACITY_FOLLOW_SYMLINKSfalse启用后符号链接目标被计数环由 walker 的祖先环检测打破并施加最大跟随深度限制默认最大深度为3README 说明。代码注释进一步说明backlog#1018旧的SymlinkTracker从不影响遍历、报告的树深其实是链深且永远跟踪 0 字节因此被移除连同无效的RUSTFS_CAPACITY_MAX_SYMLINK_DEPTH开关扫描根自身会先做std::fs::canonicalize解析backlog#1015避免容器/k8s 下drive_path本身是符号链接时因follow_root_links(false)产生单个被跳过的符号链接条目 精确 0 字节基线的静默错误。测试test_scan_dir_blocking_resolves_symlink_root验证了该修复。元数据缺失的特殊豁免遍历对.rustfs.sys/tmp/.trash路径下NotFound类型的元数据读取失败做了特判is_tmp_trash_metadata_not_foundsrc/scan.rs临时回收目录中文件被并发清理导致的NotFound被当作正常情况忽略不算部分错误。容量缓存与刷新策略HybridCapacityManagerHybridCapacityManagersrc/capacity_manager.rs是整个 crate 的状态中心持有最新总容量值total_used上次刷新时间last_update文件数file_count估算/精确标志is_estimated是否降级degraded某次刷新存在部分盘失败数据来源DataSource逐盘缓存disk_cache及完整性标志disk_cache_complete脏盘集合dirty_disks记录标记时刻配合扫描起始时间做条件清除最近 60 秒的写入分桶write_bucketsDataSource结果来源枚举RealTime无缓存时前台实时刷新realtimeScheduled调度任务触发的后台刷新scheduledWriteTriggered写频率高且缓存足够旧时触发的刷新write_triggeredFallback所有扫描失败时回退到外部提供的盘已用容量fallback。对应实现见 capacity_manager.rs。刷新入口refresh_or_joincapacity_manager.rssingleflight 前台刷新。若已有刷新在运行调用者作为 joiner 订阅 watch 通道并等待共享结果spawn_refresh_if_neededcapacity_manager.rs后台刷新。若已有刷新在运行则跳过返回false否则tokio::spawn一个后台任务start_background_task启动两个后台任务——定时容量刷新任务与运行时摘要日志任务。Singleflight 语义refresh_or_join与spawn_refresh_if_needed通过watch通道协调刷新周期同一时刻只有一个 leader 实际执行刷新joiner 在释放互斥锁之前完成订阅保证 leader 即使瞬间完成也不会漏发通知joiner 等待有上限REFRESH_JOINER_WAIT_TIMEOUT默认 300 秒leader 卡死时退化为明确错误而非无限挂起刷新函数内部的 panic 被catch_unwind捕获并转换为错误避免与 leader 一同崩溃若 leader future 在完成前被 drop如管理请求被客户端断开取消RefreshLeaderGuard的Drop会重置 singleflight 状态running false并通知所有 joiner防止running永远为true导致后续刷新全部被阻塞。写入记录无锁热路径写频率跟踪对 PUT 响应路径的性能至关重要backlog#1315WriteRecord不再用 asyncRwLock而是把每秒写入桶打包进单个u64高 32 位为单调秒键、低 32 位为计数用无锁 CAS 更新计数器使用饱和运算桶键基于Instant单调时钟而非墙钟避免 NTP 时间回拨把近期桶标记为未来而静默抑制写入触发刷新。脏盘作用域Dirty Scope与子集刷新该 crate 最重要的优化之一是只刷新被写入弄脏的盘。作用域传播src/capacity_scope.rs 提供两种脏盘传播方式token 作用域调用方先用record_capacity_scope(token, scope)把一次写操作绑定到一组盘之后record_write_operation_with_scope_token(Some(token))消费该作用域并标记脏盘。token 注册表有 TTL300 秒、软上限2048与硬上限4096防护过期条目在消费时丢弃、同 token 的新作用域会合并或替换避免复活过期脏盘全局脏盘作用域record_global_dirty_scope(scope)直接把脏盘记入全局注册表管理器在get_dirty_disks()时用drain_global_dirty_scopes()排空并合并。全局注册表带代数generation优化写入侧在记录时返回当前代数只要代数未变后续写入可直接跳过注册表互斥锁backlog#1315只有排空drain才会推进代数强制重新标记排空空注册表不推进代数避免无谓的重标记。何时允许脏盘子集刷新只刷新脏盘仅在以下前提同时成立时才是安全的disk_cache_complete true即系统已完成至少一次无部分错误的完整刷新逐盘缓存已完全填充。决策逻辑select_scheduled_capacity_refresh若还没有聚合缓存执行全量刷新建立初始值已有聚合缓存但无脏盘时调度刷新保持IdleScheduledCapacityRefresh::Idle避免反复遍历未变化的盘有脏盘但逐盘缓存不完整时执行全量刷新子集无法安全合并脏盘子集选中后若选中盘数 全部盘数退化为全量刷新只有严格子集才做dirty_subset true的部分扫描写入侧会把 EC 集合的所有盘含远端对端都标记为脏但只有本地盘会被扫描和清除因此先通过retain_dirty_disks_within丢弃拓扑外的幽灵条目backlog#1020避免脏盘 gauge 永久非零。子集刷新后的合并规则成功的全量刷新per_disk整体替换disk_cache成功的脏盘子集刷新只更新受影响盘的逐盘条目总量总是从更新后的disk_cache重算而不是直接信任子集和——update_capacity会把 cluster 级聚合total_used/file_count/is_estimated与逐盘缓存对账防止脏盘子集的字节数被误报为整个集群总量若脏盘子集刷新报告部分错误该周期失败调用方回退到全量刷新恢复一致性达到时间预算的全量刷新可能发布一个估算聚合而不建立完整逐盘基线这个有界估算会确认clear早于扫描的脏标记而扫描期间新记录的标记保持 pending防止一条旧脏标记导致无限超时循环同时不把估算当作精确值处理脏盘清除是有条件的只有标记时刻早于本次扫描起始时刻的脏盘才会被清除scan_started_at对比扫描期间落地的写入会重新标记避免下一次子集刷新把过期字节当精确值提供backlog#1020 S19。与 RustFS 主流程的关系该 crate 只提供容量原语真正的 RustFS 集成位于 rustfs/src/capacity/service.rs。高层流程启动时调用init_capacity_management_for_local_disks()service.rs它通过all_local_disk()收集本地盘映射为CapacityDiskRef后调用start_background_tasks(disk_refs)Admin 已用容量查询先尝试HybridCapacityManager缓存get_cached_capacity_with_metrics同时记录 cache hit/miss 指标缓存足够新 → 直接返回缓存值缓存过期但可接受 → 提供过期值并触发后台刷新spawn_refresh_if_needed缓存非常旧且写频率高 → 请求阻塞在refresh_or_join前台刷新上should_block_on_refresh判断缓存年龄是否达到max_stale_age初始实时扫描失败 → 回退到外部提供的盘已用容量以Fallback来源入库。此外crates/ecstore/src/set_disk.rs 负责在对象写入、heal、数据迁移等流程中记录容量作用域让本 crate 得知哪些盘被影响。公共 API 与代码示例1. 直接扫描适用于基准测试、运维工具或隔离验证use rustfs_object_capacity::{CapacityDiskRef, scan_used_capacity_disks}; let disks vec![ CapacityDiskRef { endpoint: node-a.to_string(), drive_path: /data/disk1.to_string(), }, ]; let summary scan_used_capacity_disks(disks).await?; println!( used{} files{} estimated{}, summary.used_bytes, summary.file_count, summary.is_estimated ); # Ok::(), Boxdyn std::error::Error(())2. 使用全局管理器适用于服务内的缓存与刷新编排use rustfs_object_capacity::capacity_manager::{DataSource, get_capacity_manager}; let manager get_capacity_manager(); if let Some(cached) manager.get_capacity().await { println!(cached bytes{}, cached.total_used); } manager.record_write_operation().await; let _ manager .refresh_or_join(DataSource::Scheduled, || async { rustfs_object_capacity::scan::refresh_capacity_with_scope( vec![rustfs_object_capacity::CapacityDiskRef { endpoint: node-a.to_string(), drive_path: /data/disk1.to_string(), }], false, ) .await }) .await;全局单例由get_capacity_manager()通过OnceLock惰性初始化capacity_manager.rs测试场景则可用create_isolated_manager(config)创建独立实例避免污染全局。3. 传播脏盘作用域use rustfs_object_capacity::capacity_scope::{ CapacityScope, CapacityScopeDisk, record_capacity_scope, }; use rustfs_object_capacity::capacity_manager::get_capacity_manager; use uuid::Uuid; let token Uuid::new_v4(); record_capacity_scope( token, CapacityScope { disks: vec![CapacityScopeDisk { endpoint: node-a.to_string(), drive_path: /data/disk1.to_string(), }], }, ); get_capacity_manager() .record_write_operation_with_scope_token(Some(token)) .await;环境变量与默认值配置常量定义于 crates/config/src/constants/capacity.rs完整清单如下环境变量默认值说明RUSTFS_CAPACITY_SCHEDULED_INTERVAL600s定时刷新间隔RUSTFS_CAPACITY_WRITE_TRIGGER_DELAY30s写入后的防抖debounce延迟RUSTFS_CAPACITY_WRITE_FREQUENCY_THRESHOLD20最近 60 秒写频率阈值次/分钟RUSTFS_CAPACITY_FAST_UPDATE_THRESHOLD120s考虑快速刷新所需的最小缓存年龄RUSTFS_CAPACITY_MAX_FILES_THRESHOLD200000精确计数文件阈值RUSTFS_CAPACITY_STAT_TIMEOUT3sRUSTFS_DRIVE_TIMEOUT_PROFILEhigh_latency时为60s基础扫描超时RUSTFS_CAPACITY_SAMPLE_RATE200溢出文件采样间隔RUSTFS_CAPACITY_METRICS_INTERVAL600s运行时摘要指标输出间隔RUSTFS_CAPACITY_FOLLOW_SYMLINKSfalse是否跟随符号链接RUSTFS_CAPACITY_ENABLE_DYNAMIC_TIMEOUTtrue是否启用动态超时缩放RUSTFS_CAPACITY_MIN_TIMEOUT2s动态超时下界RUSTFS_CAPACITY_MAX_TIMEOUT15shigh_latency 配置下为60s动态超时上界RUSTFS_CAPACITY_STALL_TIMEOUT20s停滞检测阈值两点重要补充来自源码实现显式值优先于 drive-timeout profile显式设置RUSTFS_CAPACITY_STAT_TIMEOUT与RUSTFS_CAPACITY_MAX_TIMEOUT时它们优先于RUSTFS_DRIVE_TIMEOUT_PROFILE提供的默认值见 capacity_manager.rs 的capacity_timeout_profile_default非法值会被钳制回默认env_u64_at_least对小于最小合法值的配置如把阈值配成 0发出告警并回退默认backlog#1019 S11避免每个扫描都报 0 字节或永远失败的配置事故后台间隔被钳制在[1s, 30 天]防止 0 值 panictokio::time::interval或Instant Duration溢出。配置缓存注意事项在非测试构建中配置缓存在OnceLock之后环境变量实际上只在首次访问时读取一次运行期间更新RUSTFS_CAPACITY_*通常不会立即生效可靠地应用配置变更通常需要重启进程。测试构建不缓存以支持temp_env变量注入测试。指标Metrics该 crate 向rustfs-io-metrics::capacity_metrics上报多族指标包括缓存命中/未命中/服务状态cache hit / miss / served state刷新进行中inflight、joiner 数量、成功/失败结果当前容量字节数current capacity bytes写频率write frequency脏盘数量dirty-disk count逐盘扫描耗时、采样模式、超时回退、停滞检测与符号链接统计。例如扫描侧会调用record_capacity_scan_disk、record_capacity_scan_mode、record_capacity_scan_sampling、record_capacity_timeout_fallback、record_capacity_dynamic_timeout管理器侧调用record_capacity_cache_hit/miss、record_capacity_refresh_inflight/joiner/result、record_capacity_current_bytes、record_capacity_write_operation、record_capacity_dirty_disk_count、record_capacity_degraded_reading等。因此该 crate 既是容量计算组件也是运行时可观测数据的重要生产者。基准测试运行基准套件cargo bench -p rustfs-object-capacity --bench capacity_scan当前基准场景对应 benches/capacity_scan.rscapacity_scan_exact单盘精确扫描 1 万个 4 KiB 文件capacity_scan_sampled单盘扫描 202,048 个文件越过阈值触发采样估算文件大小 1 字节以便快速构造capacity_scan_multi_disk四盘混合目录规模4000/6000/8000/10000 个文件的精确扫描。三个场景均通过scan_used_capacity_disks走与 Admin 容量查询相同的扫描路径而非独立的简化实现因此基准结果能真实反映生产路径的性能。已知边界与权衡它累加 RustFS 对象数据目录下的文件大小不是文件系统级du的完整替代品估算模式优先保证有界成本与可用结果而非单次运行的完美精度脏盘子集刷新只有在完整逐盘缓存建立后才安全部分错误刻意返回降级结果以提升可用性因此调用方必须关注had_partial_errors标志符号链接跟随默认关闭以换取安全性与确定性溢出估算基于采样外推超大盘亿级文件场景依赖u128中间运算保证单调性。相关源码入口crates/object-capacity/src/lib.rscrates/object-capacity/src/scan.rscrates/object-capacity/src/capacity_manager.rscrates/object-capacity/src/capacity_scope.rscrates/object-capacity/src/types.rscrates/object-capacity/benches/capacity_scan.rsrustfs/src/capacity/service.rscrates/config/src/constants/capacity.rs小结rustfs-object-capacity用一套精确前缀 采样外推 动态超时 超时回退估算 部分错误降级的组合拳在超大目录与慢盘场景下把容量扫描成本控制在有界范围内再用HybridCapacityManager的定时/写触发/前台/后台四类刷新入口、singleflight 协调、watch 通道结果共享与脏盘子集合并把已用容量这一高代价计算变成低延迟、高可用的缓存服务。理解它的取舍逻辑对于在 RustFS 或同类对象存储上规划容量监控、诊断慢容量查询、以及合理调优RUSTFS_CAPACITY_*环境变量都极具参考价值。【免费下载链接】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），仅供参考 RustFS 对象容量统计组件 rustfs-object-capacity 深度解析：扫描、采样与混合缓存刷新机制
RustFS 对象容量统计组件 rustfs-object-capacity 深度解析扫描、采样与混合缓存刷新机制【免费下载链接】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导读rustfs-object-capacity是 RustFS 对象存储中负责已用容量统计的核心组件它扫描本地数据盘目录、维护容量缓存、在写入后触发增量刷新并以尽可能低的成本和尽可能高的可用性向管理面Admin提供RustFS 对象数据当前占用多少字节这一关键答案。本文基于该 crate 的官方文档与仓库源码完整讲解其数据模型、扫描算法、HybridCapacityManager 缓存刷新策略、脏盘dirty子集刷新机制、全部环境变量与公共 API帮助读者理解大型对象存储如何在大目录、慢盘与瞬时 I/O 抖动下仍能给出可用且尽量准确的容量结果。定位它不是 du而是对象数据占用计数器组件文档开篇就划清了边界rustfs-object-capacity并不负责测量整个文件系统的容量它的职责是回答一个更具体的问题——RustFS 对象数据当前占用了多少字节以及多少个文件。它需要在三个维度之间做实际取舍准确性扫描结果应尽量贴近真实占用新鲜度写入发生后缓存应尽快反映变化扫描成本在拥有数十万乃至数百万文件的目录上完整遍历的开销必须可控。因此该组件刻意采用精确前缀 采样溢出的策略来降低大目录扫描成本并在超时、遍历停滞或部分目录失败时返回可用的降级结果而不是让整个请求立刻失败。这一点贯穿了从扫描算法到缓存刷新的全部设计。模块布局模块文件职责src/lib.rs模块声明与对外再导出scan_used_capacity_disks、CapacityDiskRef、CapacityScanSummarysrc/types.rs定义扫描输入/输出类型CapacityDiskRef、内部CapacityScanResult、公开CapacityScanSummarysrc/scan.rs目录遍历、采样估算、超时/停滞检测、多盘并发扫描以及到CapacityUpdate的转换src/capacity_manager.rs缓存持有、写频率跟踪、singleflight 刷新协调、后台任务、脏盘子集合并逻辑与全局单例src/capacity_scope.rs跟踪一次写入影响了哪些盘token 绑定的本地作用域 全局脏盘注册表benches/capacity_scan.rs对公开扫描 API 的精确、采样、多盘三类基准场景从 Cargo.toml 可以看到该 crate 依赖rustfs-configconstants 特性、rustfs-io-metrics、rustfs-utils并使用tokio、futures、walkdir作为扫描与并发基础设施criterion作为基准框架。数据模型CapacityDiskRef一次扫描的最小输入单元pub struct CapacityDiskRef { pub endpoint: String, pub drive_path: String, }定义于 src/types.rsendpoint用于区分指标metrics和日志归属标识节点drive_path本地盘根路径即遍历的起点。CapacityScanSummary公开的扫描结果pub struct CapacityScanSummary { pub used_bytes: u64, pub file_count: usize, pub sampled_count: usize, pub is_estimated: bool, pub had_partial_errors: bool, pub scan_duration: Duration, }各字段含义对应 src/types.rsused_bytes计算或估算出的已用容量字节file_count遍历到的普通文件数量sampled_count越过阈值后参与采样的溢出文件数量is_estimated结果是否为估算值而非精确值had_partial_errors遍历过程中是否遇到局部错误但仍产出了结果scan_duration扫描总耗时。值得注意的是内部还存在一个更丰富的CapacityScanResult增加了timed_out、metadata_incomplete等内部状态仅 crate 内部使用公开的CapacityScanSummary通过FromCapacityScanResult转换而来供基准和外部工具消费。扫描算法精确前缀 采样溢出 超时降级目录扫描的核心在 src/scan.rs 的get_dir_size_async整体流程如下异步运行时保护将阻塞式目录遍历包进tokio::task::spawn_blocking避免阻塞 async runtime遍历用WalkDir递归目录树只统计普通文件跳过目录、符号链接与非普通文件精确阶段文件数低于DEFAULT_MAX_FILES_THRESHOLD默认200_000时逐个累加文件大小得到精确结果采样阶段超过阈值后保留前max_files_threshold个文件作为精确前缀之后每隔sample_rate个文件采样一个用采样字节数外推溢出部分进度检查周期性检查进度——若总耗时超过超时值尝试回退到采样估算若在stall_timeout内没有观察到文件进度判定遍历停滞局部失败容忍若部分目录条目或元数据读取失败只要至少有一块盘扫描成功就返回部分成功结果并标记had_partial_errors true。溢出部分的估算与外推采样外推的核心公式在 estimate_overflow_bytessampled_bytes * overflow_count / sampled_count实现上特意使用u128做中间乘法再钳制回u64::MAX。注释与测试如test_estimate_overflow_bytes_realistic_large_disk说明了一个重要的历史回归backlog#1012此前先在u64上做saturating_mul再除一旦乘积溢出分子被钉死在u64::MAX导致盘越大、采样数越多时报告值反而单调偏小约 6000 万文件、平均 1.75 MiB、约 105 TB 的场景会少报近一半。修复后的u128路径保持单调正确。测试还覆盖了sampled_count 0时用.max(1)防除零以及极端值钳制。多盘并发多盘扫描通过buffer_unordered并发执行见 calculate_data_dir_used_capacity_report当前硬编码的最大并发度是4块盘MAX_CAPACITY_SCAN_CONCURRENCY 4src/scan.rs单盘失败不会立即中止其他盘的扫描只要至少一块盘成功就返回部分结果否则返回错误All directories failed to calculate size。超时与估算回退超时不等于硬失败这是该 crate 最重要的设计意图之一src/scan.rs若已收集到足够的采样数据超时或停滞会产出一个估算结果timed_out true、is_estimated true只有在没有任何可用估算时才返回错误估算来源是两个独立估计器的合并已见文件外推保证至少覆盖观察到的数据与文件系统级statvfs用量覆盖遍历未见到的尾部。当两者都存在时取最大值它们是从相反两侧逼近同一真值的下界/上界只有文件系统用量时精确前缀仍作为硬性下限两者都不可用共享文件系统 无样本时返回None调用方传播原始超时错误。超时回退依赖mount_point_used_bytes的一个前提只有当drive_path是专用挂载点时才信任statvfs在共享文件系统上多个逻辑盘共用一个文件系统常见于开发部署statvfs会算入无关数据因此返回None回退到扫描估算。此外还有一层硬外墙钟预算outer_scan_budgetmax_timeout * 2且不低于 5 秒。因为ProgressMonitor的检查是协作式的——只在 walker 产出条目之间运行——一旦 stat/readdir 阻塞在濒死盘或挂起的 NFS 挂载上内层检查永远不会触发外层预算用tokio::time::timeout兜底超时后通过AtomicBool取消标志请求 walker 在下一个条目处退出把线程泄漏限制在单个卡死的系统调用上。相关测试test_outer_scan_budget_bounds、test_scan_dir_blocking_stops_when_cancelled验证了这一行为。动态超时ProgressMonitor支持按目录特征动态调整超时默认开启乘数1.0 sqrt(file_count) * 0.01 log10(avg_file_size) * 0.05上限 5 倍最终钳制在[min_timeout, max_timeout]区间内src/scan.rs。另外当时间预算过半而精确前缀尚未填满时会提前冻结阈值进入采样early_sampling避免慢盘在超时时刻sampled_count 0而丢失整个扫描。符号链接处理默认不跟随符号链接RUSTFS_CAPACITY_FOLLOW_SYMLINKSfalse启用后符号链接目标被计数环由 walker 的祖先环检测打破并施加最大跟随深度限制默认最大深度为3README 说明。代码注释进一步说明backlog#1018旧的SymlinkTracker从不影响遍历、报告的树深其实是链深且永远跟踪 0 字节因此被移除连同无效的RUSTFS_CAPACITY_MAX_SYMLINK_DEPTH开关扫描根自身会先做std::fs::canonicalize解析backlog#1015避免容器/k8s 下drive_path本身是符号链接时因follow_root_links(false)产生单个被跳过的符号链接条目 精确 0 字节基线的静默错误。测试test_scan_dir_blocking_resolves_symlink_root验证了该修复。元数据缺失的特殊豁免遍历对.rustfs.sys/tmp/.trash路径下NotFound类型的元数据读取失败做了特判is_tmp_trash_metadata_not_foundsrc/scan.rs临时回收目录中文件被并发清理导致的NotFound被当作正常情况忽略不算部分错误。容量缓存与刷新策略HybridCapacityManagerHybridCapacityManagersrc/capacity_manager.rs是整个 crate 的状态中心持有最新总容量值total_used上次刷新时间last_update文件数file_count估算/精确标志is_estimated是否降级degraded某次刷新存在部分盘失败数据来源DataSource逐盘缓存disk_cache及完整性标志disk_cache_complete脏盘集合dirty_disks记录标记时刻配合扫描起始时间做条件清除最近 60 秒的写入分桶write_bucketsDataSource结果来源枚举RealTime无缓存时前台实时刷新realtimeScheduled调度任务触发的后台刷新scheduledWriteTriggered写频率高且缓存足够旧时触发的刷新write_triggeredFallback所有扫描失败时回退到外部提供的盘已用容量fallback。对应实现见 capacity_manager.rs。刷新入口refresh_or_joincapacity_manager.rssingleflight 前台刷新。若已有刷新在运行调用者作为 joiner 订阅 watch 通道并等待共享结果spawn_refresh_if_neededcapacity_manager.rs后台刷新。若已有刷新在运行则跳过返回false否则tokio::spawn一个后台任务start_background_task启动两个后台任务——定时容量刷新任务与运行时摘要日志任务。Singleflight 语义refresh_or_join与spawn_refresh_if_needed通过watch通道协调刷新周期同一时刻只有一个 leader 实际执行刷新joiner 在释放互斥锁之前完成订阅保证 leader 即使瞬间完成也不会漏发通知joiner 等待有上限REFRESH_JOINER_WAIT_TIMEOUT默认 300 秒leader 卡死时退化为明确错误而非无限挂起刷新函数内部的 panic 被catch_unwind捕获并转换为错误避免与 leader 一同崩溃若 leader future 在完成前被 drop如管理请求被客户端断开取消RefreshLeaderGuard的Drop会重置 singleflight 状态running false并通知所有 joiner防止running永远为true导致后续刷新全部被阻塞。写入记录无锁热路径写频率跟踪对 PUT 响应路径的性能至关重要backlog#1315WriteRecord不再用 asyncRwLock而是把每秒写入桶打包进单个u64高 32 位为单调秒键、低 32 位为计数用无锁 CAS 更新计数器使用饱和运算桶键基于Instant单调时钟而非墙钟避免 NTP 时间回拨把近期桶标记为未来而静默抑制写入触发刷新。脏盘作用域Dirty Scope与子集刷新该 crate 最重要的优化之一是只刷新被写入弄脏的盘。作用域传播src/capacity_scope.rs 提供两种脏盘传播方式token 作用域调用方先用record_capacity_scope(token, scope)把一次写操作绑定到一组盘之后record_write_operation_with_scope_token(Some(token))消费该作用域并标记脏盘。token 注册表有 TTL300 秒、软上限2048与硬上限4096防护过期条目在消费时丢弃、同 token 的新作用域会合并或替换避免复活过期脏盘全局脏盘作用域record_global_dirty_scope(scope)直接把脏盘记入全局注册表管理器在get_dirty_disks()时用drain_global_dirty_scopes()排空并合并。全局注册表带代数generation优化写入侧在记录时返回当前代数只要代数未变后续写入可直接跳过注册表互斥锁backlog#1315只有排空drain才会推进代数强制重新标记排空空注册表不推进代数避免无谓的重标记。何时允许脏盘子集刷新只刷新脏盘仅在以下前提同时成立时才是安全的disk_cache_complete true即系统已完成至少一次无部分错误的完整刷新逐盘缓存已完全填充。决策逻辑select_scheduled_capacity_refresh若还没有聚合缓存执行全量刷新建立初始值已有聚合缓存但无脏盘时调度刷新保持IdleScheduledCapacityRefresh::Idle避免反复遍历未变化的盘有脏盘但逐盘缓存不完整时执行全量刷新子集无法安全合并脏盘子集选中后若选中盘数 全部盘数退化为全量刷新只有严格子集才做dirty_subset true的部分扫描写入侧会把 EC 集合的所有盘含远端对端都标记为脏但只有本地盘会被扫描和清除因此先通过retain_dirty_disks_within丢弃拓扑外的幽灵条目backlog#1020避免脏盘 gauge 永久非零。子集刷新后的合并规则成功的全量刷新per_disk整体替换disk_cache成功的脏盘子集刷新只更新受影响盘的逐盘条目总量总是从更新后的disk_cache重算而不是直接信任子集和——update_capacity会把 cluster 级聚合total_used/file_count/is_estimated与逐盘缓存对账防止脏盘子集的字节数被误报为整个集群总量若脏盘子集刷新报告部分错误该周期失败调用方回退到全量刷新恢复一致性达到时间预算的全量刷新可能发布一个估算聚合而不建立完整逐盘基线这个有界估算会确认clear早于扫描的脏标记而扫描期间新记录的标记保持 pending防止一条旧脏标记导致无限超时循环同时不把估算当作精确值处理脏盘清除是有条件的只有标记时刻早于本次扫描起始时刻的脏盘才会被清除scan_started_at对比扫描期间落地的写入会重新标记避免下一次子集刷新把过期字节当精确值提供backlog#1020 S19。与 RustFS 主流程的关系该 crate 只提供容量原语真正的 RustFS 集成位于 rustfs/src/capacity/service.rs。高层流程启动时调用init_capacity_management_for_local_disks()service.rs它通过all_local_disk()收集本地盘映射为CapacityDiskRef后调用start_background_tasks(disk_refs)Admin 已用容量查询先尝试HybridCapacityManager缓存get_cached_capacity_with_metrics同时记录 cache hit/miss 指标缓存足够新 → 直接返回缓存值缓存过期但可接受 → 提供过期值并触发后台刷新spawn_refresh_if_needed缓存非常旧且写频率高 → 请求阻塞在refresh_or_join前台刷新上should_block_on_refresh判断缓存年龄是否达到max_stale_age初始实时扫描失败 → 回退到外部提供的盘已用容量以Fallback来源入库。此外crates/ecstore/src/set_disk.rs 负责在对象写入、heal、数据迁移等流程中记录容量作用域让本 crate 得知哪些盘被影响。公共 API 与代码示例1. 直接扫描适用于基准测试、运维工具或隔离验证use rustfs_object_capacity::{CapacityDiskRef, scan_used_capacity_disks}; let disks vec![ CapacityDiskRef { endpoint: node-a.to_string(), drive_path: /data/disk1.to_string(), }, ]; let summary scan_used_capacity_disks(disks).await?; println!( used{} files{} estimated{}, summary.used_bytes, summary.file_count, summary.is_estimated ); # Ok::(), Boxdyn std::error::Error(())2. 使用全局管理器适用于服务内的缓存与刷新编排use rustfs_object_capacity::capacity_manager::{DataSource, get_capacity_manager}; let manager get_capacity_manager(); if let Some(cached) manager.get_capacity().await { println!(cached bytes{}, cached.total_used); } manager.record_write_operation().await; let _ manager .refresh_or_join(DataSource::Scheduled, || async { rustfs_object_capacity::scan::refresh_capacity_with_scope( vec![rustfs_object_capacity::CapacityDiskRef { endpoint: node-a.to_string(), drive_path: /data/disk1.to_string(), }], false, ) .await }) .await;全局单例由get_capacity_manager()通过OnceLock惰性初始化capacity_manager.rs测试场景则可用create_isolated_manager(config)创建独立实例避免污染全局。3. 传播脏盘作用域use rustfs_object_capacity::capacity_scope::{ CapacityScope, CapacityScopeDisk, record_capacity_scope, }; use rustfs_object_capacity::capacity_manager::get_capacity_manager; use uuid::Uuid; let token Uuid::new_v4(); record_capacity_scope( token, CapacityScope { disks: vec![CapacityScopeDisk { endpoint: node-a.to_string(), drive_path: /data/disk1.to_string(), }], }, ); get_capacity_manager() .record_write_operation_with_scope_token(Some(token)) .await;环境变量与默认值配置常量定义于 crates/config/src/constants/capacity.rs完整清单如下环境变量默认值说明RUSTFS_CAPACITY_SCHEDULED_INTERVAL600s定时刷新间隔RUSTFS_CAPACITY_WRITE_TRIGGER_DELAY30s写入后的防抖debounce延迟RUSTFS_CAPACITY_WRITE_FREQUENCY_THRESHOLD20最近 60 秒写频率阈值次/分钟RUSTFS_CAPACITY_FAST_UPDATE_THRESHOLD120s考虑快速刷新所需的最小缓存年龄RUSTFS_CAPACITY_MAX_FILES_THRESHOLD200000精确计数文件阈值RUSTFS_CAPACITY_STAT_TIMEOUT3sRUSTFS_DRIVE_TIMEOUT_PROFILEhigh_latency时为60s基础扫描超时RUSTFS_CAPACITY_SAMPLE_RATE200溢出文件采样间隔RUSTFS_CAPACITY_METRICS_INTERVAL600s运行时摘要指标输出间隔RUSTFS_CAPACITY_FOLLOW_SYMLINKSfalse是否跟随符号链接RUSTFS_CAPACITY_ENABLE_DYNAMIC_TIMEOUTtrue是否启用动态超时缩放RUSTFS_CAPACITY_MIN_TIMEOUT2s动态超时下界RUSTFS_CAPACITY_MAX_TIMEOUT15shigh_latency 配置下为60s动态超时上界RUSTFS_CAPACITY_STALL_TIMEOUT20s停滞检测阈值两点重要补充来自源码实现显式值优先于 drive-timeout profile显式设置RUSTFS_CAPACITY_STAT_TIMEOUT与RUSTFS_CAPACITY_MAX_TIMEOUT时它们优先于RUSTFS_DRIVE_TIMEOUT_PROFILE提供的默认值见 capacity_manager.rs 的capacity_timeout_profile_default非法值会被钳制回默认env_u64_at_least对小于最小合法值的配置如把阈值配成 0发出告警并回退默认backlog#1019 S11避免每个扫描都报 0 字节或永远失败的配置事故后台间隔被钳制在[1s, 30 天]防止 0 值 panictokio::time::interval或Instant Duration溢出。配置缓存注意事项在非测试构建中配置缓存在OnceLock之后环境变量实际上只在首次访问时读取一次运行期间更新RUSTFS_CAPACITY_*通常不会立即生效可靠地应用配置变更通常需要重启进程。测试构建不缓存以支持temp_env变量注入测试。指标Metrics该 crate 向rustfs-io-metrics::capacity_metrics上报多族指标包括缓存命中/未命中/服务状态cache hit / miss / served state刷新进行中inflight、joiner 数量、成功/失败结果当前容量字节数current capacity bytes写频率write frequency脏盘数量dirty-disk count逐盘扫描耗时、采样模式、超时回退、停滞检测与符号链接统计。例如扫描侧会调用record_capacity_scan_disk、record_capacity_scan_mode、record_capacity_scan_sampling、record_capacity_timeout_fallback、record_capacity_dynamic_timeout管理器侧调用record_capacity_cache_hit/miss、record_capacity_refresh_inflight/joiner/result、record_capacity_current_bytes、record_capacity_write_operation、record_capacity_dirty_disk_count、record_capacity_degraded_reading等。因此该 crate 既是容量计算组件也是运行时可观测数据的重要生产者。基准测试运行基准套件cargo bench -p rustfs-object-capacity --bench capacity_scan当前基准场景对应 benches/capacity_scan.rscapacity_scan_exact单盘精确扫描 1 万个 4 KiB 文件capacity_scan_sampled单盘扫描 202,048 个文件越过阈值触发采样估算文件大小 1 字节以便快速构造capacity_scan_multi_disk四盘混合目录规模4000/6000/8000/10000 个文件的精确扫描。三个场景均通过scan_used_capacity_disks走与 Admin 容量查询相同的扫描路径而非独立的简化实现因此基准结果能真实反映生产路径的性能。已知边界与权衡它累加 RustFS 对象数据目录下的文件大小不是文件系统级du的完整替代品估算模式优先保证有界成本与可用结果而非单次运行的完美精度脏盘子集刷新只有在完整逐盘缓存建立后才安全部分错误刻意返回降级结果以提升可用性因此调用方必须关注had_partial_errors标志符号链接跟随默认关闭以换取安全性与确定性溢出估算基于采样外推超大盘亿级文件场景依赖u128中间运算保证单调性。相关源码入口crates/object-capacity/src/lib.rscrates/object-capacity/src/scan.rscrates/object-capacity/src/capacity_manager.rscrates/object-capacity/src/capacity_scope.rscrates/object-capacity/src/types.rscrates/object-capacity/benches/capacity_scan.rsrustfs/src/capacity/service.rscrates/config/src/constants/capacity.rs小结rustfs-object-capacity用一套精确前缀 采样外推 动态超时 超时回退估算 部分错误降级的组合拳在超大目录与慢盘场景下把容量扫描成本控制在有界范围内再用HybridCapacityManager的定时/写触发/前台/后台四类刷新入口、singleflight 协调、watch 通道结果共享与脏盘子集合并把已用容量这一高代价计算变成低延迟、高可用的缓存服务。理解它的取舍逻辑对于在 RustFS 或同类对象存储上规划容量监控、诊断慢容量查询、以及合理调优RUSTFS_CAPACITY_*环境变量都极具参考价值。【免费下载链接】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），仅供参考