第五章：核心概念

5.1 存储桶（Bucket）

5.1.1 存储桶概述

存储桶是 MinIO 中的顶级命名空间，用于组织和存储对象。

属性	说明
命名	全局唯一，不可重复
命名规范	3-63字符，小写字母、数字、点、连字符
数量限制	无限制
嵌套	不支持嵌套

5.1.2 存储桶命名

# 合法的存储桶名称
my-bucket
mybucket
my.bucket
123-bucket

# 非法的存储桶名称
MyBucket     # 不能有大写
my bucket    # 不能有空格
bucket_123   # 不能有下划线
192.168.1.1  # 不能是 IP

5.1.3 存储类型

# 创建标准存储桶（默认）
mc mb myminio/standard-bucket

# 创建存储桶并指定存储类别
mc mb myminio/hot-bucket

# 查看存储桶信息
mc stat myminio/bucket

5.2 对象（Object）

5.2.1 对象概述

对象是存储在存储桶中的基本数据单元，包括数据和元数据。

Object 结构
┌─────────────────────────────────────────────────────────┐
│                        Object                             │
├─────────────────────────────────────────────────────────┤
│  Key: logs/2024/01/server.log                            │
│  Size: 1.5 GB                                            │
│  ETag: d41d8cd98f00b204e9800998ecf8427e                  │
│  Content-Type: text/plain                                │
│  Last-Modified: 2024-01-15T10:30:00Z                     │
├─────────────────────────────────────────────────────────┤
│  User Metadata:                                           │
│  X-Amz-Meta-Owner: admin                                 │
│  X-Amz-Meta-Project: production                          │
└─────────────────────────────────────────────────────────┘

5.2.2 对象键（Object Key）

对象键是存储桶中对象的唯一标识符：

# 对象键示例
logs/2024/01/server.log
images/products/001.jpg
videos/2024-01/training.mp4
documents/reports/q1-2024.pdf

5.2.3 对象元数据

# 上传时设置元数据
mc cp file.txt myminio/bucket/ \
  --attr "Content-Type=application/json;X-Amz-Meta-Custom=custom-value"

# 查看对象元数据
mc stat myminio/bucket/file.txt

# 示例输出
# Name      : file.txt
# Size      : 1024 bytes
# Type      : application/octet-stream
# ETag      : d41d8cd98f00b204e9800998ecf8427e
# Metadata  :
#   Content-Type    : application/octet-stream
#   X-Amz-Meta-Custom : custom-value

5.3 多段上传（Multipart Upload）

5.3.1 什么是多段上传

大文件上传时，MinIO 支持将文件分割成多个部分分别上传，提高上传速度和可靠性。

Multipart Upload 流程
┌─────────────────────────────────────────────────────────┐
│  1. 初始化多段上传                                       │
│     POST /bucket/object?uploads                          │
│              │                                           │
│              ▼                                          │
│  2. 上传各个部分                                         │
│     PUT /bucket/object?partNumber=1&uploadId=xxx         │
│     PUT /bucket/object?partNumber=2&uploadId=xxx         │
│     PUT /bucket/object?partNumber=3&uploadId=xxx         │
│              │                                           │
│              ▼                                           │
│  3. 完成上传                                             │
│     POST /bucket/object?uploadId=xxx                     │
│              │                                           │
│              ▼                                           │
│  4. 组装完整文件                                         │
└─────────────────────────────────────────────────────────┘

5.3.2 多段上传配置

# 配置多段上传参数
export MINIO_API_PART_MAX_MB=5        # 单个part最大 5GB

# 列出正在进行的分段上传
mc ls --incomplete myminio/bucket/

# 中止未完成的分段上传
mc abort myminio/bucket/object --upload-id <upload-id>

# 清理所有未完成的分段上传
mc cleanup --incomplete myminio/bucket/

5.3.3 大文件上传示例

import boto3
from botocore.config import Config

# 创建 S3 客户端
s3 = boto3.client(
    's3',
    endpoint_url='http://localhost:9000',
    aws_access_key_id='admin',
    aws_secret_access_key='password123',
    config=Config(max_pool_connections=100)
)

# 配置分段上传
config = {
    'LocationConstraint': 'us-east-1',
    'ObjectSizeThreshold': 1024 * 1024 * 100,  # 100MB 以上自动分段
}

# 上传大文件（自动分段）
s3.upload_file('large-file.zip', 'bucket', 'large-file.zip')

# 手动分段上传
# 1. 初始化
create_response = s3.create_multipart_upload(
    Bucket='bucket',
    Key='large-file.zip'
)
upload_id = create_response['UploadId']

# 2. 上传各部分
parts = []
part_number = 1
with open('large-file.zip', 'rb') as f:
    while chunk := f.read(100 * 1024 * 1024):  # 100MB 每块
        part = s3.upload_part(
            Bucket='bucket',
            Key='large-file.zip',
            PartNumber=part_number,
            UploadId=upload_id,
            Body=chunk
        )
        parts.append({'PartNumber': part_number, 'ETag': part['ETag']})
        part_number += 1

