OpenIM 源码解析-新系列来了

本文是「OpenIM 源码解析」系列开篇。后续将按 Server、SDK、端到端全链路，逐章深入源码与架构。

更新本系列的同时，我们的WebRTC 源码解析也会持续更新。

一、我们为什么开这个专题？

做 IM 相关开发或者是 WebRTC 媒体信令开发的的人，大概率遇到过这些场景：

• 接入第三方 IM，按文档调 API 能跑通，但消息丢了、Seq 乱了、重连后不同步，不知道问题出在哪一层；
• 想二次开发——加个自定义消息、改推送逻辑、接业务 Webhook——不知道改 Server 还是改 SDK；
• 面试或技术分享被问到「一条消息从发送到接收经历了什么」，只能停留在概念层，讲不出源码路径。
• 我们的SDP 如何实时可靠地进行交换。

OpenIM 是一个成熟的开源 IM 方案：Server 和 SDK 核心代码都开放，社区活跃，文档齐全。但官方文档偏「使用指南」，要真正吃透设计和实现，还得回到源码。

因此，我们新开这个专题，目标很明确：

不满足于会部署、会调 API，而是把 OpenIM 的架构、模块边界、关键数据流彻底搞清楚。

系列规划已整理完毕（共 40 章 + 附录），涵盖协议层、Server 微服务、SDK 内核、端到端串联与进阶专题。本篇作为开篇，先把 OpenIM 是什么、能做什么、架构长什么样讲清楚，帮你建立全局地图。

二、OpenIM 是什么？

一句话概括：

OpenIMSDK 是一款基于组织架构进行沟通和协作的即时通讯平台，提供单聊、群聊、音视频通话、视频会议等功能。项目依托开源社区，采用更先进的运作方式迭代开发。产品支持私有化部署，确保数据安全可靠。

它和 Telegram、微信这类成品聊天产品不同。OpenIM 提供的是可集成的基础设施——你把 SDK 嵌进自己的 App，把 Server 私有化部署在自己的机房，业务数据完全自主可控。

整体由两大部分组成：

开发者的典型路径是：

业务 App  ←集成→  OpenIM SDK  ←长连接/HTTP→  OpenIM Server（私有化部署）

你的 UI、业务逻辑、账号体系自己掌控；IM 的「脏活累活」——连接保活、消息同步、离线推送、群聊扩散——交给 OpenIM 处理。

整体架构图

以上图片来源于OpenIM官网

三、官网与 GitHub：从哪里开始？

官网

• 中文站：https://www.openimsdk.com/

官网适合快速了解产品能力、查看多平台 Demo，以及获取商业支持信息。如果你想5 分钟感受 OpenIM 能做什么，从这里开始最合适。

官方文档

• 开发手册：https://docs.openim.io/zh-hans/sdks/introduction

文档覆盖部署指南、SDK 接入、API 参考，是日常开发的「字典」。本专题不会重复文档内容，而是在文档之上，补上源码视角的「为什么这样设计」。

GitHub 核心仓库

• 仓库首页 https://github.com/openimsdk

其中 openim-sdk-core 是所有开源 SDK 的跨平台底座（iOS、Android、PC、WebAssembly 等均基于此核心层封装），读透它，就等于掌握了整个客户端 IM 引擎。

社区数据（截至 2025 年）：GitHub Stars 约 **1 万+**，微信群成员 **2000+**，全球开发者持续贡献。

快速部署

• 源码部署：https://docs.openim.io/guides/gettingStarted/imSourceCodeDeployment
• Docker 一键部署：https://docs.openim.io/guides/gettingStarted/dockerCompose
• Docker 编排仓库：https://github.com/openimsdk/openim-docker

四、OpenIM 能做什么？核心功能一览

消息能力

• 文本、图片、语音、视频、文件、地理位置、引用、名片等全类型消息
• 单聊、群聊，支持已读回执、撤回、删除
• 自定义消息（ContentType 扩展），方便嵌入业务卡片、订单、红包等
• 阅后即焚、消息编辑等特色能力

社交与群组

• 好友申请、同意、删除、黑名单
• 群创建、邀请、踢人、禁言、群公告、入群验证
• 支持十万级超大群、千万级用户规模

连接与同步

• WebSocket 长连接 + 智能心跳
• 在线推送 + 离线推送（FCM、极光、个推等）
• 基于 Seq 的消息同步，断线重连后自动补偿
• 增量同步（好友、群组、会话列表）

业务扩展

• REST API：供业务后台调用（建群、发系统消息、用户管理等）
• Webhook / Callback：在关键事件前后回调你的业务服务器（如建群前审批、发消息后审计）

