子兮子兮

注意：不能直接在原单机数据目录上启动 MinIO 集群！

MinIO 单机无法直接升级为集群，只能通过“新建集群 + 数据镜像迁移 + Endpoint 切换”来平滑迁移。

核心操作步骤：

1. 新建 MinIO 集群
2. 通过镜像 / 同步工具迁移数据
3. 切换访问地址（Endpoint）

• 保证对象数据 + 元数据完整
• 控制业务写入窗口，迁移过程中只读
• DNS / 网关层无感切换

一、迁移前准备（非常重要）

1. 迁移目标与原则

迁移目标

• 将现有单机 MinIO 平滑迁移至分布式集群
• 保证对象数据、元数据完整
• 业务停写时间 ≤ 5 分钟

核心原则

• ❌ 不复用旧 MinIO 的 data 目录
• ❌ 不直接 rsync 数据目录
• ✅ 新建集群 + mc mirror 迁移
• ✅ 保留回滚能力

2. 规划集群规模

MinIO 集群要求：

• 最少 4 个节点
• 每个节点磁盘数量一致
• 总磁盘数 ≥ 4

3. 确保单机旧 MinIO 数据健康

mc alias set oldminio http://oldminio:9000 AK SK

mc admin info oldminio
mc admin heal oldminio

确保：

• 无损坏对象
• 无 heal pending

4. 冻结关键业务配置

• Bucket Policy
• Lifecycle
• User / AccessKey
• Region

导出备用：

mc admin config export oldminio > minio-config.json

二、迁移步骤

1. 部署新 MinIO 集群（不要对外暴露）

• 新机器
• 新磁盘
• 新 Endpoint
• 不挂业务

启动示例：

minio server \
  http://node{1...4}/data{1...2} \
  --console-address ":9001"

2. 使用 mc mirror 做首次全量同步

# 检查集群状态
mc admin info newminio

# 同步数据
mc mirror oldminio newminio

说明：

• 1 TB 通常 30 分钟 ~ 2 小时（看磁盘 / 网络）
• 自动复制 bucket / object / metadata
• 期间业务可正常读写
• 支持断点续传

3. 增量同步（多跑几次）

mc mirror oldminio newminio

执行 2～3 次，直到：

• 执行时间 < 1 分钟
• 变更数据量极小

说明已经“追平”。

4. 短暂停写窗口（关键）

这是唯一需要“控制”的地方

旧 MinIO 临时只读：

mc admin policy set oldminio read-only

或者确保业务侧能暂停上传。

5. 最后一次增量同步（秒级）

mc mirror oldminio newminio

确保数据完全一致，无新增对象。

6. 切换业务 Endpoint（无感）

• DNS CNAME 切换
• Nginx / Gateway 反向代理 upstream 切换
• 配置中心修改地址（Endpoint）

注意：

• AK / SK 可以保持一致
• Bucket 名不变 → 业务无感知

7．观察 & 回滚保障

• 保留旧 MinIO 只读运行 7 ~ 14 天作为回滚点
  • 只读模式：不再接入新业务
  • 回滚方式：Endpoint 切回，无需迁数据
• 验证：
  • 下载老文件
  • 上传新文件
  • 权限与策略正常
  • 生命周期生效

三、Bucket / 用户 / 策略迁移补充

用户与策略（需要手动）

mc admin user list oldminio
mc admin user add newminio xxx yyy
mc admin policy attach newminio readwrite --user xxx

或使用 mc admin config export/import。

四、生产环境最佳实践建议

可选操作，按需执行。

1. 使用 DNS 作为切换点

minio.example.com

而不是直接写 IP。

2. 同步期间开启版本控制（Versioning）

mc version enable newminio/bucket

防止误覆盖。

3. 对象量巨大时的加速参数

mc mirror --overwrite --remove --watch oldminio newminio

4. 开启 bitrot & heal 监控

mc admin heal -r newminio

5. 后续扩容非常方便

以后可以：

• 4 → 8 节点
• 每节点 1 → 2 磁盘

无需再迁数据

五、常见错误 & 坑

总结

最低集群规模下可以通过 mc mirror 在 1 小时内完成平滑迁移，实际业务停写时间可控制在 1 ~ 5 分钟。