文件存储 | OpenIM

1. 背景​

在即时通信系统里，图片、语音、视频、文件、视频封面等内容都属于对象数据。它们和普通文本消息不同，通常体积更大、上传时间更长、受网络波动影响更明显。如果所有文件都经由业务 API 服务中转，服务端会同时承担业务处理和大流量文件搬运，容易影响消息、会话、群组等核心链路的稳定性。

OpenIM 的 S3 对象存储能力，就是为了解决这个问题：让业务服务只负责鉴权、签名、元数据和访问控制，让文件数据直接进入对象存储。这样既能提高上传效率，也能降低 API 服务压力。

2. 核心定位​

OpenIM 的 S3 方案不是简单地把文件上传到 MinIO，而是一套面向 IM 场景的大对象管理能力。它覆盖上传、下载、访问、续传、去重、清理、迁移等环节。

整体上可以理解为两层：

• 服务端负责控制面：鉴权、生成临时凭证、登记对象信息、生成统一访问地址、执行过期清理。
• SDK 负责客户端上传体验：读取文件、计算哈希、分片上传、断点续传、并发控制、进度回调、取消上传。

这种拆分让“业务控制”和“文件流量”分离。服务端不再搬运大文件，客户端拿到授权后直接上传到对象存储。

3. 整体上传体验​

用户发送图片、视频或文件时，SDK 会先在本地分析文件，判断文件大小和类型，并计算文件内容特征。然后 SDK 向服务端申请一次上传授权。服务端校验用户身份和对象归属后，返回临时上传凭证。之后文件内容由客户端直接传到对象存储，不再经过 OpenIM API 服务中转。

上传完成后，服务端会登记这份对象和业务对象名之间的关系，并返回一个 OpenIM 层面的访问地址。业务消息里保存的是这个稳定地址，而不是某个存储厂商暴露的原始地址。后续访问时，OpenIM 再根据对象元数据生成临时访问链接并重定向到真实对象。

这个链路的好处是：

• 上传大文件时不会挤占业务 API 带宽。
• 下载地址可以统一由 OpenIM 管理。
• 底层存储后端变化时，业务层地址可以保持稳定。
• 私有桶也可以通过临时授权安全访问。

4. 多存储后端兼容​

OpenIM 支持多种 S3 或 S3 兼容对象存储，包括 MinIO、腾讯云 COS、阿里云 OSS、七牛 Kodo、AWS S3 等。业务层不需要感知具体厂商差异，只需要使用 OpenIM 提供的统一对象能力。

这带来的优势是部署选择更灵活：

• 私有化部署可以使用 MinIO。
• 公有云部署可以接入云厂商对象存储。
• 企业后续更换存储厂商时，业务逻辑不需要整体重写。
• 存储访问域名、内外网地址、权限策略可以按部署环境调整。

5. 客户端直传​

传统文件上传常见做法是客户端先把文件传给业务服务，业务服务再转存到对象存储。这种方式实现简单，但在大文件和高并发场景下成本很高。

OpenIM 采用客户端直传：服务端只签发短期授权，文件本体由客户端直接上传到对象存储。这样 API 服务只处理轻量请求，不承担大文件传输。

客户端直传的优势包括：

• 降低 API 服务带宽和连接压力。
• 大文件上传更稳定，不影响消息收发等核心接口。
• 对象存储天然适合承载大对象和高并发下载。
• 文件上传链路更短，整体吞吐能力更好。

6. 分片上传​

对于较大的图片、视频和文件，SDK 会使用分片上传。文件被拆成多个小块，每个分片独立上传，最后由对象存储合并成完整对象。

分片上传带来的体验提升很明显：

• 大文件不需要一次性完整上传。
• 某个分片失败时，只需要重传失败部分。
• 可以通过受控并发提升上传速度。
• 上传过程更容易展示细粒度进度。

SDK 会根据文件大小和服务端限制自动选择合适的分片大小，上层业务不需要手动处理这些细节。

7. 秒传​

