minio数据迁移方法

[AI生成]

MinIO 数据迁移方法全解

跨集群或跨服务器迁移 MinIO 数据，首选官方客户端 mc mirror，它支持断点续传、增量同步、保留元数据，且不依赖两端的物理目录结构；跨云厂商或 MinIO 与其他对象存储互迁时推荐用 rclone；只有在单机部署、可停机且两端 MinIO 版本完全一致的前提下，才考虑直接 rsync 数据目录。

迁移方案选型对比

方法	适用场景	优点	缺点/风险
mc mirror	MinIO↔MinIO、MinIO↔本地、MinIO↔S3 兼容存储	官方工具、断点续传、支持 --watch 持续同步、--preserve 保留属性	默认不迁移对象版本历史（需 mc replicate）
rclone	跨云/跨厂商、对象存储到对象存储、需要限速并发控制	通用 S3 协议、并发参数可调、支持 --dry-run 演练、rclone check 校验	需手动写配置文件，桶策略等元数据不会同步
rsync 直接拷贝数据目录	单机部署、可停机窗口、两端版本与纠删码配置完全一致	速度快、不占网络协议开销	跨版本/启用加密后极易导致对象不可读；集群纠删码布局不可随意拷贝
mc cp --recursive	小规模、单桶一次性搬迁	命令简单	无增量、无 watch，中断后需重跑
站点复制 / mc replicate	双活容灾、长期同步	同步对象版本、桶配置、IAM 用户与策略	要求两端版本一致（建议 v2024.10+）、桶必须开启版本控制

一、mc mirror 标准操作步骤（推荐方案）

1. 安装 mc 客户端

wget https://dl.min.io/client/mc/release/linux-amd64/mc -O /usr/local/bin/mc
chmod +x /usr/local/bin/mc
mc --version

2. 配置源端和目标端别名

mc alias set oldminio http://<源端IP>:9000 <ACCESS_KEY> <SECRET_KEY>
mc alias set newminio http://<目标端IP>:9000 <ACCESS_KEY> <SECRET_KEY>
# 验证连通性
mc ls oldminio/
mc ls newminio/

注意用 API 端口 9000，而不是 Console 的 9001/9090 端口，这是常见的连接失败原因。

3. 全量镜像迁移

# 单桶迁移
mc mirror --overwrite --preserve oldminio/mybucket newminio/mybucket
# 整个集群所有桶迁移
mc mirror --overwrite --preserve --active-active oldminio/ newminio/

关键参数说明：

• --overwrite：目标端已有同名对象时强制覆盖，否则会报错跳过
• --preserve, a：保留源端的文件系统属性和桶策略规则
• --remove：删除目标端源端不存在的对象（让两端完全一致，慎用）
• --watch：持续监听源端变化，用于业务不停机的增量同步
• --dry-run：先演练一遍，只列出会迁移的对象，不实际传输
• --older-than / --newer-than：按时间过滤，常用于分批迁移
• --max-workers：控制并发数，网络不稳或源端压力大时调低

4. 长时间任务用 screen/tmux 托管

mc mirror 在前台运行时，SSH 断开任务会被杀掉。建议：

screen -S minio-migrate
mc mirror --overwrite --preserve --retry oldminio/ newminio/ 2>&1 | tee migration.log
# 按 Ctrl+A 再按 D 脱离会话
# 之后用 screen -r minio-migrate 重新接入查看

二、rclone 跨存储迁移方案

1. 安装

curl https://rclone.org/install.sh | sudo bash

2. 编写配置文件 ~/.config/rclone/rclone.conf

[minio-src]
type = s3
provider = Minio
env_auth = false
access_key_id = SRC_ACCESS_KEY
secret_access_key = SRC_SECRET_KEY
region = cn-east-1
endpoint = http://src-minio:9000
[minio-dst]
type = s3
provider = Minio
env_auth = false
access_key_id = DST_ACCESS_KEY
secret_access_key = DST_SECRET_KEY
region = cn-east-1
endpoint = http://dst-minio:9000

provider = Minio 这个字段是关键，否则 rclone 会默认按 AWS S3 的虚拟主机风格寻址，导致找不到桶。

3. 同步命令

# 先演练，看会同步哪些对象
rclone sync minio-src:mybucket minio-dst:mybucket --dry-run -P
# 正式执行（16 并发，失败重试 3 次）
rclone sync minio-src:mybucket minio-dst:mybucket \
  --progress --transfers 16 --checkers 16 \
  --retries 3 --log-file /var/log/rclone-sync.log
# 校验一致性
rclone check minio-src:mybucket minio-dst:mybucket

rclone sync 会删除目标端源端不存在的对象，如果想只补差异不动已有文件，用 rclone copy。

三、直接拷贝数据目录（不推荐但可用）

适用条件苛刻：单机部署、可停机、源和目标 MinIO 版本和纠删码配置完全一致、未启用 SSE 加密。

systemctl stop minio
rsync -av --progress --exclude='.minio.sys' /data/minio/ /new/data/minio/
chown -R minio-user:minio-user /new/data/minio
systemctl start minio

.minio.sys 是 MinIO 内部元数据目录，新实例启动会自动生成，不需要迁。分布式集群下数据是按纠删码条带分布的，绝不能只拷贝部分节点的目录，否则数据无法还原。

四、高频踩坑点与应对

• 版本不一致导致元数据不兼容：不同大版本间 MinIO 对象元数据格式有变化，直拷数据目录后经常出现"对象存在但读不出来"。务必先在目标端升到与源端相同版本，或直接用 mc mirror 走 S3 协议。
• 权限配置不全：mc mirror 需要源账号具备 s3:ListAllMyBuckets、s3:ListBucket、s3:GetObject，目标账号需要 s3:PutObject。最小权限配置经常漏掉 List 权限，迁移到一半卡住。排查时建议先用 root 账号验证流程可行，再降权到业务账号。
• 桶名大小写和命名规范：S3 规范要求桶名只能小写字母、数字和连字符，长度 3-63。analytics_data 这类带下划线的桶名会导致部分 S3 兼容工具报错。从其他存储（如 Ceph 放松限制的桶名）迁到 MinIO 时，含大写字母的桶名必须先重命名。
• 对象版本历史和桶策略不随 mc mirror 迁移：mc mirror 只同步当前版本对象。如果启用了版本控制或配置了 ILM、事件通知、桶策略，需要在目标端单独用 mc replicate 或 mc admin replicate 配置，或者手动重建桶策略。
• 大文件传输中断：分片上传场景中 ETag 不等于内容 MD5，无法直接用于校验。可用 --verify-checksum 或显式开启 mc config set <alias> checksum on。网络不稳时加 --retry（mc）或 --retries（rclone）。
• 后台任务被 SSH 断连杀掉：长时间迁移任务务必放在 screen/tmux 或 systemd 单元里，输出重定向到日志文件。

五、迁移后完整性验证

# 对比两端对象数
mc ls --recursive oldminio/mybucket | wc -l
mc ls --recursive newminio/mybucket | wc -l
# 官方差异对比命令，输出为空即一致
mc diff oldminio/mybucket newminio/mybucket
# 总体积对比
mc du oldminio/mybucket
mc du newminio/mybucket
# 检查未完成的分片上传残留
mc ls --incomplete newminio/mybucket
mc rm --incomplete newminio/mybucket --force   # 清理残留

mc diff 为空、两端对象数和 du 结果一致，且业务侧能正常 GET 到关键样本文件，即可以认为迁移完成。