open-im-server S3 存储引擎切换与数据迁移指南:使用 s3convert 工具迁移对象存储数据

原创2026-09-20 19:35:401,955 阅读
文章标签:即时通讯后端微服务

open-im-server S3 存储引擎切换与数据迁移指南:使用 s3convert 工具迁移对象存储数据

导读

当 open-im-server 中的对象存储(S3 兼容存储)从 MinIO 切换到腾讯云 COS、阿里云 OSS、七牛 Kodo 或 AWS S3 后,历史消息中的图片、语音、视频等文件仍然留在旧存储中,需要把数据连同 MongoDB 中的元数据一并迁移。本篇指南围绕仓库自带的迁移工具 tools/s3 展开,讲解 s3convert 的构建、启动参数、底层迁移流程以及配置文件要求,帮助你安全、完整地在不同 S3 存储引擎之间搬迁数据。读完本文,你将掌握存储引擎切换后对象数据的完整迁移方案,并能对照源码理解其逐文件校验、断点续迁与元数据更新机制。

一、工具定位与适用场景

tools/s3 是 open-im-server 官方提供的数据迁移工具,其用途在 tools/s3/README.md 中明确描述为:

After s3 switches the storage engine, convert the data(S3 切换存储引擎后,转换数据)

它解决的是这样一类实际问题:open-im-server 的对象存储配置(object.enable)从 minio 切换到 cos / oss / kodo / aws 之后,MongoDB 的 object 元数据表中记录的 engine 仍指向旧引擎,而历史文件实体也仍存放在旧存储桶中。s3convert 负责将旧引擎中的文件对象复制到新引擎,并同步更新元数据,保证切换后用户仍能正常访问历史文件。

该工具适用以下场景:

  • 本地部署的 MinIO 迁移到公有云对象存储(COS / OSS / Kodo / AWS S3);
  • 从一种公有云对象存储迁移到另一种;
  • 任何 object.enable 被修改后需要保留历史文件的场景。

二、构建与启动

2.1 构建

在仓库根目录执行 Go 构建命令(需要已安装 Go 工具链):

go build -o s3convert main.go

命令在 tools/s3/README.md 的 build 小节中给出。由于工具位于 tools/s3/main.go,也可以从该目录直接构建:

cd tools/s3 && go build -o s3convert main.go

2.2 启动参数

s3convert 通过标准库 flag 解析两个命令行参数(见 tools/s3/main.go):

参数 说明 示例
-config open-im-server 配置目录路径 ./../../config
-name 旧的(切换前的)存储引擎名称 minio

启动命令:

./s3convert -config <config dir path> -name <old s3 name>

README 中给出的真实示例:

./s3convert -config ./../../config -name minio

其中 -name minio 表示当前配置(openim-rpc-third.yml 中的 object.enable)已经是新引擎,而旧引擎是 MinIO,需要把 MinIO 中的历史数据迁出。

程序正常结束时会在标准输出打印 success;若迁移过程中出错,错误信息会打印到标准错误并返回非零退出码(见 tools/s3/main.go)。

2.3 前置校验:新旧引擎不能相同

在正式迁移前,工具会先读取 openim-rpc-third.yml,比较其中 object.enable 与 -name 参数是否相同,若相同则直接报错退出 same s3 storage(见 tools/s3/internal/conversion.go)。也就是说,-name 必须传旧引擎、配置文件中的 enable 必须是新引擎,二者不能一致,否则迁移无意义。

三、支持的对象存储引擎

工具通过 getS3 函数(见 tools/s3/internal/conversion.go)支持以下五种引擎,对应 object.enable 的合法取值:

引擎标识 说明 配置块
minio MinIO(自建 S3 兼容存储) 独立配置文件 minio.yml
cos 腾讯云对象存储 object.cos
oss 阿里云对象存储 object.oss
kodo 七牛云对象存储 object.kodo
aws AWS S3 object.aws

传入其他名称时会返回错误 invalid object enable: <name>。

其中 MinIO 是特例:它需要单独读取 config/minio.yml 中的连接配置,并依赖 Redis 构建 MinIO 缓存客户端;而 COS / OSS / Kodo / AWS 的配置都内嵌在 object 配置块中,从 openim-rpc-third.yml 直接解析。

3.1 新旧引擎的配置读取方式

getS3 的读取逻辑(见 tools/s3/internal/conversion.go):

  • minio:从配置目录读取 minio.yml(config/minio.yml)中的 bucket、accessKeyID、secretAccessKey、sessionToken、internalAddress、externalAddress、publicRead 等字段(结构定义见 pkg/common/config/config.go),再从 redis.yml 读取 Redis 连接信息并创建 Redis 缓存,最终构建 MinIO 客户端;
  • cos / oss / kodo / aws:从 openim-rpc-third.yml 的 object.cos / object.oss / object.kodo / object.aws 子配置块构建对应客户端(结构定义见 pkg/common/config/config.go)。

