MinIO Bucket Quota 实战指南：配置、验证与清理硬性配额及其源码级实现剖析

本篇指南围绕 MinIO 的桶级配额（Bucket Quota）功能展开，完整覆盖通过 mc 客户端设置 Hard 配额、验证配额状态、清除配额配置的全部操作步骤；并结合开源仓库源码，深入剖析配额配置是如何持久化、如何在 PutObject / CopyObject / Multipart 写入路径中被强制校验、超限后返回什么错误。读完本文，你将既能直接上手配置生产环境的桶配额，也能理解其底层执行机制，便于排障与二次开发参考。

一、功能定位：什么是 Bucket Quota

MinIO 允许为桶配置 Hard（硬性）配额——当桶内对象占用的空间达到配置的配额上限后，系统禁止向该桶继续写入数据。这是一种容量管控手段：

• 防止某个桶（例如某个租户、某类业务数据）无节制地占用存储资源；
• 配额以桶为粒度生效，超限时新的写入请求（PutObject、CopyObject、Multipart 分片上传等）会被直接拒绝；
• 配额配置随桶元数据持久化保存，不会因服务重启丢失。

说明：从源码 parseBucketQuota 的校验逻辑（cmd/bucket-quota.go）可以看到，早期版本的 fifo 配额类型已被移除并明确报为非法类型，官方提示改用 mc quota clear 清理旧配置、用 mc ilm add 配置对象过期策略替代。当前仓库支持的有效配额类型即本文重点介绍的 hard 类型。

二、前置条件

• 已安装并启动 MinIO Server（可参考仓库中的部署文档 docs/docker/README.md、docs/orchestration/README.md）。
• 已安装 mc 客户端并为其配置了指向 MinIO Server 的 alias（如 myminio）。

mc 的 admin bucket quota 命令对应服务端 Admin API 的两条路由，定义在 cmd/admin-router.go：

// GetBucketQuotaConfig
adminMiddleware(adminAPI.GetBucketQuotaConfigHandler)).Queries("bucket", "{bucket:.*}")
// PutBucketQuotaConfig
adminMiddleware(adminAPI.PutBucketQuotaConfigHandler)).Queries("bucket", "{bucket:.*}")

三、设置桶的硬性配额

1. 为 mybucket 设置 1GB 硬性配额

mc admin bucket quota myminio/mybucket --hard 1gb

该命令最终会触发服务端的 PutBucketQuotaConfigHandler（cmd/admin-bucket-handlers.go），其处理链路为：

1. 通过 validateAdminReq 校验管理员签名与权限（要求 SetBucketQuota admin action，即策略中的 SetBucketQuotaAdminAction）；
2. 确认目标桶真实存在（GetBucketInfo）；
3. 读取请求体并调用 parseBucketQuota 反序列化、校验配额配置合法性；
4. 调用 globalBucketMetadataSys.Update(ctx, bucket, bucketQuotaConfigFile, data) 将配额持久化到桶元数据文件 quota.json（常量定义见 cmd/admin-bucket-handlers.go：bucketQuotaConfigFile = "quota.json"）；
5. 若开启了站点复制（Site Replication），会通过 globalSiteReplicationSys.BucketMetaHook 把配额配置变更同步到远端站点。

2. 配额值解析的细节：Size 与 Quota

enforceQuotaHard（cmd/bucket-quota.go）在确定生效的配额字节数时做了兼容处理：

var quotaSize uint64
if q != nil && q.Type == madmin.HardQuota {
    if q.Size > 0 {
        quotaSize = q.Size
    } else if q.Quota > 0 {
        quotaSize = q.Quota
    }
}

即：优先采用 Size 字段，若为 0 则回退读取 Quota 字段。二者皆为 0 时不执行配额强制——这也正是"清除配额"（清零）能够解除限制的原因。

四、验证已配置的配额

mc admin bucket quota myminio/mybucket

