企业官网建设流程全解析

RustFS 架构治理实战：obs 与 ECStore 的依赖清单、边界约束与解耦抽取计划

【免费下载链接】rustfs🚀2.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

本篇技术指南围绕 docs/architecture/obs-ecstore-dependency-inventory.md 展开，讲清 RustFS 可观测性 crate（rustfs-obs）对存储引擎 crate（rustfs-ecstore）这一"已知架构限制"是如何被收敛、审计和规划解耦的。读完本文，你将掌握：依赖清单（Dependency Inventory）的三类耦合分类法、唯一边界文件 crates/obs/src/metrics/storage_api.rs 的别名导入机制与快照 DTO 投影模式、CI 架构守卫脚本的强制规则，以及五步抽取计划（Extraction Plan）的落地路径。这些内容对任何需要在大型多 crate 项目中管理跨层依赖边界的开发者都有直接参考价值。

背景：为什么rustfs-obs依赖 ECStore 是一个"已知架构限制"

rustfs-obs是 RustFS 的可观测性 crate，提供指标（metrics）、日志与链路追踪能力。从 crates/obs/Cargo.toml 可以看到，它对rustfs-ecstore的依赖被明确注释为已知限制：

# NOTE: This dependency on rustfs-ecstore is a known architectural limitation. # The obs crate imports types from ecstore for metrics collection. # Breaking this dependency would require defining traits in obs and # implementing them in ecstore, which is a significant refactoring. rustfs-ecstore = { workspace = true } rustfs-storage-api = { workspace = true }

问题的本质是：可观测性层为了采集指标（存储容量、数据用量、配额、压缩总量、桶带宽、复制统计等），不得不读取存储引擎内部的全局运行时状态和计算结果。若不设约束，rustfs-obs内各处的 collector 会各自use rustfs_ecstore::...，形成多点渗透，未来无法整体替换。

关联文档给出的核心治理策略只有一句话：所有直接引用收敛到一个边界文件，使该依赖未来可以被 provider traits 替换而无需触碰 collectors。这份文档正是该策略的"台账"（inventory），并在变更时作为必须同步更新的契约。

依赖清单（Dependency Inventory）：三类耦合分类法

文档明确规定：权威清单不在文档中复制，而是以 crates/obs/src/metrics/storage_api.rs 顶部的use块为唯一事实来源（source of truth），每个导入归入以下三类耦合之一：

文档的结论是：collectors 只消费别名和 obs 本地 DTO。在三个类别都具备替代契约与编译覆盖之前，从 crates/obs/Cargo.toml 移除rustfs-ecstore是不安全的。

边界文件长什么样：逐一对照 import 块

从源码结构看，边界文件顶部（第 18–38 行）的导入块与上述分类一一对应：

// —— 类型耦合 —— pub(crate) use rustfs_ecstore::api::bucket::bandwidth::monitor::Monitor as ObsBucketBandwidthMonitor; pub(crate) use rustfs_ecstore::api::bucket::metadata_sys::get_quota_config as obs_get_quota_config; pub(crate) use rustfs_ecstore::api::capacity::{ get_total_usable_capacity as obs_get_total_usable_capacity, get_total_usable_capacity_free as obs_get_total_usable_capacity_free, }; pub(crate) use rustfs_ecstore::api::compression::is_disk_compression_enabled as obs_is_disk_compression_enabled; pub(crate) use rustfs_ecstore::api::data_usage::load_admin_data_usage_from_backend_cached as obs_load_data_usage_from_backend; pub(crate) use rustfs_ecstore::api::data_usage::load_compression_total_from_memory as obs_load_compression_total_from_memory; pub(crate) use rustfs_ecstore::api::error::Result as ObsEcstoreResult; pub(crate) use rustfs_ecstore::api::storage::ECStore as ObsStore; // —— 运行时句柄耦合（进程级全局句柄解析）—— pub(crate) use rustfs_ecstore::api::runtime::{ bucket_monitor as obs_get_global_bucket_monitor, expiry_state_handle as obs_expiry_state_handle, object_store_handle as obs_resolve_object_store_handle, transition_state_handle as obs_transition_state_handle, }; // —— 行为耦合：复制统计（其输出被投影为 obs 本地 DTO）—— use rustfs_ecstore::api::bucket::replication::{ BucketReplicationStats as SourceBucketReplicationStats, DurableMrfBucketBacklog, DurableMrfTargetBacklog, MrfBucketBacklogObservability, RuntimeReplicationTargetBacklog, durable_mrf_backlog_summary_snapshot, durable_mrf_target_backlog_snapshot, get_global_replication_stats, mrf_backlog_observability_snapshot, }; // —— storage-api trait（用于方法解析）—— use rustfs_storage_api as storage_contracts;

注意两个命名约定：所有从 ECStore 引出的类型与函数都被改名为Obs*/obs_*前缀别名。这样即使将来实现方从 ECStore 换成 provider trait 适配器，obs 内部其他文件无需改动任何一处引用。

边界文件末尾还有一个显式的再导出块（第 779–790 行），把全部别名打包成storage_api::metrics子模块，供 obs 内部消费：

