RustFS S3 兼容性矩阵解读：覆盖范围、测试门禁与有意偏差

RustFS S3 兼容性矩阵解读覆盖范围、测试门禁与有意偏差【免费下载链接】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/s3-compatibility-matrix.md为骨架系统梳理 RustFS 对标准 S3 API 的覆盖范围、以 Ceph s3-tests 为基础的测试门禁机制、复制Replication能力边界以及若干与 AWS S3 的有意偏差Intentional Deviations。读完本文你将掌握RustFS 声称支持的 S3 功能清单与证据来源、如何用scripts/s3-tests/run.sh复现兼容性门禁、哪些功能明确尚未通过或有意排除以及对象键校验与目录标记directory marker在版本化桶中的特殊语义。本文所有结论均来自仓库中的文档、测试清单、源码与 CI 配置文中给出的文件路径均为仓库内相对路径可点击跳转核对。一、兼容性声明的边界RustFS 到底承诺了什么RustFS 的官方措辞非常克制为受支持的功能提供广泛的 S3 API 兼容性但不声称覆盖每一个标准或厂商特定的 S3 行为参见 docs/architecture/s3-compatibility-matrix.md 的 Current Claim 一节。根目录 README.md 使用相同口径受支持的 S3 兼容客户端与功能由兼容性矩阵与测试清单共同覆盖。这意味着对 RustFS 的所有 S3 兼容性讨论都应当以scripts/s3-tests/下的四份测试清单为事实来源source of truth而不是凭印象或营销话术。计数直接由清单文件推导文档本身并不记录具体数字——截至撰写本文时仓库中四份清单的行数含注释与空行约为清单用途行数含注释/空行scripts/s3-tests/implemented_tests.txt默认本地 s3tests 运行的标准 S3 测试白名单556scripts/s3-tests/lifecycle_behavior_tests.txt由 CI 中s3-lifecycle-behavior-testslane 单独门禁的按天过期行为用例53scripts/s3-tests/unimplemented_tests.txt标准 S3 中尚未通过的功能37scripts/s3-tests/excluded_tests.txt厂商特定或有意不支持的行为317计数规则忽略空行与#注释行从文件实际内容计算见矩阵文档 Test List Sources 一节。二、测试清单体系四份清单各自管什么矩阵文档用一张表明确了四份清单的分工清单用途来源文件Implemented tests期望通过的标准 S3 测试本地 s3tests 默认运行项scripts/s3-tests/implemented_tests.txtLifecycle behavior tests按天Days-based过期用例由 CI 的s3-lifecycle-behavior-testslane 门禁scripts/s3-tests/lifecycle_behavior_tests.txtUnimplemented tests标准 S3 中尚未通过的功能scripts/s3-tests/unimplemented_tests.txtExcluded tests厂商特定或有意不支持的、被排除出门禁的行为scripts/s3-tests/excluded_tests.txtimplemented_tests.txt文件头注释还给出了受覆盖操作的完整摘要Bucket 的 Create/Delete/List/Head/GetLocationObject 的 Put/Get/Delete/Copy/HeadListObjects/ListObjectsV2 的 prefix/delimiter/marker/maxkeysMultipart 的 Create/Upload/Complete/Abort/List桶与对象 TaggingBucket PolicyPublic Access BlockPresigned URLRange 请求用户元数据条件 GETIf-Match/If-None-Match/If-Modified-SinceSSE-C 与部分 SSE-KMS 边界用例版本化并发多对象删除对象复制同/跨桶、元数据、版本化POST Object 表单上传Raw 请求条件写入PUT/Copy 的 If-Match/If-None-Match原子读写一致性Object LockPutObject 上的 SHA256/CRC64NVME 校验和CORS 配置与预检HTTP 100-continue以及NoSuchBucket语义等。2.1 为什么生命周期用例要单独跑一条 lane生命周期行为用例不能进入默认门禁implemented_tests.txt原因有三详细说明见lifecycle_behavior_tests.txt文件头注释默认测试环境关闭了后台 scannerrun.sh设置RUSTFS_SCANNER_ENABLEDfalse没有任何东西会真正执行过期删除真实的一天是 86400 秒不做加速的话一个Days1的规则要等 24 小时如果全局启用RUSTFS_ILM_DEBUG_DAY_SECS加速会破坏已经通过的test_lifecycle_expiration_header_*用例——这些用例断言(expiry-date - now).days Days而响应头中的过期时间正是由同一套 debug 缩放的expected_expiry_time()计算出来的。因此专门的 CI lane.github/workflows/ci.yml中的s3-lifecycle-behavior-tests任务会以如下环境变量启动服务RUSTFS_ILM_DEBUG_DAY_SECS10 # 1 天 10 秒对齐 s3-tests 的 lc_debug_interval RUSTFS_SCANNER_ENABLEDtrue RUSTFS_SCANNER_CYCLE2 # 每 2 秒扫一遍远小于一个 debug-day RUSTFS_DATA_USAGE_UPDATE_DIR_CYCLES1 # 每周期重扫压缩目录让 ILM 约每 2 秒评估一次 RUSTFS_SCANNER_START_DELAY_SECS0 RUSTFS_API_STALE_UPLOADS_CLEANUP_INTERVAL2s # multipart abort 清理 lane然后通过IMPLEMENTED_TESTS_FILE该文件路径把run.sh指向生命周期清单run.sh中IMPLEMENTED_TESTS_FILE默认值即implemented_tests.txt可被覆盖见 scripts/s3-tests/run.sh。当前清单里的第一批用例对应 ILM-10 里程碑覆盖前缀过期test_lifecycle_expiration/test_lifecyclev2_expiration、版本化桶的 NoncurrentVersionExpirationtest_lifecycle_noncur_expiration、ExpiredObjectDeleteMarker 级联test_lifecycle_deletemarker_expiration以及 AbortIncompleteMultipartUploadtest_lifecycle_multipart_expiration由 stale-multipart 清理循环驱动。清单还记录了轮询窗口的经验修正Days5expire3用例的窗口被放宽到8*lc_interval而非 5因为其截止时间是在Days1轮询返回后才开始计时的5 倍窗口只留下约 1 个 debug-day 余量CI 负载下曾观察到约 13 秒的单次慢扫描会把过期时间推出窗口导致计数停在 4断言 4 2 失败。目标计数2是终态更宽的窗口不会造成过度过期。三、受支持覆盖范围Supported Coverage矩阵文档给出的受支持区域与证据如下功能区域状态证据Bucket 创建/删除/列举/Head支持implemented_tests.txtObject Put/Get/Delete/Copy/Head支持implemented_tests.txtCopyObject 校验和CRC32、CRC32C、CRC64NVME、SHA1、SHA256、MD5、SHA512、XXHASH3、XXHASH64、XXHASH128含源端保留与显式覆盖支持crates/e2e_test/src/copy_object_checksum_test.rsListObjects/ListObjectsV2 的 prefix、delimiter、marker、max-keys支持implemented_tests.txtMultipart 上传 create/upload/complete/abort 及选定的 multipart copy/checksum/object-attribute 行为支持implemented_tests.txtBucket 与对象 Tagging支持implemented_tests.txtBucket Policy put/get/delete支持implemented_tests.txtPublic Access Block put/get/delete支持implemented_tests.txtPresigned GET 与 PUT URL支持implemented_tests.txtRange 与条件读取支持implemented_tests.txt用户元数据支持implemented_tests.txtSSE-C 与选定的 SSE-KMS 边界用例支持implemented_tests.txt选定的版本化、object-lock、校验和、CORS、raw request 与条件写入行为支持implemented_tests.txt其中 CopyObject 校验和是少数有专门 E2E 测试文件佐证的项目内功能crates/e2e_test/src/copy_object_checksum_test.rs 覆盖了多达 9 种校验和算法在复制时的源端保留与显式覆盖行为这比纯依赖上游 s3-tests 的覆盖面更细。3.1 SSE 行的重要限定矩阵对 SSE 行的支持含义有严格限定RustFS 能加密并解密自己写入的对象。默认构建下无法读取 MinIO 写入的 SSE 对象包括 SSE-S3、SSE-KMS、SSE-C 三种。若需读取 MinIO SSE 对象需要rio-v2迁移构建详见 docs/architecture/minio-file-format-compat.md 的 Part C Server-Side Encryption (SSE)。这意味着跨厂商的 SSE 数据迁移是受限场景部署前必须评估。四、Replication 支持边界站点复制 ≠ 桶复制矩阵文档特别强调站点复制Site Replication与桶复制Bucket Replication不是同一个兼容性声明。站点复制要求对端是 RustFS 兼容的 peer 管理 API用于协调 IAM、拓扑、桶与元数据。一个通用的 S3 兼容服务只能作为桶复制的数据目标data target无法参与站点复制。对通用 S3 目标当目标实现了对应 S3 API 且开启了版本化时RustFS 支持对象 PUT/HEAD/DELETE、Multipart 上传、标签、版本删除以及 Object Lock 变更。针对自行铸造版本 IDminting version IDs的目标RustFS 通过每目标版本账本per-target version ledger支持账本建立之前的副本pre-ledger replicas只有在确切的键 ETag能唯一对应一个目标版本时才会被接管。若某个已寻址副本已经不存在NoSuchVersion会被视为已收敛converged。矩阵文档同时列出以下能力边界而非普适 S3 声明GET /BUCKET?replication-check必须通过目标工作负载所需的各个阶段VersionFidelity可能把铸造版本的目标报告为不匹配即使账本寻址的删除与 Object Lock 阶段均成功。拒绝标准 multipart 约束、拒绝必需的 Object Lock 完整性头、或拒绝已配置校验和封装的目标在传输设置兼容之前不受支持。SSE-S3 / SSE-KMS源端解密后由目标 KMS 重新加密SSE-C使用密文透传并要求目标提供证据target evidence。不支持或语义模糊的加密元数据会失败关闭fails closed。ACL 授权有意不支持通用目标永远不会收到 RustFS 的 IAM / 站点控制平面状态。对同键同 ETag 的多个目标版本RustFS不做猜测变更保持失败并可重试直到修复操作建立无歧义的映射。运维层面的健康检查、恢复与升级规则见 docs/operations/site-replication-operations.md已测试的目标类别与可调旋钮见 docs/operations/replication-outbound-transport.md。五、尚未通过Not Yet Passing不可描述为完整的区域以下标准 S3 区域不得被描述为完整支持功能区域状态证据Bucket 访问日志access logging处理器存在get_bucket_logging、put_bucket_logging位于 rustfs/src/storage/ecfs.rs但test_*bucket_logging*用例仍列在 unimplementedunimplemented_tests.txtPOST Object 表单上传的校验和处理尚未通过unimplemented_tests.txtBucket 所有权控制ownership controls无处理器unimplemented_tests.txtMultipart 上传列举与分片查找的兼容性边界用例不属于默认门禁excluded_tests.txt依赖 IAM 账户或多存储类的用例不属于默认门禁unimplemented_tests.txtTenanted bucket policy 边界用例需要进一步调查unimplemented_tests.txt对照unimplemented_tests.txt的实际内容未实现用例可归纳为三类失败用例如test_put_bucket_logging、test_post_object_upload_checksum、test_multipart_upload_complete_without_create、test_object_copy_not_owned_bucket等、依赖 IAM 账户/多存储类的跳过用例如test_lifecycle_transition_encrypted、以及已知问题待调查用例如test_bucket_policy_tenanted_bucket。其中 bucket logging 是典型的处理器存在但功能未达标案例——源码中get_bucket_logging/put_bucket_logginghandler 已经挂载见 rustfs/src/storage/ecfs.rs但行为尚未通过上游用例因此矩阵明确将其归入Not Yet Passing。六、有意排除Intentional Exclusionsexcluded_tests.txt存放不得阻塞兼容性门禁的测试厂商特定或不可移植的行为以及产品决策上有意不支持的行为典型如 ACL 授权。文件头注释将排除项分为两类厂商特定/不可移植行为vendor-specific / non-portable例如test_bucket_get_location、test_bucket_head_extended、test_bucket_list_return_data、test_account_usage等产品决策上有意不支持的行为例如 ACL 授权相关用例。这类排除并非没做完而是明确的边界声明这些行为不构成 RustFS 的兼容性承诺也不参与门禁判定。七、与 AWS S3 的有意偏差两种必须知道的语义差异RustFS 的对象键以文件系统路径形式存储在每块盘上{drive}/{bucket}/{object}/xl.meta与 MinIO 采用相同的磁盘布局。为保持该布局无歧义以下规则是有意设计不是需要补齐的兼容性缺口需要 AWS 行为的客户端必须在自身侧适配。行为RustFSAWS S3原因对象键包含.或..路径段、或空段//如a//b/./c/../d返回400 InvalidArgumentcheck_object_args实现于 crates/ecstore/src/bucket/utils.rs镜像 MinIO 的IsValidObjectPrefix作为不透明键接受..段会解析到父目录.///段会与其他键在磁盘上别名冲突编码它们会破坏与 MinIO 兼容的磁盘格式版本化桶中的目录标记以/结尾的键可带 body以null 版本存储PutObject/HeadObject报告版本 id00000000-0000-0000-0000-000000000000ListObjectVersions报告null后续对同键的 PUT 直接原地覆盖put_opts位于 rustfs/src/storage/options.rs镜像 MinIOputOpts中 for directory objects skip creating new versions每次 PUT 生成真实版本 id保留版本历史目录标记的存在只是为了让空前缀可列举为它保留历史会在每次前缀删除后留下隐藏版本。复制仍会把该标记作为 null 版本拷贝test_bucket_replication_replicates_directory_marker_in_versioned_bucket见 crates/e2e_test/src/replication_extension_test.rscheck_object_args的源码证实了校验链路它依次做桶名校验is_meta_bucketname/check_valid_bucket_name_strict、长度与斜杠校验check_object_name_for_length_and_slash以及is_valid_object_name的键名校验crates/ecstore/src/bucket/utils.rs任何一项失败都会返回StorageError::ObjectNameInvalid对应 HTTP 400。Multipart 相关入口check_new_multipart_args、check_multipart_object_args、check_put_object_part_args、check_list_parts_args都复用了这套校验说明该规则对普通 PUT 与分片上传一致生效。八、如何复现兼容性门禁run.sh 实操指南矩阵文档指定scripts/s3-tests/run.sh为测试运行器。该脚本核心行为如下默认模式TEST_SCOPEimplemented只跑implemented_tests.txt白名单PR 门禁TEST_SCOPEall则跑完整上游套件定时全量扫描。部署模式DEPLOY_MODEbuild默认cargo build --release后运行、binary用预编译二进制默认路径./target/release/rustfs、docker构建Dockerfile.source镜像运行、existing连接已在运行的服务跳过启动。确定性测试选择脚本把清单行转换为精确的 pytest node ids3tests/functional/test_s3.py::用例名避免pytest -k子串匹配的误伤支持TESTEXPR覆盖为自定义-k表达式。分片与超时S3_SHARD_COUNT/S3_SHARD_INDEX按 node id 行号取模分片TEST_TIMEOUT默认 300 秒/用例。上游套件固定版本s3-tests 仓库固定到 commitS3TESTS_REV默认5522d1c351f75bc00ae0f64f742f3f095f5939d9并有report_compat.py在运行前校验清单分类与固定版本一致防止上游改名导致误分类。兼容性报告运行后由report_compat.py生成compat-report.md并带--fail-on-regression门禁TEST_SCOPEall时还启用--fail-on-unclassified。常用示例# 默认构建并运行 implemented_tests.txt 白名单 ./scripts/s3-tests/run.sh # 用预编译二进制 DEPLOY_MODEbinary RUSTFS_BINARY./target/release/rustfs ./scripts/s3-tests/run.sh # 连接已在运行的服务跳过启动指定主机端口 DEPLOY_MODEexisting S3_HOST192.168.1.100 S3_PORT9000 ./scripts/s3-tests/run.sh # 跑完整上游套件 TEST_SCOPEall ./scripts/s3-tests/run.sh # 生命周期行为 lane覆盖清单 debug 天加速 开启 scanner IMPLEMENTED_TESTS_FILEscripts/s3-tests/lifecycle_behavior_tests.txt \ RUSTFS_ILM_DEBUG_DAY_SECS10 RUSTFS_SCANNER_ENABLEDtrue \ RUSTFS_SCANNER_CYCLE2 RUSTFS_SCANNER_START_DELAY_SECS0 \ RUSTFS_DATA_USAGE_UPDATE_DIR_CYCLES1 \ RUSTFS_API_STALE_UPLOADS_CLEANUP_INTERVAL2s \ ./scripts/s3-tests/run.sh脚本自动设置的默认凭证/端口为S3_ACCESS_KEYrustfsadmin、S3_SECRET_KEYrustfsadmin、S3_REGIONus-east-1、S3_HOST127.0.0.1、S3_PORT9000并通过RUSTFS_UNSAFE_BYPASS_DISK_CHECKtrue允许在同一物理盘上创建多个导出目录用于测试。需要注意脚本默认关闭后台 scannerRUSTFS_SCANNER_ENABLEDfalse以把兼容性测试聚焦在前台 S3 API 行为上避免 scanner 与短生命周期测试桶竞争。九、维护规则功能通过后如何更新矩阵矩阵文档规定了严格的更新流程Update Rule当某个功能开始通过测试时将其用例条目从unimplemented_tests.txt移入implemented_tests.txt在同一个 PR中更新本文档矩阵对应的行不得改动 README 中超出受支持覆盖范围的措辞handler 级别的状态缺失、stub 或端点发散由 docs/architecture/minio-rustfs-router-compatibility.md 跟踪。这条规则保证了 README 的兼容性措辞、矩阵文档与测试清单三者始终同步任何兼容性声明都有可复现的测试证据兜底。十、总结如何正确引用 RustFS 的兼容性能力引用兼容性事实时优先引用implemented_tests.txt的具体用例与对应源码如 CopyObject 校验和见crates/e2e_test/src/copy_object_checksum_test.rs而不是泛泛地说完全兼容 S3。部署集成前对照Not Yet Passing与Intentional Exclusions两个小节核对你依赖的 API如 bucket logging、POST Object 校验和、ACL、bucket ownership controls是否在支持范围内。涉及复制场景明确区分站点复制仅 RustFS peer与桶复制通用 S3 目标并确认对端对版本化、Object Lock、校验和封装的支持程度。涉及 MinIO 迁移注意磁盘格式兼容的两处有意偏差键名校验、目录标记 null 版本以及 SSE 对象在默认构建下不可跨厂商读取的限制。RustFS 的 S3 兼容性不是一句口号而是一套由清单文件、固定版本的 ceph/s3-tests、专用 CI lane 与源码测试共同维护的、可复现、可审计的工程事实——这正是本文希望传达的核心。【免费下载链接】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），仅供参考