1. 项目概述为什么一个开源IM服务值得你花两小时认真读完OpenIM 这个名字在最近半年的开发者社区里出现频率明显变高不是因为某家大厂突然宣布自研替代方案而是因为一群长期深耕通讯底层的工程师把一套真正能跑在生产环境里的即时通讯服务完整、干净、无保留地开源了。它不叫“轻量版”、不标榜“适合学习”而是直接以“企业级”为设计目标——支持百万级在线、消息必达、离线消息可靠同步、已读回执、多端状态同步、群聊消息去重与幂等这些词不是PPT里的功能列表而是代码里每一行都经过压测验证的逻辑。我最早接触 OpenIM 是在帮某高校实验室做远程协作系统时原计划用 Firebase Realtime Database 搭建简易聊天模块结果发现其消息时序一致性在弱网下不可控且无法满足国产化信创环境部署要求转而试用 OpenIMServer 后三天内就完成了从单机部署到三节点集群的平滑迁移最让我意外的是它的 SDK 设计哲学不是“封装得越厚越好”而是把连接管理、心跳保活、重连策略、本地消息队列、加密密钥协商这些容易出错的环节全部收口只暴露 clean、send、recv、onMessage 这几个语义清晰的接口。这意味着哪怕你是个刚写完第一个 React 组件的前端新人只要理解“发消息就是调 send()收消息就是监听 onMessage”就能在 20 分钟内跑通一个可发可收的 Web 端聊天界面。它解决的从来不是“能不能做个聊天框”而是“如何让聊天功能在真实网络、真实设备、真实用户行为下稳定如呼吸”。这篇文章不讲源码逐行注释也不堆砌架构图而是带你从零开始亲手把 OpenIMServer 部署起来把 OpenIMSDK 接进一个真实可用的 Vue3 项目再用一个具体场景——比如“客服会话自动分配未读消息聚合提醒”——验证它是否真如文档所说“开箱即用”。如果你正面临选型焦虑或者已经踩过环信、融云、声网 IM SDK 的坑又或者只是想搞懂一个现代 IM 服务背后到底要处理多少“看不见的脏活”那接下来的内容就是你该留下的理由。2. OpenIMServer 架构深度拆解不是微服务拼盘而是通信协议的精密编排2.1 核心分层逻辑为什么它不叫“OpenIM 微服务套件”而叫“OpenIM Server”很多团队第一次看 OpenIM 文档时会被它的服务列表吓一跳msg_gateway、push、relation、friend、group、user、msg、rpc_proxy……光是启动脚本里就有十多个二进制文件。但千万别被表象误导——这并非典型的“为拆而拆”的微服务架构。我实际参与过两个基于 OpenIM 的定制化改造项目一次是给某政务协同平台增加内部工单沟通模块另一次是为某医疗 IoT 设备管理后台添加设备告警推送通道。两次部署后第一件事都是打开netstat -tuln | grep :1000结果发现所有服务默认监听的都是127.0.0.1:端口而非0.0.0.0:端口。这个细节非常关键OpenIM 的服务间通信95% 以上走的是本地 Unix Domain Socket 或 gRPC over localhost而不是跨网络的 HTTP 调用。换句话说它本质上是一个“逻辑微服务、物理单体”的混合架构。msg_gateway 是唯一对外暴露的入口它接收 WebSocket/HTTP 请求完成鉴权、协议解析支持 OpenIM 自定义二进制协议和兼容 WebSocket-Text、消息路由之后它通过本地 gRPC 调用 msg 服务存消息、调用 relation 服务查好友关系、调用 group 服务处理群组事件——所有这些调用都在同一台机器内存中完成延迟控制在 0.2ms 以内。这种设计直接规避了传统微服务最头疼的三个问题网络抖动导致的链路超时、服务发现失败引发的雪崩、跨服务事务一致性难题。你可以把它理解成一台精密的瑞士手表齿轮各个 service各自独立运转但所有动力都来自同一个主发条msg_gateway且齿轮之间通过刚性轴本地 IPC直连没有皮带打滑。这也是为什么 OpenIM 在 4C8G 的阿里云 ECS 上单机就能支撑 5 万并发长连接——它省掉的不是代码行数而是每一次跨网络调用带来的不可控抖动。2.2 消息投递的“三重保险”机制从发送成功到用户看到中间到底发生了什么很多人以为 IM 消息“发出去”就等于“对方收到了”这是最大的认知偏差。OpenIM 的消息投递链路实际上是一套环环相扣的确认与补偿机制。我们以一条普通文本消息为例从 A 用户发送给 B 用户的全过程第一重保险客户端本地持久化 网关确认A 的 SDK 调用sendMessage()后SDK 立即将消息写入本地 SQLite 数据库标记为statussending同时通过 WebSocket 向 msg_gateway 发送加密后的消息包。msg_gateway 收到后先校验签名、检查 A 的登录态、判断 B 是否在线然后生成全局唯一msgID格式为msg_{unix_timestamp}_{random_6}将消息元数据发送者、接收者、msgID、时间戳、内容哈希存入 Redis 的 Sorted Set用于按时间排序并立即向 A 的 WebSocket 连接返回{status: success, msgID: xxx}。此时 A 的 SDK 将本地消息状态更新为statussent。注意这一步不保证 B 已收到只保证“网关已受理”。第二重保险服务端异步投递 离线兜底msg_gateway 触发一个异步任务若 B 当前在线其长连接注册在 msg_gateway 的内存连接池中则直接将消息推送给 B 的连接若 B 不在线则将消息写入 MySQL 的offline_message表含接收者 ID、消息体、过期时间并触发 push 服务向 B 的设备推送 APNs/华为 HMS 透传通知。这里的关键是MySQL 写入成功才认为“离线消息已可靠落库”。我实测过在 MySQL 主库宕机时OpenIM 会自动降级为仅内存缓存离线消息配置项offline_msg_cache_size可控并在主库恢复后自动补写避免消息丢失。第三重保险客户端 ACK 与服务端状态同步B 的 SDK 收到消息后会立即向 msg_gateway 发送一条ack_msg请求携带msgID和recv_time。msg_gateway 更新 Redis 中该消息的ack_status1并通知 relation 服务更新 A-B 的对话最后活跃时间。如果 B 的 SDK 因崩溃未发出 ACKmsg_gateway 会在 30 秒后主动查询 B 的连接状态若仍在线则重发若离线则等待 B 下次上线时SDK 自动拉取未 ACK 的消息列表并批量 ACK。这套机制确保了“已读回执”的原子性——你看到的“已读”图标不是客户端自己画的而是服务端真实收到了对方设备的确认信号。提示OpenIM 的消息去重不是靠客户端时间戳而是靠服务端生成的msgID。所有 SDK 在发送前必须等待网关返回msgID才能更新 UI否则会出现“重复发送”幻觉。我在某次灰度发布中因前端 SDK 优化了发送按钮防抖逻辑跳过了等待msgID的步骤导致用户点一次发送服务端收到三条相同内容不同msgID的消息最终靠后台定时任务清洗才恢复。2.3 集群部署的“无状态”真相哪些组件能水平扩展哪些必须主从OpenIM 官方文档说“支持水平扩展”但没明说的是只有 msg_gateway 和 push 服务真正无状态其余服务都有隐式状态依赖。我用一套三节点集群Node1/Node2/Node3做过压力测试结论很明确可无脑扩缩容msg_gateway负载均衡到 Nginx、pushAPNs 连接池共享HMS Token 自动刷新。加机器加吞吐无需任何配置变更。需谨慎扩缩容user、relation、group、friend 这四个服务它们的业务逻辑本身无状态但底层依赖 MySQL 的主从复制延迟。当 Node1 上的 user 服务执行“创建用户”操作MySQL 主库写入后从库同步有 100~300ms 延迟。如果紧接着 Node2 上的 relation 服务查询该用户的好友列表可能查不到刚创建的用户。解决方案是所有写操作强制路由到主库OpenIM 默认开启read_from_mastertrue读操作可走从库但关键路径如登录态校验、关系查询必须走主库。这不是缺陷而是对强一致性的主动取舍。绝对不可扩缩容msg 服务消息存储和 rpc_proxygRPC 网关。msg 服务的 MySQL 表结构包含shard_key字段分库分表逻辑硬编码在代码中目前只支持按receiver_id哈希分片且分片数在初始化时固定默认 16。你想从 16 分片扩到 32不行没有在线扩容工具必须停服导数据。rpc_proxy 更简单粗暴它只是一个反向代理把外部 gRPC 请求转发给内部 service本身不存状态但所有 service 的 gRPC 地址都写死在它的配置文件里加机器就得改配置、重启。所以真实的集群部署建议是msg_gateway 和 push 服务部署 3~5 实例其余服务除 msg 外部署 2 实例主从msg 服务必须单实例或 MySQL 主从但写永远只走主。别被“微服务”字眼迷惑OpenIM 的扩展性是围绕“连接数”和“消息吞吐”设计的不是围绕“服务实例数”设计的。3. OpenIMSDK 集成实战Vue3 项目从零接入避开 90% 的新手坑3.1 SDK 选型与初始化为什么 Web 端必须用 openim-sdk-js而不是“通用 SDK”OpenIM 官方提供三套 SDKopenim-sdk-jsWeb/Node.js、openim-sdk-iosSwift、openim-sdk-androidKotlin。很多开发者第一反应是“找通用 SDK”试图用openim-sdk-js同时跑在 Vue3 和 Electron 中。这是个危险信号。openim-sdk-js的核心依赖是wsWebSocket 客户端和crypto-js加解密但它在浏览器环境和 Node.js 环境的初始化方式完全不同。在 Vue3 项目中你必须使用openim-sdk-js的浏览器专用构建版本dist/openim-sdk-js.browser.min.js因为它内部做了两件事一是用window.WebSocket替代require(ws)二是将crypto-js的 AES 加密逻辑替换为 Web Crypto APIwindow.crypto.subtle以满足 Chrome 对非安全上下文http://的限制。如果你错误地在 Vue3 中引入openim-sdk-js.node.min.js启动时就会报Error: Cannot find module ws——因为 Vue3 打包器Vite根本找不到 Node.js 的ws模块。正确的初始化姿势如下以 Vue3 Composition API 为例// src/composables/useOpenIM.ts import { ref, onMounted, onUnmounted } from vue import OpenIMSDK from openim-sdk-js/dist/openim-sdk-js.browser.min.js const imClient refany(null) const connectionStatus refconnecting | connected | disconnected(disconnected) export function useOpenIM() { const initSDK (userID: string, token: string, wsUrl: string) { // 1. 创建 SDK 实例必须传入完整的 wsUrl含协议、域名、端口 imClient.value new OpenIMSDK.SDK({ userID, token, wsUrl, // 例如 wss://im.example.com:10002 platform: 6, // 6 Web 平台必须显式指定 logLevel: 2, // 2 INFO调试时设为 3DEBUG }) // 2. 注册全局事件监听器必须在 connect 前注册 imClient.value.onConnectSuccess () { connectionStatus.value connected console.log(OpenIM SDK connected successfully) } imClient.value.onConnectFailed (err: any) { connectionStatus.value disconnected console.error(OpenIM SDK connect failed:, err) } imClient.value.onUserTokenExpired () { // token 过期需重新登录获取新 token console.warn(User token expired, please re-login) } } const connect async () { if (!imClient.value) return try { connectionStatus.value connecting await imClient.value.connect() // 此处会发起 WebSocket 连接 } catch (err) { console.error(Connect error:, err) connectionStatus.value disconnected } } return { imClient, connectionStatus, initSDK, connect, } }注意platform: 6这个参数极其关键。OpenIM 的服务端会根据platform值决定是否启用某些特性比如 Web 平台默认关闭“后台消息静默推送”因为浏览器限制而 iOS 平台则会自动注册 APNs。漏掉它SDK 可能连接成功但收不到消息。3.2 消息收发的核心闭环从点击发送到 UI 更新每一步都不能少在 Vue3 中实现一个“输入框发送按钮”的聊天界面看似简单实则暗藏五个必须处理的环节。我见过太多项目卡在第 3 步最后归咎于“SDK 有 bug”。其实只是流程没走全。消息预提交Pre-Send用户点击发送SDK 必须先调用createTextMessage()创建消息对象而不是直接send()。因为createTextMessage()会生成本地clientMsgID格式client_{timestamp}_{random}并填充senderID、receiverID、contentType等元数据。这一步是后续去重和状态更新的基础。本地 UI 即时反馈createTextMessage()返回后立即将该消息对象含clientMsgID插入 Vue 的响应式消息列表messageList.value并设置status: sending。UI 层立刻显示“正在发送…”的 loading 状态。这给了用户确定性反馈避免重复点击。服务端发送与状态同步调用imClient.value.sendMessage(messageObj, receiverID, sessionType)。此方法返回一个 Promise。关键点来了Promise resolve 后SDK 会触发onSendMessage回调但此时消息状态仍是sending。你必须在onSendMessage回调里根据返回的serverMsgID由服务端生成更新本地消息的status: sent。如果这里不做UI 会一直显示“正在发送”直到超时。接收消息的双向绑定SDK 的onRecvNewMessage回调是全局的它会收到所有发给当前用户的会话消息包括单聊和群聊。你需要在回调里根据messageObj.sessionType和messageObj.recvID单聊时为对方 ID群聊时为群 ID找到对应会话将messageObj插入该会话的消息列表并设置status: received。注意不要直接push()到全局列表必须按会话隔离。已读回执的显式触发当用户滚动到某条消息位置或点击“标记为已读”按钮时必须手动调用imClient.value.markMessageAsRead([messageObj.clientMsgID])。SDK 不会自动帮你发 ACK这是为了给你完全的控制权——比如客服系统可能要求“只有坐席人工查看后才算已读”。下面是一个精简但完整的发送逻辑示例// src/composables/useChat.ts import { ref } from vue import { useOpenIM } from ./useOpenIM export function useChat(conversationID: string) { const { imClient } useOpenIM() const messageList refany[]([]) const sendMessage async (text: string) { if (!imClient.value || !text.trim()) return // 1. 创建消息对象 const messageObj imClient.value.createTextMessage(text) // 2. 本地预提交UI 立即更新 const localMsg { ...messageObj, status: sending, clientMsgID: messageObj.clientMsgID, sendTime: Date.now(), senderID: current_user_id, // 实际应从登录态获取 recvID: conversationID, } messageList.value.push(localMsg) try { // 3. 发送到服务端 const result await imClient.value.sendMessage( messageObj, conversationID, 1 // 1 单聊 sessionType ) // 4. 服务端返回后更新本地状态 const sentMsgIndex messageList.value.findIndex( m m.clientMsgID messageObj.clientMsgID ) if (sentMsgIndex ! -1) { messageList.value[sentMsgIndex].status sent messageList.value[sentMsgIndex].serverMsgID result.serverMsgID } } catch (err) { console.error(Send failed:, err) // 5. 发送失败更新状态为 error可提供重发按钮 const failedIndex messageList.value.findIndex( m m.clientMsgID messageObj.clientMsgID ) if (failedIndex ! -1) { messageList.value[failedIndex].status error } } } return { messageList, sendMessage, } }3.3 群聊与会话管理如何用 20 行代码实现“未读消息角标”和“会话置顶”OpenIM 的会话conversation概念是比“聊天窗口”更高一层的抽象。一个 conversationID 是由sessionTyperecvIDgroupID群聊时拼接而成的字符串比如单聊是1_user123群聊是2_group456。SDK 提供了getConversationList()方法但它返回的是“所有会话的快照”不是实时流。要实现微信式的“未读角标”你必须自己维护一个unreadCountMap。核心思路是利用 SDK 的onNewMessageRevoked消息撤回、onRecvNewMessage新消息、onRecvMessageRead已读回执这三个回调实时更新内存中的未读计数。// src/stores/conversationStore.ts import { defineStore } from pinia import { useOpenIM } from /composables/useOpenIM export const useConversationStore defineStore(conversation, () { const unreadCountMap refRecordstring, number({}) // 初始化首次加载会话列表时清空并重置 const initUnreadMap (conversations: any[]) { conversations.forEach(conv { unreadCountMap.value[conv.conversationID] conv.unreadCount || 0 }) } // 监听新消息每来一条对应会话未读1 const onRecvNewMessage (message: any) { const convID message.conversationID unreadCountMap.value[convID] (unreadCountMap.value[convID] || 0) 1 } // 监听已读回执当用户阅读某会话清零 const onRecvMessageRead (readInfo: any) { const convID readInfo.conversationID unreadCountMap.value[convID] 0 } // 监听消息撤回不影响未读计数撤回的是已读消息 const onNewMessageRevoked (revokeInfo: any) { // 通常无需处理 } // 提供 getter const getUnreadCount (convID: string) unreadCountMap.value[convID] || 0 return { unreadCountMap, initUnreadMap, onRecvNewMessage, onRecvMessageRead, onNewMessageRevoked, getUnreadCount, } })然后在useOpenIM的初始化阶段把这些回调挂载上去// 在 useOpenIM 的 initSDK 函数末尾添加 imClient.value.onRecvNewMessage (message: any) { conversationStore.onRecvNewMessage(message) } imClient.value.onRecvMessageRead (readInfo: any) { conversationStore.onRecvMessageRead(readInfo) }至于“会话置顶”OpenIM 服务端不提供isPinned字段但 SDK 允许你在本地对conversationList排序。最佳实践是在 Pinia store 中维护一个pinnedConvIDs: string[]数组每次调用getConversationList()后先过滤出pinnedConvIDs中的会话再拼接剩余会话。这样既不影响服务端逻辑又能实现客户端置顶。4. 部署实战从单机 Docker 到生产级 Kubernetes避坑指南全记录4.1 单机 Docker 部署5 分钟跑通但必须改掉这 3 个默认配置OpenIM 官方 GitHub 提供了docker-compose.yml但直接docker-compose up -d启动90% 的人会遇到连接失败。原因在于三个默认配置与生产环境严重冲突WS 端口暴露错误官方docker-compose.yml中msg_gateway服务的端口映射是- 10002:10002这没错。但它的environment里有一行OPENIM_WS_PORT10002这行配置会让 msg_gateway 在生成 WebSocket 连接地址时错误地拼出ws://localhost:10002。而你的 Vue3 应用运行在浏览器里localhost指向的是用户电脑不是服务器正确做法是在msg_gateway的 environment 中删除OPENIM_WS_PORT改为显式设置OPENIM_API_URLhttps://your-domain.com。SDK 初始化时会用这个 URL 拼接 WS 地址wss://your-domain.com:10002。MySQL 密码太弱官方镜像默认 MySQL root 密码是123456这在任何环境都不安全。你必须在docker-compose.yml的mysql服务下修改environmentenvironment: MYSQL_ROOT_PASSWORD: YourStrongPass2024 MYSQL_DATABASE: openim并同步修改openim-server服务的OPENIM_MYSQL_DSN格式为root:YourStrongPass2024tcp(mysql:3306)/openim?charsetutf8mb4parseTimeTruelocLocal。Redis 密码为空同理官方 Redis 配置无密码OPENIM_REDIS_ADDR默认是redis:6379。生产环境必须加密码。修改redis服务environment: REDIS_PASSWORD: RedisSecurePass#1并更新openim-server的OPENIM_REDIS_ADDR为redis:6379OPENIM_REDIS_PASSWORD为RedisSecurePass#1。改完这三项docker-compose up -d启动后用curl -v http://localhost:10002/ping测试网关健康返回{status:ok}即成功。此时你的 Vue3 应用就可以用wss://your-domain.com:10002连接了。4.2 Nginx 反向代理配置为什么必须用proxy_buffering off和proxy_http_version 1.1当 OpenIMServer 部署在公有云上你绝不能让客户端直连:10002端口。必须用 Nginx 做 TLS 终结和反向代理。但 OpenIM 的 WebSocket 连接对 Nginx 配置极其敏感。我曾在一个项目中因 Nginx 配置遗漏一行导致所有移动端用户连接 30 秒后自动断开。以下是经过生产环境千次验证的 Nginx 配置片段放在server块内# WebSocket 代理必须的 header map $http_upgrade $connection_upgrade { default upgrade; close; } upstream openim_ws { server 127.0.0.1:10002; keepalive 32; } server { listen 443 ssl http2; server_name im.example.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; # 关键禁用 proxy_buffering否则 WebSocket 帧会被缓存导致粘包 proxy_buffering off; proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k; # WebSocket 协议升级必需 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 超时设置WebSocket 必须长连接 proxy_read_timeout 86400; # 24小时足够长 proxy_send_timeout 86400; proxy_connect_timeout 75; location / { proxy_pass http://openim_ws; # 关键必须开启 WebSocket 支持 proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }注意proxy_buffering off是灵魂。OpenIM 的 WebSocket 消息是二进制帧流Nginx 默认开启 buffering会把多个小帧合并成一个大包发送导致客户端 SDK 解析失败表现为“连接成功但收不到消息”。这个坑我花了整整两天抓包才定位到。4.3 Kubernetes 生产部署StatefulSet 与 Headless Service 的黄金组合当你需要部署高可用集群时Kubernetes 是唯一选择。但 OpenIM 的 msg 服务消息存储有状态不能用 Deployment。必须用 StatefulSet PersistentVolumeClaimPVC。核心 YAML 片段如下以 msg 服务为例# msg-statefulset.yaml apiVersion: apps/v1 kind: StatefulSet metadata: name: openim-msg spec: serviceName: openim-msg-headless # 必须指向 headless service replicas: 1 # msg 服务不支持多副本必须为 1 selector: matchLabels: app: openim-msg template: metadata: labels: app: openim-msg spec: containers: - name: openim-msg image: openim/msgs:v3.5.0 env: - name: OPENIM_MYSQL_DSN value: root:YourPasstcp(openim-mysql:3306)/openim?... - name: OPENIM_REDIS_ADDR value: openim-redis:6379 - name: OPENIM_REDIS_PASSWORD value: RedisPass ports: - containerPort: 10003 name: grpc volumeMounts: - name: msg-storage mountPath: /data volumes: - name: msg-storage persistentVolumeClaim: claimName: openim-msg-pvc # PVC 名称需提前创建 --- # headless service为 StatefulSet 提供稳定的 DNS 记录 apiVersion: v1 kind: Service metadata: name: openim-msg-headless annotations: service.alpha.kubernetes.io/tolerate-unready-endpoints: true spec: clusterIP: None # 关键headless selector: app: openim-msg ports: - port: 10003 name: grpc为什么必须用 Headless Service因为 StatefulSet 的每个 Pod 都有唯一、固定的 DNS 名称如openim-msg-0.openim-msg-headless.default.svc.cluster.local。msg 服务的 gRPC 客户端比如 user 服务在连接时必须用这个 FQDN而不是openim-msg.default.svc.cluster.local后者是 ClusterIP Service会做负载均衡而 msg 服务只能有一个实例。Headless Service 不提供 ClusterIP只提供 DNS 记录完美匹配 StatefulSet 的需求。实操心得PVC 的 StorageClass 必须支持ReadWriteOnceRWO且底层存储如 AWS EBS、阿里云云盘必须是 SSD 类型。我测试过用 HDD 云盘当消息写入峰值超过 500 QPS 时MySQL 的innodb_log_waits指标飙升导致消息延迟超过 2 秒。换成 io2 类型 EBS 后稳定支撑 3000 QPS。5. 常见问题与排查技巧实录那些文档里不会写的“血泪经验”5.1 连接不上先查这 5 个地方90% 的问题当场解决OpenIM 的连接问题80% 都出在基础设施层而非 SDK 或服务端代码。我整理了一份“连接五查法”按顺序执行基本能秒杀所有连接异常检查项操作命令/方法预期结果常见错误1. 端口连通性telnet your-domain.com 10002或nc -zv your-domain.com 10002Connected to...防火墙拦截、安全组未开放 10002 端口、Nginx 未监听 4432. TLS 证书有效性openssl s_client -connect your-domain.com:443 -servername your-domain.com 2/dev/nullopenssl x509 -noout -datesnotAfterDec 31 23:59:59 2025 GMT3. WebSocket 升级头curl -i -N -H Connection: Upgrade -H Upgrade: websocket -H Sec-WebSocket-Version: 13 https://your-domain.com响应头含HTTP/1.1 101 Switching ProtocolsNginx 配置遗漏proxy_set_header Upgrade $http_upgrade;4. 服务端健康检查curl -k https://your-domain.com:10002/ping若启用了 HTTPS{status:ok}msg_gateway 服务未启动、端口被占用、MySQL 连接失败5. SDK 初始化参数检查 Vue3 代码中new OpenIMSDK.SDK({})的wsUrl必须是wss://your-domain.com:10002不能是ws://localhost:10002开发环境误用 localhost、生产环境忘记加swss提示curl -i命令会显示完整响应头重点看Connection和Upgrade字段是否为upgrade。如果看到HTTP/1.1 200 OK说明 Nginx 根本没触发 WebSocket 升级100% 是配置问题。5.2 消息收不到别急着骂 SDK先看这 3 个日志开关消息收发是 OpenIM 最常被质疑的功能。但绝大多数“收不到”其实是日志没开看不到真实原因。OpenIM 的日志系统有三级开关必须全部打开才能准确定位SDK 端 DEBUG 日志在new OpenIMSDK.SDK({})时设置logLevel: 3DEBUG。它会打印每一条 WebSocket 帧的收发详情包括clientMsgID、serverMsgID、seq序列号。如果这里看到recv: {cmd: new_msg, ...}说明服务端已推送问题在你的onRecvNewMessage回调里如果完全没日志说明 WebSocket 连接已断。msg_gateway 服务端 TRACE 日志修改config/config.yaml将log.level改为trace并确保log.outputPaths包含/var/log/openim。重启后tail -f /var/log/openim/msg_gateway.log搜索关键词onRecvNewMessage或sendToUser。如果看到sendToUser: userIDuser123, msgIDmsg_12345, statussuccess说明服务端已投递如果看到user not online说明接收方不在线消息已进离线队列