OpenIM 支持基于文件内容的秒传。SDK 会计算文件内容特征，服务端可以判断相同内容是否已经存在。如果对象存储里已经有这份文件，就不再重复上传文件内容，而是直接登记一次新的业务引用并返回访问地址。

秒传的价值主要体现在重复发送场景：

• 同一用户重复发送相同文件时，可以瞬间完成。
• 不同消息引用同一份真实对象，减少重复存储。
• 降低网络传输成本和对象存储写入成本。
• 弱网环境下减少不必要的重传。

秒传不是按文件名判断，而是按内容特征判断，因此更适合 IM 文件场景。

8. 断点续传​

SDK 会在本地记录上传进度。上传过程中，如果网络中断、应用退出、进程重启，已经成功上传的分片不会丢失。用户再次上传同一个文件时，SDK 可以从本地恢复状态，只补传尚未完成的分片。

断点续传能显著改善弱网和移动端体验：

• 大文件失败后不用从头开始。
• 切后台、断网、重启后仍能继续。
• 每个已成功的分片都能沉淀为有效进度。
• 用户重试成本更低，失败体验更可控。

这也是 OpenIM S3 方案相比普通表单上传的重要优势之一。

9. 并发与内存控制​

SDK 支持分片并发上传，但不会无节制地并发。上传时会根据分片大小和内存预算动态调整并发数量，避免为了追求速度导致客户端内存过高。

当分片较小时，SDK 可以并发上传多个分片；当分片较大时，SDK 会降低并发；如果分片过大，还会退回更稳妥的流式上传方式。

这种策略在移动端、桌面端、Web/WASM 等环境中都更稳。它兼顾了上传速度、内存占用和设备稳定性。

10. 进度反馈与取消上传​

SDK 会把上传过程拆成多个可感知阶段，例如打开文件、计算哈希、获得上传会话、上传分片、完成合并等。上层 UI 可以据此展示更准确的进度，而不是只有一个模糊的百分比。

对于大文件来说，这一点很重要。用户可以清楚知道当前是在本地计算、网络上传，还是等待服务端完成合并。

SDK 也支持取消上传。业务侧可以为上传任务绑定取消标识，用户点击取消后，SDK 会中止对应上传任务，避免继续消耗网络和设备资源。

11. 统一访问地址​

OpenIM 上传完成后返回的是 OpenIM 统一访问地址，而不是直接暴露对象存储原始地址。访问文件时，OpenIM 会根据对象元数据生成临时访问链接，再跳转到真实存储地址。

这样设计有几个好处：

• 消息里保存的文件地址更稳定。
• 底层存储迁移不会直接影响历史消息。
• 私有对象也可以通过临时授权安全访问。
• 可以统一处理文件名、内容类型、图片缩略图等访问策略。

对于图片类对象，访问层还可以支持缩略图、格式转换、宽高裁剪等派生能力，从而提升聊天图片加载效率。

12. 权限与隔离​

普通用户上传对象时，对象会归入当前用户自己的命名空间。这样可以避免用户伪造或覆盖其他用户的文件对象。服务端在生成上传授权前会进行身份校验和对象归属校验，确保上传行为受控。

对象存储的长期密钥不会下发给客户端。客户端拿到的只是短期上传或访问凭证，即使链接泄露，风险也会被限制在较短时间和特定对象范围内。

这种方式兼顾了直传效率和安全边界。

13. 元数据治理​

对象存储只负责保存文件内容，但 IM 系统还需要知道这份文件属于哪个用户、哪个业务类型、使用哪个存储后端、什么时候创建、是否可以清理等信息。

OpenIM 会为每个业务对象登记元数据。元数据把“业务对象名”和“真实存储对象”分离开来。多个业务对象可以引用同一个真实对象，这也是秒传和去重能够成立的基础。

元数据治理带来的能力包括：

• 统一生成访问地址。
• 支持内容去重和秒传。
• 支持按业务类型做生命周期清理。
• 支持统计真实对象是否仍被引用。
• 支持未来迁移底层存储。

