第14章 从 MinIO 迁移到 RustFS 技术指南
← 所有文章 从 MinIO 迁移到 RustFS:技术指南 2025年12月7日 9分钟阅读 最佳实践 通用用法
2026年10月修订。这是目前推荐的迁移路径。复制流程修订自 2025年12月 soakes 的投稿。
通过将对象通过 S3 API 复制,将常见的 S3 工作负载从 MinIO 迁移到新的 RustFS 1.0 部署。在验证通过之前,保持 MinIO 源端完整不变,然后将客户端指向 RustFS 端点。
RustFS 支持常见的 S3 工作流:存储桶和对象操作、列表、分块上传、版本控制、生命周期、标签、IAM、存储桶策略以及服务端加密工作流。它与所有 AWS S3 或 MinIO API 并不完全相同。请阅读已知的兼容性差异,并针对目标版本验证你的应用所使用的操作。
本指南不承诺零停机、SLA 或价格。它也不会用当前的 RustFS 二进制文件替换 MinIO 数据目录。
该查阅哪一页
| 页面 | 用途 | | :--- | :--- | | 本指南 | 迁移到当前 RustFS 1.0 版本的推荐路径。 | | 二进制替换,2026年3月18日 | 仅适用于 RustFS 1.0.0-alpha.89 的历史示例。 | | RustFS 1.0.0 GA | 1.0.0 正式版发布的内容。 | | GitHub 发布 | 要安装的标签。在生产切换前请确认。 |
已发布的 RustFS 二进制文件和容器镜像不包含用于 MinIO 磁盘读取的专用 rio-v2 构建。不要将当前的 rustfs/rustfs 镜像指向 MinIO 数据目录并将其视为迁移。
版本预期
源端:一个可以使用 AWS 签名版本 4 凭据读取的 MinIO 部署。本指南不认证特定的 MinIO RELEASE 标签,并且 MinIO 管理 API 与 S3 数据平面是独立的界面。清点你实际运行的源版本,包括存储桶是否使用版本控制、Object Lock、默认加密或外部 KMS。
目标端:RustFS 1.0.0,通用可用版本于 2026年9月16日,或后续的 1.0 补丁版本。下文示例使用明确的镜像 rustfs/rustfs:1.0.3,发布于 2026年10月17日。该补丁保留了 1.0.2 的服务端代码并更新了嵌入式 Console。在拉取之前检查当前发布版本,并固定你验证过的标签。不要为新的迁移安装 1.0.0-alpha.89。
客户端:MinIO 客户端 mc,在此作为 S3 客户端使用(别名、ls、mirror、diff、stat、cp),或带有 --endpoint-url 的 AWS CLI。不要将 mc admin 用作迁移接口来针对 RustFS。
拓扑限制
复制过程不保留 MinIO 的驱动器布局。在独立的卷上启动 RustFS。目标端的驱动器数量不必与源端相同。奇偶校验会减少相对于原始磁盘的可用容量;请根据纠删码配置文档确定目标端大小。
文档中规定的布局规则:
单驱动器池具有自动奇偶校验 EC:0。主机是故障域。下文的 Compose 示例即为该布局,你可以用它来排练复制过程。这不是生产环境的持久性计划。 多驱动器纠删集包含 2 到 16 个驱动器。多节点、多磁盘安装文档将生产集群记录为至少四台服务器,每台至少有一个磁盘。 RUSTFS_VOLUMES 在每个节点上必须相同,包括端点顺序。RustFS 会拒绝后续更改端点数量、顺序或 RUSTFS_ERASURE_SET_DRIVE_COUNT。 当有多个卷参数时,每个参数都需要省略号。每个池必须扩展为至少两个驱动器端点。单驱动器池不能加入多池部署。参见集群生命周期。 Docker 的默认桥接网络不支持多节点 RustFS。多节点容器使用主机网络,如 Docker 安装文档所述。 不要将 RustFS 卷放置在 NFS 上。Linux 先决条件建议数据磁盘使用 XFS。
哪些不会自动迁移
mc mirror 复制当前对象字节。公共 mc 文档将该命令描述为同步当前对象,不包括版本历史。在处理用户元数据和标签之前,请将其视为未经验证,直到你进行抽查。存储桶配置、身份和复制不会随对象复制一起迁移。
| 项目 | 预期结果 | | :--- | :--- | | 当前对象字节 | 在最终遍历成功后由 mc mirror 复制。 | | 用户元数据和标签 | 不保证。在切换前,对样本进行 mc stat 比较。 | | 旧版本和删除标记 | 普通镜像不复制它们。如果源存储桶有版本控制,请在两侧统计版本数。 | | Object Lock 保留和法律保留 | 镜像不会建立它们。在复制锁定数据之前,在目标存储桶上启用 Object Lock,然后验证样本。 | | 存储桶策略、生命周期、CORS、网站、日志 | 从源端导出并重新应用。存储桶访问日志和所有权控制与 AWS S3 不等价。 | | ACL 授权策略 | 不是 RustFS 授权模型。预设 ACL 标头仅部分有效。使用 IAM 和存储桶策略。 | | 事件通知 | 在 RustFS 上重新配置。 | | 存储桶复制和站点复制 | 在数据复制后重新配置。镜像不会移动复制拓扑。 | | IAM 用户、组、策略和服务账户 | 在 RustFS 上重新创建。用于复制的根密钥不是应用凭据。 | | LDAP、OIDC 和 STS | 重新配置。此流程不导入这些提供商。 | | MinIO 服务器配置和 mc admin 状态 | 保留在 MinIO 上。 | | 进行中的分块上传 | 在最终复制之前在源端完成或中止它们。 | | S3 客户端无法解密的对象 | 保留不动。KES、MinKMS 或其他外部密钥服务可能留下客户端无法读取的密文。即使上传者未设置 SSE 标头,存储桶默认加密也可以加密对象,因此假设存储桶为明文之前,请清点加密情况。 | | 转换过的对象 | 仅当通过 MinIO 的 GET 返回你要存储的字节时才复制它们。 |
1. 备份
采取如果切换被推迟所需的备份。
在停止写入器之前,快照或以其他方式备份 MinIO 数据磁盘和服务配置。 记录存储桶列表、版本控制状态、Object Lock 状态、存储桶策略、生命周期规则、通知目标以及正在使用的身份提供商。 保持 MinIO 已安装及其数据目录不变。此流程从不格式化这些磁盘,也从不通过它们写入迁移。 存储 RustFS Compose 文件以及你在目标端设置的访问密钥。在共享该文件之前替换占位符秘密。
2. 静默写入
停止应用写入器。让进行中的分块上传完成,或中止它们。在客户端仍在写入时启动的镜像可能会遗漏该遍历开始后创建的对象。
之前的一次性 mc mirror 可以减少最终遍历移动的数据量。在最终复制之前停止该命令。mc mirror --watch 会持续监视源端直到你终止它;它并不能消除停止写入器、运行最终复制并进行验证的需要。不要传递 --remove。该标志会删除源端不存在的目标端对象。
3. 部署 RustFS 目标端
使用空的 RustFS 卷。下文中的服务、卷和网络名称指代相同的键。
仅在确认发布页面上的该标签后,才固定 rustfs/rustfs:1.0.3。将 RUSTFS_ACCESS_KEY 和 RUSTFS_SECRET_KEY 设置为不同于镜像默认值 rustfsadmin 的值。MinIO 样式的 MINIO_ROOT_USER 和 MINIO_ROOT_PASSWORD 仅在未设置规范变量时被接受,且已被弃用。参见凭据管理。
```yaml services: rustfs: image: rustfs/rustfs:1.0.3 container_name: rustfs hostname: rustfs environment: RUSTFS_VOLUMES: /data RUSTFS_ADDRESS: ":9000" RUSTFS_CONSOLE_ENABLE: "true" RUSTFS_CONSOLE_ADDRESS: ":9001" RUSTFS_ACCESS_KEY: replace-with-your-access-key RUSTFS_SECRET_KEY: replace-with-your-secret-key RUSTFS_REGION: us-east-1 ports: - "9000:9000" - "9001:9001" volumes: - rustfs-data:/data networks: - rustfs
networks: rustfs: driver: bridge
volumes: rustfs-data: ```
RUSTFS_VOLUMES=/data 与挂载卷匹配。这是单个本地驱动器。就绪状态是 S3 端口上的无认证探测,而不是 Console 端口。从主机:
```bash curl -fsS http://127.0.0.1:9000/health/ready ```
200 表示存储、IAM 和同伴健康已就绪。503 表示未就绪。该探测在复制之前是必需的,但它不是对象已迁移的证据。状态检查文档描述了响应。
保持 MinIO 在其现有端点。这两个服务是复制时独立的 S3 端点。
4. 复制
在能够到达两个端点的主机上安装 mc。在此窗口内使用根凭据,以便客户端可以创建缺失的存储桶并读取源端命名空间。当源端依赖版本控制或 Object Lock 设置时,在镜像之前在 RustFS 上创建版本化或 Object Lock 存储桶,并针对目标版本确认调用。
```bash mc alias set minio-old https://minio.example.com SOURCE_ACCESS_KEY SOURCE_SECRET_KEY mc alias set rustfs-new http://127.0.0.1:9000 TARGET_ACCESS_KEY TARGET_SECRET_KEY
mc ls minio-old mc ls rustfs-new
mc mirror --dry-run minio-old/production-data rustfs-new/production-data mc mirror --overwrite minio-old/production-data rustfs-new/production-data ```
为每个存储桶重复镜像操作。--dry-run 列出工作但不写入。--overwrite 在源端副本是你希望保留的那个时替换目标端对象。如果没有 --overwrite,mc mirror 会跳过目标端已存在的对象,记录错误并继续。
RustFS 默认使用路径样式寻址。显式设置客户端端点。将区域设置为 us-east-1,或为你配置的 RUSTFS_REGION。虚拟主机样式 URL 还需要 RUSTFS_SERVER_DOMAINS。
当字节到达 RustFS 后,从你保存的清单中重新应用存储桶策略、生命周期规则、CORS、通知和复制。为应用创建 IAM 用户,并从客户端配置中退役根密钥。
5. 验证
在端口 9001 打开 Console 仅表明进程正在提供 UI。在发送流量之前,使用以下检查。
```bash curl -fsS http://127.0.0.1:9000/health/ready
mc diff minio-old/production-data rustfs-new/production-data
mc ls --recursive minio-old/production-data | wc -l mc ls --recursive rustfs-new/production-data | wc -l
mc stat minio-old/production-data/path/to/object mc stat rustfs-new/production-data/path/to/object
mc cp minio-old/production-data/path/to/object ./source-object mc cp rustfs-new/production-data/path/to/object ./target-object sha256sum ./source-object ./target-object ```
结果解读如下:
mc diff 无输出意味着客户端未报告列表差异。它不是逐字节的证明。 递归计数应与你复制的存储桶匹配。版本化存储桶需要单独的版本计数;普通镜像未复制旧版本。 比较大小和你计算的校验和。当分块布局改变时,ETags 可能不同,因此仅 ETag 相等不是成功测试。 mc stat 是用户元数据和标签的抽查。如果样本与你应用所需的不匹配,请重新复制或重新应用元数据。 针对 RustFS 端点运行应用的一次只读遍历,使用与生产环境相同的 SDK 调用。
通过更改客户端配置中的 S3 端点进行切换。保持路径样式和区域与服务器对齐。在允许写入器之前监视错误。
6. 回滚
回滚将客户端返回到 MinIO。
将应用指回 MinIO 端点和凭据。 保留 MinIO 数据目录原样。在你计划的验证窗口通过之前,不要删除它。 若要丢弃有问题的 RustFS 副本,删除新的 rustfs-data 卷并重复部署和复制。这只删除目标端副本。 由于此流程不写入 MinIO,因此没有第二个恢复步骤。
延伸阅读
* S3 协议,包括已知的兼容性差异 * 凭据管理 * 状态检查 * 纠删码配置 * 集群生命周期 * Docker 安装 * RustFS 1.0.0 GA 公告 * 1.0.0-alpha.89 的历史二进制替换 * GitHub 发布
MinIO 是 MinIO, Inc. 的注册商标。RustFS 与 MinIO, Inc. 无关联,未获其认可或赞助。