minio 的 bucket-policy 是绑定到存储桶的 json 格式声明式权限策略，用于控制谁在什么条件下对哪些资源执行哪些操作；它独立于用户策略，支持 allow/deny、条件限制及资源通配。
MinIO 的 bucket-policy 是什么，它能做什么
bucket-policy 是 MinIO 中基于 JSON 的声明式权限控制机制，作用对象是存储桶（bucket）及其内部对象（object）。它不依赖用户身份认证（如 access key），而是直接绑定到 bucket 上，决定“谁、在什么条件下、能对哪些资源执行哪些操作”。常见用途包括：开放某个 bucket 的只读访问（用于静态网站托管）、限制特定 IP 访问、禁止 public PUT 但允许 GET、或按前缀隔离子目录级权限。
注意：它和 MinIO 的 user-policy（绑定到具体用户）是两套独立系统；若同时存在，二者策略会合并生效（取并集），但 deny 语句优先于 allow。
写一个合法的 bucket-policy JSON 必须满足哪些结构条件
MinIO 对策略 JSON 格式要求严格，稍有偏差就会返回 MalformedPolicy 错误。关键点包括：
-
Version字段必须为"2012-10-17"（固定字符串，不是日期） -
Statement必须是数组，即使只有一条规则也要写成[{...}] - 每个
Statement至少包含Effect（"Allow"或"Deny"）、Action（字符串或字符串数组，如"s3:GetObject"）、Resource（格式为"arn:aws:s3:::bucket-name/*"或"arn:aws:s3:::bucket-name"） -
Principal可为"<em>"</em>（任意主体），也可指定具体用户 ARN；若省略，则默认等价于{"AWS": [""]}，但显式写出更安全 -
Condition是可选对象，键名必须是带命名空间的（如"IpAddress"→"aws:SourceIp"）
示例（允许所有人在指定 IP 段内读取 my-bucket 下所有对象）：
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": ["s3:GetObject"],
"Resource": ["arn:aws:s3:::my-bucket/*"],
"Condition": {
"IpAddress": {
"aws:SourceIp": "192.168.1.0/24"
}
}
}
]
}
用 mc 命令行设置 policy 最快最稳的方式
MinIO 官方推荐且最可靠的设置方式是使用 mc（MinIO Client），而非直接调用 API 或改 UI（UI 不支持完整策略语法）。步骤如下：
- 确保
mc已配置好别名（如mc alias set myminio <a href="https://www.php.cn/link/b99c61acedb54c5253819b7b4f2d88c6">https://www.php.cn/link/b99c61acedb54c5253819b7b4f2d88c6</a> ACCESS_KEY SECRET_KEY） - 将策略保存为本地文件（如
policy.json），确保无 BOM、UTF-8 编码、无注释 - 执行：
mc admin bucket policy set myminio/my-bucket policy.json - 验证是否生效：
mc admin bucket policy get myminio/my-bucket
常见失败原因：
- 文件路径写错或权限不足（
mc读的是本地文件，不是 MinIO 上的 object） -
Resource中的 bucket 名拼写错误，或漏掉/*导致无法匹配对象级操作 - 使用了 MinIO 不支持的
Action（如s3:ListAllMyBuckets是账户级操作，不能放在 bucket policy 中）
为什么设置了 bucket-policy 还是 403？几个高频盲区
策略写对了、也成功 set 了，但请求仍被拒绝，大概率卡在这几个地方：
- MinIO 服务端启用了
--anonymous模式（即关闭了认证），此时bucket-policy中的Principal: "*"才有效；如果启用了 IAM 认证且未显式授权用户，即使 policy 允许，也会因用户本身无基础权限而失败 - 请求使用的 endpoint 协议不一致：比如 policy 允许
<a href="https://www.php.cn/link/350b50ff383f715fb131aaeecf586710">https://www.php.cn/link/350b50ff383f715fb131aaeecf586710</a>，但你用https://发起请求，aws:SourceIp或aws:UserAgent条件可能意外失效 - 对象 key 包含特殊字符（如空格、中文、
+），导致签名计算与 policy 中Resource的通配匹配不一致；建议统一 URL-encode 后再测试 - 使用了
s3:PutObject但没同时加s3:PutObjectAcl—— 如果客户端 SDK 自动尝试设置 ACL（如x-amz-acl: public-read），而 policy 没放行该动作，就会静默失败
真正麻烦的不是写 policy，而是策略生效后和实际请求头、签名、endpoint、客户端行为之间的隐式耦合。调试时优先用 curl -v 看完整响应头和 error code，比看日志更快。
