RustFS 与 MinIO 的 Router 兼容边界异常清单、源码级实现与迁移排查指南【免费下载链接】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 仓库中的兼容性例外文档docs/architecture/minio-rustfs-router-compatibility.md展开系统梳理 RustFS 相对 MinIO 在 S3 数据平面与管理控制平面上的行为差异清单并结合rustfs/src/storage/ecfs.rs、rustfs/src/admin下的真实源码实现逐项印证帮助你在「同一个mc/SDK 调用在 MinIO 上成功、在 RustFS 上失败」时快速判定该端点是缺失、仅部分兼容还是被有意改成不同行为。一、这份兼容性文档的定位与「事实来源」RustFS 是一个 S3 兼容的高性能对象存储系统支持从 MinIO、Ceph 等 S3 兼容平台迁移并与之共存。在迁移与共存场景下最高频的问题就是某个在 MinIO 上可用的客户端调用在 RustFS 上失败了。该文档给出的核心规则是本文档只列出例外exceptions。凡未列入此文档的端点均按与 MinIO 等价的行为实现。即「不出现在清单里 已实现」文档禁止向其中添加「已实现」行。要验证某个端点是否真的存在文档指定了三条权威来源source of truth平面事实来源S3 数据平面rustfs/src/storage/ecfs.rs中对s3s::S3trait 的实现管理平面路由rustfs/src/admin/mod.rs中的make_admin_route管理平面注册完整性注册盘点测试 route_registration_test.rs以及路由/动作守卫快照 admin-route-action-snapshot.md更完整的 s3tests 级别兼容声明见 s3-compatibility-matrix.md尚未实现条目在 unimplemented_tests.txt 中留痕。二、状态图例四类例外状态文档为每个例外定义了四种状态阅读异常清单前必须先理解状态含义缺失missing没有对应的 RustFS 路由或处理器部分兼容partial路由已注册且功能可用但有文档记录的 MinIO 行为子集会被拒绝已注册未完成registered, incomplete路由已注册处理器按行为契约返回NotImplemented行为不一致behavior differs已实现但有意偏离 MinIO 的响应契约管理平面前缀归一化管理路径以规范前缀/rustfs/admin为基准/minio/admin作为别名经路由器归一化后被接受。这一点在源码中得到确认rustfs/src/admin/router.rs中的canonicalize_admin_path会把/minio/admin/v3/info映射为/rustfs/admin/v3/info其测试canonicalize_admin_path_maps_compat_prefix_to_rustfs_prefix见 router.rs还验证了/minio/administrator/object这类近似前缀不会被误归一化。因此习惯使用 MinIO 前缀的客户端脚本无需修改 URL 即可访问 RustFS 管理 API。三、S3 数据平面例外清单除下表所列外s3s::S3trait 的全部方法都实现在 ecfs.rs 中S3 操作状态细节GetBucketReplicationMetrics缺失没有get_bucket_replication_metrics复制指标改由管理端/v3/replicationmetrics暴露GetBucketOwnershipControls缺失无处理器相应 s3tests 条目保留在 unimplemented_tests.txtPutBucketOwnershipControls, DeleteBucketOwnershipControls缺失无处理器DeleteBucketNotification, DeleteBucketLogging, DeleteBucketRequestPayment, DeleteBucketAccelerate部分兼容没有独立的 DELETE 处理器通过 PUT 路径写入空配置来清除配置PutBucketAcl, PutObjectAcl部分兼容仅支持 Canned-ACL 头携带 XML grant 请求体时返回NotImplementedGetObjectTorrent行为不一致按设计返回404 NoSuchKey而非501 NotImplemented让客户端优雅降级3.1 ACLCanned-ACL 头可用XML grant 体被拒put_bucket_acl的实现位于 ecfs.rs先校验 bucket 存在然后判断请求中的access_control_policy是否为空——非空即返回NotImplemented错误消息明确给出替代方案ACL XML grants are not supported; use canned ACL headers or omit ACLput_object_acl见 ecfs.rs采用同样的判定逻辑且会先解析对象信息、生成事件上下文后再做相同检查。这意味着通过x-amz-acl请求头设置 Canned ACL 的路径是完整可用的而通过请求体传AccessControlPolicyXML 的路径会被明确拒绝。迁移脚本如果依赖 XML grant 授权例如给第三方账号加 grant需要改为 IAM 策略或 Canned ACL。3.2 GetObjectTorrent用 404 而非 501 让客户端降级get_object_torrent位于 ecfs.rs源码注释直接解释了这一「行为不一致」的设计动机// Torrent functionality is not implemented in RustFS // Per S3 API test expectations, return 404 NoSuchKey (not 501 Not Implemented) // This allows clients to gracefully handle the absence of torrent support record_s3_op(S3Operation::GetObjectTorrent); Err(S3Error::new(S3ErrorCode::NoSuchKey))返回NoSuchKey会被多数 S3 客户端当作「对象不存在/特性不可用」静默处理避免整条流水线因 501 中断。排查时若发现某客户端在 RustFS 上「拿不到 torrent」属于预期行为无需视为故障。3.3 四个 DELETE 配置端点走 PUT 写空DeleteBucketNotification、DeleteBucketLogging、DeleteBucketRequestPayment、DeleteBucketAccelerate 没有独立的 DELETE 处理器等效操作是通过对应 PUT 端点提交空配置。以 accelerate 为例put_bucket_accelerate_configuration见 ecfs.rs会序列化请求体中的配置并走update_bucket_metadata_config_if_incarnation更新 bucket 元数据且带有 incarnation 乐观并发校验PUT 一个空AccelerateConfiguration即可达到 DELETE 语义。四、管理控制平面例外清单route_registration_test.rs中断言的每条路由都已注册例外如下MinIO 管理端族状态细节Batch jobs/v3/start-job、/v3/list-jobs、/v3/status-job、/v3/describe-job、/v3/cancel-job已注册未完成start-job对已知 job 类型返回NotImplemented对未知类型返回InvalidRequestlist-jobs返回空列表status/describe/cancel 返回 no-such-jobService controlPOST /v3/service行为不一致restart/stop均触发优雅停机需进程管理器重新拉起无进程内重启freeze/unfreeze切换全局冻结标志Inspect dataGET|POST /v3/inspect-data行为不一致返回单个精确volumefile的原始字节带大小上限而非 MinIO 的加密 raw-drive-file 归档Pools decommission / cancel / clear部分兼容端点未初始化单池或未初始化集群时返回NotImplemented/v3/top/drives、/v3/top/net缺失仅注册了/v3/top/locksBucket / site 复制 per-object diff缺失存在/v3/replicationmetrics与站点复制状态但没有 diff 端点MRFmost-recent-failures复制指标细分缺失仅有通用/v3/metrics流与复制指标 wire4.1 Batch jobs契约级拒绝永不接受任务batch_job.rs 的模块注释写明了行为契约start-job对KNOWN_JOB_TYPES当前为replicate、keyrotate、expire见 batch_job.rs返回NotImplemented对未知类型返回InvalidRequest任何任务都不会被接受或持久化因此list-jobs恒返回空列表status/describe/cancel对合法的jobId恒返回NoSuchJob风格错误。之所以keyrotate必须持续拒绝原因见 kms-bulk-rekey-contract.md。对依赖mc admin replicate start-job类批量工作流的团队这是一个硬边界任务定义提交不会被持久化不存在「排队后补跑」。4.2 Service controlrestart 是「优雅停机」而非「进程内重启」ServiceHandle位于 system.rs。源码中的关键事实restart与stop都调用request_graceful_shutdown()其实现是向自身进程raise(SIGTERM)走既有的wait_for_shutdown()优雅停机序列排空服务器、刷新审计/事件通知器。源码注释明确说明RustFS 没有进程内 supervisor 去 re-exec 二进制进程管理器systemd、k8s负责重新拉起。freeze/unfreeze操作全局原子标志SERVICE_FROZENsystem.rs。注意源码注释与响应体都声明该标志目前是advisory only——响应中effective: false消息为 freeze flag recorded, but RustFS does not yet gate request admission on it (advisory only)即冻结并不会真正暂停请求准入。权限上四种动作分别映射到ServiceRestartAdminAction、ServiceStopAdminAction、ServiceFreezeAdminAction后两者共用经authorize_admin_request鉴权缺凭据直接InvalidRequest。该文档还指出 route_policy.rs 目前仍将/v3/service分类为 deferredNotImplemented与 handler 实际已可用的状态并存——排查时以 handler 源码为准。4.3 Inspect data单对象原文 vs MinIO 加密归档GET|POST /v3/inspect-data由InspectDataHandlersystem.rs处理注册于 system.rs。与 MinIO 返回加密的 raw-drive-file 归档不同RustFS 的 v3 端点返回一个精确volumefile的原始字节且带大小上限有界的归档能力位于POST /v4/inspect/archiveinspect_archive.rs。同样地route_policy.rs仍将 v3 路由分类为 deferredNotImplemented属于文档化的行为不一致。4.4 Pools decommission 家族单池场景下的 NotImplementedpools.rs 中 decommission / cancel / clear 相关分支在端点尚未初始化典型为单池或未初始化集群时返回s3_error!(NotImplemented)如 pools.rs 等多处。这是「部分兼容」状态的含义多池、已初始化集群上路径完整可用单节点/单池部署上这些操作被明确拒绝而非静默忽略。4.5 已注册、不再是例外的端点族以下曾经缺失的端点族现已注册因此不再列入例外清单可作为「已兼容」参照/v3/healthinfo、/v3/obdinfo、/v3/force-unlock、/v3/top/locks、/v3/speedtest*、/v3/log、/v3/trace、/v3/profile、/v3/profiling/*、/v3/idp/{ldap|openid}/*、/v3/idp-config/*。五、迁移排查决策流程结合上述清单遇到「MinIO 上能跑、RustFS 上失败」时的排查路径先看路径前缀/minio/admin与/rustfs/admin等价排除前缀问题后再看状态码。按状态码分类501 NotImplemented且消息含 ACL XML grants are not supported → 改用 Canned-ACL 请求头501 NotImplemented出现在 batch job / 单池 decommission → 属于「已注册未完成」或「部分兼容」检查集群形态是否单池或改用替代端点404 NoSuchKey出现在 GetObjectTorrent → 预期行为torrent 不可用InvalidRequest invalid jobType→ job 类型不在KNOWN_JOB_TYPES内。对照替代端点复制指标走管理端/v3/replicationmetricswire 见 replication_metrics_wire.rsdrive 级 inspect 归档走POST /v4/inspect/archive。未列入清单即视为已实现若失败端点不在上述两张表中应优先怀疑配置/权限/客户端版本问题并以route_registration_test.rs的断言与 admin-route-action-snapshot.md 为路由存在性的最终依据。六、兼容边界的维护规则文档的 Update Rule 规定了这张清单的演化方式当某个例外的状态发生变化时必须在修改 handler 的同一个 PR 中同步修改本文档对应行管理路由的变更还需扩展 route_registration_test.rs 与 admin-route-action-snapshot.md。不得向本文档添加「已实现」行——从清单中消失本身就是「已实现」的声明。这一机制保证了文档不会随时间膨胀也意味着你在评估某个端点是否已补齐时直接检查该行是否还存在即可。七、适用前提小结本文所有结论基于当前仓库快照S3 平面以 ecfs.rs 的s3s::S3trait 实现为准管理平面以 admin/mod.rs 的make_admin_route与注册测试为准。例外清单是动态的随着 handler 补齐行会被删除引用本文做迁移决策时请以仓库最新文档与route_registration_test.rs测试为准。与 s3tests 的逐操作对照见 s3-compatibility-matrix.md未实现测试条目维护在 unimplemented_tests.txt。【免费下载链接】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），仅供参考