因此运行工具前,必须保证配置目录中存在 openim-rpc-third.yml、minio.yml、redis.yml、mongo.yml 等文件,且内容与 open-im-server 实际运行时的配置一致。

四、迁移流程与底层实现

Main 函数(见 tools/s3/internal/conversion.go)是迁移的入口,整体流程分为四个阶段。

4.1 阶段一:统计旧引擎对象数量

工具先通过 MongoDB 查询旧引擎下有多少条对象元数据记录:

count, err := getEngineCount(s3db, oldS3.Engine())
log.Printf("engine %s count: %d", oldS3.Engine(), count)

GetEngineCount 对应 MongoDB 中的聚合统计:db.object.count({engine: <旧引擎>})(实现见 pkg/common/storage/database/mgo/object.go)。这里的 object 集合即对象元数据表,其文档结构在 pkg/common/storage/model/object.go 中定义,包含 name(唯一标识)、engine(所属存储引擎)、key(存储对象键)、size(文件大小)、content_type、create_time 等字段。

4.2 阶段二:逐条取出元数据并迁移

主循环从 i = 1 到 count+1 逐条处理:

for i := 1; i <= count+1; i++ {
    res, err := doObject(s3db, newS3, oldS3, skip)
    ...
}

doObject(见 tools/s3/internal/conversion.go)是单对象迁移的核心,其处理逻辑如下:

  1. 取出下一条待迁移记录:GetEngineInfo(ctx, oldS3.Engine(), 1, skip) 按 engine 过滤、跳过已处理的数量,每次取 1 条(mgo/object.go);
  2. 查不到记录则结束:len(infos) == 0 时返回 End: true,主循环 break;
  3. 幂等去重检查:db.Take(ctx, newS3.Engine(), obj.Name) 查询该对象在新引擎下是否已存在元数据。若已存在(返回 nil 错误)说明该对象已迁移过,直接 Skip,跳过本次处理;只有 mongo.ErrNoDocuments(无记录)才会继续迁移——这一机制保证了工具在中断后重启可断点续迁;
  4. 生成下载与上传的预签名 URL:oldS3.AccessURL 生成旧引擎的临时下载地址(有效期 1 小时),newS3.PresignedPutObject 生成新引擎的预签名上传地址(同样 1 小时),并携带原 ContentType;
  5. 流式搬运:通过 http.Get 下载旧对象,再把响应体直接作为 PUT 请求体上传到新引擎(http.NewRequest(http.MethodPut, putURL.URL, downloadResp.Body)),文件以流式传输,不落本地磁盘;
  6. 处理源文件丢失:若旧引擎返回 HTTP 404(StatusNotFound),说明源文件已不存在,此时返回 Skip: true 跳过并继续(只跳过文件实体,不更新元数据);
  7. 更新元数据:上传成功后调用 db.UpdateEngine(ctx, obj.Engine, obj.Name, newS3.Engine()),把该记录的 engine 字段从旧引擎更新为新引擎(mgo/object.go)。

4.3 阶段三:Skip 计数与主循环推进

每轮 doObject 返回一个 Result:

type Result struct {
    Skip bool
    End  bool
}
  • End: true:没有更多待迁移记录,主循环结束;
  • Skip: true:当前记录被跳过(已在目标引擎中存在元数据,或源文件 404),skip 计数 +1,下一轮从下一条继续;
  • 普通成功:skip 不变,下一轮继续取下一条。

之所以要维护独立的 skip 计数,是因为 GetEngineInfo 用的是 MongoDB 的 skip + limit 分页:每轮取出 1 条,若该条被跳过,则需要跳过位置 +1 才能取到下一条未处理的记录。主循环上界取 count+1 而非 count,正是为了容纳这些跳过导致的额外轮次。

4.4 阶段四:进度日志

每一轮都会打印耗时与结果:

log.Printf("start %d/%d", i, count)
log.Printf("end [%s] %d/%d result %+v", time.Since(start), i, count, *res)

单文件操作(下载、上传、更新元数据)的超时由 defaultTimeout = 10s(conversion.go)控制;单次 HTTP 下载与上传之间还会打印 file size 便于核对文件大小。

五、完整迁移操作步骤

以下是一个从 MinIO 切换到腾讯云 COS 的完整实操流程:

5.1 修改存储配置

编辑 config/openim-rpc-third.yml 中的 object 配置块,把 enable 改为新引擎并填写对应配置(参考 config/openim-rpc-third.yml):

object:
  # 从 minio 切换为 cos / oss / kodo / aws
  enable: cos
  cos:
    bucketURL: https://temp-1252357374.cos.ap-chengdu.myqcloud.com
    secretID: <你的 SecretID>
    secretKey: <你的 SecretKey>
  # oss / kodo / aws 同理,填写各自的 endpoint、bucket、accessKeyID 等字段