pub(crate) mod metrics { pub(crate) use super::storage_contracts::{BucketOperations, BucketOptions, StorageAdminApi}; pub(crate) use super::{ ObsBucketBandwidthMonitor, ObsBucketReplicationStatsSnapshot, ObsEcstoreResult, ObsStore, obs_bucket_replication_stats_snapshot, obs_expiry_state_handle, obs_get_global_bucket_monitor, obs_get_quota_config, obs_get_total_usable_capacity, obs_get_total_usable_capacity_free, obs_is_disk_compression_enabled, obs_load_compression_total_from_memory, obs_load_data_usage_from_backend, obs_on_demand_migration_backfill_snapshot, obs_on_demand_migration_snapshot, obs_replication_site_stats_snapshot, obs_resolve_object_store_handle, obs_transition_state_handle, }; }

crates/obs/src/metrics/mod.rs 随即以pub(crate) use storage_api::metrics::{...}把这组别名重新暴露给 collector 层，形成"ECStore → 边界文件别名 → obs 内部统一再导出"的单向通路。

行为耦合的投影模式：ECStore 数据如何变成 obs 本地 DTO

"行为耦合"一类的关键不在于别名，而在于投影（projection）：ECStore 拥有的计算结果先被转换成 obs 自己拥有的 DTO 结构体，collectors 从此只见 DTO、不见 ECStore 类型。边界文件中定义了一组Obs*Snapshot结构体，例如：

• ObsBucketReplicationStatsSnapshot：桶级复制统计的完整快照，含sent_bytes/sent_count、total_failed_*、last_min_failed_*、last_hour_failed_*、代理请求（proxied_get/head/put/tagging）计数、resync 计数、运行时与持久化（durable MRf）积压量，以及每目标明细targets: Vec<ObsBucketReplicationTargetStatsSnapshot>与target_backlogs；
• ObsBucketReplicationTargetStatsSnapshot：单目标带宽上限/当前带宽、延迟、发送量、失败量；
• ObsReplicationSiteStatsSnapshot：站点级活跃 worker、队列深度、传输速率等聚合值。

投影入口是异步辅助函数obs_bucket_replication_stats_snapshot()：它调用 ECStore 侧的get_global_replication_stats()、durable_mrf_backlog_summary_snapshot()、mrf_backlog_observability_snapshot()等（这些原始句柄与方法名只允许出现在该文件中），把多个来源按桶名归并后组装成Vec<ObsBucketReplicationStatsSnapshot>。值得注意的工程细节包括：

• 数值转换统一走i64_to_u64_floor_zero（负值截断为 0）与saturating_add，避免指标路径出现 panic；
• 桶名集合由"全部桶统计 + 仅 durable 桶 + 仅 MRF 可观测桶 + 仅运行时目标桶"做差集并集，保证任一来源独有的桶也不会丢失；
• 当obs_resolve_object_store_handle()返回None（存储不可用）时，durable/MRF 相关快照退化为Default，指标路径不中断。

同一文件中的obs_replication_site_stats_snapshot()则从站点指标中聚合出"集群级传输速率 = 所有桶目标xfer_rate_lrg.avg + xfer_rate_sml.avg之和"这类保持既有指标语义的聚合值——这些聚合逻辑属于 ECStore 拥有、投影到 obs 的"行为"，正是行为耦合的典型案例。

Collector 侧如何消费

指标采集入口 crates/obs/src/metrics/stats_collector.rs 只导入边界再导出层的别名，例如：

use super::metrics::{ obs_bucket_replication_stats_snapshot, obs_get_quota_config, obs_get_total_usable_capacity, obs_get_total_usable_capacity_free, obs_load_compression_total_from_memory, obs_load_data_usage_from_backend, ... }; // 例如： let data_usage = obs_load_data_usage_from_backend(store).await?; let total = usize_to_u64_saturating(obs_get_total_usable_capacity(&storage_info.disks, storage_info));

