MinIO 服务端限制深度解析：集群规模、S3 API 边界与对象命名规则

本篇基于 MinIO 官方限制说明文档 docs/minio-limits.md，系统梳理 MinIO 在生产部署中的各类硬性限制：纠删码集群的规模与仲裁要求、S3 API 的容量与分片边界、不支持的 S3 API 及其替代方案、对象命名约束。读完之后，你可以依据仓库中的源码实现验证这些限制的实际执行位置，为容量规划、客户端设计与迁移 AWS S3 工作负载提供可核对的依据。

生产部署的操作系统建议

官方文档首先给出了一条基础前提：为获得最佳生产配置，MinIO 建议使用 Linux 内核 4.x 及以上版本。对象命名等特性同样受操作系统与文件系统影响（后文详述），因此在生产环境中 MinIO 明确推荐 Linux 作为承载平台。这一建议与仓库中的多平台支持代码（如 cmd/os_linux.go 系列文件 与 Windows 专属实现 cmd/os_windows.go）相印证：MinIO 虽具备跨平台能力，但部分文件名语义在不同文件系统上并不等价。

纠删码集群的规模与仲裁限制

对于多盘/多机纠删码部署，文档给出了如下规格表：

项目	规格
每集群最大服务器数	无上限
最小服务器数	02
服务器数为 1 时，每服务器最小磁盘数	02
服务器数为 2 或 3 时，每服务器最小磁盘数	01
服务器数为 4 时，每服务器最小磁盘数	01
每服务器最大磁盘数	无上限
读仲裁（Read quorum）	N/2
写仲裁（Write quorum）	N/2+1

仲裁模型的源码依据

读仲裁 N/2、写仲裁 N/2+1 是纠删码系统一致性的核心。在 MinIO 的纠删码实现中，这一模型贯穿元数据读写路径：

• 读路径只需超过半数磁盘（N/2）返回数据即可重建，因为纠删码本身具备冗余能力；
• 写路径要求多数派（N/2+1）确认，避免在磁盘故障叠加时出现"多数派数据撕裂"。

从源码结构看，cmd/erasure.go 与 cmd/erasure-object.go 中的读写函数均围绕 readQuorum/writeQuorum 参数展开，cmd/erasure-server-pool.go 则在多池（multi-pool）架构下将同样的仲裁约束扩展到跨池集合。理解这一点后，规格表中的"最小服务器数 2、单机最少 2 盘"要求就顺理成章：仲裁与纠删冗余需要足够的独立故障域，单机 1 盘既无法构成纠删码冗余，也不满足仲裁计算。

S3 API 容量与操作限制

这是容量规划最常用的一节，文档给出的完整规格如下：

项目	规格
最大桶（bucket）数	无上限（官方建议不超过 500000）
每桶最大对象数	无限制
最大对象大小	50 TiB
最小对象大小	0 B
单次 PUT 操作的最大对象大小	5 TiB
每次上传（multipart upload）的最大分片数	10,000
分片大小范围	5 MiB 到 5 TiB；最后一片可以为 0 B 到 5 TiB
List Parts 请求单次返回的最大分片数	10000
List Objects 请求单次返回的最大对象数	1000
List Multipart Uploads 请求单次返回的最大上传数	1000
桶名最大长度	63
对象名最大长度	1024
对象名中每个以 '/' 分隔的段的最大长度	255
每对象最大版本数	10000（可配置为更高值，但不建议超过 10000）

原文 NOTE：虽然 MinIO 不对桶数量设置硬上限，但集群硬件随负载与扩展模式存在自然极限。官方建议参考 MinIO SUBNET 获取生产场景的架构与容量规划指导。

关键限制的源码验证

上述多数限制并非仅停留在文档层面，而是直接硬编码在请求校验路径中，可逐一在仓库中核对：

1. 10,000 分片上限。cmd/utils.go 的注释明确写着 "Maximum Part ID for multipart upload is 10000"；超过该值会返回 cmd/typed-errors.go 中定义的 errInvalidMaxParts（"Part number is greater than the maximum allowed 10000 parts"）。同时 cmd/api-response.go 用 maxPartsList = 10000 限制 ListParts 响应中的分片数量。
2. 分片最小 5 MiB。cmd/object-api-errors.go 定义了 PartTooSmall 错误类型（"error if part size is less than 5MB"），分片合并（complete multipart）阶段的校验在 cmd/utils.go 触发，最终映射到 S3 的 EntityTooSmall 错误码（见 cmd/api-errors.go 与 cmd/api-errors_test.go）。注意最后一片可以小于 5 MiB（甚至 0 B），这正是规格表中"Last part can be 0 B to 5 TiB"的由来。
3. 桶名 3–63 字符、DNS 风格。cmd/object-api-utils.go 的 IsValidBucketName 完整实现了文档所述规则：长度必须在 3 到 63 之间；按点号分段后每段不能以连字符开头或结尾；只允许小写字母、数字与连字符；且整体不能形如 IP 地址（4 段全数字被拒绝）。违反时返回 InvalidBucketName 错误码（cmd/api-errors.go）。
4. 对象名 1024 字符上限与合法性。cmd/object-api-utils.go 的 checkObjectNameForLengthAndSlash 在长度超过 1024 时返回 ObjectNameTooLong；IsValidObjectName/IsValidObjectPrefix（cmd/object-api-utils.go）则拒绝空名称、以 / 结尾的名称、非法 UTF-8、连续 //、NUL 字符以及坏路径分量。对应单元测试见 cmd/object-api-utils_test.go。
5. 桶数量 500000 的建议值。cmd/generic-handlers.go 中有注释 "maxBuckets upto 500000 for any MinIO deployment"，表明该建议值已进入请求处理层的考量。