平台支持

五、架构一览：Server 与 SDK 分别长什么样？

5.1 OpenIM Server：微服务架构

Server 不是单体应用，而是一组可独立部署的微服务。核心进程包括：

                    ┌─────────────┐                    │  openim-api │  ← REST API 网关（业务后台入口）                    └──────┬──────┘                           │ gRPC    ┌──────────────────────┼──────────────────────┐    │                      │                      │┌───▼────┐  ┌──────▼──────┐  ┌────▼─────┐  ┌─────▼─────┐│ msg    │  │ conversation│  │  group   │  │ relation  │  ... RPC 服务│ (消息)  │  │  (会话)     │  │  (群组)   │  │  (好友)   │└───┬────┘  └─────────────┘  └──────────┘  └───────────┘    │    │ Kafka    ▼┌──────────────┐     ┌─────────────┐│ msgtransfer  │ ──→ │   MongoDB   │  消息持久化│ (消息管道)    │     └─────────────┘└──────┬───────┘       │       ▼┌──────────────┐     ┌─────────────┐│    push      │ ──→ │  在线/离线   │  推送到客户端│  (推送服务)   │     │   推送通道   │└──────────────┘     └─────────────┘┌──────────────┐│ msggateway   │  ← WebSocket 长连接网关（SDK 直连）│ (连接中枢)    │└──────────────┘

关键设计要点：

• msggateway 维护所有客户端长连接，是 SDK 的「入口」
• msg RPC 处理消息发送、同步、已读等核心逻辑
• msgtransfer 通过 Kafka 异步写库，削峰填谷
• push 负责把消息推到在线用户，离线用户走 FCM/极光等
• 存储层：MongoDB 持久化 + Redis 缓存热点数据

5.2 OpenIM SDK：分层架构

SDK 核心（openim-sdk-core）采用清晰的分层：

┌─────────────────────────────────────────┐│  open_im_sdk/          对外 API 层       │  InitSDK、Login、SendMessage...├─────────────────────────────────────────┤│  internal/             业务模块层        ││  ├── interaction/      长连接 + 消息同步  ││  ├── conversation_msg/ 会话与消息处理    ││  ├── user/             用户管理          ││  ├── group/            群组管理          ││  ├── relation/         好友关系          ││  └── third/            文件上传、日志     │├─────────────────────────────────────────┤│  pkg/                  基础设施层        ││  ├── db/               SQLite 本地存储   ││  ├── common/           命令队列、工具     ││  └── constant/         常量定义          │└─────────────────────────────────────────┘

关键设计要点：

• interaction 模块统一管理 WebSocket 连接、心跳、重连、消息拉取
• conversation_msg 是消息处理的「中枢」，收发、已读、撤回都在这里
• 各模块通过 Cmd2Value 命令队列 串行消费事件，避免并发竞态
• 本地 SQLite 存储消息和会话，保证离线可读、快速加载

5.3 一条消息的生命周期

理解架构最好的方式，是跟踪一条消息：

发送方 App  → SDK 本地落库（乐观更新）  → WebSocket 发送到 msggateway  → RPC msg 校验 & 分配 Seq  → Kafka → msgtransfer 写 MongoDB  → push 服务推送到接收方  → 接收方 msggateway 下发  → 接收方 SDK 入库 & 回调 OnRecvNewMessage  → 接收方 App 刷新 UI

系列第 28 章会逐步展开这条链路上每一个函数的源码位置。现在只需记住：SDK 负责「端」，Server 负责「云」，protocol 负责「契约」。

六、为什么选择 OpenIM？五大优势

01 完全开源，数据自主

核心代码 Apache 2.0 协议开源，Server 私有化部署，消息数据不出你的机房。对金融、医疗、政企等对数据安全敏感的行业尤其重要。

02 微服务架构，按需扩展

不是把所有功能塞进一个进程。连接网关、消息服务、推送服务各自独立，流量大了加机器即可。十万级大群、千万用户、百亿消息——架构上为此做了分层治理。

03 跨平台统一底座

openim-sdk-core 用 Go 编写，通过 gomobile / WASM 覆盖 iOS、Android、PC、Web。所有平台共享同一套同步、存储、连接逻辑，不会出现「Android 有 bug、iOS 正常」的割裂。

04 扩展友好

• 自定义消息类型：扩展 ContentType 即可
• 业务介入：Webhook 在事件前后回调你的服务
• 后台集成：REST API 让业务系统直接发消息、建群

「一切皆消息」的通信模型，让扩展变得简单。

05 社区活跃，生态完整

