MinIO 对象存储¶

MinIO 是一款高性能的 S3 兼容对象存储服务，用 Go 语言编写，可以在本地搭建一个"私有版 AWS S3"，特别适合存储测序数据、比对结果等大文件，是生信数据管理的利器。

核心知识点¶

知识点	说明
工具定位	高性能 S3 兼容对象存储
开发语言	Go
许可证	GNU AGPL v3.0
核心优势	完全 S3 API 兼容、高性能、支持分布式部署
适用场景	大文件存储（FASTQ/BAM/VCF）、数据湖、AI/ML 数据
最大对象	单个对象最大 50TB
数据持久性	纠删码保证 99.999999999%（11 个 9）
客户端	mc 命令行工具 + Python/Java/Go SDK

安装配置¶

方法一：Docker 安装（推荐）¶

# 用 Docker 运行 MinIO
docker run -d \
  --name minio \
  -p 9000:9000 \                      # API 端口
  -p 9001:9001 \                      # Web 控制台端口
  -v minio_data:/data \               # 数据持久化
  -e MINIO_ROOT_USER=admin \          # 管理员用户名
  -e MINIO_ROOT_PASSWORD=password123 \  # 管理员密码（至少8位）
  minio/minio server /data --console-address ":9001"

# 访问 Web 控制台
# 浏览器打开 http://localhost:9001
# 用 admin/password123 登录

方法二：二进制安装¶

# 下载 MinIO 服务器
wget https://dl.min.io/server/minio/release/linux-amd64/minio  # 下载
chmod +x minio                                                   # 添加执行权限
sudo mv minio /usr/local/bin/                                   # 移到系统路径

# 下载 mc 客户端
wget https://dl.min.io/client/mc/release/linux-amd64/mc         # 下载客户端
chmod +x mc
sudo mv mc /usr/local/bin/

# 启动 MinIO
mkdir -p ~/minio_data                    # 创建数据目录
MINIO_ROOT_USER=admin MINIO_ROOT_PASSWORD=password123 \
  minio server ~/minio_data --console-address ":9001"

配置 mc 客户端¶

# 添加 MinIO 服务器别名
mc alias set local http://localhost:9000 admin password123  # 配置别名

# 验证连接
mc admin info local                   # 查看服务器信息

基本使用¶

1. mc 命令行操作¶

# 创建存储桶（bucket，类似文件夹）
mc mb local/sequencing-data           # 创建名为 sequencing-data 的桶
mc mb local/analysis-results          # 创建 analysis-results 桶

# 上传文件
mc cp sample.fastq.gz local/sequencing-data/     # 上传单个文件
mc cp --recursive raw_data/ local/sequencing-data/  # 递归上传整个目录

# 下载文件
mc cp local/sequencing-data/sample.fastq.gz ./   # 下载文件
mc cp --recursive local/sequencing-data/ ./data/  # 递归下载

# 列出文件
mc ls local/                          # 列出所有桶
mc ls local/sequencing-data/          # 列出桶内文件

# 删除文件
mc rm local/sequencing-data/old_file.fq.gz       # 删除单个文件
mc rm --recursive local/sequencing-data/temp/    # 递归删除目录

# 查看文件信息
mc stat local/sequencing-data/sample.fastq.gz    # 文件详细信息
mc du local/sequencing-data/                      # 查看桶的大小

2. Python 操作（boto3，与 AWS S3 相同接口）¶

import boto3  # AWS SDK for Python（也适用于 MinIO）

# 创建 MinIO 客户端
s3 = boto3.client(
    "s3",
    endpoint_url="http://localhost:9000",  # MinIO 地址
    aws_access_key_id="admin",             # 用户名
    aws_secret_access_key="password123",   # 密码
)

# 创建桶
s3.create_bucket(Bucket="my-data")        # 创建桶

# 上传文件
s3.upload_file(
    "sample.fastq.gz",                    # 本地文件路径
    "my-data",                             # 桶名
    "raw/sample.fastq.gz"                 # 对象键（远端路径）
)

