258 lines
7.9 KiB
Markdown
258 lines
7.9 KiB
Markdown
好的，我来为你系统整理一下 MinIO / AWS S3 中 **策略 JSON 的语法和常用参数**。这份指南结合了你之前遇到的桶权限场景，帮助理解每部分的作用。
|
||
|
||
---
|
||
|
||
## 一、策略 JSON 顶层结构
|
||
|
||
一个完整的策略由以下元素组成：
|
||
|
||
```json
|
||
{
|
||
"Version": "2012-10-17", // 版本号（必须，固定值）
|
||
"Statement": [ // 一个或多个权限声明
|
||
{
|
||
"Sid": "OptionalId", // 可选，声明ID
|
||
"Effect": "Allow", // 允许或拒绝
|
||
"Principal": {...}, // 谁（仅某些类型的策略需要）
|
||
"Action": [...], // 哪些操作
|
||
"Resource": [...], // 哪些资源
|
||
"Condition": {...} // 条件限制（可选）
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> **注意**：在 MinIO 中，用户/组策略（Identity Policy）通常不需要 `Principal`，它用于存储桶策略（Bucket Policy）。我们这里主要讲解用户/组策略。
|
||
|
||
---
|
||
|
||
## 二、各字段详解
|
||
|
||
### 1. `Version`（必选）
|
||
- **固定值**：`"2012-10-17"`
|
||
- 表示策略语言的版本，当前所有 S3 兼容系统都使用这个值。
|
||
|
||
### 2. `Statement`（必选）
|
||
- 类型：**数组**，内部包含一个或多个声明对象。
|
||
- 每个声明定义一组权限。
|
||
|
||
### 3. `Sid`（可选）
|
||
- **Statement ID**：任意字符串，用于标识该声明。
|
||
例如：`"Sid": "AllowListBucket"`
|
||
|
||
### 4. `Effect`（必选）
|
||
- 两个取值：`"Allow"` 或 `"Deny"`
|
||
- **Deny 优先级高于 Allow**。即如果一个请求匹配了某个 Deny 声明，即使有 Allow 也会被拒绝。
|
||
|
||
### 5. `Action`（必选）
|
||
- 指定允许或拒绝的**操作**。取值可以是：
|
||
- **单个操作**：`"Action": "s3:GetObject"`
|
||
- **多个操作**：`"Action": ["s3:GetObject", "s3:PutObject"]`
|
||
- **通配符所有操作**：`"Action": "s3:*"`
|
||
（也可以是 `"*"` 表示所有服务所有操作，但不推荐）
|
||
- **常用 S3 Action** 见下文第四部分。
|
||
|
||
### 6. `Resource`（必选）
|
||
- 指定操作作用的**资源**（桶、对象、前缀等）。使用 **ARN（Amazon Resource Name）** 格式。
|
||
- **MinIO / S3 的 ARN 格式**：
|
||
```
|
||
arn:aws:s3:::桶名称
|
||
arn:aws:s3:::桶名称/对象键
|
||
arn:aws:s3:::桶名称/前缀/*
|
||
```
|
||
- 示例：
|
||
- `"arn:aws:s3:::orderbook"` —— 桶本身
|
||
- `"arn:aws:s3:::orderbook/*"` —— 桶内所有对象
|
||
- `"arn:aws:s3:::orderbook/2024/*"` —— 桶内 `2024/` 前缀下的所有对象
|
||
- `"arn:aws:s3:::orderbook/report.pdf"` —— 单个对象
|
||
- 可以写数组包含多个资源。
|
||
|
||
### 7. `Condition`（可选）
|
||
- 用于在**特定条件**下才生效。格式为 `"条件运算符": { "条件键": "值" }`
|
||
- 常见条件运算符：
|
||
- `StringEquals`、`StringNotEquals`
|
||
- `StringLike`（支持 `*` 通配符）、`StringNotLike`
|
||
- `IpAddress`、`NotIpAddress`
|
||
- `Bool`（布尔值）
|
||
- `DateGreaterThan`、`DateLessThan`
|
||
- 常见条件键（S3）：
|
||
- `s3:prefix` —— 对象前缀
|
||
- `s3:delimiter` —— 分隔符
|
||
- `s3:max-keys` —— ListObjects 的最大数量
|
||
- `aws:SourceIp` —— 客户端 IP
|
||
- `aws:RequestedRegion` —— 请求的区域
|
||
- **示例**：只允许来自特定 IP 的上传
|
||
```json
|
||
"Condition": {
|
||
"IpAddress": {
|
||
"aws:SourceIp": "192.168.1.100/32"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、策略生效规则（重要）
|
||
|
||
1. **默认隐式拒绝**：任何未在策略中明确 Allow 的操作，都会被拒绝。
|
||
2. **显式 Deny 优先**：只要任意一个声明匹配 `Effect: "Deny"`，即使其他声明有 Allow，也会被拒绝。
|
||
3. **合并策略**：用户可能同时有**用户策略**、**组策略**、**桶策略**，最终权限是这些策略的并集，再减去 Deny。
|
||
|
||
---
|
||
|
||
## 四、常用 S3 Action 分类（MinIO 支持大部分）
|
||
|
||
| 分类 | Action | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| **读操作** | `s3:ListBucket` | 列出桶内对象（需要桶资源 `arn:aws:s3:::bucket`） |
|
||
| | `s3:GetObject` | 下载对象 |
|
||
| | `s3:GetObjectAcl` | 获取对象的 ACL |
|
||
| | `s3:GetObjectTagging` | 获取对象的标签 |
|
||
| | `s3:HeadObject` | 获取对象元数据（不返回内容） |
|
||
| **写操作** | `s3:PutObject` | 上传对象 |
|
||
| | `s3:DeleteObject` | 删除对象 |
|
||
| | `s3:DeleteObjectVersion` | 删除特定版本（启用版本控制时） |
|
||
| | `s3:PutObjectAcl` | 修改对象的 ACL |
|
||
| | `s3:PutObjectTagging` | 设置/修改对象标签 |
|
||
| | `s3:AbortMultipartUpload` | 终止分片上传 |
|
||
| **桶管理** | `s3:CreateBucket` | 创建桶 |
|
||
| | `s3:DeleteBucket` | 删除桶 |
|
||
| | `s3:PutBucketPolicy` | 设置桶策略 |
|
||
| | `s3:GetBucketPolicy` | 获取桶策略 |
|
||
| | `s3:PutBucketVersioning` | 设置版本控制 |
|
||
| | `s3:PutBucketLifecycle` | 设置生命周期规则 |
|
||
| **多部分上传** | `s3:ListMultipartUploadParts` | 列出已上传的分片 |
|
||
| | `s3:UploadPart` | 上传分片 |
|
||
|
||
> **提示**：使用 `s3:*` 可匹配该服务下所有操作。MinIO 还支持一些扩展操作（如 `admin:*`），但通常不写在用户存储策略中。
|
||
|
||
---
|
||
|
||
## 五、实战示例：逐步构建一个桶控制策略
|
||
|
||
### 场景：只允许对 `orderbook` 桶进行读写，**不允许删除**
|
||
|
||
```json
|
||
{
|
||
"Version": "2012-10-17",
|
||
"Statement": [
|
||
{
|
||
"Effect": "Allow",
|
||
"Action": [
|
||
"s3:ListBucket",
|
||
"s3:GetObject",
|
||
"s3:PutObject"
|
||
],
|
||
"Resource": [
|
||
"arn:aws:s3:::orderbook",
|
||
"arn:aws:s3:::orderbook/*"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 场景：完全控制 `orderbook` 桶（所有操作）
|
||
|
||
```json
|
||
{
|
||
"Version": "2012-10-17",
|
||
"Statement": [
|
||
{
|
||
"Effect": "Allow",
|
||
"Action": "s3:*",
|
||
"Resource": [
|
||
"arn:aws:s3:::orderbook",
|
||
"arn:aws:s3:::orderbook/*"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 场景：只允许上传到 `uploads/` 前缀，且文件名为 `incoming-*`
|
||
|
||
```json
|
||
{
|
||
"Version": "2012-10-17",
|
||
"Statement": [
|
||
{
|
||
"Effect": "Allow",
|
||
"Action": "s3:PutObject",
|
||
"Resource": "arn:aws:s3:::orderbook/uploads/incoming-*"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 场景：拒绝删除任何对象（显式 Deny）
|
||
|
||
```json
|
||
{
|
||
"Version": "2012-10-17",
|
||
"Statement": [
|
||
{
|
||
"Effect": "Allow",
|
||
"Action": "s3:*",
|
||
"Resource": [
|
||
"arn:aws:s3:::orderbook",
|
||
"arn:aws:s3:::orderbook/*"
|
||
]
|
||
},
|
||
{
|
||
"Effect": "Deny",
|
||
"Action": [
|
||
"s3:DeleteObject",
|
||
"s3:DeleteObjectVersion"
|
||
],
|
||
"Resource": "arn:aws:s3:::orderbook/*"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 场景：限制只能从特定 IP 访问
|
||
|
||
```json
|
||
{
|
||
"Version": "2012-10-17",
|
||
"Statement": [
|
||
{
|
||
"Effect": "Allow",
|
||
"Action": "s3:GetObject",
|
||
"Resource": "arn:aws:s3:::orderbook/*",
|
||
"Condition": {
|
||
"IpAddress": {
|
||
"aws:SourceIp": "10.0.0.0/24"
|
||
}
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、常见错误与调试
|
||
|
||
| 错误现象 | 可能原因 | 解决方案 |
|
||
| :--- | :--- | :--- |
|
||
| 能列出桶，但无法上传 | 桶对象资源 `/*` 缺失 | 确保 Resource 包含 `arn:aws:s3:::桶名/*` |
|
||
| 无法列出桶内对象 | 缺少 `s3:ListBucket` 或桶级 Resource | 添加桶本身资源（不带 `/*`） |
|
||
| 能上传但无法覆盖 | 显式 Deny 或没有完整写入权限 | 检查是否有 `s3:PutObject` |
|
||
| IP 限制不生效 | Condition 语法错误或键名不对 | 使用 `aws:SourceIp` 且值为 CIDR |
|
||
| 策略不生效 | 策略未正确附加到用户/组 | 使用 `mc admin policy attach` 检查 |
|
||
|
||
---
|
||
|
||
## 七、MinIO 特有提醒
|
||
|
||
- MinIO 默认禁用 `s3:CreateBucket` 等管理操作，除非你使用 `root` 或拥有管理员策略。
|
||
- MinIO 支持 **内置策略**（如 `readonly`、`readwrite`、`consoleAdmin`），可以直接附加。
|
||
- 策略 JSON 大小限制通常为 **20KB**（MinIO 默认）。
|
||
- 使用 `mc` 命令可以验证策略语法：
|
||
`mc admin policy create myminio mypolicy ./policy.json`
|
||
|
||
---
|
||
|
||
希望这份整理能够帮助你灵活编写策略。如果你有具体的访问控制需求，可以提供描述，我可以直接为你生成策略 JSON。 |