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 minio4. 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，方便统一管理。