RustFS 复制目标健康检查指南：理解与使用 `GET /BUCKET?replication-check`

RustFS 复制目标健康检查指南理解与使用GET /BUCKET?replication-check【免费下载链接】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 的复制目标健康检查扩展GET /BUCKET?replication-check展开说明它如何对桶复制配置中引用的每个复制目标执行端到端探针验证解释它为何是带写操作的 GET、其 JSON 响应契约与各阶段语义并结合rustfs/src/admin/router.rs的实现与crates/e2e_test的端到端测试深入剖析版本身份契约VersionFidelity、SSE-C 透传探测与清理流程的底层原理。读完本文你将能正确调用、自动化或调试该接口并能读懂任意一个复制目标探测失败时的 JSON 输出与各阶段状态含义。一、接口概述一个会写数据的 GETGET /BUCKET?replication-check是 RustFS 提供的带签名的 S3 扩展接口signed S3 extension用于校验桶复制配置bucket replication configuration中引用的每一个复制目标replication target是否健康可用。路由的分发逻辑位于 rustfs/src/admin/router.rs通过查询参数精确匹配replication-check触发处理入口处理函数为run_replication_checkrouter.rs#L2900-L2927。文档将 rustfs/src/admin/router.rs 明确标注为唯一事实来源source of truth其中三个关键常量直接定义了探针行为常量值含义REPLICATION_CHECK_PROBE_PREFIX.rustfs.sys/replication-check/探针对象的保留命名空间前缀REPLICATION_CHECK_ERROR_MAX_BYTES512错误信息单行最大字节数REPLICATION_CHECK_CODE_VERSION_MISMATCHBucketRemoteTargetVersionMismatch目标不采纳源版本 ID 时的机器可读错误码使用时机原文明确当你准备调用、自动化或调试GET /BUCKET?replication-check或者需要解释为什么一次 GET 在复制目标上写入了对象又删除了对象时都应阅读本文档。调用前的硬性前置条件从run_replication_check的入口逻辑router.rs#L2900-L2926可以看出接口在以下情况下会直接返回InvalidRequest源桶未开启版本控制BucketVersioningSys::enabled(bucket)为 false 时报错replication validation requires bucket versioning to be enabled没有已配置的复制目标过滤后目标列表为空时报错replication check requires at least one configured replication target复制配置存在过期目标stale targetvalidate_replication_check_config_targetsrouter.rs#L1943-L1978会比对配置中的 Role/规则目标 ARN 与实际BucketTargets列表发现引用了未注册的目标时直接拒绝。也就是说调用前请确保源桶已开启版本控制、已配置至少一个远端复制目标、且配置中的 ARN 与实际注册的目标一致。二、重要警告这不是只读操作Active Mutation尽管方法名是GET这个操作绝不是只读的。文档明确列出它在每个目标上依次执行的四个动作在.rustfs.sys/replication-check/uuid/uuid下写入一个8 字节的探针对象REPLICATION_CHECK_PROBE_PREFIX命名空间创建一个带复制的删除标记replicated delete marker永久删除探针对象版本枚举该探针 key 的确切位置并尝试删除所有剩余的对象版本与删除标记。因此在发送请求之前必须获得运维人员operator的确认。响应体中的ActiveMutation: true与MutationDescription字段正是为了让任何调用方包括脚本与自动化工具都能明确感知这一事实——详见 router.rs#L1858-L1878 中响应序列化逻辑。探针 key 的安全设计探针 key 的生成由new_replication_probe_keyrouter.rs#L2386-L2388完成{REPLICATION_CHECK_PROBE_PREFIX}{uuid}/{uuid}即保留命名空间 两个独立的随机 UUID。随机性保证探针不会与用户对象冲突且攻击者无法预知 key 位置。写入前还有两道防线预检allocate_replication_probe_keyrouter.rs#L2390-L2417先用list_object_versions按前缀检查该 key 是否已被占用最多重试 4 次确认无任何版本或删除标记存在后才使用原子写探针 PUT 携带If-None-Match: *router.rs#L2635即使并发被应用程序创建的同名 key 抢占条件写也会失败而不会覆盖。若目标因并发冲突返回PreconditionFailedexecute_replication_probe会据此跳过清理阶段router.rs#L2271因为此时并没有产生任何探针产物。探针请求的复制身份探针 PUT 不是普通的上传它完整模拟了线上复制live replication的请求形态。build_replication_probe_put_options与build_replication_probe_headersrouter.rs#L2431-L2472会附加以下头部x-rustfs-source-version-id源版本 ID每次探针生成一个新的非空 UUIDx-rustfs-source-mtimeRFC3339 格式的源对象时间x-rustfs-source-replication-request: truex-rustfs-source-replication-check: true标记这是一次复制检查x-amz-replication-status: REPLICA。同时版本 ID 还会以?versionId查询参数的形式携带append_version_id_query这与真实复制 PUT 的数据路径完全一致源码注释称其为 P0-5 shape确保探针测试的正是线上路径真正依赖的形态。三、响应契约HTTP 200 JSON在所有已配置目标检查完成后路由返回HTTP 200与 JSON 体Content-Type: application/jsonrouter.rs#L1858-L1878。顶层Status在任意目标或清理阶段失败时为FAILED其他目标的成功结果仍然保留部分成功不会互相覆盖。目标列表按 ARN 排序输出。文档给出的完整失败示例逐字保留{ Status: FAILED, ActiveMutation: true, MutationDescription: Writes a probe object, creates a delete marker, deletes the probe version, and cleans up all probe artifacts on each target., ProbeNamespace: .rustfs.sys/replication-check/, Targets: [ { Arn: arn:minio:replication::target, Bucket: replica, Status: FAILED, Error: probe cleanup failed: target delete object version check failed: AccessDenied, Phases: { Bucket: { Status: OK }, Versioning: { Status: OK }, ObjectLock: { Status: OK }, Put: { Status: OK }, VersionFidelity: { Status: OK }, DeleteMarker: { Status: OK }, VersionDelete: { Status: OK }, Cleanup: { Status: FAILED, Error: target delete object version check failed: AccessDenied } } } ] }字段契约文档原文表FieldContractPhases.*.StatusOK、FAILED或SKIPPED。Error单行文本截断到REPLICATION_CHECK_ERROR_MAX_BYTES512 字节省略远端消息、端点、凭证、签名与授权材料。Cleanup清理失败永远是显式的绝不会被报告为一次成功的检查。Code仅在调用方需要分支处理的失败中出现目前为BucketRemoteTargetVersionMismatch。Go 解码器会忽略未知键。各阶段Phases的完整集合响应体中的Phases由 9 个阶段组成与源码中ReplicationCheckPhases结构体一一对应router.rs#L256-L276Bucket→Versioning→ObjectLock→Put→VersionFidelity→SsecPassthrough→DeleteMarker→VersionDelete→Cleanup阶段状态的默认值是SKIPPEDReplicationCheckPhaseStatus::defaultrouter.rs#L291-L299只有真正执行并成功的阶段才被置为OK失败的阶段置为FAILED并附带错误信息。这一点对读响应至关重要SKIPPED不代表通过了而代表没有执行。四、逐阶段执行流程从 Bucket 检查到 Cleanupcheck_replication_targetrouter.rs#L1994-L2117是单个目标的检查入口各阶段按顺序推进1. 同部署自指检查如果目标的target_bucket等于源桶且目标 deployment ID 与当前部署一致直接判定失败target bucket must not match source bucket on the same deploymentrouter.rs#L2007-L2013。2. Bucket 阶段通过head_bucket验证目标桶存在router.rs#L2023。失败时返回如target bucket check failed: access denied或target bucket check failed: target bucket does not exist后者由NoSuchBucket/NotFound错误码映射而来见format_replication_check_client_errorrouter.rs#L1894-L1931。3. Versioning 阶段通过get_bucket_versioning检查目标桶是否开启版本控制。未开启版本控制是硬失败错误信息为target bucket is not versionedrouter.rs#L2037。4. ObjectLock 阶段仅当源桶开启了对象锁source_bucket_requires_object_lockrouter.rs#L2889-L2898时才强制执行否则直接置为OK。目标桶未开启对象锁时失败target bucket is not object lock enabled。5. Put 与探针执行通过execute_replication_proberouter.rs#L2237-L2384驱动后续所有阶段其内部按以下顺序执行Put普通单对象 PUT写入 8 字节探针对象VersionFidelity校验版本身份契约见下文第五节SsecPassthroughSSE-C 透传探测见下文第六节DeleteMarker对探针版本创建复制删除标记VersionDelete按目标分配的版本 ID 删除探针版本Cleanup清理全部探针产物。DeleteMarker与VersionDelete阶段只有在 Put 成功且探针返回了版本 ID 时才会执行router.rs#L2334否则保持SKIPPED——这正是文档所说仅当探针 Put 本身失败或未报告版本 ID 时被 SKIPPED的实现位置。6. Cleanup不留任何痕迹清理是整个检查的最后一道关卡也是文档特别强调失败必须显式报告的阶段。cleanup_replication_proberouter.rs#L2803-L2887分两步按已知版本 ID 删除对探测过程中收集到的至多 4 个版本 ID普通 PUT、multipart、SSE-C 探针、删除标记逐一执行版本删除分页枚举兜底用list_object_versions按探针 key 前缀分页枚举把枚举出的每一个残留版本与删除标记全部删除直到is_truncated为 false。删除时对NoSuchKey/NoSuchVersion宽容处理probe_version_already_gonerouter.rs#L2799-L2801因为 VersionDelete 阶段可能已经删除了探针版本严格 S3 目标如 Wasabi会对重复 DELETE 返回NoSuchVersion而 RustFS/MinIO 返回 204——无论哪种目标都已达成。端到端测试test_replication_check_succeeds_with_remote_targetreplication_extension_test.rs#L2586-L2622专门验证了这一点检查成功后用list_object_versions按前缀.rustfs.sys/replication-check/枚举必须同时满足versions 为空且 delete_markers 为空。清理失败时顶层错误会以probe cleanup failed: ...前缀呈现router.rs#L2382且绝不会把失败的清理报告为成功。五、VersionFidelity 阶段版本身份契约这是整个检查最核心的阶段。其设计动机源码注释 P1-19是一个不采纳源版本 ID 的目标永远不会回应源版本 ID从而破坏版本寻址的复制版本删除、修复等的收敛性。双写入路径探测探针在两条写入路径上分别验证版本身份契约router.rs#L2126-L2132、router.rs#L2157-L2173PutObject 路径探针 PUT 携带源版本 ID头部加?versionId查询参数正是线上复制使用的精确形态目标必须以相同 ID应答。应答版本 ID 与发送的源版本 ID 不一致即视为漂移version_fidelity_errorrouter.rs#L2225-L2235Multipart 路径第二个探针走CreateMultipartUpload → UploadPart → CompleteMultipartUpload目标在 initiate 时固定版本、只在 completion 时上报版本。因为一个目标可能采纳 PutObject 的版本 ID却在 multipart 上自行铸造自己的 ID——所以必须单独再探测一次router.rs#L2275-L2295。只有当 PutObject 路径的 VersionFidelity 通过后才会执行 multipart 探测失败消息会明确指出是哪条路径发生了漂移错误文本中带有on PutObject或on CreateMultipartUpload字样。判定与错误码若目标自行铸造版本 IDmints its own该阶段失败并携带机器可读错误码Code: BucketRemoteTargetVersionMismatch同时该目标整体状态为FAILED。端到端测试test_replication_check_flags_version_minting_target与test_replication_check_flags_multipart_only_version_minting_targetreplication_extension_test.rs#L9278、replication_extension_test.rs#L9042分别覆盖了两种漂移场景。但复制仍然收敛目标版本账本文档特别说明向此类目标复制仍然可以收敛。原因是复制工作线程replication worker会把目标为每个对象版本分配的 ID 记录在源端的目标版本账本target-version ledger中——内部元数据键为replication-target-version-arn——并用该 ID 来寻址版本删除、标签与对象锁更新。正因如此DeleteMarker与VersionDelete阶段探测的恰好就是这条路径它们寻址的是目标为探针对象分配的 ID而非源 ID。因此在一个会漂移的目标上这两个阶段能够回答账本寻址的清除操作对这个端点是否有效清理阶段也用同一个 ID 移除探针。这套即便版本身份不达标也要验证账本寻址清除路径的设计使检查结果能精确区分契约破坏与实际可用性两个维度。结果写入运行时能力缓存探针的裁决并不会止步于一次响应check_replication_target末尾会把版本身份结论写入BucketTargetSys运行时能力缓存router.rs#L2103-L2114VersionFidelityOK→ 记录VersionIdentityCapability::Adopts携带BucketRemoteTargetVersionMismatch失败 → 记录VersionIdentityCapability::MintsOwn。此后复制工作线程对已知自行铸造 ID的目标改用内容身份定位副本而非反复驱动 PUT对已验证采纳 ID 的目标跳过自身的 HEAD-back 审计无需每次重新学习探针刚建立的结论。六、SsecPassthrough 阶段SSE-C 透传能力探测这是一个与 VersionFidelity 并列、但语义截然不同的扩展阶段源码注释 N2。SSE-C客户提供的加密密钥复制依赖 RustFS 通过传输头把解密材料元数据透传给目标若目标丢弃这些头部SSE-C 副本会静默丢失解密材料fail-closed 风险。探测方式ssec_passthrough_probe_objectrouter.rs#L2665-L2721执行以下动作用与线上 SSE-C 复制相同的透传传输头完整线上名称非x-rustfs/x-minio后缀形式写入一个新探针版本x-amz-server-side-encryption-customer-algorithm: AES256x-amz-server-side-encryption-customer-key-MD5: AAAAAAAAAAAAAAAAAAAAAAREPLICATION_CHECK_SSEC_PROBE_KEY_MD5语法合法的占位 MD5x-amz-server-side-encryption-customer-original-size: 8通过复制检查通道replication-check 通道对该探针版本执行HEAD-back带replication_check豁免与代理抑制检查 HEAD 响应是否回显x-amz-server-side-encryption-customer-algorithm。一个 RustFS 目标会把透传头还原为存储的 SSE-C 元数据并在 HEAD 时回显该算法头而丢弃头部的目标如 MinIO、通用 S3存下的是普通对象HEAD 时什么也不回显。探针对象本身从不真正做 SSE-C 加密只需要元数据往返探针体始终是 8 字节明文。与 VersionFidelity 的关键区别文档与源码router.rs#L2297-L2327都强调一个设计取舍SsecPassthrough 失败不会导致目标整体 FAILED。版本身份漂移破坏的是每一个对象的复制契约因此必须让目标变红而丢弃 SSE-C 透传头只是限制了一项能力——一个纯明文部署、对 MinIO 目标复制是完全健康的不应该变红。该阶段自己的FAILED状态与机器可读错误码BucketRemoteSsecPassthroughUnsupportedREPLICATION_CHECK_CODE_SSEC_PASSTHROUGH仍会保留在响应中供 madmin 消费者使用裁决同样会写入BucketTargetSys能力缓存SsecPassthroughCapability::Supported/Unsupportedrouter.rs#L2090-L2102让复制工作线程对标记目标失败关闭fail closedSSE-C 复制。端到端测试test_replication_check_flags_ssec_passthrough_dropping_targetreplication_extension_test.rs#L5027覆盖了该场景而test_replication_check_succeeds_with_remote_target则断言 RustFS 目标在该阶段返回OK。七、错误信息的安全性设计Error字段的约束单行、≤512 字节、不含敏感信息由两个函数共同保证bound_replication_check_errorrouter.rs#L1880-L1892先把\r、\n替换为空格确保单行再按REPLICATION_CHECK_ERROR_MAX_BYTES截断截断时回退到 UTF-8 字符边界以避免截断多字节字符并追加...format_replication_check_client_errorrouter.rs#L1894-L1931对远端错误做结构化映射只暴露 S3 错误码而非原始消息——因为远端消息与传输错误可能回显签名 URL、凭证或端点 user-info对不受信任的调用方返回这些内容是危险的AccessDenied会按阶段映射为可操作的权限提示如s3:ReplicateObject permissions missing for replication user、s3:ReplicateDelete permissions missing for replication user、s3:ReplicateDelete/s3:DeleteObject permissions missing for replication userNoSuchBucket/NotFound映射为target bucket does not exist纯字母数字的 S3 错误码原样保留其余一律收敛为remote request failed。单元测试replication_check_error_is_single_line_and_bounded与replication_check_unknown_transport_error_does_not_expose_secretsrouter.rs#L4329、router.rs#L4356分别验证了截断边界与敏感信息过滤。八、调用方式与验证路径发起请求接口需要 SigV4 签名方法是GET路径为桶级查询。端到端测试给出了精确的调用形态replication_extension_test.rs#L1572-L1578GET /bucket?replication-check示例使用 curl 风格占位示意# 以 SigV4 签名后的 GET 请求为例 curl -X GET https://rustfs-endpoint/bucket?replication-check \ -H Authorization: AWS4-HMAC-SHA256 ... \ -H x-amz-date: timestamp响应为 HTTP 200 JSON顶层Status与Targets[].Phases是判断健康与否的依据。ActiveMutation: true始终出现在响应中提醒调用方该操作在目标上留下了探针痕迹随后已被清理。仓库内可验证的测试覆盖端到端测试crates/e2e_test/src/replication_extension_test.rs覆盖成功路径全部阶段OK且探针产物清零、目标未开启对象锁、源桶未开启版本控制、缺少复制配置、桶不存在、同部署自指目标、版本铸造目标单路径与仅 multipart 路径、SSE-C 透传被丢弃的目标、multipart 探针失败中止等场景单元测试rustfs/src/admin/router.rs#L3899-L4493覆盖响应构造记录主动变更、保留部分目标结果、空目标列表运行时拒绝、错误截断与脱敏、AccessDenied 按阶段映射、目标过滤、过期目标拒绝等行为。九、实操排查指引结合本文档与源码实现使用该接口排查复制问题时可按以下思路进行先确认前置条件源桶版本控制已开启、复制配置存在、至少一个目标已注册且 ARN 一致——否则请求会在入口被InvalidRequest拒绝整体看StatusOK表示所有目标全部阶段通过FAILED则需要逐个目标查看Phases逐阶段定位按Bucket → Versioning → ObjectLock → Put → VersionFidelity → SsecPassthrough → DeleteMarker → VersionDelete → Cleanup顺序阅读。靠前的阶段失败如Bucket、Versioning通常是目标配置问题Put失败通常是复制凭证缺少s3:ReplicateObject权限Cleanup失败通常是缺少s3:ReplicateDelete/s3:DeleteObject权限——错误文本已经给出了对应的权限提示关注Code字段出现BucketRemoteTargetVersionMismatch说明目标自行铸造版本 ID版本寻址的复制版本删除、修复无法在该目标收敛——此时应检查目标是否为 RustFS或确认复制配置是否需要更换目标出现BucketRemoteSsecPassthroughUnsupported说明目标丢弃 SSE-C 透传头SSE-C 副本存在解密材料丢失风险复制工作线程会据此对 SSE-C 复制失败关闭纯明文部署则可忽略验证无残留检查完成后可在目标桶上用list_object_versions按前缀.rustfs.sys/replication-check/枚举应无任何版本与删除标记残留——这也是仓库端到端测试对成功路径的断言方式。十、小结GET /BUCKET?replication-check是 RustFS 复制运维中最具信息量的单一诊断接口它以一次带签名的 GET 完成对每个复制目标的桶可达性、版本控制、对象锁、写入能力、版本身份契约PutObject 与 multipart 双路径、SSE-C 透传能力、删除路径与残留清理的九阶段端到端验证。理解其主动变更性质、OK/FAILED/SKIPPED三态语义、Code错误码的分支含义以及版本账本寻址与运行时能力缓存机制是正确解读检查结果、自动化复制健康监控的前提。源码实现位于 rustfs/src/admin/router.rs完整行为契约与测试佐证可对照 crates/e2e_test/src/replication_extension_test.rs 与本文档 docs/operations/replication-check.md 本身阅读。【免费下载链接】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），仅供参考