各云厂商配置字段说明:

  • COS(object.cos):bucketURL(存储桶访问域名)、secretID、secretKey、可选 sessionToken、publicRead;
  • OSS(object.oss):endpoint、bucket、bucketURL、accessKeyID、accessKeySecret、可选 sessionToken、publicRead;
  • Kodo(object.kodo):endpoint、bucket、bucketURL、accessKeyID、accessKeySecret、可选 sessionToken、publicRead;
  • AWS S3(object.aws):region、bucket、accessKeyID、secretAccessKey、可选 sessionToken、publicRead。

对应的结构体定义可查阅 pkg/common/config/config.go。

注意:MinIO 的配置是独立文件 config/minio.yml,切换后新引擎不再读取该文件,但迁移工具仍需要它来访问旧存储,因此迁移完成前不要删除或修改 minio.yml。

5.2 确认 MongoDB 与 Redis 配置

迁移工具需要连接 MongoDB 读取/更新 object 元数据(getMongo 读取 mongo.yml,见 conversion.go),迁移 MinIO 数据时还需要 Redis(构建 MinIO 缓存客户端)。请确认配置目录下的 mongo.yml、redis.yml 与 open-im-server 实际运行环境一致,且 MongoDB 中 object 集合可访问。

5.3 构建并执行迁移

go build -o s3convert main.go
./s3convert -config ./../../config -name minio

执行后观察日志:

engine minio count: 12345
start 1/12345
file size 204800
end [1.2s] 1/12345 result {false false}
...
success

看到最终 success 即迁移完成。

5.4 验证结果

  • 检查日志中无 error 输出,退出码为 0;
  • 在目标存储桶(如 COS)中确认历史文件已存在;
  • 随机抽查若干历史消息,确认图片、语音、文件可正常访问;
  • 如需核对元数据,可查询 MongoDB:db.object.find({engine: "minio"}) 应返回空(或仅剩 404 跳过的记录),db.object.find({engine: "cos"}) 的数量应等于原 minio 数量减去被 404 跳过的记录。

六、迁移机制的可靠性与边界

6.1 断点续迁与幂等

工具以 MongoDB 中对象的 name 为唯一标识(name 字段建有唯一索引,见 mgo/object.go)。每轮迁移前先用 Take 检查目标引擎下是否已存在同名元数据(conversion.go),已存在则跳过。因此迁移过程中途中断后,重新执行同一命令即可从断点继续,重复执行也不会产生重复数据。

6.2 迁移粒度与一致性

  • 迁移以单条元数据记录为最小单位,先复制文件实体、后更新 engine 字段;
  • 文件上传成功但元数据更新失败时,该记录会在下一轮被 Take 识别为“已迁移”(目标引擎下已有同名元数据),直接跳过,不会重复上传——但此时 engine 字段可能仍未更新,若出现此类情况建议人工核对;
  • 源文件在旧存储中已删除(404)时,工具只跳过该对象并保留原元数据,不会误删记录。

6.3 注意事项

  • 云厂商存储桶需允许预签名 URL 操作:迁移依赖 AccessURL(下载)与 PresignedPutObject(上传),需要对应引擎 SDK 支持预签名,且新存储桶应开启可写权限;
  • 文件过大时注意超时:单对象默认超时 10 秒(defaultTimeout),超大文件的下载/上传可能超时失败,可结合日志定位具体对象后人工处理;
  • 不要在迁移过程中同时修改配置:工具启动时一次性读取新旧两套配置,运行期间修改配置文件不会生效;
  • 迁移完成后清理:确认数据完整后,再按需下线旧存储(如关闭 MinIO 服务、删除旧桶数据)。

七、源码速查

关注点 文件
工具入口与命令行参数解析 tools/s3/main.go
迁移核心流程 Main / doObject tools/s3/internal/conversion.go
工具使用说明 tools/s3/README.md
对象元数据模型(object 集合) pkg/common/storage/model/object.go
MongoDB 对象存取实现(GetEngineCount / GetEngineInfo / UpdateEngine 等) pkg/common/storage/database/mgo/object.go
存储引擎配置结构(Minio / Cos / Oss / Kodo / Aws) pkg/common/config/config.go
对象存储配置示例(object.enable) config/openim-rpc-third.yml
MinIO 连接配置示例 config/minio.yml

结语

tools/s3 为 open-im-server 的存储引擎切换提供了开箱即用的数据迁移方案:只需在配置中声明新引擎、用 -name 指定旧引擎,工具便会自动完成对象文件的跨存储复制与 MongoDB 元数据更新,并借助基于唯一标识的幂等检查实现断点续迁。从源码可见,整个迁移围绕「预签名 URL 流式搬运 + engine 字段更新」这一简洁模型展开,兼顾了可恢复性与数据一致性,是完成 S3 存储平滑切换的关键配套工具。

登录后查看全文
open-im-server