官方提供 Flutter / Android / Web / uni-app 等多端 Demo 和 SDK 封装；文档、Issue、Slack / 微信群响应及时。遇到问题不孤单。

七、本专题后续安排

本篇是「地图篇」。全系列共 40 章正文 + 6 个附录，覆盖 protocol、open-im-server、openim-sdk-core 三个核心仓库。下面列出完整目录，方便你按需追更。

每章统一结构：架构图 → 关键入口 → 核心数据结构 → 源码走读 → 双端协作 → 常见坑

第一篇：协议层 protocol（第 1–2 章）

第 1 章：Proto 体系与代码生成

• sdkws.proto：WebSocket 载荷、推送结构
• 各 RPC 服务 proto：msg / conversation / group / relation / user / auth / push / msggateway
• constant：ContentType 区间、平台 ID、错误码

第 2 章：ReqIdentifier 与长连接协议

• msggateway 请求/响应帧格式（ReqIdentifier、MsgIncr、OperationID）
• Server 编解码与 SDK encoder.go 的对应关系

第二篇：OpenIM Server 架构深潜（第 3–15 章）

第 3 章：配置、启动与服务发现

• Viper 配置加载、服务发现（standalone / K8s / etcd）
• putCmd + cmds.run：多服务同进程启动机制
• Prometheus 指标注册

第 4 章：存储分层架构

• Controller 层 → Database 抽象（Mongo）→ Cache 层（Redis + mcache）
• 读写路径：RPC → Controller → Cache → DB

第 5 章：openim-api —— REST 网关

• 路由表、鉴权中间件、限流
• 典型接口（发消息、建群、拉会话）如何转 RPC

第 6 章：openim-msggateway —— WebSocket 长连接中枢

• 连接建立、心跳、在线状态
• 按 ReqIdentifier 分发、多设备多连接管理
• 压缩与编解码

第 7 章：openim-msgtransfer —— 消息管道与持久化

• Kafka 消费模型（online history / to mongo）
• 消息写入 Mongo 的分片与索引策略
• 与 push、msggateway 的衔接

第 8 章：openim-push —— 在线推送与离线推送

• 在线用户实时下发
• FCM / 极光 / 个推等离线推送适配
• Push 与 MsgGateway 的职责边界

第 9 章：RPC 服务群（一）—— auth + user

• auth：Token 签发与校验
• user：资料、在线状态、通知、统计

第 10 章：RPC 服务群（二）—— relation（好友/黑名单）

• 好友申请、同意、删除全链路
• 增量同步协议（incrversion）
• Callback / Webhook 钩子

第 11 章：RPC 服务群（三）—— group

• 建群、邀请、踢人、群资料变更
• 群成员缓存与大群优化思路
• 群通知 ContentType 与下发路径

第 12 章：RPC 服务群（四）—— conversation

• ConversationID 生成规则
• 会话列表、未读数、置顶、草稿
• 会话级 Seq 管理（seq_conversation）

第 13 章：RPC 服务群（五）—— msg（核心）

• 发送：校验 → 写库 → 推 Kafka
• 同步：拉取与空洞补齐
• 已读、撤回、删除
• 好友/群/用户类通知消息

第 14 章：RPC 服务群（六）—— third

• 对象存储（S3）、日志上报、工具类接口

第 15 章：定时任务 openim-crontask

• 消息清理、S3 过期、分布式锁

第三篇：OpenIM SDK 架构深潜（第 16–26 章）

第 16 章：SDK 对外接口与调用模型

• InitSDK / Login / Logout
• 异步回调、operationID、线程模型
• UserContext 核心对象组装

第 17 章：命令队列与事件驱动

• Cmd2Value 通道与 DoListener 模式
• 为何 notification 与 chat message 分路处理

第 18 章：长连接管理 interaction

• readPump / writePump / heartbeat 三协程模型
• 重连策略、请求-响应异步匹配（MsgIncr）
• 前后台切换、网络变化处理

第 19 章：消息同步器 MsgSyncer

• syncedMaxSeqs 与空洞拉取
• Push 触发 vs 主动 Pull
• 重装/首次登录全量同步、批处理优化

第 20 章：会话与消息 conversation_msg

• 主循环与事件消费
• 发送：创建消息 → 发送队列 → 长连接
• 接收：入库 → 更新会话 → 回调 UI
• 已读回执、撤回、消息校验

第 21 章：通知处理 notification

• ContentType 路由到 relation / user / group / conversation
• SetNotificationSeq 与通知 Seq 独立推进
• 通知 vs 普通消息的存储差异

第 22 章：增量同步体系（SDK 侧）

• conversation / group / relation 各模块增量同步
• 全量 vs 增量：何时全量、何时增量
• Version 对齐与冲突处理