对应服务端 GetBucketQuotaConfigHandler（cmd/admin-bucket-handlers.go）：校验 GetBucketQuota admin 权限与桶存在性后，调用 globalBucketMetadataSys.GetQuotaConfig 从桶元数据中读出 quota.json 的内容，JSON 序列化后原样返回给客户端。因此该命令输出的就是当前桶上持久化的配额配置本身（类型与配额大小），可用于变更后的状态核对。

五、清除桶的配额配置

mc admin bucket quota myminio/mybucket --clear

--clear 本质上是复用 PUT 接口、提交一个配额值为 0 的配置。PutBucketQuotaConfigHandler 中对此有专门处理（cmd/admin-bucket-handlers.go）：

if quotaConfig.Size == 0 && quotaConfig.Quota == 0 {
    bucketMeta.Quota = nil   // 站点复制钩子中不再下发 Quota 负载
}

由于写入路径（第四节所述）只有在 quotaSize > 0 时才执行超限判断，因此配置清零后该桶恢复无限制写入。

六、配额是如何被强制执行的：源码级剖析

1. 核心判定逻辑

全部强制逻辑集中在 cmd/bucket-quota.go 的 enforceQuotaHard（第 103–133 行）：

func (sys *BucketQuotaSys) enforceQuotaHard(ctx context.Context, bucket string, size int64) error {
    if size < 0 {
        return nil
    }

    q, err := sys.Get(ctx, bucket)          // 读取桶的 quota.json 配置
    if err != nil {
        return err
    }

    var quotaSize uint64
    if q != nil && q.Type == madmin.HardQuota {
        if q.Size > 0 {
            quotaSize = q.Size
        } else if q.Quota > 0 {
            quotaSize = q.Quota
        }
    }
    if quotaSize > 0 {
        if uint64(size) >= quotaSize {       // 单次写入本身已超过配额
            return BucketQuotaExceeded{Bucket: bucket}
        }

        bui := sys.GetBucketUsageInfo(ctx, bucket)   // 当前桶已用量
        if bui.Size > 0 && ((bui.Size + uint64(size)) >= quotaSize) {
            return BucketQuotaExceeded{Bucket: bucket}
        }
    }

    return nil
}

要点：

• 判定是"本次写入大小"与"当前已用量 + 本次写入大小"两道关卡，任一达到 quotaSize 即拒绝；
• 比较使用 >=，即桶用量精确达到上限后，哪怕再写 1 字节也会超限；
• 错误类型为 BucketQuotaExceeded（定义于 cmd/object-api-errors.go），对外映射为 Admin API 错误码 XMinioAdminBucketQuotaExceeded（见 cmd/api-errors.go）。

2. "当前已用量"从哪来：带缓存的数据扫描结果

GetBucketUsageInfo（cmd/bucket-quota.go）依赖一个进程内缓存 bucketStorageCache，其刷新策略在 Init 中定义：

bucketStorageCache.InitOnce(10*time.Second,
    cachevalue.Opts{ReturnLastGood: true, NoWait: true},
    func(ctx context.Context) (DataUsageInfo, error) {
        ...
        ctx, done := context.WithTimeout(ctx, 2*time.Second)
        defer done()
        return loadDataUsageFromBackend(ctx, objAPI)
    },
)

• 用量数据来源于 MinIO 后台数据扫描器（data scanner）落盘/汇总的 DataUsageInfo，即桶级实际占用统计；
• 缓存 TTL 为 10 秒，且开启 ReturnLastGood——即使刷新失败也会返回最后一次成功的值；刷新失败时仅记一次日志（unable to retrieve usage information ... relying on older value cached in-memory）。从源码结构看，这是一种典型的"宁可短暂滞后、不可影响写入路径"的可用性取舍；
• 若缓存中没有任何可用用量值，会记录 quota will not be enforced 的告警并跳过强制（见第 74 行日志），即用量不可靠时配额不做硬拦截，这一点在排障时值得注意。