# 下载文件
s3.download_file(
    "my-data",                             # 桶名
    "raw/sample.fastq.gz",               # 对象键
    "downloaded_sample.fastq.gz"          # 本地保存路径
)

# 列出文件
response = s3.list_objects_v2(Bucket="my-data")
for obj in response.get("Contents", []):
    print(f"{obj['Key']}  {obj['Size']} bytes")

# 生成预签名 URL（临时分享链接）
url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-data", "Key": "raw/sample.fastq.gz"},
    ExpiresIn=3600  # 1 小时有效
)
print(f"分享链接: {url}")

3. 生信数据管理示例¶

#!/bin/bash
# upload_sequencing_data.sh - 上传测序数据到 MinIO

PROJECT="t2d_metagenome"
BUCKET="local/sequencing-data/${PROJECT}"

# 创建项目目录结构
mc mb ${BUCKET}/raw/         2>/dev/null  # 原始数据
mc mb ${BUCKET}/clean/       2>/dev/null  # 质控后数据
mc mb ${BUCKET}/aligned/     2>/dev/null  # 比对结果
mc mb ${BUCKET}/results/     2>/dev/null  # 分析结果

# 上传原始 FASTQ 文件
echo "上传原始数据..."
mc cp --recursive raw_data/ ${BUCKET}/raw/

# 上传质控后的数据
echo "上传质控数据..."
mc cp --recursive clean_data/ ${BUCKET}/clean/

# 查看空间使用
mc du ${BUCKET}

echo "上传完成"

高级用法¶

1. 生命周期管理（自动清理旧数据）¶

# 设置数据过期策略（30天后自动删除临时文件）
mc ilm rule add local/sequencing-data \
  --prefix "temp/" \                   # 只对 temp/ 目录生效
  --expiry-days 30                     # 30 天后过期

# 查看策略
mc ilm rule list local/sequencing-data

2. 版本控制¶

# 启用版本控制（防止误删）
mc version enable local/sequencing-data  # 开启版本控制

# 查看文件的所有版本
mc ls --versions local/sequencing-data/sample.fastq.gz

3. 事件通知¶

# 配置文件上传通知（比如上传完成后自动触发分析）
mc event add local/sequencing-data arn:minio:sqs::1:webhook \
  --event put \                        # 上传事件
  --prefix "raw/" \                    # 只监控 raw/ 目录
  --suffix ".fastq.gz"                # 只监控 .fastq.gz 文件

常见报错与解决¶

报错信息	原因	解决方法
`Connection refused`	MinIO 服务未启动	检查服务是否运行
`Access Denied`	用户名密码错误或无权限	检查配置的 access key
`Bucket already exists`	桶已存在	正常情况，不影响使用
`The specified key does not exist`	对象键（路径）错误	检查文件路径
上传大文件失败	超时或网络中断	使用分片上传或增加超时时间
密码太短	密码不足 8 位	MinIO 要求密码至少 8 个字符

速查表¶

# ===== MinIO 速查表 =====

# 安装
docker run -d -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=admin \
  -e MINIO_ROOT_PASSWORD=password123 \
  minio/minio server /data --console-address ":9001"

# mc 客户端配置
mc alias set local http://localhost:9000 admin password123

# 桶操作
mc mb local/bucket                    # 创建桶
mc rb local/bucket                    # 删除桶
mc ls local/                          # 列出桶

# 文件操作
mc cp file local/bucket/              # 上传
mc cp local/bucket/file ./            # 下载
mc cp -r dir/ local/bucket/           # 递归上传
mc ls local/bucket/                   # 列出文件
mc rm local/bucket/file               # 删除文件
mc du local/bucket/                   # 查看大小
mc cat local/bucket/file.txt          # 查看内容

# 管理
mc admin info local                   # 服务器信息
mc ilm rule add local/bucket --expiry-days 30  # 生命周期
mc version enable local/bucket        # 版本控制

# Python (boto3)
# pip install boto3
# s3 = boto3.client("s3", endpoint_url="http://localhost:9000", ...)
# s3.upload_file("local", "bucket", "key")
# s3.download_file("bucket", "key", "local")