第 23 章：用户 / 好友 / 群组模块

• user：资料缓存、通知
• relation：好友列表、申请、黑名单
• group：群资料、成员、filter

第 24 章：本地数据库 pkg/db

• SQLite 表结构（消息表、会话表、Seq 表）
• 事务与批量写入策略

第 25 章：Third 模块 —— 文件上传与日志

• 分片上传、断点续传
• 日志压缩上报

第 26 章：跨平台编译与绑定

• gomobile / WASM
• Android / iOS 接入要点

第四篇：端到端源码串联（第 27–35 章）

专题高潮部分：Server 与 SDK 左右对照读，每章配时序图。

第 27 章：登录与长连接建立

• SDK：Login → Token → WS URL 参数
• Server：Gateway 鉴权 → 在线注册

第 28 章：发送一条文本消息

• SDK：本地落库 → WS SendMsg
• Server：Gateway → RPC msg → Kafka → Transfer → Push → 对端收包

第 29 章：消息同步与 Seq 机制

• Server：seq_conversation / PullMsgBySeq
• SDK：syncedMaxSeqs / SplitPullMsgNum
• 空洞、重复、乱序如何处理

第 30 章：群聊消息扩散

• 大群写扩散 vs 读扩散（OpenIM 实际策略）
• 成员列表缓存、推送扇出

第 31 章：好友申请通知全链路

• Server relation 发 notification
• SDK doNotificationManager → UI 回调

第 32 章：已读回执

• Server as_read ↔ SDK read_drawing
• 未读数在两端如何保持一致

第 33 章：撤回与删除

• 服务端状态变更 → 通知下发 → SDK 本地消息修正

第 34 章：断线重连与消息补偿

• SDK 重连后 LoadSeq + 增量拉取
• Server 在线状态变化与离线 Push

第 35 章：Webhook / Callback 业务扩展

• 各模块 callback 触发点
• 业务系统介入：建群前审批、发消息后审计等

第五篇：进阶专题（第 36–40 章）

第 36 章：性能与容量设计

• 十万级大群、千万用户下的关键瓶颈点
• 缓存、批处理、Kafka 分区策略

第 37 章：可观测性

• Prometheus 指标、operationID 全链路追踪
• 日志规范与问题定位手册

第 38 章：部署架构演进

• 单机 all-in-one → 微服务拆分 → K8s
• msggateway 多副本与连接粘性

第 39 章：二次开发与扩展指南

• 新增 ContentType / 自定义消息
• 新增 RPC 接口与 SDK API 的完整改动清单

第 40 章：源码阅读方法论与调试环境搭建

• 本地起 Server + SDK integration_test
• 常用断点位置、抓包与日志对照表

章节总览（速查表）

推荐追更顺序

不必严格按章节号阅读，建议按「获得感」优先：

第 0 篇（本篇）→ 建立全局认知    ↓第 1–2 篇（协议层）→ 搞懂组件间契约    ↓第 28 篇（发消息）→ 第一条完整链路，最有成就感    ↓┌────────────────────┬────────────────────┐│ Server 深潜         │ SDK 深潜            ││ 第 6 + 8 + 13 章    │ 第 16–20 章         ││ 网关/推送/消息 RPC   │ 接口/长连接/同步/会话 │└─────────┬──────────┴──────────┬─────────┘          ↓                     ↓          第 27–35 篇（端到端串联）                    ↓          第 21–22 + 31 篇（通知 & 增量同步）                    ↓          第 36–40 篇（进阶专题）

有明确问题也可以「跳读」——比如只关心通知，直接看第 21 + 31 章；只关心重连，看第 18 + 34 章。

八、写在最后

OpenIM 不是最简单的 IM 方案，但可能是最适合想深入理解 IM 系统设计的开源项目——代码质量高、模块边界清晰、文档和社区跟得上。

如果你：

• 正在接入或维护基于 OpenIM 的项目；
• 想从零设计一套 IM 系统，需要参考成熟实现；
• 或者单纯对「消息怎么从 A 发到 B」这件事好奇；

欢迎持续关注本专题。下一篇，我们将进入 协议层——从 protocol 仓库的 Proto 定义出发，搞清楚 OpenIM 各组件之间的「契约」是什么。

相关链接

• 官网：https://www.openim.io/zh

• 文档：https://docs.openim.io/zh

• Server 仓库：https://github.com/openimsdk/open-im-server

• SDK Core 仓库：https://github.com/openimsdk/openim-sdk-core

如果这篇对你有帮助，欢迎转发给正在做 IM 和WebRTC 的同事。有问题欢迎在评论区交流。