minio

1. MinIO 是什么？

MinIO 是单个二进制即可运行的开源对象存储，专门用来保存非结构化数据（图片、音视频、备份、日志等），并提供与 Amazon S3 相同的 API。它的优势是轻量、性能高、部署简单，非常适合在本地或私有云场景替代 S3。

2. 前置知识：对象存储速览

了解对象存储与文件存储、块存储的差异有助于正确地组织数据。

特性	文件存储	块存储	对象存储（MinIO）
数据结构	目录 + 文件	固定大小的块	桶 Bucket + 对象 Object
访问方式	路径（/docs/a.txt）	直接读写磁盘块	通过 Key（如 my-bucket/pic.jpg）
协议	NFS、SMB	SCSI、iSCSI	S3 API、HTTP/HTTPS
适用场景	文档共享、源码库	数据库、虚拟机磁盘	大数据、备份、静态资源

对象存储可以想象成“给每个包裹贴上唯一条形码后扔进同一个仓库”，需要时只凭条形码就能取出，非常适合存海量文件。

3. 环境准备与安装

本节介绍如何在本地快速启动 MinIO，方便后续实验。默认使用内置账号 minioadmin / minioadmin，上线环境请自行修改。

3.1 下载与启动单节点

# 说明：Windows PowerShell 中下载并运行 MinIO
Invoke-WebRequest -Uri https://dl.min.io/server/minio/release/windows-amd64/minio.exe -OutFile minio.exe
.\minio.exe server D:\minio-data --console-address ":9001"


# 说明：macOS 终端中下载并运行 MinIO
curl -O https://dl.min.io/server/minio/release/darwin-amd64/minio
chmod +x minio
./minio server ~/minio-data --console-address ":9001"

• API 默认监听 http://127.0.0.1:9000，Web 控制台在 http://127.0.0.1:9001。
• 登录控制台即可创建 Access Key、Secret Key，用于程序访问。

3.2 安装 Python SDK

本教程使用官方 minio 包（基于 S3 API）。先安装依赖：

# 说明：在 Windows PowerShell 中安装 Python SDK
python -m pip install minio


# 说明：在 macOS 终端中安装 Python SDK
python3 -m pip install minio

4. MinIO 核心概念

掌握几个关键词即可理解 MinIO 的工作方式。

4.1 对象（Object）

对象是最小存储单元，包含文件内容、本地自定义元数据以及唯一 Key。上传文件时可以附带标签、Content-Type 等信息。

4.2 桶（Bucket）

桶是存放对象的容器，类似文件夹。桶名在同一个 MinIO 实例中必须唯一，可以为每个桶配置访问策略、生命周期等。

4.3 S3 兼容 API

MinIO 完整实现了 S3 API，因此 AWS CLI、boto3、Terraform 等工具可以无缝对接。对已有 S3 代码只需改下 endpoint 即可。

4.4 纠删码与分布式部署（可选）

生产环境可以配置多个节点，让 MinIO 自动把数据和校验块分布到不同硬盘上。即使部分节点宕机，数据依旧可读可写。但入门可以先从单机模式练习。

5. Python 实战示例

以下示例都使用 minio 包，并假设 MinIO 服务运行在 http://127.0.0.1:9000，Access Key 与 Secret Key 均为 minioadmin（默认值）。

5.1 创建桶并上传文件

# 说明：导入 Path 与 MinIO 客户端，准备连接对象存储
from pathlib import Path

from minio import Minio
from minio.error import S3Error

# 说明：配置 MinIO 客户端，连接到本地 9000 端口
client = Minio(
    endpoint="127.0.0.1:9000",
    access_key="minioadmin",
    secret_key="minioadmin",
    secure=False  # 说明：本地环境使用 HTTP
)

def ensure_bucket(bucket_name: str) -> None:
    # 说明：检查桶是否存在，不存在则创建
    if not client.bucket_exists(bucket_name):
        client.make_bucket(bucket_name)

def upload_sample(bucket_name: str, object_name: str, file_path: Path) -> None:
    # 说明：上传本地文件为对象
    client.fput_object(bucket_name, object_name, file_path.as_posix())

def list_objects(bucket_name: str) -> None:
    # 说明：遍历桶内所有对象，打印名称和大小
    for obj in client.list_objects(bucket_name, recursive=True):
        print(f"{obj.object_name}\t{obj.size} bytes")

if __name__ == "__main__":
    try:
        # 说明：准备示例桶与本地文本文件
        bucket = "demo-bucket"
        sample_file = Path("hello.txt")
        sample_file.write_text("Hello MinIO!", encoding="utf-8")

        # 说明：确保桶存在，然后上传并列出对象
        ensure_bucket(bucket)
        upload_sample(bucket, "docs/hello.txt", sample_file)
        list_objects(bucket)
    except S3Error as exc:
        print(f"MinIO error: {exc}")

5.2 生成一次性下载链接

有时希望临时共享一个对象，可以创建带有效期的预签名 URL。

# 说明：导入时间工具和 MinIO 客户端
from datetime import timedelta

from minio import Minio

# 说明：配置客户端，连接到本地 MinIO 服务器
client = Minio(
    endpoint="127.0.0.1:9000",
    access_key="minioadmin",
    secret_key="minioadmin",
    secure=False
)

def create_presigned_url(bucket_name: str, object_name: str) -> str:
    # 说明：生成指定对象的临时下载链接
    return client.presigned_get_object(
        bucket_name=bucket_name,
        object_name=object_name,
        expires=timedelta(hours=1)
    )

if __name__ == "__main__":
    # 说明：生成并打印下载链接
    url = create_presigned_url("demo-bucket", "docs/hello.txt")
    print(f"Download link: {url}")

6. 常见使用场景

• 云原生持久化 ：在 Kubernetes 中部署 MinIO，为微服务或任务提供对象存储。
• 备份与容灾 ：通过生命周期策略把旧数据复制到另一套 MinIO 或公有云。
• 静态资源托管 ：前端静态文件、图片、视频都能放在 MinIO，并直接用 CDN/反向代理对外提供。
• AI/ML 数据集 ：把训练样本集中到 MinIO，配合 Spark、PyTorch 等框架直接读取 S3 接口。
• 日志归档 ：把应用或数据库的归档文件定期上传至 MinIO，方便统一管理。