14. 生命周期清理​

IM 系统里的文件对象并不都需要永久保存。比如图片、语音、视频、视频封面等消息对象，可以根据业务策略设置保留时间。

OpenIM 支持按业务分类清理过期对象。清理时不会简单粗暴地删除真实文件，而是先删除过期业务引用，再判断真实对象是否仍被其他业务对象引用。只有没有任何引用时，才会删除对象存储里的真实文件。

这种引用计数式清理可以避免误删。它和秒传能力天然配套：同一份真实文件可能被多个消息引用，只有所有引用都过期后，真实对象才应该被删除。

15. FormData 小程序兼容通道​

除了完整的 SDK 分片上传链路，OpenIM 还保留了 FormData 表单直传能力。这条链路主要用于小程序 JSSDK，用来适配小程序平台的文件上传能力和调用限制。

需要特别说明的是，Go 语言提供的 SDK 不会调用 FormData。Go SDK 使用的是完整的分片上传链路。

FormData 是兼容通道，不具备完整上传链路的高级能力。它不支持：

• 分片上传。
• 秒传。
• 本地断点续传。
• 分片并发。
• 分片级校验和分片级进度回调。

因此，普通 App、桌面端、Go SDK、Web/WASM 端应优先使用完整的 SDK 上传能力；小程序 JSSDK 在平台限制下可以使用 FormData 作为简化直传方案。

16. 存储迁移能力​

由于 OpenIM 在元数据中记录了对象所属的存储后端，系统具备从一个对象存储迁移到另一个对象存储的基础能力。例如从自建 MinIO 迁移到云厂商对象存储，或者在不同云厂商之间切换。

迁移时，系统可以读取旧存储中的真实对象，写入新存储，并更新元数据中的存储后端信息。业务消息里保存的是 OpenIM 统一访问地址，因此迁移后历史消息仍然可以通过原有方式访问。

这降低了长期运维风险，也减少了被单一存储厂商或部署形态绑定的成本。

17. 相比传统上传方式的优势​

OpenIM S3 方案的优势可以归纳为五类。

性能方面，文件流量直达对象存储，API 服务只处理控制请求，大文件上传不会挤占核心业务接口。

稳定性方面，分片上传、断点续传、分片校验、取消上传和受控并发共同提升了弱网环境下的成功率。

成本方面，秒传和去重减少重复上传与重复存储，生命周期清理减少无效对象长期占用空间。

安全方面，客户端只拿短期授权，不接触对象存储长期密钥；文件访问也可以通过临时链接进行控制。

演进方面，统一对象地址和元数据治理让底层存储可以迁移或替换，业务层不需要感知具体厂商变化。

18. 适用场景​

OpenIM S3 对象存储适合以下场景：

• 聊天图片、原图、缩略图。
• 语音消息。
• 视频消息和视频封面。
• 普通文件消息。
• ASR 等需要临时对象上传的能力。
• 私有化部署中的文件存储。
• 大文件、弱网、移动端上传场景。

如果业务只需要小程序端简单表单上传，可以使用 FormData 兼容通道；如果需要秒传、分片、断点续传和更完整的上传体验，应使用 SDK 的完整上传能力。

19. 总结​

OpenIM 的 S3 对象存储能力，是一套面向 IM 大对象场景的文件基础设施。它通过客户端直传降低服务端压力，通过分片和断点续传提升弱网体验，通过秒传和生命周期清理降低成本，通过统一访问地址和元数据治理提升长期可维护性。

它的核心价值，是把文件上传从“业务 API 的沉重负担”变成“可授权、可续传、可去重、可治理、可迁移的对象服务能力”。对于企业级 IM，这种设计能同时提升性能、稳定性、安全性、成本控制和后续演进能力。

官网：https://openim.io

开发文档：https://docs.openim.io

部署文档：https://docs.openim.io/zh-hans/guides/solution/openclaw

GitHub仓库：https://github.com/openimsdk