[crates/obs/src/metrics/runtime_sources.rs](https://link.gitcode.com/i/1805314cb39357c519ddeff0a95aae60)同理，通过bucket_monitor_handle() -> Option<Arc<ObsBucketBandwidthMonitor>>拿到桶带宽监控器句柄，而不直接触碰rustfs_ecstore::api::runtime。这就是文档所说"collectors 只消费别名和 obs 本地 DTO"的完整证据链。

边界文件自带聚焦测试

文件内#[cfg(test)] mod tests覆盖了投影逻辑的语义，可作为未来替换实现时的行为基准：

• on_demand_migration_callbacks_supply_runtime_snapshots：验证register_on_demand_migration_metrics_source的OnceLock回调注册与快照读取；
• obs_replication_numeric_conversions_floor_negative_values：负值归零语义；
• replication_backlog_count_*：失败目标 + 当前队列的积压合计、负值截断、既有失败积压语义；
• bucket_replication_runtime_snapshot_maps_target_flow_fields_from_source/bucket_replication_snapshot_maps_runtime_and_durable_backlog：字段级映射正确性（含 target 级带宽、延迟、发送量与失败窗口）；
• durable-only、MRF-only、MRF 不可用等退化场景的快照形态。

这些测试意味着：即便实现方从 ECStore 换成 provider trait，只要 DTO 字段映射行为不变，测试即可作为编译与行为双重覆盖。

抽取计划（Extraction Plan）：五步解耦路线

文档给出的抽取计划逐条继承了"先立契约、后换实现、最后摘依赖"的顺序：

1. 所有对 ECStore 与 storage-api 的直接导入，持续集中收敛在 crates/obs/src/metrics/storage_api.rs 中；
2. 持续把 ECStore 的数据用量与复制统计投影为 obs 本地 DTO，再交给 collectors 消费（当前已实现）；
3. 在 obs 侧引入由 obs 拥有的 provider trait，覆盖：存储信息（storage info）、桶信息（bucket info）、配额（quota）、数据用量（data usage）、复制（replication）、带宽（bandwidth）、生命周期队列快照（lifecycle queue snapshots）；
4. 待 trait 形态被聚焦测试覆盖后，由 ECStore 或 ECStore 拥有的适配器 crate 实现这些 trait；
5. 仅当指标行为经由 provider trait 保持不变之后，才从rustfs-obs中移除rustfs-ecstore依赖。

从源码结构看，第 3 步已有雏形：register_on_demand_migration_metrics_source采用"应用侧注册函数指针快照、obs 侧只调用"的注入模式，绕过了对 ECStore 的直接调用；provider trait 化后，其余别名（capacity、quota、data usage 等）可沿用同一套模式逐一迁移。

守卫（Guardrails）：CI 如何防止边界腐化

以上规则不是文档约定，而是由 scripts/check_architecture_migration_rules.sh 在 CI 中强制执行。与该文档直接相关的守卫包括：

1. 文档自身必须保持有效章节（防止台账被删改后规则失锚）：

require_source_contains "docs/architecture/obs-ecstore-dependency-inventory.md" "## Dependency Inventory" "..." require_source_contains "docs/architecture/obs-ecstore-dependency-inventory.md" "## Extraction Plan" "..." require_source_contains "docs/architecture/obs-ecstore-dependency-inventory.md" "crates/obs/src/metrics/storage_api.rs" "..."

2. 原始复制统计句柄不得越界：脚本在crates/obs/src/metrics全目录内检索ObsReplicationStats|obs_get_global_replication_stats|replication_stats_handle|get_sr_metrics_for_node|get_proxy_stats|mrf_stats等标识符，并排除边界文件本身——任何在 collectors 或其他模块直接使用原始句柄/方法的代码都会使 CI 失败，错误信息明确指向"必须留在 storage_api.rs 的快照辅助函数之后"。

3. ECStore 与 storage-api 符号必须走边界：脚本对crates/obs/src全量扫描 ECStore/storage-api 符号引用，唯一豁免是crates/obs/src/metrics/storage_api.rs，否则报"obs 源文件必须经由 obs metrics storage_api 边界路由 ECStore 与 storage-api 符号"。

4. 禁止再导出桥接模块：脚本明确把crates/obs/src/metrics/ecstore_compat.rs、crates/obs/src/storage_compat.rs列为禁止复活的 compat 桥接文件名，并要求任何 storage compat 逻辑"包装数据用量访问而非再导出 ECStore 函数"——正对应文档中"不得新增 passthrough 桥接模块（第二个 storage_api.rs、ecstore_compat.rs 或类似物）"的守卫项。

5. 台账与守卫联动：任何移除某一依赖类别的抽取 PR，必须在同一变更中更新这份 inventory 与守卫脚本。脚本头部的注释也点明了这类守卫的性质：它们是"永久性架构边界守卫（防回归），而非迁移进度门禁"——即使相关迁移 issue 已关闭，守卫也不退役。

此外，docs/architecture/ecstore-api-facade-inventory.md 将crates/obs/src/metrics/storage_api.rs登记为 ECStore 公开 facade 的消费者边界之一（覆盖 bucket 带宽、生命周期、复制、配额、容量、数据用量、错误、运行时、存储等 facade 分组），与本文档互为佐证。

小结：一个可复用的跨层依赖治理范式

把文档与源码合起来看，RustFS 在这条依赖边界上建立了一套完整的"清单—边界—投影—测试—守卫"五层机制：

1. 清单：以边界文件 import 块为唯一事实来源，按类型/句柄/行为三类耦合登记，避免台账与代码漂移；
2. 边界：所有跨 crate 引用改名为Obs*/obs_*别名并集中在单一文件，实现"一处替换"；
3. 投影：ECStore 计算结果在进入 collector 前转换为 obs 本地 DTO，消费侧与具体实现彻底解耦；
4. 测试：边界文件内置字段级映射与退化场景测试，作为未来 provider trait 实现的行为契约；
5. 守卫：CI 脚本同时校验文档章节存在、原始句柄不越界、桥接模块不复活，且要求抽取 PR 同步更新台账与守卫。

这套做法的价值在于：它把"未来要解耦"从一句愿望变成了可审计、可回归验证、可增量推进的工程资产——在rustfs-obs真正摘除rustfs-ecstore依赖之前，边界已经不可能被悄悄打破。

【免费下载链接】rustfs🚀2.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