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