从源码结构看，"最大对象 50 TiB、单次 PUT 5 TiB"这一组合意味着：单个对象可以通过多分片拼接达到 50 TiB，但任何一次 PutObject 请求本身不得超过 5 TiB，超出必须走 Multipart Upload 路径。

MinIO 不支持的 Amazon S3 API 清单

文档指出以下 API 被认为在 AWS S3 之外冗余或实用性较低，MinIO 不予实现，并给出了各自的替代路径：

不支持的桶级 API

API	MinIO 的替代方案
BucketACL	改用桶策略（bucket policy）实现访问控制
BucketCORS	所有桶默认对所有 HTTP 动词开启 CORS，可选择性限制 CORS 域
BucketWebsite	使用 Caddy 或 Nginx 等反向代理实现静态站点托管
BucketAnalytics、BucketMetrics、BucketLogging	改用桶通知（bucket notification）API

关于 CORS 的默认行为，从源码结构看，cmd/crossdomain-xml-handler.go 实现了 cross-domain 策略的处理逻辑，与"默认全开、可选收紧"的文档表述一致；桶策略的加载与求值则在 cmd/bucket-policy.go 与 cmd/bucket-policy-handlers.go 中。

不支持的对象级 API

• ObjectACL —— 同样以桶策略替代。

文档还提示：如果你认为遗漏了某个应当支持的 API，可以在 MinIO 的 GitHub issue 区提交理由与建议。

对象命名限制

这部分是迁移 S3 工作负载时最容易踩坑的地方，文档给出三类约束：

1. 受操作系统与文件系统约束。对象名中包含 ^*|\/&"; 等字符的对象名在 Windows 或不支持特殊字符文件名的文件系统上不可用。文档明确警告：该列表不穷尽，具体取决于所用操作系统与文件系统，应咨询操作系统厂商获取完整特殊字符清单。MinIO 对生产负载推荐 Linux。
   • 仓库侧印证：MinIO 将对象直接落盘为文件系统条目，并针对不同平台的 inode/目录项行为做了分支实现，例如 cmd/os-dirent_ino.go 与 cmd/os-dirent_fileino.go、cmd/os-rename_linux.go 与 cmd/os_reliable.go，说明"对象名 = 文件路径"这一实现前提使命名约束天然依赖底层文件系统。
2. 必须为合法 UTF-8、长度不超过 1024（对应上文 S3 API 限制，实现见 IsValidObjectPrefix）。
3. 禁止父子对象冲突。对象不能与作为其"父对象"的对象并存，以下两种模式都不受支持，依赖此行为的应用应改用不冲突的唯一键：

PUT <bucketname>/a/b/1.txt
PUT <bucketname>/a/b

PUT <bucketname>/a/b
PUT <bucketname>/a/b/1.txt

无论先后顺序如何，a/b 作为完整对象与 a/b/... 前缀对象同时存在都会产生歧义——因为在文件系统视角下，a/b 无法同时是一个文件和一个目录。

总结与容量规划要点

• 集群侧：纠删码部署遵循"读 N/2、写 N/2+1"仲裁模型，单机至少 2 盘、多机至少 2 节点，服务器数与每服务器磁盘数本身无上限，上限实际由硬件与负载决定。
• API 侧：桶数建议不超过 500,000；对象最大 50 TiB、单次 PUT 最大 5 TiB；分片 5 MiB–5 TiB、单上传最多 10,000 片；列表类请求的分页上限为 1000（ListObjects/ListMultipartUploads）与 10,000（ListParts）；桶名 3–63 字符、对象名 ≤1024 字符且每段 ≤255 字符。
• 兼容性侧：BucketACL/ObjectACL 用桶策略替代，BucketWebsite 交给 Caddy/Nginx，日志与分析需求转向桶通知。
• 命名侧：跨平台部署时避免在对象名中使用平台相关特殊字符，避免父子对象键冲突，生产环境推荐 Linux 内核 4.x 及以上。

以上每一项限制都可以在仓库源码中找到对应的校验实现（重点参考 cmd/object-api-utils.go、cmd/typed-errors.go、cmd/api-errors.go、cmd/api-response.go），建议在接入校验与客户端重试逻辑开发时，直接以这些源码位置作为行为契约的依据。