RustFS KMS 管理 API 契约路由、IAM 动作与密钥列表分页规则全解【免费下载链接】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/operations/kms-admin-contract.md 为骨架系统讲解 KMS 管理面Admin API的完整契约每一个/rustfs/admin/v3/kms/*端点对应的 IAM 动作、风险等级、是否为 per-key 授权以及GET /kms/keys密钥列表的严格分页规则。无论你是要接入 CLI、控制台还是自动化脚本还是需要编写 IAM 策略来收紧 KMS 权限读完后都能准确判断每个路由的授权语义并写出可正确翻页、可容忍损坏密钥记录的客户端。适用范围与事实来源本文适用于将客户端CLI、控制台、自动化脚本接入 RustFS KMS 管理端点的场景核心需要明确三件事每条路由所需的 IAM 动作、风险等级、以及密钥列表的分页规则。文档的事实来源均可直接在本仓库中核对rustfs/src/admin/route_policy.rs每个路由的 action 与风险等级定义由 rustfs/src/admin/route_registration_test.rs 断言保证路由注册与策略一致crates/kms/src/backends/mod.rsDEFAULT_LIST_KEYS_PAGE_SIZE、MAX_LIST_KEYS_PAGE_SIZE、list_keys_page_size等分页常量与切页逻辑crates/kms/src/snapshots/ 与 rustfs/src/admin/handlers/snapshots/各端点的响应形状由快照测试锁定。所有 KMS 管理端点的 wire 前缀均为/rustfs/admin/v3。其中GET /kms/status与GET /kms/service-status返回不同类型的响应/kms/status上的capabilities字段是增量式additive且可选的。Per-key 列表示该路由是否针对其命名的密钥进行授权详见 Per-key KMS 授权值为no表示该路由匹配调用者策略中的任意 KMS 资源。端点矩阵完整路由、动作与风险等级下表是全部 KMS 管理端点的权威清单来自 rustfs/src/admin/route_policy.rs 中ADMIN_ROUTE_POLICY_SPECS的 KMS 段落route_policy.rs 第 816-939 行与原文档逐条对应Method and endpointIAM actionRiskPer-keyNotesPOST /kms/configurekms:Configurehighno持久化到集群存储、切换本节点、向对端广播尽力而为的重载POST /kms/reconfigurekms:Configurehighno与 configure 契约相同POST /kms/startkms:ServiceControlhighnoPOST /kms/stopkms:ServiceControlhighnoPOST /kms/reloadkms:ServiceControlhighno重新读取持久化配置而不重新提交密钥复用 configure 的响应形状GET /kms/statuskms:ServiceControlsensitiveno后端类型加能力矩阵POST /kms/statuskms:ServiceControlhighno兼容路由不是客户端命令GET /kms/service-statuskms:ServiceControlsensitiveno携带cluster_config指纹与consistent标志GET /kms/configkms:Configuresensitiveno包含运维路径展示前必须脱敏POST /kms/clear-cachekms:ClearCachehighno返回KmsClearCacheResponse{status,message}POST /kms/keyskms:Configurehighno创建密钥与配置共用 Configure 动作GET /kms/keyskms:ListKeyssensitiveno见下文密钥列表契约GET /kms/keys/{key_id}kms:DescribeKeysensitiveyes?impacttrue可选返回配置引用报告DELETE /kms/keys/deletekms:DeleteKeycriticalyesJSON bodyforce_immediate还需要confirm_key_id和服务端RUSTFS_KMS_ALLOW_IMMEDIATE_DELETION开关POST /kms/keys/cancel-deletionkms:DeleteKeyhighyesPOST /kms/keys/enablekms:EnableKeyhighyesPOST /kms/keys/disablekms:DisableKeyhighyesPOST /kms/keys/rotatekms:RotateKeyhighyes受 KMS 后端安全属性 中的轮换约束约束POST /kms/keys/rekeykms:Rekeyhighno批量 DEK 重包裹扫描集群范围见 KMS 批量 Rekey 契约GET /kms/keys/rekey/statuskms:RekeysensitivenoPOST /kms/keys/rekey/cancelkms:RekeyhighnoPOST /kms/keys/update-descriptionkms:UpdateKeyDescriptionhighyesPOST /kms/keys/tagkms:TagResourcehighyesPOST /kms/keys/untagkms:UntagResourcehighyesPOST /kms/generate-data-keykms:GenerateDataKeyhighyes响应携带 base64 明文数据密钥绝不可在 UI 或 CLI 中展示GET /kms/backupkms:Backupsensitiveno仅状态与就绪信息不含 KEK 材料POST /kms/backupkms:Backuphighno仅返回backup_id与元数据POST /kms/restore/dry-runkms:Restoresensitiveno预检不写任何数据POST /kms/restorekms:Restorehighno需要confirm_backup_id与confirm_conflict_policyPOST /kms/restore/abortkms:Restorehighno需要confirm_target_key_dirPOST /kms/create-key,POST /kms/key/createkms:Configurehighnomc遗留别名等价POST /kms/keys密钥名来自key-id查询参数mc的形态或name标签两者同时携带且值不同时以400拒绝GET /kms/describe-key,GET /kms/key/statuskms:DescribeKeysensitiveyesGET /kms/keys/{key_id}的遗留别名GET /kms/list-keyskms:ListKeyssensitivenoGET /kms/keys的遗留别名列表契约相同注意上表中的端点均省略了统一前缀/rustfs/admin/v3实际请求形如POST /rustfs/admin/v3/kms/configure。风险等级背后的设计意图风险等级不是随意标注的源码注释直接给出了理由理解它有助于在接入时正确对待每个端点DELETE /kms/keys/delete是唯一一个critical级别的 KMS 路由。源码注释route_policy.rs 第 868-878 行明确指出销毁主密钥会让所有在其下加密的对象永久不可读且服务端没有任何机制能恢复这些对象。等待窗口pending-deletion与 cancel-deletion 是唯一的恢复路径——这正是POST /kms/keys/cancel-deletion只保持high级别的原因POST /kms/keys/rekey使用独立的集群范围kms:Rekey动作而不是复用某个 per-key 动作。源码注释route_policy.rs 第 900-901 行说明rekey 扫描会跨 bucket 遍历并重写对象元数据因此需要独立的集群级授权kms:Backup与kms:Restore同样使用独立动作因为它们作用于所有密钥的材料而非某个具体密钥route_policy.rs 第 915-916 行密钥创建与后端配置共用kms:Configure这意味着“创建密钥”在权限模型上是集群管理员的职责而不是密钥管理者的职责见 Per-key KMS 授权 的说明。各端点组的职责划分从端点矩阵可以清晰地划分出四组职责服务控制组kms:ServiceControlstart/stop/reload/status/service-status负责 KMS 服务的启停、配置重载与状态查看。其中service-status返回的cluster_config携带每个节点的配置指纹与consistent标志可用于检测集群内 KMS 配置分叉详见 KMS 后端安全属性密钥生命周期组per-key 动作创建kms:Configure、DescribeKey、EnableKey、DisableKey、RotateKey、DeleteKey、UpdateKeyDescription、TagResource/UntagResource以及批量Rekey数据密钥组generate-data-keykms:GenerateDataKey是 SSE-KMS 数据路径的核心动作备份恢复组kms:Backup/kms:Restorebackup、restore/dry-run、restore、restore/abort以及clear-cachekms:ClearCache。Per-key 授权谁可以对哪个密钥做什么端点矩阵中的Per-key列是本契约的核心概念之一值为yes的路由会针对请求命名的那个密钥进行授权。密钥标识取自请求体的key_id字段回退到keyId查询参数。而值为no的路由如GET /kms/keys匹配调用者策略中的任意 KMS 资源。RustFS 的 KMS 授权基于身份策略identity policy一条语句可以限定其适用的密钥因此授予kms:DisableKey不再意味着对集群内所有密钥生效。KMS 资源使用与 S3 相同的空账号 ARN 形态模式匹配arn:aws:kms:::key/key_id恰好该密钥arn:aws:kms:::key/app-*所有以app-开头的密钥 idarn:aws:kms:::*所有密钥arn:aws:kms:::alias/name保留别名解析落地前不匹配任何内容编写策略时有几条硬规则混用kms:与s3:动作的语句会被拒绝携带 KMS 资源但动作不是 KMS 动作的语句会被拒绝Deny优先于Allow。仓库内置了三个 KMS 角色模板KMSKeyAdministrator密钥生命周期治理、KMSKeyUser读写 SSE-KMS 对象的工作负载、KMSAuditor仅可见性。三者均不授予kms:Configure、kms:ServiceControl、kms:ClearCache、kms:Backup或kms:Restore这些集群管理权限保留给consoleAdmin——这与本文端点矩阵中 per-key 动作与集群动作的划分完全一致。详细的资源语法、模板清单与 SSE-KMS 数据路径强制RUSTFS_KMS_ENFORCE_SSE_KEY_POLICY参见 Per-key KMS 授权。密钥列表契约GET /kms/keysGET /kms/keys以及遗留别名GET /kms/list-keys共享同一个列表契约。这条契约是接入 KMS 客户端时最容易出错的部分下面逐条展开。limit缺省、非法值与上限limit是可选参数。缺省时服务端应用DEFAULT_LIST_KEYS_PAGE_SIZE100一旦提供就必须能解析为非负整数limitabc、limit-1以及无值的limit都会以400拒绝而不会静默按缺省值处理limit0是合法的“请求空页”请求返回空页任何超过MAX_LIST_KEYS_PAGE_SIZE1000的页大小都被按 1000 提供——响应带truncated和可用的next_marker因此只要客户端一直翻页直到truncated为 false仍能到达每一个密钥客户端绝不能假设返回的页就是它请求的大小。源码实现印证了这些规则。在 crates/kms/src/backends/mod.rs 第 163-172 行 中两个常量被明确定义pub(crate) const DEFAULT_LIST_KEYS_PAGE_SIZE: u32 100; pub(crate) const MAX_LIST_KEYS_PAGE_SIZE: u32 1_000;而list_keys_page_sizemod.rs 第 244-249 行实现了解析逻辑Some(0)返回None表示“请求了零个密钥”大于上限的值被 clamp 到上限而非拒绝。该函数带有单元测试覆盖mod.rs 第 1001-1041 行包括limit0、u32::MAXclamp 到 1000 等边界。常量注释解释了为何必须设上限一页并不是廉价的切片——列出的每个标识符都要消耗后端一次元数据查找Local 上是磁盘读Vault Transit 上是 HTTP 往返无界的limit会把一次请求变成对密钥存储的无界扇出fan-out。上限在切页处统一应用任何后端都无法绕过。marker不透明的游标marker对客户端是不透明的应把它当作一个原样回传的游标绝不能当作可以自行构造的值。具体语义因后端而异在Local、Vault KV2、Vault Transit、Static后端上它恰好是密钥标识符的排他下界exclusive lower bound——这正是分页能在列表过程中经受密钥创建/销毁而不出错的原因在AWS后端上它是 AWS 自己的分页令牌向其发送密钥 id 会被拒绝空marker等价于没有 marker。分页的实现位于paginate_keysmod.rs 第 201-231 行通过partition_point找到第一个大于 marker 的标识符作为起点next_marker取当前页最后一个标识符。注释特别强调marker 是标识符上的排他下界而非序列索引因此密钥在排序中的任何位置被新增或删除——包括 marker 指向的密钥本身被删除——都不会导致列表跳过密钥或从头开始。过滤器filter在切页之后应用因此被过滤后的页可能很短——甚至为空——而后面仍有更多密钥。客户端必须翻页直到truncated为 false而不是直到某页返回变短为止。unreadable_key_ids损坏密钥的诚实报告unreadable_key_ids仅当服务端列出了某个密钥但其记录无法描述时出现——例如由更新版本构建写入的记录或已损坏的材料。关键设计原则是这些标识符被报告而非省略因此列表永远不会悄悄低估密钥集合展示清单的客户端应将其标记为损坏而不是丢弃分页总是越过损坏密钥继续前进与具体密钥无关的失败超时、5xx、权限拒绝仍会使整个列表失败而不会出现在此字段中。该字段的定义位于 crates/kms/src/types.rs 第 491-510 行 的ListKeysResponse结构包含keys、next_marker、truncated和unreadable_key_ids四个字段。类型注释解释了其存在理由无法解释的密钥记录绝不能从keys中悄然消失否则库存会误读为“你没有这个密钥”而删除扫描的普查也会基于一个从未完整看到的密钥集合进行。后端层面对应的分类逻辑在 mod.rs 第 266-276 行 的ListedKeyFailure枚举中Vanished密钥在扫描与读取之间消失正常现象丢弃并前进与Unreadable记录仍在存储中但当前构建无法解释通过unreadable_key_ids上报而非省略或变成整页失败。响应形状由快照锁定参见 rustfs__admin__handlers__kms_keys__tests__kms_admin_list_keys_response_with_unreadable_keys.snap 与 rustfs__admin__handlers__kms_keys__tests__kms_admin_list_keys_api_response.snap。一个刻意的错误而非报告全空且不可读有一个场景被刻意设计为错误而不是报告一次覆盖了整个密钥集合的列表——即没有marker且truncated为 false——其中没有任何密钥可读。此时若返回空的keys数组任何在此字段出现之前编写的客户端都无法区分“没有密钥的部署”和“全部损坏的部署”而前者通常的处理方式是去新建密钥。因此这种情况返回500并指名第一个失败具体标识符记录在服务端日志中。而截断的页或从 marker 恢复的页总是报告而非失败所以损坏的密钥永远不会“卡住”它后面的密钥。相关文档导航本契约与以下运维文档紧密关联接入或排障时可组合阅读KMS 管理 API 契约本文档路由、动作与分页规则Per-key KMS 授权资源语法、内置角色模板、SSE-KMS 数据路径强制与迁移路径KMS 后端安全属性主密钥轮换、保留、销毁与升级顺序各后端的能力与保密边界KMS 批量 Rekey 契约POST /kms/keys/rekey批量重包裹作业的完整验收标准Vault KMS 认证手册Vault 凭证来源、刷新与 fail-closed 窗口KMS 可观测性手册KmsKeyRotationOverdue等告警与监控指标KMS 灾难恢复演练密钥目录与备份恢复的演练流程。接入时建议遵循的实践要点客户端永远按truncated翻页对unreadable_key_ids以“损坏”呈现而非丢弃对GET /kms/status与GET /kms/service-status分别处理两种不同的响应类型在展示GET /kms/config结果前先脱敏generate-data-key返回的明文数据密钥绝不落入 UI 或日志。【免费下载链接】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），仅供参考 
长河君 · 2026/9/11 20:38:16 · 阅读 1.2k RustFS KMS 管理 API 契约：路由、IAM 动作与密钥列表分页规则全解
RustFS KMS 管理 API 契约路由、IAM 动作与密钥列表分页规则全解【免费下载链接】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/operations/kms-admin-contract.md 为骨架系统讲解 KMS 管理面Admin API的完整契约每一个/rustfs/admin/v3/kms/*端点对应的 IAM 动作、风险等级、是否为 per-key 授权以及GET /kms/keys密钥列表的严格分页规则。无论你是要接入 CLI、控制台还是自动化脚本还是需要编写 IAM 策略来收紧 KMS 权限读完后都能准确判断每个路由的授权语义并写出可正确翻页、可容忍损坏密钥记录的客户端。适用范围与事实来源本文适用于将客户端CLI、控制台、自动化脚本接入 RustFS KMS 管理端点的场景核心需要明确三件事每条路由所需的 IAM 动作、风险等级、以及密钥列表的分页规则。文档的事实来源均可直接在本仓库中核对rustfs/src/admin/route_policy.rs每个路由的 action 与风险等级定义由 rustfs/src/admin/route_registration_test.rs 断言保证路由注册与策略一致crates/kms/src/backends/mod.rsDEFAULT_LIST_KEYS_PAGE_SIZE、MAX_LIST_KEYS_PAGE_SIZE、list_keys_page_size等分页常量与切页逻辑crates/kms/src/snapshots/ 与 rustfs/src/admin/handlers/snapshots/各端点的响应形状由快照测试锁定。所有 KMS 管理端点的 wire 前缀均为/rustfs/admin/v3。其中GET /kms/status与GET /kms/service-status返回不同类型的响应/kms/status上的capabilities字段是增量式additive且可选的。Per-key 列表示该路由是否针对其命名的密钥进行授权详见 Per-key KMS 授权值为no表示该路由匹配调用者策略中的任意 KMS 资源。端点矩阵完整路由、动作与风险等级下表是全部 KMS 管理端点的权威清单来自 rustfs/src/admin/route_policy.rs 中ADMIN_ROUTE_POLICY_SPECS的 KMS 段落route_policy.rs 第 816-939 行与原文档逐条对应Method and endpointIAM actionRiskPer-keyNotesPOST /kms/configurekms:Configurehighno持久化到集群存储、切换本节点、向对端广播尽力而为的重载POST /kms/reconfigurekms:Configurehighno与 configure 契约相同POST /kms/startkms:ServiceControlhighnoPOST /kms/stopkms:ServiceControlhighnoPOST /kms/reloadkms:ServiceControlhighno重新读取持久化配置而不重新提交密钥复用 configure 的响应形状GET /kms/statuskms:ServiceControlsensitiveno后端类型加能力矩阵POST /kms/statuskms:ServiceControlhighno兼容路由不是客户端命令GET /kms/service-statuskms:ServiceControlsensitiveno携带cluster_config指纹与consistent标志GET /kms/configkms:Configuresensitiveno包含运维路径展示前必须脱敏POST /kms/clear-cachekms:ClearCachehighno返回KmsClearCacheResponse{status,message}POST /kms/keyskms:Configurehighno创建密钥与配置共用 Configure 动作GET /kms/keyskms:ListKeyssensitiveno见下文密钥列表契约GET /kms/keys/{key_id}kms:DescribeKeysensitiveyes?impacttrue可选返回配置引用报告DELETE /kms/keys/deletekms:DeleteKeycriticalyesJSON bodyforce_immediate还需要confirm_key_id和服务端RUSTFS_KMS_ALLOW_IMMEDIATE_DELETION开关POST /kms/keys/cancel-deletionkms:DeleteKeyhighyesPOST /kms/keys/enablekms:EnableKeyhighyesPOST /kms/keys/disablekms:DisableKeyhighyesPOST /kms/keys/rotatekms:RotateKeyhighyes受 KMS 后端安全属性 中的轮换约束约束POST /kms/keys/rekeykms:Rekeyhighno批量 DEK 重包裹扫描集群范围见 KMS 批量 Rekey 契约GET /kms/keys/rekey/statuskms:RekeysensitivenoPOST /kms/keys/rekey/cancelkms:RekeyhighnoPOST /kms/keys/update-descriptionkms:UpdateKeyDescriptionhighyesPOST /kms/keys/tagkms:TagResourcehighyesPOST /kms/keys/untagkms:UntagResourcehighyesPOST /kms/generate-data-keykms:GenerateDataKeyhighyes响应携带 base64 明文数据密钥绝不可在 UI 或 CLI 中展示GET /kms/backupkms:Backupsensitiveno仅状态与就绪信息不含 KEK 材料POST /kms/backupkms:Backuphighno仅返回backup_id与元数据POST /kms/restore/dry-runkms:Restoresensitiveno预检不写任何数据POST /kms/restorekms:Restorehighno需要confirm_backup_id与confirm_conflict_policyPOST /kms/restore/abortkms:Restorehighno需要confirm_target_key_dirPOST /kms/create-key,POST /kms/key/createkms:Configurehighnomc遗留别名等价POST /kms/keys密钥名来自key-id查询参数mc的形态或name标签两者同时携带且值不同时以400拒绝GET /kms/describe-key,GET /kms/key/statuskms:DescribeKeysensitiveyesGET /kms/keys/{key_id}的遗留别名GET /kms/list-keyskms:ListKeyssensitivenoGET /kms/keys的遗留别名列表契约相同注意上表中的端点均省略了统一前缀/rustfs/admin/v3实际请求形如POST /rustfs/admin/v3/kms/configure。风险等级背后的设计意图风险等级不是随意标注的源码注释直接给出了理由理解它有助于在接入时正确对待每个端点DELETE /kms/keys/delete是唯一一个critical级别的 KMS 路由。源码注释route_policy.rs 第 868-878 行明确指出销毁主密钥会让所有在其下加密的对象永久不可读且服务端没有任何机制能恢复这些对象。等待窗口pending-deletion与 cancel-deletion 是唯一的恢复路径——这正是POST /kms/keys/cancel-deletion只保持high级别的原因POST /kms/keys/rekey使用独立的集群范围kms:Rekey动作而不是复用某个 per-key 动作。源码注释route_policy.rs 第 900-901 行说明rekey 扫描会跨 bucket 遍历并重写对象元数据因此需要独立的集群级授权kms:Backup与kms:Restore同样使用独立动作因为它们作用于所有密钥的材料而非某个具体密钥route_policy.rs 第 915-916 行密钥创建与后端配置共用kms:Configure这意味着“创建密钥”在权限模型上是集群管理员的职责而不是密钥管理者的职责见 Per-key KMS 授权 的说明。各端点组的职责划分从端点矩阵可以清晰地划分出四组职责服务控制组kms:ServiceControlstart/stop/reload/status/service-status负责 KMS 服务的启停、配置重载与状态查看。其中service-status返回的cluster_config携带每个节点的配置指纹与consistent标志可用于检测集群内 KMS 配置分叉详见 KMS 后端安全属性密钥生命周期组per-key 动作创建kms:Configure、DescribeKey、EnableKey、DisableKey、RotateKey、DeleteKey、UpdateKeyDescription、TagResource/UntagResource以及批量Rekey数据密钥组generate-data-keykms:GenerateDataKey是 SSE-KMS 数据路径的核心动作备份恢复组kms:Backup/kms:Restorebackup、restore/dry-run、restore、restore/abort以及clear-cachekms:ClearCache。Per-key 授权谁可以对哪个密钥做什么端点矩阵中的Per-key列是本契约的核心概念之一值为yes的路由会针对请求命名的那个密钥进行授权。密钥标识取自请求体的key_id字段回退到keyId查询参数。而值为no的路由如GET /kms/keys匹配调用者策略中的任意 KMS 资源。RustFS 的 KMS 授权基于身份策略identity policy一条语句可以限定其适用的密钥因此授予kms:DisableKey不再意味着对集群内所有密钥生效。KMS 资源使用与 S3 相同的空账号 ARN 形态模式匹配arn:aws:kms:::key/key_id恰好该密钥arn:aws:kms:::key/app-*所有以app-开头的密钥 idarn:aws:kms:::*所有密钥arn:aws:kms:::alias/name保留别名解析落地前不匹配任何内容编写策略时有几条硬规则混用kms:与s3:动作的语句会被拒绝携带 KMS 资源但动作不是 KMS 动作的语句会被拒绝Deny优先于Allow。仓库内置了三个 KMS 角色模板KMSKeyAdministrator密钥生命周期治理、KMSKeyUser读写 SSE-KMS 对象的工作负载、KMSAuditor仅可见性。三者均不授予kms:Configure、kms:ServiceControl、kms:ClearCache、kms:Backup或kms:Restore这些集群管理权限保留给consoleAdmin——这与本文端点矩阵中 per-key 动作与集群动作的划分完全一致。详细的资源语法、模板清单与 SSE-KMS 数据路径强制RUSTFS_KMS_ENFORCE_SSE_KEY_POLICY参见 Per-key KMS 授权。密钥列表契约GET /kms/keysGET /kms/keys以及遗留别名GET /kms/list-keys共享同一个列表契约。这条契约是接入 KMS 客户端时最容易出错的部分下面逐条展开。limit缺省、非法值与上限limit是可选参数。缺省时服务端应用DEFAULT_LIST_KEYS_PAGE_SIZE100一旦提供就必须能解析为非负整数limitabc、limit-1以及无值的limit都会以400拒绝而不会静默按缺省值处理limit0是合法的“请求空页”请求返回空页任何超过MAX_LIST_KEYS_PAGE_SIZE1000的页大小都被按 1000 提供——响应带truncated和可用的next_marker因此只要客户端一直翻页直到truncated为 false仍能到达每一个密钥客户端绝不能假设返回的页就是它请求的大小。源码实现印证了这些规则。在 crates/kms/src/backends/mod.rs 第 163-172 行 中两个常量被明确定义pub(crate) const DEFAULT_LIST_KEYS_PAGE_SIZE: u32 100; pub(crate) const MAX_LIST_KEYS_PAGE_SIZE: u32 1_000;而list_keys_page_sizemod.rs 第 244-249 行实现了解析逻辑Some(0)返回None表示“请求了零个密钥”大于上限的值被 clamp 到上限而非拒绝。该函数带有单元测试覆盖mod.rs 第 1001-1041 行包括limit0、u32::MAXclamp 到 1000 等边界。常量注释解释了为何必须设上限一页并不是廉价的切片——列出的每个标识符都要消耗后端一次元数据查找Local 上是磁盘读Vault Transit 上是 HTTP 往返无界的limit会把一次请求变成对密钥存储的无界扇出fan-out。上限在切页处统一应用任何后端都无法绕过。marker不透明的游标marker对客户端是不透明的应把它当作一个原样回传的游标绝不能当作可以自行构造的值。具体语义因后端而异在Local、Vault KV2、Vault Transit、Static后端上它恰好是密钥标识符的排他下界exclusive lower bound——这正是分页能在列表过程中经受密钥创建/销毁而不出错的原因在AWS后端上它是 AWS 自己的分页令牌向其发送密钥 id 会被拒绝空marker等价于没有 marker。分页的实现位于paginate_keysmod.rs 第 201-231 行通过partition_point找到第一个大于 marker 的标识符作为起点next_marker取当前页最后一个标识符。注释特别强调marker 是标识符上的排他下界而非序列索引因此密钥在排序中的任何位置被新增或删除——包括 marker 指向的密钥本身被删除——都不会导致列表跳过密钥或从头开始。过滤器filter在切页之后应用因此被过滤后的页可能很短——甚至为空——而后面仍有更多密钥。客户端必须翻页直到truncated为 false而不是直到某页返回变短为止。unreadable_key_ids损坏密钥的诚实报告unreadable_key_ids仅当服务端列出了某个密钥但其记录无法描述时出现——例如由更新版本构建写入的记录或已损坏的材料。关键设计原则是这些标识符被报告而非省略因此列表永远不会悄悄低估密钥集合展示清单的客户端应将其标记为损坏而不是丢弃分页总是越过损坏密钥继续前进与具体密钥无关的失败超时、5xx、权限拒绝仍会使整个列表失败而不会出现在此字段中。该字段的定义位于 crates/kms/src/types.rs 第 491-510 行 的ListKeysResponse结构包含keys、next_marker、truncated和unreadable_key_ids四个字段。类型注释解释了其存在理由无法解释的密钥记录绝不能从keys中悄然消失否则库存会误读为“你没有这个密钥”而删除扫描的普查也会基于一个从未完整看到的密钥集合进行。后端层面对应的分类逻辑在 mod.rs 第 266-276 行 的ListedKeyFailure枚举中Vanished密钥在扫描与读取之间消失正常现象丢弃并前进与Unreadable记录仍在存储中但当前构建无法解释通过unreadable_key_ids上报而非省略或变成整页失败。响应形状由快照锁定参见 rustfs__admin__handlers__kms_keys__tests__kms_admin_list_keys_response_with_unreadable_keys.snap 与 rustfs__admin__handlers__kms_keys__tests__kms_admin_list_keys_api_response.snap。一个刻意的错误而非报告全空且不可读有一个场景被刻意设计为错误而不是报告一次覆盖了整个密钥集合的列表——即没有marker且truncated为 false——其中没有任何密钥可读。此时若返回空的keys数组任何在此字段出现之前编写的客户端都无法区分“没有密钥的部署”和“全部损坏的部署”而前者通常的处理方式是去新建密钥。因此这种情况返回500并指名第一个失败具体标识符记录在服务端日志中。而截断的页或从 marker 恢复的页总是报告而非失败所以损坏的密钥永远不会“卡住”它后面的密钥。相关文档导航本契约与以下运维文档紧密关联接入或排障时可组合阅读KMS 管理 API 契约本文档路由、动作与分页规则Per-key KMS 授权资源语法、内置角色模板、SSE-KMS 数据路径强制与迁移路径KMS 后端安全属性主密钥轮换、保留、销毁与升级顺序各后端的能力与保密边界KMS 批量 Rekey 契约POST /kms/keys/rekey批量重包裹作业的完整验收标准Vault KMS 认证手册Vault 凭证来源、刷新与 fail-closed 窗口KMS 可观测性手册KmsKeyRotationOverdue等告警与监控指标KMS 灾难恢复演练密钥目录与备份恢复的演练流程。接入时建议遵循的实践要点客户端永远按truncated翻页对unreadable_key_ids以“损坏”呈现而非丢弃对GET /kms/status与GET /kms/service-status分别处理两种不同的响应类型在展示GET /kms/config结果前先脱敏generate-data-key返回的明文数据密钥绝不落入 UI 或日志。【免费下载链接】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），仅供参考