# 3. 完成上传
s3.complete_multipart_upload(
    Bucket='bucket',
    Key='large-file.zip',
    UploadId=upload_id,
    MultipartUpload={'Parts': parts}
)

5.4 版本控制（Versioning）

5.4.1 版本控制概述

启用版本控制后，每次对对象的修改都会创建一个新版本，保留历史版本。

Versioning 存储结构
┌─────────────────────────────────────────────────────────┐
│  Bucket (versioning enabled)                              │
├─────────────────────────────────────────────────────────┤
│  object.txt (最新版本)                                   │
│  ├─ Version ID: v3 (当前)                               │
│  ├─ Version ID: v2                                      │
│  └─ Version ID: v1                                      │
└─────────────────────────────────────────────────────────┘

5.4.2 版本控制操作

# 启用版本控制
mc version enable myminio/mybucket

# 暂停版本控制
mc version suspend myminio/mybucket

# 查看版本状态
mc version info myminio/mybucket

# 上传新版本
mc cp updated-file.txt myminio/mybucket/file.txt

# 列出所有版本
mc ls --versions myminio/mybucket/

# 下载特定版本
mc cp --version-id <version-id> myminio/mybucket/file.txt /tmp/

# 删除指定版本
mc rm --version-id <version-id> myminio/mybucket/file.txt

5.4.3 版本控制与删除

# 简单删除（添加删除标记）
mc rm myminio/mybucket/file.txt
# 结果：添加 Delete Marker，保留所有版本

# 永久删除（彻底删除）
mc rm --version-id <version-id> myminio/mybucket/file.txt
# 结果：永久删除指定版本

5.5 对象锁定（Object Locking）

5.5.1 合规模式 vs 治理模式

模式	说明	权限要求
合规模式 (Compliance)	锁定期间任何人无法删除	只有合规官可以移除
治理模式 (Governance)	可被特权用户覆盖	需要特殊权限

5.5.2 创建锁定存储桶

# 创建带对象锁定的存储桶
mc mb --with-lock myminio/compliance-bucket

# 启用默认锁定规则
mc object-lock set myminio/compliance-bucket \
  --default-retention-days 30 --mode compliance

5.5.3 上传锁定对象

# 上传带保留期的对象
mc cp file.txt myminio/compliance-bucket/ \
  --lock-until "2024-12-31T23:59:59Z"

# 上传带法律保留的对象
mc cp file.txt myminio/compliance-bucket/ \
  --legal-hold on

# 查看对象锁定状态
mc retention info myminio/compliance-bucket/file.txt

5.6 生命周期管理

5.6.1 生命周期规则

{
  "Rules": [
    {
      "ID": "cleanup-old-logs",
      "Status": "Enabled",
      "Filter": {
        "Prefix": "logs/"
      },
      "Expiration": {
        "Days": 90
      }
    },
    {
      "ID": "transition-to-archive",
      "Status": "Enabled",
      "Filter": {
        "Prefix": "archive/"
      },
      "Transitions": [
        {
          "Days": 30,
          "StorageClass": "GLACIER"
        }
      ]
    }
  ]
}

5.6.2 设置生命周期规则

# 创建生命周期配置文件
cat > lifecycle.json << 'EOF'
{
  "Rules": [
    {
      "ID": "expire-old-files",
      "Status": "Enabled",
      "Filter": {
        "Prefix": ""
      },
      "Expiration": {
        "Days": 365
      }
    },
    {
      "ID": "delete-incomplete-uploads",
      "Status": "Enabled",
      "Filter": {
        "Prefix": ""
      },
      "AbortIncompleteMultipartUpload": {
        "DaysAfterInitiation": 7
      }
    }
  ]
}
EOF

# 应用生命周期规则
mc ilm import myminio/mybucket < lifecycle.json

# 查看生命周期规则
mc ilm ls myminio/mybucket/

# 删除生命周期规则
mc ilm rm --id expire-old-files myminio/mybucket

5.7 访问控制列表（ACL）

5.7.1 ACL 权限

权限	说明
READ	列出和读取对象
WRITE	上传、删除对象
READ_ACP	读取 ACL
WRITE_ACP	修改 ACL
FULL_CONTROL	完全控制

5.7.2 设置 ACL

# 设置存储桶为公开读取
mc anonymous set download myminio/mybucket

# 设置特定用户权限
mc policy set download myminio/mybucket/user-prefix/

# 查看当前策略
mc anonymous list myminio/mybucket

5.8 总结

本章深入介绍了 MinIO 的核心概念，包括存储桶、对象、多段上传、版本控制和生命周期管理等。掌握这些概念对于高效使用 MinIO 至关重要。下一章将学习 MinIO Client 的高级用法。