3. 哪些 API 路径会触发配额检查

enforceBucketQuotaHard 是各写入入口的统一收口（cmd/bucket-quota.go，globalBucketQuotaSys 为 nil 时直接放行）。仓库中它被调用于以下关键位置：

写入路径	位置	说明
PutObject	cmd/object-handlers.go	普通对象上传，size 为请求体大小
PutObject（另一分支）	cmd/object-handlers.go	处理带校验和等变体的上传路径
CopyObject	cmd/object-handlers.go	跨桶复制时按 srcInfo.GetActualSize() 对目标桶计费；同桶元数据复制（cpSrcDstSame）不检查
Multipart: CreateMultipartUpload/分片	cmd/object-multipart-handlers.go	按当前分片大小检查
Multipart: UploadPart（另一分支）	cmd/object-multipart-handlers.go	对 dstBucket 按 actualPartSize 检查

也就是说，普通上传、服务端复制、分片上传这些会真正增加桶容量的操作都会过配额闸门；读取、删除等不增加容量的操作不受影响。

七、配置存储位置与多站点同步

• 持久化位置：配额以 quota.json 形式保存在桶元数据目录中，由 globalBucketMetadataSys 统一管理读写（GetQuotaConfig / Update 两个方法，见 cmd/bucket-metadata-sys.go）。Get 侧即 BucketQuotaSys.Get（cmd/bucket-quota.go），返回 *madmin.BucketQuota。
• 元数据状态上报：在桶元数据状态接口中，quota.json 被单独标记为 Quota 元数据项（cmd/admin-bucket-handlers.go），未设置时返回 BucketQuotaConfigNotFound。
• 站点复制：设置/修改配额后，PutBucketQuotaConfigHandler 会构造 madmin.SRBucketMeta{Type: SRBucketMetaTypeQuotaConfig, ...} 并调用站点复制钩子，将配置下发到其他站点；配额为 0 时（即清除场景）Quota 负载置 nil 以表达"取消"。

八、典型排障思路

1. 写入被拒绝，错误码 XMinioAdminBucketQuotaExceeded：先 mc admin bucket quota myminio/<bucket> 确认配额值，再用 mc admin info / 用量接口核对桶实际用量是否已贴近上限。
2. 刚删了大量对象，但仍报超限：用量数据来自数据扫描周期汇总且缓存有 10 秒 TTL（见 bucketStorageCache 初始化），从源码结构看用量统计存在分钟级以内的滞后属于正常现象，稍等一个扫描周期后再试。
3. 设置了配额却不生效：检查日志中是否出现 quota will not be enforced（用量缓存为空）或 unable to retrieve usage information（用量刷新失败但回退旧值）——分别对应用量数据尚不可用与降级运行两种情况。
4. 迁移旧环境出现 invalid quota type 'fifo'：旧版 fifo 配额已移除，按日志提示用 mc admin bucket quota myminio/<bucket> --clear 清理旧配置，改用 mc ilm add 管理对象过期。

九、小结

操作	命令
设置 1GB 硬性配额	mc admin bucket quota myminio/mybucket --hard 1gb
查看配额	mc admin bucket quota myminio/mybucket
清除配额	mc admin bucket quota myminio/mybucket --clear

MinIO 的桶配额实现可以概括为三层：配置层由 Admin API（PUT/GET quota.json 桶元数据文件）负责写入与读取，并支持多站点复制；判定层 enforceQuotaHard 依据"单次大小"与"已用量+本次大小"双重条件返回 BucketQuotaExceeded；数据层由后台数据扫描器提供桶用量、经 10 秒 TTL 的内存缓存（失败时回退旧值）供快速查询。PutObject、CopyObject、Multipart 分片上传等所有增加容量的写入路径都统一接入该闸门，从而在对象存储 API 层面实现了确定性的容量管控。